--- title: Install New Relic eBPF agent for Linux hosts source: https://docs.newrelic.com/docs/ebpf/linux-installation --- You can install the New Relic eBPF agent on your Linux host to monitor your entire system health. The eBPF agent provides deep visibility into application performance without requiring code changes or deploying language-specific agents. ## Install the New Relic eBPF agent [#install-linux] ### Before you begin [#requirements] You must meet the prerequisites outlined in the [eBPF compatibility and requirements](https://docs.newrelic.com/docs/ebpf/requirements#linux) documentation for Linux hosts. ### Install the eBPF agent [#install] To install the eBPF agent: 1. Log in to your New Relic account. 2. Go to **[left navigation pane > + Integration & Agents > eBPF Agent](https://onenr.io/0oR8XWW36RG)**. 3. On the Select an account screen, select the account you want to install the eBPF agent on, and click **Continue**. 4. On the Select an installation method page, select **On a host**, and click **Continue**. 5. On the Enter your user key screen, select one of the following options, then click **Continue**: - **Use an existing key**: If you already have a user key, provide the user key. For more information, refer to [User keys](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key). - **Create a new key**: If you don't have a user key, click **Create a new key** to create one. 6. On the Configure the host integration screen, enter the deployment name for host, then click **Continue**. 7. On the Install the agent screen, run the provided command in your terminal to install the eBPF agent via Debian package. 1. Copy and paste the displayed command to install the eBPF agent on your Debian host. 2. To verify the installation, run the following command: ```bash sudo systemctl status newrelic-ebpf-agent ``` Upon successful installation, the status of these services display as active (running). > #### 💡 TIP > > You can customize the eBPF agent configuration by editing the `newrelic-ebpf-agent.yaml` file available at `/etc/newrelic-ebpf-agent/newrelic-ebpf-agent.yaml`. For more information on the configuration parameters, refer to [Configuration parameters](#config-params). > #### ⚠️ IMPORTANT > > On `yum`-based hosts, this installation command overwrites `/etc/yum.repos.d/newrelic-infra.repo` so that it points to a preview yum channel used to fetch the `newrelic-ebpf-agent` package. This replaces the `baseurl` that the infrastructure agent's own repository file normally uses, and affects RHEL-family hosts (RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux) as well as Amazon Linux (2, 2022, and 2023). > > If you also manage the [infrastructure agent](https://docs.newrelic.com/docs/infrastructure/infrastructure-agent/linux-installation/package-manager-install) or on-host integrations (for example `nri-elasticsearch`) through this same repository file, `yum check-update` may stop showing new versions for them after installing or upgrading the eBPF agent, because the preview channel carries a smaller, different package set. > > To restore the standard update path for the infrastructure agent and its integrations, re-run the repository setup command for your OS from [Add the infrastructure agent repository](https://docs.newrelic.com/docs/infrastructure/infrastructure-agent/linux-installation/package-manager-install#centos-rhel-repository) (RHEL-family) or [Amazon Linux](https://docs.newrelic.com/docs/infrastructure/infrastructure-agent/linux-installation/package-manager-install#amazon-linux-repository), then refresh the yum cache: > > ````bash > sudo yum clean all > sudo yum -q makecache -y --disablerepo='*' --enablerepo='newrelic-infra' > ``` > > This doesn't affect Debian or Ubuntu hosts, where the eBPF agent is installed from a `.deb` package outside of the infrastructure agent's `apt` source list. > > > ```` ### Access the eBPF data in New Relic [#access-data] Once the eBPF agent is installed, it automatically starts collecting data from your Linux host. You can access this data in New Relic's OpenTelemetry UI. For more information on New Relic OpenTelemetry UI, refer [OpenTelemetry APM UI](https://docs.newrelic.com/docs/opentelemetry/get-started/apm-monitoring/opentelemetry-apm-ui). **To view the eBPF data in New Relic:** 1. Go to **[one.newrelic.com](https://one.newrelic.com) > APM & Services**. 2. In the search banner, set the search criteria as `instrumentation.name = nr_ebpf`: ![eBPF filter for eBPF data in New Relic OpenTelemetry UI](https://docs.newrelic.com/images/ebpf_filters.webp "eBPF filters") ## Upgrade the eBPF agent [#upgrade] To upgrade the eBPF agent on a Linux host, re-execute the installation command from the New Relic UI. This process will install the new agent version while automatically removing the older one. > #### ⚠️ IMPORTANT > > Upgrading through a package manager is not supported. You must use the installation command from the New Relic UI for a successful upgrade. > #### ⚠️ IMPORTANT > > On `yum`-based hosts (RHEL-family and Amazon Linux), re-running the installation command also overwrites `/etc/yum.repos.d/newrelic-infra.repo` again. If you rely on that file to keep the infrastructure agent or its on-host integrations updated via `yum`, repeat the [repository restore steps](#install) after each eBPF agent upgrade. To get the latest installation command: 1. Go to **[one.newrelic.com](https://one.newrelic.com) > + Integration & Agents > eBPF Agent**. 2. Follow the installation flow to get the updated command. 3. Run the command on your host to upgrade the agent. 4. Restart the ebpf agent service using the below command: ```bash sudo systemctl restart newrelic-ebpf-agent ``` ## Configuration parameters [#config-params] The [`newrelic-ebpf-agent.yaml`](https://github.com/newrelic/newrelic-ebpf-agent/blob/main/newrelic-ebpf-agent.yaml) file contains the following configuration parameters: > #### 💡 TIP > > The eBPF agent automatically generates entity names differently depending on the environment: > > - In hosts or Docker, these names are a combination of the process name, its directory or container ID, and the listening port. For example, `ruby:/home/ubuntu/app:[5678]` or `java:f4aead533895:[8080]`. > > - In Kubernetes, these names are derived from the service name for example, `mysql-database-service`. > > Assigning custom name to applications: > > - You can assign a custom name to your application by setting the `NEW_RELIC_APP_NAME` environment variable for both Kubernetes and on-host applications. **General configuration** These parameters control the core identity and data destination for the eBPF agent. | Parameter name | Description | Data type | Example value | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------ | | `licenseKey` | Specifies your New Relic license key, which is required to send data. | String | `"22387565c...FFFFNRAL"` | | `deploymentName` | Specifies a unique name for your deployment to help identify its data in New Relic. | String | `"my-deployment"` | | `region` | If using a customSecretLicenseKey, you must supply your region `"US"`/`"EU"`/`"JP"`/`"GOV"`. Otherwise, leave this value as an empty string. | String | `""` | | `customOtlpEndpoint` | Custom OTLP endpoint URL. When set, this takes precedence over the region-based static endpoints. | String | `""` | | `customOtlpEndpointTlsEnabled` | Whether TLS is enabled on the custom OTLP endpoint. Only applicable when `customOtlpEndpoint` is set. | Boolean | `true` | | `customOtlpEndpointTlsCertPath` | Path to custom CA certificates for OTLP endpoint TLS validation. If empty, system default CA certificates are used. | String | `""` | | `otlpProxy.host` | HTTP/HTTPS proxy hostname for routing OTLP telemetry data through a corporate proxy. If empty, no proxy is used. | String | `"proxy.example.com"` | | `otlpProxy.port` | Proxy port for the OTLP proxy. | Integer | `""` | | `otlpProxy.scheme` | Proxy URL scheme. Accepted values: `http`, `https`. | String | `"http"` | | `otlpProxy.user` | Username for proxy Basic Authentication. If empty, no authentication is used. | String | `""` | | `otlpProxy.password` | Password for proxy Basic Authentication. Only used together with `otlpProxy.user`. | String | `""` | | `otlpProxy.url` | Complete proxy URL. When set, this overrides the individual `otlpProxy.host`, `port`, `scheme`, `user`, and `password` settings. Format: `http://[user:pass@]host:port`. | String | `""` | | `logLevel` | Sets the agent's log level. Options are `OFF`, `FATAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` in increasing order of verbosity. | String | `"INFO"` | | `logFilePath` | Specifies the file path for agent logs. If empty or the path is invalid, logs are sent to standard output (stdout). | String | `"/var/log/newrelic-ebpf-agent"` | | `reportApmData` | Controls APM data reporting. Accepted values: `"true"` (always send), `"false"` (never send), `"auto"` (send only when neither APM nor OTel agent is attached). | String | `"auto"` | | `reportNetworkMetrics` | Controls network metrics reporting. When enabled, the agent collects and reports network metrics including TCP statistics. Accepted values: `"true"` (always send), `"false"` (never send), `"auto"`. | String | `"auto"` | | `reportLogs` | Controls application log reporting. Accepted values: `"true"` (always send), `"false"` (never send), `"auto"` (send unless the attached APM agent is actively collecting logs itself, or an OTel agent is attached at all). See [Automatic detection and backoff](https://docs.newrelic.com/docs/ebpf/logs/#automatic-backoff) for details. | String | `"false"` | | `agentMetadataReporting` | Enables agent and entity metadata reporting. By default, the agent exports agent and entity metadata to New Relic over HTTP. Set this to `false` to disable the metadata reporting HTTP export path entirely. | Boolean | `true` | | `ai_monitoring.enabled` | Controls GenAI telemetry reporting. Accepted values: `"true"` (always send), `"false"` (never send), `"auto"` (send only when no language APM or OTel agent is already reporting AI monitoring data for the entity). | String | `"false"` | | `ai_monitoring.samplingLatency` | Defines the latency-based sampling threshold for exporting GenAI spans. Supports values from `p0` to `p99`. | String | `"p50"` | | `ai_monitoring.samplingErrorRate` | Defines the error-rate threshold for a GenAI route where surpassing it means the corresponding spans of the route are exported. Options: `1`-`100`. | String | `""` | | `ai_monitoring.genAICaptureMessageContent` | When `true`, captures full prompt and completion content for GenAI interactions. Only takes effect when `ai_monitoring.enabled` is `true` or `auto`. Use with caution. | Boolean | `false` | | `httpPathNormalizationPatterns` | Defines HTTP path normalization patterns. Each pattern must contain at least one `*` wildcard. Use a `!` prefix for exclusion patterns to preserve paths as is (skip auto-clustering). The agent applies these patterns before auto-clustering, and they take precedence over it. | List | `["/api/users/*", "/api/orders/*", "!/health/*"]` | | `httpBodyLimitBytes` | Sets the maximum number of bytes captured from an HTTP request/response body. Default: `1048576` (1 MB) when `ai_monitoring.enabled` is `true` or `auto`, otherwise `1024` (1 KB). Increase this value if New Relic truncates AI monitoring payloads. | Integer | `2097152` | | `includePortInServerEntityIdentification` | The configuration allows you to include or exclude ports from auto-discovered entity names. Typically, names appear as `processName:cwd/container_name:[port]`, e.g., `python:frosty_merkle:[80]`. To exclude port details, set this option to `false` for names such as `python:frosty_merkle`. | Boolean | `true` | | `entityLabels` | Custom labels to be added to all entities reported by the eBPF agent. These labels appear as `tags.*` attributes in New Relic (e.g., `tags.environment`, `tags.datacenter`). | Map | `{datacenter: "us-east-1", environment: "production"}` | | `downloadedPackagedHeadersPath` | Sets the absolute path of the complete directory where the required linux headers are manually downloaded and placed for the eBPF agent to use. This is useful under restricted environments where agent is not able to download required linux headers. The required headers are identified by the agent based on the kernel version. Use only after NR support recommendation. | String | `""` | | `distroKernelHeadersPath` | Sets the absolute path of the complete directory where the linux headers are present for the eBPF agent to use. This is useful where required linux headers could not be installed or path could not be determined. Use only after NR support recommendation. | String | `""` | > #### ⚠️ IMPORTANT > > The eBPF agent supports HTTP CONNECT proxies using the `http://` scheme only. Due to gRPC limitations, the `https://` scheme (a TLS-encrypted connection directly to the proxy) isn't supported. 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. For full setup instructions, see [Configure a proxy for the eBPF agent](https://docs.newrelic.com/docs/ebpf/proxy-configuration). **All data filters** Configure filters to drop all types of data (network metrics and APM data) based on provided configuration. | Parameter name | Description | Data type | Example value | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------- | | `allDataFilters.dropServiceNameRegex` | Regular expression pattern to match entity names for dropping ALL data (network metrics + APM data). For example: `"java-app|otel-collector|\\bservice1\\b"`. Use either dropServiceNameRegex or keepServiceNameRegex to filter service names, not both. If both are provided, keepServiceNameRegex takes precedence. | String | `""` | | `allDataFilters.keepServiceNameRegex` | Regular expression pattern to match entity names to always keep ALL data for. This bypasses all drop filters. For example: `"critical-service|important-app|\\bmust-monitor\\b"`. Use either dropServiceNameRegex or keepServiceNameRegex to filter service names, not both. If both are provided, keepServiceNameRegex takes precedence. | String | `""` | | `allDataFilters.dropApmAgentEnabledEntity` | Drop all data for applications/entities that have NewRelic/OpenTelemetry APM agents running. | Boolean | `false` | **APM data filters** Configure filters to drop eBPF APM data based on provided configuration. | Parameter name | Description | Data type | Example value | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------- | | `apmDataFilters.dropEntityName` | List of entity names for dropping eBPF APM data. For example: `["kube-dns", "otel-collector", "service1"]`. | List | `[]` | | `apmDataFilters.keepEntityName` | List of entity names to always keep eBPF APM data. By default all entities are kept/enabled. This bypasses `apmDataFilters.dropEntityName` filter. For example: `["critical-service", "important-app"]`. | List | `[]` | | `apmDataFilters.jvmMetricsReporting` | Enable JVM metrics reporting. When enabled, the agent collects and reports JVM metrics for Java applications. | Boolean | `true` | **Network metrics data filters** Configure filters to drop/keep network metrics data based on provided configuration. | Parameter name | Description | Data type | Example value | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------- | | `networkMetricsDataFilter.dropEntityName` | List of entity names for dropping network metrics data. For example: `["kube-dns", "otel-collector", "service1"]`. | List | `[]` | | `networkMetricsDataFilter.keepEntityName` | List of entity names to always keep network metrics data. By default all entities are kept/enabled. This bypasses `networkMetricsDataFilter.dropEntityName` filter. For example: `["critical-service", "important-app"]`. | List | `[]` | **Log data filters** Configure filters to control the application logs the eBPF agent collects and reports. These settings only take effect when `reportLogs` is set to `"true"` or `"auto"`. | Parameter name | Description | Data type | Example value | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------- | | `logDataFilters.applicationLogReporting.enabled` | Enables log collection from entities matching the filters below. | Boolean | `true` | | `logDataFilters.applicationLogReporting.fileRegex` | Regular expression to match log file names to include. | String | `".*.log$"` | | `logDataFilters.applicationLogReporting.logLevelThreshold` | Minimum log level to report (for example, `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`). | String | `"INFO"` | | `logDataFilters.applicationLogReporting.maxSamplesPerMinute` | Maximum number of log samples to collect per minute from an entity. Once this limit is reached, events are sampled to maintain an even distribution across the harvest cycle. | Integer | `10000` | | `logDataFilters.applicationLogReporting.keepStdStreamEntityRegex` | Regular expression to match entity names to keep logs from STDOUT and STDERR. Use `.*` to forward logs for all entities. | String | `".*"` | | `logDataFilters.applicationLogReporting.keepFileEntityRegex` | Regular expression to match entity names to keep logs from log files. Use `.*` to forward logs for all entities. | String | `".*"` | **Protocol tracing configuration** This section allows you to enable monitoring for specific network protocols and configure how trace data (spans) is collected. You can enable or disable monitoring for protocols like HTTP, MySQL, and others, and set parameters for span collection based on latency or error rates. The following protocols are supported: - HTTP - Thrift - MySQL - MariaDB - Aurora MySQL - PostgreSQL - MongoDB - Apache Cassandra - Redis - DynamoDB - MSSQL - Kafka - AMQP - DNS MySQL protocol tracing (`protocols.mysql`) also covers MariaDB and Aurora MySQL, as both engines use the same wire protocol as MySQL. Configuration doesn't require a separate `mariadb` or `aurora_mysql` section; enabling or disabling `protocols.mysql` controls tracing for all supported engines. The agent automatically detects the specific database flavor per connection during the server handshake and reports it on each record. You can't configure this detection manually. | Parameter name | Description | Data type | Example value | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------- | | `protocols.global.max_unlinked_spans` | Controls maximum unlinked spans reported per protocol. Set to 0 to disable limit. Unlinked spans are spans that the eBPF agent captures but cannot associate with its parent. | Integer | `100` | | `protocols.global.unlinked_spans_error_quota_percentage` | Reserves a configurable percentage of the unlinked span quota for error spans, ensuring error visibility even when normal spans arrive first. | Integer | `30` | | `protocols..enabled` | If `true`, enables monitoring for the specified protocol (for example, `http`, `mysql`, and any others). | Boolean | `true` | | `protocols..spans.enabled` | If `true`, exports trace spans for the enabled protocol. | Boolean | `true` | | `protocols..spans.samplingLatency` | Defines the latency-based sampling threshold for exporting spans. Supports values from `p0` to `p99`. | String | `"p50"` | | `protocols..spans.samplingErrorRate` | For HTTP and Thrift only. Exports spans from any route where the error rate exceeds the specified percentage (1-100). | String | `""` | ## Uninstall the eBPF agent [#uninstall] To uninstall the eBPF agent from a Linux host, use your system's package management tools: ```bash sudo apt-get purge newrelic-ebpf-agent ``` > #### 💡 TIP > > It is not necessary to stop the service before running the uninstall command. [eBPF Kubernetes installation](https://docs.newrelic.com/docs/ebpf/k8s-installation/) Learn how to set up the New Relic eBPF agent for your Kubernetes cluster. [Troubleshooting eBPF](https://docs.newrelic.com/docs/ebpf/troubleshooting/no-ui-data/) Learn how to troubleshoot issues with the New Relic eBPF agent. [eBPF best practices](https://docs.newrelic.com/docs/ebpf/best-practices/) Learn about best practices for using the New Relic eBPF agent.