---
title: Configure a Proxy for the New Relic eBPF Agent
source: https://docs.newrelic.com/docs/ebpf/proxy-configuration
---

If your environment routes outbound traffic through a corporate proxy, you can configure the New Relic eBPF agent to send OTLP telemetry through that proxy. This page explains how to configure proxy support on Linux hosts and Kubernetes clusters, the proxy server requirements, and how to troubleshoot common issues.

> #### ⚠️ IMPORTANT
>
> The eBPF agent supports HTTP CONNECT proxies using the `http://` scheme only. Due to gRPC limitations, the agent doesn't support the `https://` scheme (a TLS-encrypted connection directly to the proxy). However, your telemetry data is always TLS-encrypted **end-to-end** between the agent and the New Relic OTLP endpoint. The `http://` prefix dictates only how the agent talks to the proxy to establish the tunnel. The proxy itself only sees encrypted traffic and never has access to your data.

## How proxy support works [#how-it-works]

The eBPF agent uses gRPC's built-in HTTP proxy support. When you configure a proxy, the agent:

1.  Connects to the proxy server.
2.  Sends an `HTTP CONNECT` request to open a tunnel to the New Relic OTLP endpoint.
3.  Performs a TLS handshake with the OTLP endpoint through that tunnel.
4.  Adds a `Proxy-Authorization: Basic <base64>` header if you provided credentials.

## Proxy server requirements [#proxy-requirements]

Your proxy server must support:

-   The HTTP `CONNECT` method (required for TLS tunneling to the OTLP endpoint).
-   Tunneling to port `443` (the OTLP endpoint uses HTTPS).
-   HTTP Basic Authentication, if you use authenticated proxy access.

### Supported proxy servers [#supported-proxies]

| Proxy                  | Supported?  | Notes                                                                                            |
| ---------------------- | ----------- | ------------------------------------------------------------------------------------------------ |
| Squid                  | Yes         | Recommended. Supports `CONNECT` out of the box.                                                  |
| Apache `mod_proxy`     | Yes         | Requires `AllowCONNECT` configuration.                                                           |
| nginx                  | With module | Requires the `ngx_http_proxy_connect_module` module.                                             |
| HAProxy                | No          | HAProxy is a reverse proxy/load balancer and doesn't support the forward-proxy `CONNECT` method. |
| Most corporate proxies | Usually yes | Check with your IT or networking team.                                                           |

## Credential character limitations [#credential-limitations]

> #### ⚠️ CAUTION
>
> If your proxy username contains uppercase letters, or your username or password contains special characters, proxy authentication fails silently. The eBPF agent catches these cases at startup and logs an error so you aren't left debugging a silent failure.

When you configure proxy credentials, only use the following characters:

-   **Username:** Lowercase letters (`a–z`), digits (`0–9`), hyphen (`-`), underscore (`_`), period (`.`), and tilde (`~`). Uppercase letters aren't allowed.
-   **Password:** Letters (`a–z`, `A–Z`), digits (`0–9`), hyphen (`-`), underscore (`_`), period (`.`), and tilde (`~`).

The following characters are **not allowed** in either the username or the password: `@`, `:`, `/`, `?`, `#`, `[`, `]`, `!`, `$`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `;`, `=`, `%`, spaces, and other special characters.

If your existing proxy credentials use disallowed characters, ask your proxy administrator to create a dedicated proxy account for the eBPF agent that uses a lowercase alphanumeric username and a simple password.

## Configuration precedence [#configuration-precedence]

When more than one source defines a proxy, the agent applies them in this order:

-   `otlpProxy.url` — Complete proxy URL.
-   `otlpProxy.*` — Individual proxy settings (`host`, `port`, `scheme`, `user`, `password`).

This precedence applies to both Linux host and Kubernetes deployments.

## Configure a proxy [#configure]

### For Kubernetes

For Kubernetes clusters, configure the proxy in your Helm `values.yaml` file.

Add an `otlpProxy:` block to your `values.yaml`:

