Install Sidecar and Deploy Collectors

This guide walks you through the process of setting up Graylog Sidecar to centrally manage and monitor log collectors across your environment. You will begin by reviewing the required prerequisites, then install the Sidecar package and the collector you plan to manage. After that, you will edit the sidecar.yml file, start and register the Sidecar service, and prepare Graylog to receive and control the new agent.

Once the Sidecar is registered, the guide shows you how to create a collector configuration in the Graylog interface and deploy it to your hosts. You will also learn how to verify that the configuration was applied successfully.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

  • Your Graylog user account must be able to access System > Sidecars and generate API tokens. See Permission Management for more information.
  • Network connectivity must exist from hosts to the Graylog REST API (for example, HTTPS :9000) and any relevant input ports (for example, Beats :5044, Syslog :514, GELF :12201).
  • You must have administrative access on each target host (Linux or Windows).
  • You are familiar with your chosen collector (Filebeat, Winlogbeat, Auditbeat) and its supported operating system.

Create a Sidecar API Token

Creating a valid API token first ensures that Sidecar can register successfully with Graylog when the service starts. For full information on creating API tokens, see REST API Access Tokens. To generally create an API token for use with Sidecar:

  1. Navigate to System > Sidecars > Administration.
  2. Select Create or reuse a token for a Sidecar node.
  3. Enter a descriptive name, such as production-servers.
  4. Enter a TTL (Time-to-Live) for the token based on your organization's security policy.
  5. Copy the token securely, as it will not be displayed again.

Hint: Use one token per environment (i.e. production, staging) to simplify rotation and auditing.

Install the Sidecar Package

The Sidecar package installs the agent that manages collectors locally on each host. You will need to install it on every server or endpoint that generates logs for Graylog. 

Warning: Before installing, confirm that your Sidecar and Graylog versions are compatible, and always install the most recent version of Sidecar wherever possible. This guide assumes you are running Graylog 7.0 and installing Sidecar 1.5.1. See the Sidecar release repository for more information on Sidecar versions.

Install Sidecar on Linux

Install the package that matches your Linux distribution.

Debian or Ubuntu (DEB):

wget https://packages.graylog2.org/repo/packages/graylog-sidecar<version>.deb
sudo dpkg -i graylog-sidecar-<version>.deb
sudo apt install graylog-sidecar

RHEL, CentOS, SUSE (RPM):

Copy 
wget https://packages.graylog2.org/repo/packages/graylog-sidecar<version>.rpm
sudo rpm -i graylog-sidecar-<version>.x86_64.rpm

Install Sidecar on Windows

  1. Download the Graylog Sidecar installation (.exe or .msi) from the Graylog downloads repository and run the program as an administrator. Note the installer registers Sidecar as a Windows service that starts automatically at boot.

  2. Verify installation in the Services console by confirming that the Graylog Sidecar service is present.

Set Up an Input in Graylog

Before deploying Sidecar, you must configure at least one input in Graylog to receive the data sent by your collectors. Sidecar manages the collectors, but the collectors themselves forward logs directly to a Graylog input. If no input is configured and running, your logs will not reach Graylog even if Sidecar is functioning correctly.

Ensure that network connectivity exists from each host to both the Graylog REST API and the specific input ports you plan to use. Verify that the required input types are created, configured, and actively running in Graylog before continuing with the Sidecar setup.

Sidecar can send to any Graylog input type as long as the input matches the format and protocol used by the collector’s output. For example:

See Inputs for more information on available input types.

Install the Collector

Before Sidecar can manage any log collection on a host, the underlying collector it will control must already be installed. By default, Sidecar on Linux includes the Filebeat and Auditbeat collectors, and on Windows it includes the Filebeat and Auditbeat collectors. Sidecar is pre-configured to detect additional collectors via the collector_binaries_list value in the sidecar.yml. If you are using another collector, you can add the path to its executable in the configuration. Installing the target collector first ensures that when Sidecar starts, it can immediately detect the collector, report its status to Graylog, and receive the appropriate configuration.

Install the collector that matches your operating system and log ingestion strategy. Sidecar supports the following collectors by default. See the individual documentation for support with installing the following collectors on your host: 

