Installing forwarder on Linux

This document describes how to install and run Chronicle forwarder in Linux environments. You can install Chronicle forwarder on a variety of Linux distributions (Debian, Ubuntu, Red Hat, Suse, etc.). Google Cloud provides the software using a Docker container. You can run and manage the Docker container on either a physical or virtual machine running Linux.

Customize the configuration files

Based on the information you submitted prior to deployment, Google Cloud provides you with the Chronicle forwarder software and configuration files. Google Cloud taylors your configuration files to the forwarder instance on your network. If you need to alter the configuration, contact Chronicle Support.

System requirements

The following are general recommendations. For recommendations specific to your system, contact Chronicle Support.

  • RAM—1.5 GB for each collected data type. For example, endpoint detection and response (EDR), DNS, and DHCP are all separate data types. You would need 4.5 GB of RAM to collect data for all three.

  • CPU—2 CPUs are sufficient to handle less than 10,000 events per second (EPS) (total for all data types). If you expect to forward more than 10,000 EPS, provision 4 to 6 CPUs.

  • Disk—100 MB of disk space is sufficient, regardless of how much data Chronicle forwarder handles. Chronicle forwarder does not buffer to disk.

Verify the firewall configuration

If you have firewalls or authenticated proxies in between the Chronicle forwarder container and the Internet, they require rules to open access to the following hosts:

Connection Type Destination Port
TCP 443
TCP 443
TCP 443

Install Docker

You can install Docker on a variety of host operating systems. The actual installation of Docker is dependent on the host environment. Google Cloud provides limited documentation to assist you in installing Docker on several of the more popular Linux distributions. However, Docker is open source and substantial documentation is already available.

Once you have installed Docker on your system, the rest of the Chronicle forwarder installation process is identical, regardless of which Linux distribution you are using.

Check that Docker is installed on your system by executing the following command (elevated privileges):

# docker ps

The following response indicates that Docker has been installed properly:


You can gather additional information about your Docker installation using the following command:

# docker info

If you have problems with Docker, Chronicle Support might request the output from this command to help with debugging.

Install the forwarder

This section describes how to install Chronicle Fforwarder using a Docker container on a Linux system.

Step 1. Download, transfer and install the forwarder configuration files

Google Cloud provides forwarder configuration files specific to your operating system (Linux or Windows). Download the files from the link provided by your Chronicle representative to a local directory on your laptop (for example, named chronicle). After you complete the following steps, transfer the configuration files from your laptop to your forwarder ~/config directory within the user’s home directory.

  1. Connect to your Linux forwarder via terminal.

  2. Create a new user on the Linux forwarder.

    # adduser <username>

    # passwd <username>

    # usermod -aG wheel <username>

  3. Change directory to the home directory of the new user that will run Docker Container.

  4. Create a directory to store the Chronicle forwarder configuration files: # mkdir ~/config

  5. Change directory

  6. Once files have been transferred, confirm the configuration files are located in the ~/config directory:

    # ls -l

Step 2. Install the key for the Chronicle Container Registry

Google Cloud provided JSON file (the file has a .json extension) contains the credentials needed to access the Chronicle Docker registry.

  1. Copy the following command text (including the line breaks) to a text editor and rename the .json file name within brackets to your Chronicle Docker Authentication file name.

      docker login \
         -u _json_key \
         --password-stdin \
     < ./chronicle-container-c2da10b71454-oneline.json
  2. Once edit is complete, copy the full command text and run the command from within the ~/config directory on the Linux forwarder.

  3. Output of the above docker login command should be Login Succeeded.

If you run into an issue, confirm the Docker version running:

# docker version

Older versions of Docker (for example, 1.13.1) may require different command line arguments. The differences are noted below.

Step 2 for older versions of Docker that don't support --password-stdin

For older versions of Docker (versions that do not accept --password-stdin), copy the contents of your JSON file and paste them at the password prompt.

  1. Issue the following command:

    $ cat ./<filename>.json

  2. Copy the output of the cat command.

  3. Login to Docker:

    docker login -u _json_key

  4. At the Password: prompt, paste the clipboard contents.

    Regardless of how you provide the password (--password-stdin or copy and paste), the output of the docker login command should be Login Succeeded.

Step 3. Run the forwarder within the Docker container

You can use the following procedures to start Chronicle forwarder the first time as well as to upgrade to the latest version of the Chronicle container:

The --log-opt options have been available since Docker 1.13. These options limit the size of the container log files and should be used as long as your version of Docker supports them.

  1. If you are upgrading, start by cleaning up any previous Docker runs. In the following example, the name of the Docker container is cfps, then obtain the latest Docker image from Google Cloud with the # docker pull command below.

    # docker stop cfps
    # docker rm cfps
  2. Obtain the latest Docker image from Google Cloud:

    # docker pull

  3. Start Chronicle forwarder from the Docker container:

    docker run \
      --detach \
      --name cfps \
      --restart=always \
      --log-opt max-size=100m \
      --log-opt max-file=10 \
      --net=host \
      -v ~/config:/opt/chronicle/external \

These commands are also provided as a shell script called

The Docker container (and Chronicle forwarder) persist after system reboots.

