- 21 Mar 2023
- 8 Minutes to read
-
PDF
Traffic mirroring for VM
- Updated on 21 Mar 2023
- 8 Minutes to read
-
PDF
Traceable provides a script for setting up traffic-mirroring on a virtual machine. The script installs and runs two services. The first service collects and sends the mirrored traffic to the Traceable Platform agent. The second service, namely, Traceable Platform agent, sends the mirrored traffic to the Traceable Platform. Both these services run using systemctl
. You can also use the script in an airgapped environment, or to install the Traceable Platform agent.
systemctl
is a command-line utility for controlling the systemd
system and service manager on Linux operating systems. It provides several commands for managing systemd
units, which are the building blocks of a systemd-based system. systemd
is a system and service manager for Linux operating systems. It provides a standard process for controlling what programs run when a Linux system boots up. For more information on systemctl
, see How to use systemctl to manage Linux services.
Download
Traceable provides two scripts, one for installation and the other for uninstallation. To download the scripts, go to Traceable's download site. Navigate to install → traffic-mirroring → linux → latest. You can also download these scripts by entering the commands as mentioned below.
Installation script
Enter the following command:
curl -O https://downloads.traceable.ai/install/traffic-mirroring/linux/latest/install.sh
Uninstall script
Enter the following command:
curl -O https://downloads.traceable.ai/install/traffic-mirroring/linux/latest/uninstall.sh
Installation
The installation script is a utility to install and configure traffic-mirroring components. It can be used as follows:
sudo ./install.sh Subcommand Arguments [Optional-Arguments]
The sub-commands for the installation script are:
mirror
The mirror
sub-command installs the Traceable Platform agent and Suricata and runs them as systemctl
services. The service that you are mirroring traffic from can be either encrypted or unencrypted. For more information on the available command-line arguments, check help. The following is a sample usage of the mirror
sub-command with different arguments:
sudo ./install.sh mirror -i INTERFACE -e ENVIRONMENT -s SERVICE_NAME [ -r REMOTE_ENDPOINT ] [ -f FILTER_OPTION ] [ -t ] [ --no-download ] [ --enable-tls-capture [ --run-non-tls-server ] --server-port SERVER_PORT ]
The following table explains the usage of the command arguments:
Argument | Mandatory | Description |
---|---|---|
| Yes | Interface ID for the mirrored traffic. |
| Yes | Service name for the mirrored traffic. |
| Yes | Environment name for the mirrored traffic. |
| No | Remote endpoint for Traceable Platform Agent. |
| No | Custom filter option for mirroring. |
| No | Prompt for Traceable token for authentication. Check token for more details. |
| No | Use local packages to install Traceable and its components. For more information, see Airgapped installation. |
Mirroring with SSL/TLS
If your mirrored service is using SSL/TLS protocol, then in-addition use the following arguments:
Argument | Mandatory | Description |
---|---|---|
| Yes | Capture traffic encrypted with TLS/SSL. |
| No | Run Traceable without TLS. By default, Traceable server uses TLS encryption. |
| No | Port where a TCP server runs when you enable TLS capture. Master keys are sent to this TCP server in standard format. |
mirroring example
Following are a few examples of using the mirror
sub-command:
- If your service is running on eth0 interface, you can use the following command:ActionScript
sudo ./install.sh mirror -i eth0 -e myEnvironment -s myService -t
- If your service is running with TLS, you can use the following command:ActionScript
sudo ./install.sh mirror -i eth0 -e myEnvironment -s myService -t --enable-tls-capture
ebpf
The ebpf
sub-command installs the Traceable Platform agent and eBPF and runs them as systemctl
services. For more information on the available command-line arguments, check help. The following is a sample usage of the ebpf
sub-command with different arguments:
sudo ./install.sh ebpf -e ENVIRONMENT -s SERVICE_NAME [ -r REMOTE_ENDPOINT ] [ -P PIDs ] [ -S SSL_DIRS ] [ -E EXCLUDE_PROCESSES ] [ -R MAX_RET_PROBES ] [ -t ] [ --no-download ]
The following table explains the usage of the command arguments:
Argument | Mandatory | Description |
---|---|---|
| Yes | Service name for the mirrored traffic. |
| Yes | Environment name for the mirrored traffic. |
| No | Remote endpoint for Traceable Platform agent. |
| No | Comma-separated list of PIDs that you wish to track. |
| No | Comma-separated list of SSL directories. |
| No | Comma-separated list of process names that you wish to exclude from tracking. |
| No | Maximum number of return probes. |
| No | Prompt for Traceable Token for authentication. Check token for more details. |
| No | Use local packages to install Traceable and its components. For more information, see Airgapped installation. |
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: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 processes with PID (process ID) 10001 and 10010.ActionScript
sudo ./install.sh ebpf -e myEnvironment -s myService -P 10001,10010 -t
ebpf-only
The ebpf-only
sub-command installs only the eBPF solution and runs them as systemctl
services. For more information on the available command-line arguments, check help. The following is a sample usage of the ebpf-only
sub-command with different arguments:
sudo ./install.sh ebpf-only -s SERVICE_NAME --tpa-endpoint ENDPOINT [ -P PIDs ] [ -S SSL_DIRS ] [ -E EXCLUDE_PROCESSES ] [ -R MAX_RET_PROBES ] [ --tls-root-cert ROOT_CA_CERT ] [ --reporting-port REPORT_PORT ] [ --remote-port REMOTE_PORT ] [ --exporter EXPORTER ] [ --no-download ]
The following table explains the usage of the command arguments:
Argument | Mandatory | Description |
---|---|---|
| Yes | Service name for the mirrored traffic. |
| Yes | Endpoint of Traceable Platform Agent. |
| No | Comma-separated list of PIDs to be tracked. |
| No | Comma-separated list of SSL directories. |
| No | Comma-separated list of process names to be excluded from tracking. |
| No | Maximum number of return probes. |
| No | eBPF span exporter. Allowed values are |
| No | Reporting endpoint port of Traceable Platform Agent. |
| No | Remote endpoint port of Traceable Platform Agent. |
| No | Root CA used to sign certificate for Traceable Platform Agent. eBPF uses this to validate Traceable Platform Agent's certificate. If this value is provided, eBPF uses TLS encryption for data sent to the Traceable Platform agent. |
| No | Use local packages to install eBPF and its components. For more information, see Airgapped installation. |
ebpf-only examples
Following are a few examples of using the ebpf-only
sub-command:
- If your Traceable Platform agent is running on IP address
10.120.0.3
, and you wish to install eBPF solution and send the mirrored traffic to the Traceable Platform agent, use the following command:ActionScriptsudo ./install.sh ebpf-only -s myService --tpa-endpoint 10.120.0.3
- If your Traceable Platform agent is running with 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 Traceable Platform agent as well. Enter the following command:ActionScriptsudo ./install.sh ebpf-only -s myService --tpa-endpoint 10.120.0.3 --tls-root-cert /path/to/root/ca
tpa-only
The tpa-only
sub-command installs the Traceable Platform agent and runs it as a systemctl
service. For more information on the available command-line arguments, check help. The following is a sample usage of the tpa-only
sub-command with different arguments:
sudo ./install.sh tpa-only -e ENVIRONMENT [ -s SERVICE_NAME ] [ -r REMOTE_ENDPOINT ] [ -t ] [ --no-download ] [ --tls-endpoint ENDPOINT --tls-key KEY --tls-cert CERT --tls-root-cert ROOT_CA_CERT ]
The following table explains the usage of the command arguments:
Argument | Mandatory | Description |
---|---|---|
| Yes | Environment name for the mirrored traffic. |
| No | Service name for the mirrored traffic. |
| No | Remote endpoint for Traceable Platform agent. |
| No | Prompt for Traceable token for authentication. Check token for more details. |
| No | Use local packages to install eBPF and its components. For more information, see Airgapped installation. |
Traceable Platform agent with TLS
You can choose to enable TLS server on Traceable Platform agent. The following arguments enable TLS:
Argument | Mandatory | Description |
---|---|---|
| Yes | TLS Endpoint of Traceable Platform agent. |
| Yes | Path to the private key for Traceable Platform agent. |
| Yes | Path to the certificate file for Traceable Platform agent. |
| Yes | Path to the root CA file for Traceable Platform agent. |
tpa-only examples
Following are a few examples of using the tpa-only
sub-command:
- If you wish to install Traceable Platform Agent without TLS server, enter the following command:ActionScript
sudo ./install.sh tpa-only -e myEnvironment -t
- If you wish to set up a TLS server with endpoint as
0.0.0.0:5443
, enter the following command:ActionScriptsudo ./install.sh tpa-only -e myEnvironment -t --tls-endpoint 0.0.0.0:5443 --tls-key /path/to/key --tls-cert /path/to/cert --tls-root-cert /path/to/root/ca
help
The help sub-command renders the detailed description of the available command-line arguments and example usages of this script.
Uninstallation
Go to Traceable's download site and navigate to install → traffic-mirroring → linux → latest to download the uninstallation script. Run the following command:
sudo ./uninstall.sh
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 opt to run a central agent, to which all machines with eBPF can send mirrored traffic. This can be accomplished in two simple steps:
- Run the installation script with the
tpa-only
subcommand on the virtual machine (VM) where you wish to install the central agent. - 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:
- Enable the TLS server during installation with the
tpa-only
subcommand. - Use the same root CA certificate for all
ebpf-only
installations.
Airgapped installation
Traceable provides a script for setting up traffic-mirroring in an airgapped environment. An airgapped system is a computer or network that is physically isolated from the internet and other unsecured networks. This type of system is used to protect sensitive data and systems from external threats such as hackers and malware. Airgapped systems are often used in industries where data security is of the utmost importance.
For airgapped installation, Traceable provides two archives, one for amd64 machines and the other for arm64 machines. To download the archive, go to Traceable's download site. Navigate to install → traffic-mirroring → linux → latest.
Transfer the downloaded archive to your airgapped system. Untar the archive by entering the following command, for example, for an amd64 machine:
tar xvzf traffic-mirroring-amd64.tar.gz
Change directory:
cd traffic-mirroring-amd64/bin/
The following two files are part of the above directory:
install.sh
uninstall.sh
To install, run any sub-command as mentioned in the Installation section by adding the --no-download
option. This option uses the local packages from the tar file to complete the installation instead of being dependent on internet.
Token
When installing the Traceable Platform Agent, you must provide the platform token to authenticate with the platform. This can be done in multiple ways.
- Export the token as an environment variable:ActionScript
export TA_REFRESH_TOKEN=""
- Put the token in default token file:ActionScript
echo "" | sudo tee /etc/traceable/agent/token
- Provide the command-line flag
-t
or--token
and enter the token when prompted.