Warning: After collector installation, do not start the collector manually. Sidecar starts and manages the collector after registration.

Edit Sidecar Configuration

All platforms utilize the same YAML-based configuration file for Sidecar. If you need to edit this configuration file, do so before starting or restarting the service. To open the configuration file on Linux systems, use:

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

For Windows (using PowerShell):

Copy 
notepad "C:\Program Files\Graylog\sidecar\sidecar.yml

Edit Required Configuration Settings

Sidecar requires two settings for authentication. These values must be present in sidecar.yml. For more information on configurable settings for Sidecar, see Sidecar Configuration Settings Reference.

The server_url defines the Graylog API endpoint Sidecar uses to communicate with the Graylog Server, and must include the /api/ path, as in the following example: 

Copy 
server_url: "https://your-graylog-server:9000/api/"

The server_api_token is a personal access token generated in Graylog, as noted above, and grants the Sidecar permission to authenticate and send status updates. Ensure you store this token securely, as it provides direct access to the Sidecar’s management functionality.

Copy 
server_api_token: "your-generated-token"

Edit Recommended Configuration Settings

The following fields are not strictly required, but they represent the minimum recommended settings for a functional and easily managed Sidecar deployment. These values help Sidecar identify the host, match and apply collector configurations, and connect securely.

The node_name provides a readable identifier for the host. This name appears in the Graylog interface and helps administrators recognize the system sending status updates. By default, it is set to the endpoint's short hostname. Only change this if you need to:

Copy 
node_name: "your-hostname"

The tags field assigns one or more tags, which the Sidecar uses to determine which configuration to request from Graylog. At least one tag is required for the Sidecar to map itself to the correct collector configuration. This list conforms to standard YAML list formatting:

Copy 
tags: [linux, "site A"]

Or, in a more traditional format for longer lists:

Copy 
tags:
  - linux
  - site A

To improve security, set tls_skip_verify to false (recommended). This ensures the Sidecar verifies the Graylog Server’s TLS certificate when using HTTPS:

Copy 
tls_skip_verify: false

Finally, the update_interval defines how often Sidecar polls the Graylog Server for configuration updates and status checks. If omitted, the default is 10s:

Copy 
update_interval: 10s

In general, the primary reason to change this value would be if your MongoDB instance is experiencing performance issues. This value can also be globally overridden by setting the Update Interval selection in Graylog under System > Configurations > Sidecars if the Override Sidecar Configuration box is checked.

Hint: Use HTTPS in production environments, assign clear and descriptive node names, and keep your tag sets consistent across systems to ensure predictable configuration management

Start and Register the Sidecar Service

After editing sidecar.yml, start the Sidecar service. This step applies to all platforms.

Start on Linux

Enable and start the service:

Copy 
sudo systemctl enable graylog-sidecar
sudo systemctl start graylog-sidecar
sudo systemctl status graylog-sidecar            

Sidecar logs are available at /var/log/graylog-sidecar/sidecar.log.

Start on Windows

Start the Sidecar service from the Services console or by using PowerShell:

Copy 
Start-Service graylog-sidecar
Get-Service graylog-sidecar            

Verify Registration in Graylog

When the service starts, the Sidecar attempts to register the host with Graylog. Registration succeeds only when the following conditions are met:

  • server_url is correct and includes the /api/ path.
  • The API token is valid and has not expired or been revoked.
  • Connectivity to the Graylog server is available.
  • At least one supported collector is installed on the host.
  • The service has permission to run locally.

After the initial check-in, the host appears in Graylog under Sidecar Overview. To confirm the Sidecar has been registered successfully:

  1. Navigate to System > Sidecars > Sidecar Overview.

  2. Locate the host by its configured node_name.

  3. Confirm the Last Seen value is recent.

  4. Verify the operating system, Sidecar version, and installed collectors display correctly.

  5. Ensure the tags shown in the UI match the tags defined in sidecar.yml.

Create a Collector Configuration in Graylog

