- 13 Nov 2024
- 4 Minutes to read
- Print
- DarkLight
- PDF
Mirroring on a Linux machine
- Updated on 13 Nov 2024
- 4 Minutes to read
- Print
- DarkLight
- PDF
Traceable’s Mirroring Agent for Linux is a lightweight, high-performance tool designed to capture network traffic for analysis. This topic provides detailed instructions on installing and configuring the Mirroring Agent using the install.sh
script. The topic covers various installation options, including non-TLS and TLS traffic capture, advanced memory management, filtering, and proxy settings. Additionally, this document walks you through configuring the agent for different deployment environments, explaining how to use optional parameters to tailor the installation for specific use cases.
The Mirroring Agent supports both encrypted (TLS) and non-encrypted (non-TLS) traffic capture, allowing flexible configurations through YAML files and command-line options.
Before you begin
Before proceeding, ensure the following:
You have
sudo
privileges on the Linux machine.The Traceable Mirroring Agent package is available. You can download it from Traceable’s download site.
Make sure that the Traceable Platform agent is installed. For more information on installing the Platform agent using a script, see the Installation using script topic.
Installation
Complete the following steps to install the mirroring agent:
If you have not already downloaded the mirroring package, download it by using the following command:
wget https://downloads.traceable.ai/agent/mirroring-agent/linux/latest/traceable-mirroring-linux-amd64.tar.gz
For example, the above command downloads the AMD64 version of the mirroring agent.
Extract the package:
tar xvzf traceable-mirroring-linux-amd64.tar.gz cd traffic-mirroring/
Install the agent and set up the
systemd
service:sudo ./install.sh install
The installation script install.sh
offers several modes to help set up, remove, or obtain help for the installation:
Command | Description |
---|---|
| Installs the binary and sets up the |
| Stops the service, removes the binary, and cleans up the configuration. |
| Displays help with available commands and options. |
Example usage for ./install.sh help
:
Usage: ./install.sh {install|uninstall|help} [OPTIONS]
Commands:
install Install the binary and set up the service.
uninstall Stop the service, remove the binary, and clean up the service configuration.
help Display this help message.
Installation Options
The install.sh
script provides advanced options to fine-tune the agent’s performance and behavior.
Command Structure
./install.sh install [--cpu CPU] [--memory MEM] [--after TARGET]
[--overrideconf FILE] [--gen-certs] [--cn CN]
Option Breakdown
Option | Description | Example Usage |
---|---|---|
| Restricts the CPU usage for the service. Supports values like |
|
| Limits the memory usage for the service. Supports units like |
|
| Sets a systemd After dependency for the service, specifying which service should start first. |
|
| Specifies a custom configuration file path for override settings. |
|
| Generates self-signed certificates for the TLS key capture server. |
|
| Specifies the Common Name (CN) for self-signed certificates, with a default of |
|
Example Commands
Basic Installation:
sudo ./install.sh install
Installs and starts the service with default settings.
Installation with CPU, Memory Limits, and System Dependency:
sudo ./install.sh install --cpu 50% --memory 512M --after network.target
Limits CPU and memory usage, and specifies that the service should start after
network.target
.Installation with Override Configuration and TLS Certificates:
sudo ./install.sh install --gen-certs --cn agent.traceable.ai --overrideconf /home/ubuntu/override.yaml
Sets up the service, generates self-signed TLS certificates with the specified CN, applies overrides from the specified YAML file, and starts the service.
Uninstall:
sudo ./install.sh uninstall
Stops and removes the service and its configuration.
Help:
sudo ./install.sh help
Displays help information for available commands and options.
TLS Configuration
TLS configurations allow for secure traffic capture, with options for both file-based key readers and a key server.
The script allows self-signed certificates to be generated in the certs
folder, relative to the extracted tar. You can use the following command and YAML override configuration to capture TLS traffic:
sudo ./install.sh install --gen-certs --cn agent.traceable.ai --overrideconf ~/override.yaml
Sample YAML Configuration for TLS with Key Server
packet_capture:
interface: <interface>
bpf_filter: <filter>
agent:
mirroring_agent:
tls_handler:
enabled: true
key_server:
enabled: true
port: 8001
secure: true
key_file: ./certs/domain.key
cert_file: ./certs/domain.crt
mirror_handler:
processing_delay_ms: 1000
export_handler:
go_agent_config:
service_name: <myservice>
secure: false
ca_cert_file: ""
reporting:
endpoint: <reporting_endpoint>
filter_config:
remote_config:
endpoint: <remote_endpoint>
In this configuration:
interface
: Specifies the network interface to capture traffic from (e.g.,eth0
).bpf_filter
: The BPF filter to capture specific traffic (e.g., TCP on port 80).tls_handler
: This block handles TLS traffic decryption with the key server enabled and using self-signed certificates.export_handler
: This section exports the captured traffic data using a configured service name, reporting endpoint, and remote configuration.reporting_enpoint
: The Traceable Platform address.remote_endpoint
: IP address or hostname of the Traceable Platform agent.
TLS configuration
Configuration | Type | Description |
---|---|---|
| bool | Enables/disables the TLS handler. |
| bool | Enables the key file reader (for session keys). |
| string | Path to the session keys file. |
| bool | Enables/disables the TLS key server. |
| int | Port on which the TLS key server should listen. |
| string | Specifies whether the key server should run over TLS. |
| string | Path to the TLS key file for the server. |
| string | Path to the TLS certificate file for the server. |
Non-TLS Configuration Example
Here’s a sample configuration for non-TLS traffic capture:
packet_capture:
interface: <interface>
bpf_filter: <filter>
agent:
mirroring_agent:
export_handler:
go_agent_config:
service_name: <myservice>
secure: false
ca_cert_file: ""
reporting:
endpoint: <reporting_endpoint>
filter_config:
remote_config:
endpoint: <remote_endpoint>
In this configuration:
interface
: The network interface to capture traffic from (e.g.,eth0
).bpf_filter
: The BPF filter to capture specific traffic (e.g., TCP traffic on port 80).secure: false
: Specifies that TLS is disabled for this configuration.reporting_enpoint
: The Traceable Platform address.remote_endpoint
: IP address or hostname of the Traceable Platform agent.
Logging Configuration
The Mirroring Agent supports advanced logging options, including log rotation, log levels, and specifying error output paths.
Configuration | Type | Description |
---|---|---|
| string | Specifies the log level. Supported values: |
| bool | Enables/disables log rotation (default: |
| int | Specifies the maximum log file size before rotation (default: 10MB). |
| int | Specifies the maximum number of log backups to retain (default: 5). |