--- title: "Mirroring on a Linux machine" slug: "mirroring-on-a-linux-machine" updated: 2024-11-13T04:29:30Z published: 2024-11-13T04:29:30Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://downloads.traceable.ai/#agent/mirroring-agent/linux/latest/) 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](/docs/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: ```plaintext 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: ```plaintext tar xvzf traceable-mirroring-linux-amd64.tar.gz cd traffic-mirroring/ ``` 3. Install the agent and set up the `systemd` service: ```plaintext 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`: ```plaintext 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 ```plaintext ./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**: ```plaintext sudo ./install.sh install ``` Installs and starts the service with default settings. - **Installation with CPU, Memory Limits, and System Dependency**: ```plaintext 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**: ```plaintext 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**: ```plaintext sudo ./install.sh uninstall ``` Stops and removes the service and its configuration. - **Help**: ```plaintext 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: ```plaintext sudo ./install.sh install --gen-certs --cn agent.traceable.ai --overrideconf ~/override.yaml ``` #### Sample YAML Configuration for TLS with Key Server ```yaml packet_capture:  interface:  bpf_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:        secure: false        ca_cert_file: ""        reporting:          endpoint:        filter_config:          remote_config:            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: ```yaml packet_capture:  interface:  bpf_filter: agent:  mirroring_agent:    export_handler:      go_agent_config:        service_name:        secure: false        ca_cert_file: ""        reporting:          endpoint:        filter_config:          remote_config:            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). |