A collector configuration defines which log files or event sources the collector reads and where it sends the collected data. Sidecar retrieves and applies this configuration when the tags assigned to the configuration match the tags defined on the host.

  1. Navigate to System > Sidecars > Configuration and select Create Configuration.

  2. Choose the collector type and enter the YAML content for your collector. For example, a simple Filebeat configuration would be as follows:

    Copy 
    filebeat.inputs:
    - type: log
      # value is irrelevant, just must be unique among all inputs:
      id: log
      paths:
      - /var/log/nginx/*.log
      fields:
        # Any custom fields you want:
        environment: production
        # event_source_product required for some Illuminate content packs:
        event_source_product: nginx-web

    output.beats:
    hosts: ["your-graylog-server:5044"]                    

  3. Assign the tags for the hosts that should receive this configuration, for example,
    [production,webservers].

    Hint: Plan a consistent tagging strategy before deploying Sidecar. Tags determine which hosts receive which configurations, and a clear strategy (for example, grouping by environment or role) scales cleanly across larger environments.

  4. Test the configuration on a single host to ensure the collector starts cleanly and logs begin flowing into Graylog.

  5. (Optional) Use variables to avoid repeating values such as hostnames or ports. For example,
    ${user.graylog_host}.

  6. (Optional) Use snippets to include reusable blocks of configuration content. Sidecar appends snippet content to the final rendered configuration.

Deploy and Verify Configuration

Sidecar automatically applies configurations whenever the tags on the host match the tags assigned to a configuration.

Deploy the Configuration

  1. Navigate to System > Sidecars > Configuration and open the configuration you want to deploy.

  2. Assign the tags for the hosts that should receive the configuration.

  3. Select Update Configuration. Sidecar retrieves the updated configuration during its next update_interval.

Verify the Configuration

  1. Navigate to System > Sidecars > Manage Sidecars.

  2. Select the host you deployed to.

  3. Confirm that the expected collector is running and that the applied configuration name matches the configuration you assigned.

  4. Check your Graylog input to confirm logs are arriving.

  5. Validate on one host before applying changes broadly across your environment.

Troubleshooting and Common Issues

The following section outlines troubleshooting steps for common issues to assist you in resolving potential challenges you may encounter.

Issue: Configuration Not Appearing on the Host

The Sidecar agent is running, but no configuration is being applied to the host.

Solution: Verify Tags, Collector Type, and Service Status

  1. Confirm the tags in sidecar.yml exactly match the tags assigned to the configuration in Graylog.
  2. Ensure the installed collector matches the collector type specified in the configuration.
  3. Verify that the Sidecar service is running and checking in with Graylog.

Issue: Configuration Reverts or Does Not Apply

The configuration initially appears but later disappears or reverts to none.

Solution: Check Tag Alignment and Token Validity

  1. Ensure the host’s tags match the configuration’s assigned tags without variation.
  2. Verify that the API token has not expired or been revoked.
  3. Restart the Sidecar service to force a configuration pull.

Issue: Sidecar Agent Missing or Inactive

The host does not appear in the Sidecar UI or shows as inactive.

Solution: Confirm API Connectivity and Network Access

  1. Verify that the server_url in sidecar.yml points to a reachable Graylog REST API endpoint.
  2. Test network connectivity to port 9000 and confirm DNS resolution.
  3. Check for firewall, proxy, or TLS certificate issues that may block communication.

Issue: Collector Fails to Start

The collector process is installed but does not start or immediately stops.

Solution: Validate YAML Syntax and Collector Installation

  1. Check for invalid YAML syntax, missing indentation, or use of tabs instead of spaces.
  2. Confirm that the collector binaries are installed and located in the expected paths.
  3. Review collector logs for configuration, permission, or startup errors.

Issue: No Logs Arriving in Graylog

The Sidecar and collector appear healthy, but no logs are visible in Graylog.

Solution: Verify Input Status and Output Configuration

  1. Verify that your Graylog input is active and reachable from the host.
  2. Confirm that file paths and permissions allow the collector to read the log files.
  3. Ensure the collector output references the correct destination host and port.

Issue: Logs Not Indexing in Graylog

Logs reach Graylog but do not show up in search results.

Solution: Review Stream Routing and Index Health

  1. Verify that the input writes to the correct stream.
  2. Check that pipelines or extractors are not dropping or rejecting messages.
  3. Confirm index rotation, retention, and disk space settings allow new data to be written.

Further Reading

Explore the following additional resources and recommended readings to expand your knowledge on related topics: