Warning: This article covers installation steps for Linux operating systems only. If you are setting up Sidecar on Windows, please refer to our guide on Windows Sidecar Installation.

In order to install Graylog Sidecar, there are a few preparatory steps that should be taken both in Graylog and on the host machine. Please note the following guide describes a self-managed Graylog Sidecar configuration. For information on using Sidecar in Graylog Cloud, please see Sidecar in the Cloud.

Installation Steps in Graylog

Prerequisites

Before installing Sidecar, make sure that you have a Beats input in order to receive data from the Beats collector, and configure your input to receive Sidecar logs on port 5044.

  1. Navigate to System > Inputs.
  2. Select Beats as the input.
  3. Click Launch new input to prompt a new form.
  4. Check the Global box if you would like to receive the data set among other nodes.
  5. Make sure that the port field is set to 5044.

Create an API Token

  1. Navigate to System > Sidecars.
  2. Click on Create or reuse a token for the graylog-Sidecar user.
  3. Enter a name into the Token Name field.
  4. Click on Create Token.

Hint: Save the API server token in a safe yet accessible location in case you need to retrieve it.

Download Sidecar

You can find .deb and .rpm packages in our package repository. Please follow the version matrix to select the correct package and download it from our GitHub page.

Sidecar Version Graylog Server Version
1.5.x 5.2.x or higher

1.4.x

5.0.x or higher
1.3.x 5.0.x
1.2.x 3.2.5 or higher
1.1.x 3.2.5 or higher

Installation Steps on the Host Machine

Select your method of installation based upon your chosen operating system.

Hint: All of the following commands in this section should be executed in the remote machine from where you want to collect log data.

1. Install the Graylog Sidecar repository configuration and Graylog Sidecar itself with the following commands:

Copy 
wget https://packages.graylog2.org/repo/packages/graylog-sidecar-repository_1-5_all.deb
sudo dpkg -i graylog-sidecar-repository_1-5_all.deb
sudo apt-get update
sudo apt-get install graylog-sidecar

2. Edit the configuration file and activate Sidecar as a system service. Please note that most configuration parameters come with built-in defaults. The only parameters whose values need to be configured manually are server_url and server_api_token.

Copy 
sudo vi /etc/graylog/sidecar/sidecar.yml

sudo graylog-sidecar -service install

# Ubuntu 14.04 with Upstart
sudo start graylog-sidecar

# Ubuntu 16.04 and later with systemd
sudo systemctl enable graylog-sidecar
sudo systemctl start graylog-sidecar

1. Install the Graylog Sidecar repository configuration and Graylog Sidecar itself with the following commands:

Copy 
sudo rpm -Uvh https://packages.graylog2.org/repo/packages/graylog-sidecar-repository-1-5.noarch.rpm
sudo yum install graylog-sidecar
            

2. Edit the configuration and activate sidecar as a system service. Please note that most configuration parameters come with built-in defaults. The only parameters whose values need to be configured manually are server_url and server_api_token.

Copy 
vi /etc/graylog/sidecar/sidecar.yml

sudo graylog-sidecar -service install

sudo systemctl enable graylog-sidecar
sudo systemctl start graylog-sidecar        

1. Install the Graylog Sidecar repository configuration and Graylog Sidecar itself with the following commands:

Copy 
sudo rpm -Uvh https://packages.graylog2.org/repo/packages/graylog-sidecar-repository-1-5.noarch.rpm
sudo mv /etc/yum.repos.d/* /etc/zypp/repos.d/
sudo zypper up
sudo zypper install graylog-sidecar
Continue? y
Do you want to reject the key, or trust always? [r/a/?] (r): a

2. Edit the configuration and activate the sidecar as a system service. Please note that most configuration parameters come with built-in defaults. The only parameters whose values need to be configured manually are server_url and server_api_token.

Copy 
sudo vi /etc/graylog/sidecar/sidecar.yml
sudo graylog-sidecar -service install

sudo systemctl enable graylog-sidecar
sudo systemctl start graylog-sidecar

Now that your Sidecar installation is complete, we recommend you proceed to Install Sidecar Collectors.

sidecar.yml Configuration Reference

Below is a list of parameters used in the sidecar.yml configuration file for your reference:

Parameter

Description

server_url

URL to the Graylog API, e.g.: https://192.168.1.1:9000/api/
server_api_token

The API token to use to authenticate against the Graylog server API.
e.g. 1jq26cssvc6rj4qac4bt9oeeh0p4vt5u5kal9jocl1g9mdi4og3n
The token is mandatory and needs to be configured.
node_id

The node ID of the sidecar. This can be a path to a file or an ID string.
Example file path: file:/etc/graylog/sidecar/node-id
Example ID string:6033137e-d56b-47fc-9762-cd699c11a5a9
Every sidecar instance needs a unique ID!
Default: file:/etc/graylog/sidecar/node-id
node_name

Name of the Sidecar instance, will also show up in the web interface.
The host name will be used if not set.
update_interval

The interval where the sidecar will fetch new configurations from the Graylog server in seconds
Default:10

The Graylog server considers all sidecars that frequently perform these updates "active". In order to globally configure a threshold which determines when a sidecar should be considered "inactive," please navigate to "Sidecars System" under the System/Configuration menu.
tls_skip_verify

This configures if the sidecar should skip the verification of TLS connections. Default: false
send_status

This controls the transmission of detailed sidecar information like collector status,
metrics and log file lists. It can be disabled to reduce load on the Graylog server if needed.
Default:true
list_log_files

Send a directory listing to Graylog and display it on the host status page,
e.g. /var/log. This can also be a list of directories. Default:[]
cache_path

The directory where the sidecar stores internal data. Default: /var/cache/graylog-sidecar

collector_configuration_directory

The directory where the sidecar generates configurations for collectors.
Default: /var/lib/graylog-sidecar/generated

log_path

The directory where the sidecar stores its logs. Default:/var/log/graylog-sidecar

log_rotate_max_file_size

The maximum size of the log file before it gets rotated. Default: 10MiB

log_rotate_keep_files

The maximum number of old log files to retain.

collector_binaries_accesslist

A list of binaries that are allowed to be executed by the Sidecar.
An empty list disables the access list feature.
Default: /usr/bin/filebeat,/usr/bin/packetbeat,/usr/bin/metricbeat,/usr/bin/heartbeat,
/usr/bin/auditbeat,/usr/bin/journalbeat,/usr/share/filebeat/bin/filebeat,
/usr/share/packetbeat/bin/packetbeat,/usr/share/metricbeat/bin/metricbeat,
/usr/share/heartbeat/bin/heartbeat,/usr/share/auditbeat/bin/auditbeat,
/usr/share/journalbeat/bin/journalbeat,/usr/bin/nxlog,/opt/nxlog/bin/nxlog
tags

List of configuration tags. All configurations on the server side that match the tag list will be fetched and merged by this instance.