Step 4. Monitor and manage the forwarder

The following Docker commands help you to monitor and manage Chronicle forwarder:

  • Check if the Docker container is running:

    docker ps

  • Display the logs from the container. Note that this can generate a substantial volume of output, but is useful for debugging:

    docker logs cfps

  • To see what is running inside the container:

    docker top cfps

  • To stop the container:

    docker stop cfps

Collect Splunk data

You can configure Chronicle forwarder to forward your Splunk data to Chronicle. Google Cloud configures Chronicle forwarder with the following information to forward your data from Splunk:

  • URL for the Splunk REST API (for example,

  • Splunk queries to generate data for each of the required data types (for example, index=dns).

You need to make your Splunk account credentials available to Chronicle forwarder.

Create a local file for your Splunk credentials and name it creds.txt. Place your username on the first line and the password on the second line:

  cat creds-file


For customers who are using Chronicle forwarder to access a Splunk instance, copy the creds.txt file to the config directory (the same directory as the configuration files). For example:

cp creds-file ~/config/creds.txt

Verify the creds.txtem> file is in its proper location:

ls ~/config

Collect syslog data

Chronicle forwarder can operate as a Syslog server, meaning you can configure any appliance or server that supports sending syslog data over a TCP or UDP connection to forward their data to Chronicle forwarder. You can control exactly what data the appliance or server sends to Chronicle forwarder. Chronicle forwarder can then forward the data to Chronicle.

The configuration file (provided by Google Cloud) specifies which ports to monitor for each type of forwarded data (for example, port 10514). By default, Chronicle forwarder accepts both TCP and UDP connections.

Configure rsyslog

To configure rsyslog, you need to specify a target for each port (for example, each data type). Consult your system documentation for the correct syntax. The following examples illustrate an rsyslog target configuration:

  • TCP log traffic: dns.* @

  • UDP log traffic: dns.* @

Enable TLS for syslog configurations

You can enable TLS for the Syslog connection to the Chronicle forwarder. In the Chronicle forwarder configuration file, specify the location of your certificate and certificate key as shown in the following example:

certificate "/opt/chronicle/external/certs/edb3ae966a7bbe1f.pem"
certificate_key "/opt/chronicle/external/certs/forwarder.key"

Based on the example shown, the Chronicle forwarder configuration would be modified as follows:

- syslog:
      enabled: true
      data_type: WINDOWS_DNS
      batch_n_seconds: 10
      batch_n_bytes: 1048576
  connection_timeout_sec: 60
  certificate: "/opt/chronicle/external/certs/edb3ae966a7bbe1f.pem"
  certificate_key: "/opt/chronicle/external/certs/forwarder.key"

You can create a certs directory under the configuration directory and store the certificate files there.

Collect packet data

Chronicle forwarder can capture packets directly from a network interface using libpcap on Linux. Packets are captured and sent to Chronicle instead of log entries. Packet capture is handled from a local interface only. To enable packet capture for your system, contact Chronicle Support.

Google Cloud configures Chronicle forwarder with the Berkeley Packet Filter (BPF) expression used when capturing packets (for example, port 53 and not localhost).

Toggle data compression

Log compression reduces network bandwidth consumption when transferring logs to Chronicle. However, compression might cause an increase in CPU usage. The tradeoff between CPU usage and bandwidth depends on many factors, including the type of log data, the compressibility of that data, the availability of CPU cycles on the host running the forwarder and the need for reducing network bandwidth consumption.

For example, text based logs compress well and can provide substantial bandwidth savings with low CPU usage. However, encrypted payloads of raw packets do not compress well and incur higher CPU usage.

Since most of the log types ingested by the forwarder are efficiently compressible, log compression is enabled by default to reduce bandwidth consumption. However, if the increased CPU usage outweighs the benefit of the bandwidth savings, you can disable compression by setting the compression field to false in the Chronicle forwarder configuration file as shown in the following example:

  compression: false
      collector_id: 10479925-878c-11e7-9421-10604b7cb5c1
      customer_id: ebdc4bb9-878b-11e7-8455-10604b7cb5c1
      secret_key: |
          "type": "service_account",

Frequently asked questions

What is a Docker container?

  • Docker containers, like virtual machines, provide additional security, isolation and resource management.

  • Virtual Machines—have both a privileged space (linux kernel) and a user space (everything you interact with: libc, python, ls, tcpdump, etc).

  • Containers—have only a user space (everything you interact with: libc, python, ls, tcpdump, etc) and relies on the host's privilege space.

Why distribute Chronicle forwarder using a container?

  • Better security through isolation:
    • Customer environment and requirements do not affect Chronicle forwarder.
    • Chronicle forwarder environment and requirements do not affect the customer.
    • Container distribution mechanism already exists and can be private and separate for Google Cloud and customers.

Why only Linux for containers? What about Windows?

  • Containers were developed for Linux first and are production ready.

  • Windows support for Containers is improving. Containers are available for Windows Server 2016 and Windows 10.

Do you need to learn advanced Docker commands?

  • Chronicle forwarder uses a single container, so there is no need to learn about Swarm, orchestration, Kubernetes, or other advanced Docker concepts or commands.