Contents x
Traffic mirroring for VM
  • 21 Mar 2023
  • 8 Minutes to read
  • PDF
Contents

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

-i | --interface INTERFACE  

Yes

Interface ID for the mirrored traffic.

-s | --service SERVICE

Yes

Service name for the mirrored traffic.

-e | --environment ENVIRONMENT

Yes

Environment name for the mirrored traffic.

-r | --remote-endpoint ENDPOINT

No

Remote endpoint for Traceable Platform Agent.

-f | --filter-option FILTER 

No

Custom filter option for mirroring.

-t | --token

No

Prompt for Traceable token for authentication. Check token for more details.

--no-download

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

--enable-tls-capture

Yes

Capture traffic encrypted with TLS/SSL.

--run-non-tls-server

No

Run Traceable without TLS. By default, Traceable server uses TLS encryption.

--server-port PORT 

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

-s | --service SERVICE

Yes

Service name for the mirrored traffic.

-e | --environment ENVIRONMENT

Yes

Environment name for the mirrored traffic.

-r | --remote-endpoint ENDPOINT

No

Remote endpoint for Traceable Platform agent.

-P | --pids PROCESSES

No

Comma-separated list of PIDs that you wish to track.

-S | --ssl-dirs DIRECTORIES 

No

Comma-separated list of SSL directories. 

-E | --exclude-processes PROCESSES

No

Comma-separated list of process names that you wish to exclude from tracking.

-R | --max-return-probes VALUE    

No

Maximum number of return probes.

-t | --token

No

Prompt for Traceable Token for authentication. Check token for more details.

--no-download

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

-s | --service SERVICE

Yes

Service name for the mirrored traffic.

--tpa-endpoint ENDPOINT

Yes

Endpoint of Traceable Platform Agent. 

-P | --pids PROCESSES

No

Comma-separated list of PIDs to be tracked.

-S | --ssl-dirs DIRECTORIES 

No

Comma-separated list of SSL directories. 

-E | --exclude-processes PROCESSES

No

Comma-separated list of process names to be excluded from tracking.

 -R | --max-return-probes VALUE   

No

Maximum number of return probes.

--exporter EXPORTER

No

eBPF span exporter. Allowed values are ZIPKIN and OTLP. The default exporter is OTLP.

--reporting-port PORT

No

Reporting endpoint port of Traceable Platform Agent.

--remote-port PORT

No

Remote endpoint port of Traceable Platform Agent.

--tls-root-cert PATH

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-download

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:
    ActionScript
    sudo ./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:
    ActionScript
    sudo ./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

-e | --environment ENVIRONMENT

Yes

Environment name for the mirrored traffic.

-s | --service SERVICE

No

Service name for the mirrored traffic.

-r | --remote-endpoint ENDPOINT

No

Remote endpoint for Traceable Platform agent. 

-t | --token

No

Prompt for Traceable token for authentication. Check token for more details.

--no-download

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

--tls-endpoint ENDPOINT

Yes

TLS Endpoint of Traceable Platform agent.

--tls-key PATH

Yes

Path to the private key for Traceable Platform agent.

--tls-cert PATH

Yes

Path to the certificate file for Traceable Platform agent.

--tls-root-cert PATH

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:
    ActionScript
    sudo ./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:

  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.

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.
Was this article helpful?
What's Next
©2023 Traceable Inc
terms of services
privacy policy
oss disclosures

Cookie consent

By entering and using this site, you consent to the use of only necessary cookies to enhance your site experience and improve our services.