---
title: "Install eBPF using script"
slug: "install-ebpf-using-script"
updated: 2024-11-13T04:39:48Z
published: 2024-11-13T04:39:48Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Install eBPF using script

This topic guides you through the process of installing eBPF on a virtual machine using the Traceable Platform Agent (TPA) install script. eBPF (Extended Berkeley Packet Filter) enables efficient traffic capture directly from the Linux kernel, enabling high-performance traffic monitoring with minimal overhead. This installation method is suitable for environments where kernel-level visibility is required without external traffic routing or hardware-based solutions.

The installation script offers two modes of operation for eBPF:

- **eBPF with TPA**: This mode installs eBPF and Traceable Platform agent (TPA). There is no prerequisite to having TPA previously installed. If you are starting out, this is the mode you can start with. For production deployments, ebpf-only is the preferred mode.
- **eBPF-Only**: This mode installs only ebpf on the host. This mode has a prerequisite to having a Traceable Platform agent already deployed.

This topic will walk you through setting up both modes and provide the necessary steps to customize the eBPF deployment according to your environment's specific needs.

---

## Download

To download the script, go to Traceable's [download](https://downloads.traceable.ai/) site. Navigate to **install → traffic-mirroring → linux → latest**.****Click on the `install.sh` script to download it, or enter the following command in your terminal:

```actionscript
curl -O https://downloads.traceable.ai/install/traffic-mirroring/linux/latest/install.sh
```

Provide the execute permission to the script. Enter the following command:

```actionscript
chmod +x install.sh
```

---

## Installation

The installation script is a utility that installs and configures traffic-mirroring components. It can be used as follows:

```actionscript
sudo ./install.sh Subcommand Arguments [Optional-Arguments]
```

The sub-commands for the script are:

```actionscript
mirror      Uses packet capture for data collection
ebpf        Uses eBPF for data collection
tpa-only    Install Traceable Platform Agent (TPA) only
ebpf-only   Install eBPF only
cleanup     Remove Traceable deployments
help        Prints help
```

---

## ebpf

The `ebpf `sub-command installs the Traceable Platform agent and eBPF and runs them as `systemd` services. For more details of this command (synopsis, example usages, argument descriptions), enter the following:

```actionscript
./install.sh ebpf help
```

The command has the following syntax:

```actionscript
./install.sh ebpf -e ENVIRONMENT -s SERVICE_NAME [-r REMOTE_ENDPOINT]
    [-P PORTS] [-S SSL_DIRS] [-E EXCLUDE_PROCESSES] [--mode MODE]
    [-R MAX_RETURN_PROBES] [--remote-cert-path ROOT_CA_CERT] [-t]
    [--tpa-loglevel TPA_LOGLEVEL] [--tpa-log-max-size-mb TPA_LOGSIZE] 
    [--tpa-log-max-backups TPA_LOGCOUNT] [--ebpf-loglevel EBPF_LOGLEVEL]
    [--ebpf-log-max-size-mb EBPF_LOGSIZE] [--ebpf-log-max-backups EBPF_LOGCOUNT] 
    [--no-download] [--enable-java-tls-capture] [--ebpf-max-memory EBPF_MAX_MEM]
    [--tpa-max-memory TPA_MAX_MEM] [--set-memory-accounting] 
    [--ebpf-request-per-second-limit EBPF_REQUEST_LIMIT] [--ebpf-max-connection EBPF_MAX_CONNECTION] 
    [--ebpf-go-memory-limit EBPF_GO_MEMORY_LIMIT] [--otlp-max-connection-age OTLP_MAX_CONNECTION_AGE]
    [--http-proxy HTTP_PROXY] [--https-proxy HTTPS_PROXY] [--no-proxy NO_PROXY]
    [--tpa-max-cpu TPA_MAX_CPU] [--ebpf-max-cpu EBPF_MAX_CPU]
```

The following table explains the usage of the command arguments:

