Configure a Proxy for the New Relic eBPF Agent

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.

How proxy support 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

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

Credential character limitations

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

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

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

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

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

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

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

Verify your proxy configuration

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

Check the agent log

Check the agent log for proxy-related messages:

$
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

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

$
# 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.

Security considerations

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.