```yaml
otlpProxy:
  host: "proxy.corporate.com"
  port: 8080
  scheme: "http"
  user: "myuser"
  password: "mypassword"
  url: ""
  existingSecret: ""
```

Alternatively, set `url:` to `http://[user:pass@]host:port` to provide a complete proxy URL. The agent supports only the `http` scheme.

For production deployments, store credentials in a Kubernetes secret instead of setting `user:` and `password:` inline. Create the secret with `proxy-user` and `proxy-password` keys, and reference it through `existingSecret:`:

```bash
kubectl create secret generic ebpf-proxy-creds \
  --namespace newrelic \
  --from-literal=proxy-user=myuser \
  --from-literal=proxy-password=mypassword
```

Then apply the change:

```bash
helm upgrade --install nr-ebpf-agent newrelic/nr-ebpf-agent -n newrelic --values values.yaml
```

For the full list of `otlpProxy.*` parameters, see [K8s configuration parameters](https://docs.newrelic.com/docs/ebpf/k8s-installation/#config-params) on the Kubernetes installation page.

### For Linux

For Linux hosts, configure the proxy in the `newrelic-ebpf-agent.yaml` configuration file.

Add an `otlpProxy:` block to `/etc/newrelic-ebpf-agent/newrelic-ebpf-agent.yaml`:

```yaml
otlpProxy:
  host: "proxy.corporate.com"
  port: 8080
  scheme: "http"
  user: "myuser"
  password: "mypassword"
  url: ""
```

Alternatively, set `url:` to `http://[user:pass@]host:port` to provide a complete proxy URL. The agent supports only the `http` scheme.

After saving the file, restrict its permissions and restart the agent:

```bash
sudo chmod 600 /etc/newrelic-ebpf-agent/newrelic-ebpf-agent.yaml
sudo systemctl restart newrelic-ebpf-agent
```

For the full list of `otlpProxy.*` parameters, see [Configuration parameters](https://docs.newrelic.com/docs/ebpf/linux-installation/#config-params) on the Linux installation page.

## Verify your proxy configuration [#verify-config]

After you configure the proxy, validate that the agent is using it as expected.

### Check the agent log [#check-agent-log]

Check the agent log for proxy-related messages:

```bash
journalctl -u newrelic-ebpf-agent | grep -i proxy
```

Look for one of these messages:

-   `Using proxy for OTLP endpoint: <endpoint> via http://<host>:<port>` — Proxy is enabled.
-   `Proxy authentication enabled (username: <user>)` — Basic Authentication is configured.
-   `Direct connection to OTLP endpoint (no proxy configured)` — No proxy is in use.

### Test proxy connectivity [#test-connectivity]

Use `curl` to confirm that your proxy supports the `HTTP CONNECT` method and can reach the New Relic OTLP endpoint:

```bash
# Unauthenticated proxy
curl -v -x http://proxy.example.com:8080 https://otlp.nr-data.net

# Authenticated proxy
curl -v -x http://user:pass@proxy.example.com:8080 https://otlp.nr-data.net
```

A successful response includes:

```
< HTTP/1.1 200 Connection established
* Proxy replied 200 to CONNECT request
* CONNECT phase completed!
```

If the agent isn't routing through the proxy or you encounter errors, see [Troubleshoot the eBPF proxy](https://docs.newrelic.com/docs/ebpf/troubleshooting/proxy).

## Security considerations [#security]

When you route the agent through a proxy, keep the following in mind:

-   **Telemetry data stays TLS-encrypted end-to-end.** The proxy only sees an encrypted tunnel to the OTLP endpoint. It never has access to your data.
-   **Proxy credentials are sent in plaintext to the proxy** because the agent doesn't support the `https://` proxy scheme. Only use proxy authentication on a trusted network between the agent and the proxy. If you need encrypted transport between the agent and the proxy, run the proxy on `localhost` or use a VPN.
-   **The agent never writes passwords to its logs.** The username may appear in log lines such as `Proxy authentication enabled (username: <user>)` for debugging.
-   **Kubernetes deployments should use `existingSecret` instead of inline credentials** to keep proxy passwords out of your `values.yaml` file and source control.