Warning: This article covers installation steps for Windows operating systems only. If you are setting up Sidecar on Linux, please refer to our guide on Linux 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

Install the Sidecar Service in Windows

The Windows installer can be run interactively:

Copy 
$ graylog_sidecar_installer_1.5.0-1.exe

Complete the following steps in the Windows Sidecar installer:

  1. Name your Sidecar instance.
  2. Enter your server API token.
  3. Click Install to close the installer.

Once finished, you can change or configure the sidecar.yml file, which should be located in C:\\Program Files\\Graylog\\sidecar\\sidecar.yml. Most configuration parameters come with built-in defaults. The only parameters that need adjustment are server_url and server_api_token.

Alternatively, you can run the installer in silent mode:

Copy 
$ graylog_sidecar_installer_1.5.0-1.exe /S -SERVERURL=http://your Graylog IP address or DNS name/api -APITOKEN=yourapitoken

Note that the Windows installer supports additional options in silent mode, such as:

Copy 
-TAGS=["example","IIS"], -NODENAME=mynodename, -NODEID=1234, -SENDSTATUS=false,-TLSSKIPVERIFY=true, -UPDATEINTERVAL=10s.

Activate Sidecar as a System Service

Now, open a command prompt using administrator rights. Run the following commands (and prefix the commands with & if you are using PowerShell):

Copy 
"C:\Program Files\graylog\sidecar\graylog-sidecar.exe" -service install
"C:\Program Files\graylog\sidecar\graylog-sidecar.exe" -service start
            

Add a Winlogbeat Collector Configuration

Follow the steps below to add a Winlogbeat collector configuration to your Sidecar in order to ingest Windows event logs. If you would like to add a different collector, proceed to Install Sidecar Collectors.

  1. Navigate back to Graylog and locate your Windows device under System > Sidecars.
  2. Select the winlogbeat collector, which is under the Windows Sidecar machine on the left.
  3. Select the windows_sidecar configuration (which you had set up earlier). This can be found under the Configure drop-down menu on the right-hand side.

  4. Click the Process drop-down menu on the right-hand side and choose a configuration.

  5. Click Start.

Your Graylog instance will now start collecting logs from your Windows machine. Now you can proceed to Getting Started with Graylog Sidecar for details on how to use your Sidecar collector(s).

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.