Mirroring on a Linux machine

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:

1. 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.

2. Extract the package:

   tar xvzf traceable-mirroring-linux-amd64.tar.gz
   cd traffic-mirroring/

3. 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:

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

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

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.