Mirroring on a Linux machine
  • 13 Nov 2024
  • 4 Minutes to read
  • Dark
    Light
  • PDF

Mirroring on a Linux machine

  • Dark
    Light
  • PDF

Article summary

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:

Command

Description

install

Installs the binary and sets up the systemd service.

uninstall

Stops the service, removes the binary, and cleans up the configuration.

help

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

--cpu <CPU>

Restricts the CPU usage for the service. Supports values like 0.5 (half a CPU core) or 50% (50% of CPU time).

--cpu 50% or --cpu 0.5

--memory <MEM>

Limits the memory usage for the service. Supports units like M (for megabytes).

--memory 512M

--after <TARGET>

Sets a systemd After dependency for the service, specifying which service should start first.

--after network.target

--overrideconf <FILE>

Specifies a custom configuration file path for override settings.

--overrideconf /path/to/override.yaml

--gen-certs

Generates self-signed certificates for the TLS key capture server.

--gen-certs

--cn <CN>

Specifies the Common Name (CN) for self-signed certificates, with a default of traceable.mirroring.agent.

--cn agent.traceable.ai

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

agent.mirroring_agent.tls_handler.enabled

bool

Enables/disables the TLS handler.

agent.mirroring_agent.tls_handler.key_file_reader.enabled

bool

Enables the key file reader (for session keys).

agent.mirroring_agent.tls_handler.key_file_reader.file_path

string

Path to the session keys file.

agent.mirroring_agent.tls_handler.key_server.enabled

bool

Enables/disables the TLS key server.

agent.mirroring_agent.tls_handler.key_server.port

int

Port on which the TLS key server should listen.

agent.mirroring_agent.tls_handler.key_server.secure

string

Specifies whether the key server should run over TLS.

agent.mirroring_agent.tls_handler.key_server.key_file

string

Path to the TLS key file for the server.

agent.mirroring_agent.tls_handler.key_server.cert_file

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

logging.level

string

Specifies the log level. Supported values: debug, info, warn, error (default: info).

logging.log_rotation.enabled

bool

Enables/disables log rotation (default: true).

logging.log_rotation.max_size

int

Specifies the maximum log file size before rotation (default: 10MB).

logging.log_rotation.max_backups

int

Specifies the maximum number of log backups to retain (default: 5).


Was this article helpful?

What's Next