| **Argument** | **Mandatory** | **Description** |
| --- | --- | --- |
| `-s SERVICE` | Yes | The service name for the mirrored traffic. |
| `-e ENVIRONMENT` | Yes | Environment name for the mirrored traffic. |
| `-r REMOTE_ENDPOINT` | No | Remote endpoint for Traceable Platform agent. |
| `-P PORTS` | No | Comma-separated list of ports that you wish to track. |
| `-S SSL_DIRS` | No | Comma-separated list of SSL directories. |
| `-E EXCLUDE_PROCESSES` | No | Comma-separated list of process names that you wish to exclude from tracking. |
| `--mode MODE` | No | Traffic type to be captured. `MODE` can take the following values: - `ingress`: capture all ingress traffic for given `PORTS`. - `egress`: capture all egress traffic for the given `PORTS`. - `ingress_and_egress`: capture all ingress as well as egress traffic for given `PORTS`. The default value is `ingress`. |
| `-R MAX_RETURN_PROBES ` | No | Maximum number of return probes. |
| `-t \| --token` | No | Prompt for Traceable Token for authentication. Check [token](/v1/docs/traffic-mirroring-for-vm#token) for more details. |
| `--remote-cert-path PATH` | No | Root CA used to sign certificate for the Traceable Platform. |
| `--tpa-loglevel TAP_LOGLEVEL` | No | Logging level for the Traceable service. The allowed values are `info`, `warn`, `error`, and `debug`. The default value is `info`. |
| `--tpa-log-max-size-mb TPA_LOGSIZE` | No | The maximum log file size in MB created by the Traceable service. The default value is 10 MB. |
| `--tpa-log-max-backups TPA_LOGCOUNT` | No | Maximum number of backup log files created by the Traceable service. The default value is 10. |
| `--ebpf-loglevel EBPF_LOGLEVEL` | No | Logging level for the eBPF service. The allowed values are `info`, `warn`, `error`, `debug` and `trace`. The default value is `info`. |
| `--ebpf-log-max-size-mb EBPF_LOGSIZE` | No | Maximum log file size in MB created by the eBPF service. The default value is 10 MB. |
| `--ebpf-log-max-backups EBPF_LOGCOUNT` | No | Maximum number of backup log files created by the eBPF service. The default value is 10. |
| `--no-download` | No | Use local packages to install Traceable and its components. For more information, see [Airgapped installation](/v1/docs/traffic-mirroring-for-vm#airgapped-installation). |
| `--enable-java-tls-capture` | No | Set it to `true`, if you wish to capture Java TLS traffic. The default value is `false`. |
| `--ebpf-max-memory EBPF_MAX_MEM` | No | Maximum memory limit for the eBPF service. Takes a memory size in bytes. If the value is suffixed with K, M, G, or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system. |
| `--tpa-max-memory TPA_MAX_MEM` | No | Maximum memory limit for the Traceable service. Takes memory size in bytes. If the value is suffixed with K, M, G, or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, you can select the value as a percentage, which is taken relative to the installed physical memory on the system. |
| `--set-memory-accounting` | No | Set MemoryAccounting to `true` for the services. This is required on VMs where `DefaultMemoryAccounting` property is not enabled. |
| `--ebpf-request-per-second-limit` | No | Sets the maximum number of requests the eBPF tracer would capture in a second. |
| `--ebpf-max-connection` | No | Sets the maximum number of connections the eBPF tracer tracks at any given time. |
| `--ebpf-go-memory-limit` | No | This is the substitute for the `GOMEMLIMIT` environment variable. The argument expects input in k8 units. The default value is 0, which translates to no limit being set. Examples: 128974848, 129e6, 129M, 128974848000m, 123Mi |
| `--otlp-max-connection-age` | No | Sets the keepalive duration for the OTLP server in the Traceable Platform agent. The duration can be expressed as a string. The acceptable units are ns, us, s, m, and h. Example: 100ms = 100 milliseconds, 120s = 120 seconds, 120m = 120 minutes, 2h = 2 hours. The default value is infinity. |
| `--http-proxy` | No | Used for setting proxy URL for HTTP requests until overwritten by` --no-proxy`. |
| `--https-proxy` | No | Used for setting proxy URL for HTTPS requests until overwritten by` --no-proxy`. |
| `--no-proxy` | No | Specifies a string that contains comma-separated values specifying hosts that should be excluded from proxying. |
| `--tpa-max-cpu TPA_MAX_CPU` | No | Sets the maximum percentage of CPU that the Traceable Platform Agent (TPA) process is allowed to use. For example, `--tpa-max-cpu 100%` would limit the TPA process to one full CPU core. Setting `--tpa-max-cpu 200%` would allow it to use up to two cores. |
| `--ebpf-max-cpu EBPF_MAX_CPU` | No | Sets the maximum CPU percentage for the eBPF process. For example, `--ebpf-max-cpu 100%` allows the process to use up to one CPU core. With `--ebpf-max-cpu 200%`, two cores can be used. |

#### ebpf examples

Following are a few examples of using the `ebpf` sub-command:

- If you wish to capture all the traffic, use the following command:

ActionScriptActionScript

```actionscript
sudo ./install.sh ebpf -e myEnvironment -s myService -t
```
- If you wish to capture traffic from a specific process or a set of processes, use the following command. In the example below, data is captured from ports 8080 and 9001.

ActionScriptActionScript

```actionscript
sudo ./install.sh ebpf -e myEnvironment -s myService -P 8080,9001 -t
```

---

## ebpf-only

The `ebpf-only` sub-command installs only the eBPF solution and runs them as `systemctl` services. For more details of this command (synopsis, example usages, argument descriptions), enter the following:

> [!NOTE]
> Note
> 
> This mode requires that Traceable Platform agent is already installed.

```actionscript
./install.sh ebpf-only help
```

The command has the following syntax:

```actionscript
./install.sh ebpf-only -s SERVICE_NAME --tpa-endpoint ENDPOINT [-P PORTS]
    [-S SSL_DIRS] [-E EXCLUDE_PROCESSES] [-R MAX_RET_PROBES] [--mode MODE]
    [--tls-root-cert ROOT_CA_CERT] [--reporting-port REPORTING_PORT]
    [--remote-port REMOTE_PORT] [--exporter EXPORTER] [--loglevel LOGLEVEL]
    [--log-max-size-mb SIZE] [--log-max-backups COUNT] 
    [--no-download] [--enable-java-tls-capture] [--max-memory MAX_MEMORY]
    [--set-memory-accounting] [--request-per-second-limit REQUEST_LIMIT] [--max-connection MAX_CONNECTION]
    [--go-memory-limit GO_MEMORY_LIMIT] [--max-cpu MAX_CPU]
```

The following table explains the usage of the command arguments:

| **Argument** | **Mandatory** | **Description** |
| --- | --- | --- |
| `-s SERVICE_NAME` | Yes | The service name for the mirrored traffic. |
| `--tpa-endpoint ENDPOINT` | Yes | Endpoint of Traceable Platform Agent. |
| `-P PORTS` | No | Comma-separated list of ports that you wish to track. |
| `-S SSL_DIRS` | No | Comma-separated list of SSL directories. |
| `-E EXCLUDE_PROCESSES` | No | Comma-separated list of process names to be excluded from tracking. |
| `-R MAX_RETURN_PROBES` | No | Maximum number of return probes. The default value is 1. |
| `--mode MODE` | No | Traffic type to be captured. `MODE` can take the following values: - `ingress`: capture all ingress traffic for given `PORTS`. - `egress`: capture all egress traffic for the given `PORTS`. - `ingress_and_egress`: capture all ingress as well as egress traffic for given `PORTS`. The default value is `ingress`. |
| `--tls-root-cert ROOT_CA_CERT` | No | Root CA used to sign certificate for Traceable Platform Agent. eBPF uses this to validate the Traceable Platform Agent's certificate. If this value is provided, eBPF uses TLS encryption for data sent to the Traceable Platform Agent. |
| `--reporting-port REPORTING_PORT` | No | Reporting endpoint port of Traceable Platform Agent. If `--tls-root-cert` is provided, the default value is `5443`. Otherwise, the default value is `4317`. |
| `--remote-port REMOTE_PORT` | No | Remote endpoint port of Traceable Platform Agent. If `--tls-root-cert` is provided, the default value is `5443`. Otherwise, the default value is `5441`. |
| `--exporter EXPORTER` | No | eBPF span exporter. Allowed values are `ZIPKIN` and `OTLP`. The default exporter is `OTLP`. |
| `--loglevel LOGLEVEL` | No | Logging level for the eBPF service. The allowed values are `info`, `warn`, `error`, `debug` and `trace`. The default value is `info`. |
| `--log-max-size-mb SIZE` | No | Maximum log file size in MB created by the eBPF service. The default value is 10 MB. |
| `--log-max-backups COUNT` | No | Maximum number of backup log files created by the eBPF service. The default value is 10. |
| `--no-download` | No | Use local packages to install Traceable and its components. For more information, see [Airgapped installation](/v1/docs/traffic-mirroring-for-vm#airgapped-installation). |
| `--enable-java-tls-capture` | No | Set it to `true`, if you wish to capture Java TLS traffic. The default value is `false`. |
| `--max-memory MAX_MEMORY` | No | Maximum memory limit for the Traceable service. Takes memory size in bytes. If the value is suffixed with K, M, G, or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, you can select the value as a percentage, which is taken relative to the installed physical memory on the system. |
| `--set-memory-accounting` | No | set MemoryAccounting to true for the eBPF service. This is required on VMs where the `DefaultMemoryAccounting` property is not enabled. |
| `--request-per-second-limit` | No | Sets the maximum number of requests the eBPF tracer would capture in a second. |
| `--max-connection` | No | Sets the maximum number of connections the eBPF tracer tracks at any given time. |
| `--go-memory-limit` | No | This is the substitute for the `GOMEMLIMIT` environment variable. The argument expects input in k8 units. The default value is 0, which translates to no limit being set. Examples: 128974848, 129e6, 129M, 128974848000m, 123Mi. |
| `--max-cpu MAX_CPU` | No | Specifies the maximum CPU percentage for the eBPF. For instance, `--max-cpu 100%` limits the process to one core and `--max-cpu 200%` would use two cores. This parameter ensures that the eBPF process doesn't exceed your set CPU limit. |

#### ebpf-only examples

Following are a few examples of using the `ebpf-only` sub-command:

- If your Traceable Platform agent is running on an IP address `10.120.0.3`, and you wish to install the eBPF solution and send the mirrored traffic to the Traceable Platform agent, use the following command:

ActionScriptActionScript

```actionscript
sudo ./install.sh ebpf-only -s myService --tpa-endpoint 10.120.0.3
```
- If your Traceable Platform agent is running with the TLS server on `10.120.0.3` and you have your root CA at `/path/to/root/ca`, then you can enable TLS encryption for the traffic sent from eBPF to the Traceable Platform agent. Enter the following command:

ActionScriptActionScript

```actionscript
sudo ./install.sh ebpf-only -s myService --tpa-endpoint 10.120.0.3 --tls-root-cert /path/to/root/ca
```

---

## eBPF with centralized Traceable Platform agent

When you use the `ebpf` subcommand for installation, the eBPF and Traceable Platform Agent are deployed on the same machine. eBPF starts capturing traffic and sends it to the agent. To streamline the forwarding process, you may run a central agent to which all devices with eBPF can send mirrored traffic. This can be accomplished in two simple steps:

1. Run the installation script with the `tpa-only` subcommand on the virtual machine (VM) where you wish to install the central agent.
2. Run the installation script with the `ebpf-only` subcommand on all other VMs hosting your services.

If you wish to ensure secure communication between the VM capturing traffic and the central agent, follow these additional steps:

1. Enable the TLS server during installation with the `tpa-only` subcommand.
2. Use the same root CA certificate for all `ebpf-only` installations.

---

## Uninstallation

Enter the following command to uninstall. Note that the install script is used for both installation and uninstallation.

```actionscript
sudo ./install.sh cleanup
```