Install Graylog Collector

In Graylog 7.2, Graylog Collector has been released as a preview feature for evaluation and feedback purposes. This feature's design and behavior could change significantly in future releases. To share feedback on your experience with Graylog Collector, email feedback@graylog.com.

Graylog Collector runs as a service on each host you want to collect logs from. You generate an enrollment token in Graylog, which determines the fleet the collector joins, then install the collector on the host. This article explains how to install Graylog Collector on Linux, Windows, and macOS, and how to confirm the collector enrolled.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

  • Your Graylog cluster runs Graylog 7.2 or later with HTTPS enabled.

  • You must be a Graylog administrator.

In addition, each host where you install Graylog Collector must meet the following requirements:

  • You must have administrator access to the host, meaning sudo on Linux and macOS or administrator rights on Windows.

  • The host has at least one CPU core, 128 MB of RAM, and 128 MB of free disk space.

  • The host can reach your Graylog server URL and the ingest endpoint over HTTPS, both as outbound connections.

  • If your Graylog server uses a private certificate authority (CA) or a self-signed certificate, the CA certificate is installed in the host's system trust store.

Graylog Collector supports the following platforms.

Platform

Architecture

Versions

Red Hat Enterprise Linux (RHEL) and derivatives

amd64, arm64

8, 9, 10

Ubuntu

amd64, arm64

22.04, 24.04

Debian

amd64, arm64

12, 13

SUSE Linux Enterprise Server (SLES)

amd64, arm64

15

Amazon Linux

amd64, arm64

2023

Windows Server

amd64

2016, 2019, 2022, 2025

Windows

amd64

10, 11

macOS

Intel, Apple silicon

13.0 and later

Docker and Kubernetes are not supported deployment targets.

Initialize Collector Infrastructure

Before any collector can enroll, you must configure the ingest endpoint for your cluster in Graylog, which you need to do only once. Saving the endpoint initializes the infrastructure Graylog uses to issue collector certificates and sets the address collectors send their data to.

To initialize collector infrastructure, go to System > Collectors, then select the Settings tab:

  1. Enter the External hostname that collectors connect to, which is typically a load balancer or the Graylog server's own hostname. Graylog prefills a value from your environment, but the prefilled value is not always reachable from collector hosts, so verify the hostname before saving.

  2. Enter the External port. The default is 14401.

  3. Leave Create ingest input selected so Graylog creates the input that receives collector data. The check box appears during initial setup only.

  4. Select Confirm settings.

For the collector lifecycle settings, which govern how long Graylog keeps track of collectors that stop reporting in, see Configure Collector Settings.

Generate an Enrollment Token

A fleet can contain any number of collectors, and every collector belongs to exactly one fleet. You choose the fleet when you generate the token. Every collector enrolling with the same token joins the same fleet, so a single token can serve an entire rollout.

To generate a token, go to System > Collectors, then select the Deployment tab:

  1. Select the fleet the collectors should join.

    • To use an existing fleet, choose one from Select existing fleet.

    • To create one, select Create new fleet, enter a unique Name and an optional Description in the New Fleet dialog, then select Create fleet.

  2. Select a token type.

    • Short-lived token expires in one day. Use it when you install interactively, generating a fresh token for each rollout rather than storing one.

    • Custom token takes a name and an expiry of 24 hours, seven days, 30 days, or never. Use it for a staged rollout or for configuration management, where the same token enrolls many hosts over time.

  3. Select Generate token.

Important: Graylog displays the token value once, when you generate it, and cannot show it again. If you lose the value, generate a new token.

The token grants membership in a fleet, so treat it as a credential. As a best practice, generate a new token for each rollout rather than storing tokens. When a staged rollout or configuration management needs the same token over time, hold it in a secrets store or an automation variable rather than a plain file, and remove it from collector hosts after enrollment.

Install Graylog Collector

After you generate a token, the Install the Collector step shows a ready-to-run command for each platform. The command downloads Graylog Collector, installs it, enrolls it in the selected fleet, and starts the service.

To install with the generated command:

  1. Select the tab for the host's platform, either Linux, Windows, or macOS.

  2. Select Copy command.

  3. Run the command on the host. On Linux and macOS, run it in a terminal as a user who can use sudo. On Windows, run it in an elevated PowerShell session, because the command uses PowerShell syntax and fails in Command Prompt.

The Enrolling Hosts panel below the command listens for new collectors and lists each host as it checks in. Run the same command on as many hosts as you like, because they all enroll into the fleet the token is scoped to.

Install from a Package

Install from a package when you deploy hosts through configuration management, when endpoint protection blocks the generated command, or when a host cannot download and run a script. Select Copy token only on the Install the Collector step to take the token without the command.

Replace <version> in the commands below with the release you are installing.

  1. Download the package for your distribution and architecture from the Graylog Collector releases page.

    Distribution

    Architecture

    Package

    Debian, Ubuntu

    amd64

    graylog-collector_<version>-1_amd64.deb

    Debian, Ubuntu

    arm64

    graylog-collector_<version>-1_arm64.deb

    RHEL and derivatives

    x86_64

    graylog-collector-<version>-1.x86_64.rpm

    RHEL and derivatives

    aarch64

    graylog-collector-<version>-1.aarch64.rpm

  2. Install the package. For Debian and Ubuntu, run the following command:

    Copy 
    sudo dpkg -i graylog-collector_<version>-1_amd64.deb

    For Red Hat Enterprise Linux (RHEL) and derivatives, run the following command:

    Copy 
    sudo rpm -ivh graylog-collector-<version>-1.x86_64.rpm

    The package installs a systemd unit but does not start it.

  3. Create the enrollment configuration file with restricted permissions:

    Copy 
    sudo cp /etc/graylog/collector/enrollment.env.example /etc/graylog/collector/enrollment.env
    sudo chmod 0600 /etc/graylog/collector/enrollment.env

  4. Open /etc/graylog/collector/enrollment.env and set both values, removing the leading # from each:

    Copy 
    GLC_SERVER__AUTH__ENROLLMENT_ENDPOINT=https://graylog.example.com:9000
    GLC_SERVER__AUTH__ENROLLMENT_TOKEN=eyJhb...

    The enrollment endpoint is the URL you use to reach Graylog in a browser.

    If your Graylog server uses a self-signed certificate, also set the environment variable GLC_SERVER__AUTH__INSECURE_TLS=true.

    Warning: This setting turns off certificate verification, so the collector accepts whatever certificate the server presents. Install a trusted certificate on your Graylog server before running collectors in production.

  5. Enable and start the service:

    Copy 
    sudo systemctl enable --now graylog-collector

Hint: You can enroll before starting the service by running graylog-collector enroll --endpoint <url> --token <token>, which keeps the token out of enrollment.env entirely. The command creates the keys, obtains the certificate, and stores the connection settings. Running the command again on an enrolled host reports the existing enrollment and exits without contacting the server, and a failed enrollment returns a non-zero exit code, so the command is safe to include in a configuration management run.

Graylog Collector installs a Windows service named graylog-collector that runs as LocalSystem. The installer starts the service when installation finishes and sets it to start at boot, so no separate start step is needed.

  1. Download graylog-collector-<version>.msi from the Graylog Collector releases page.

  2. Install the package. To install interactively, run the following command:

    Copy 
    msiexec /i graylog-collector-<version>.msi

    The installer requires the enrollment endpoint and token before it continues.

    To install unattended, supply the enrollment settings as properties instead:

    Copy 
    msiexec /i graylog-collector-<version>.msi /qn ^
    ENROLLENDPOINT="https://graylog.example.com:9000" ^
    ENROLLTOKEN="<token>"

    An unattended install that omits either value still starts the service, but the service stops again because the collector cannot enroll.

    If your Graylog server uses a self-signed certificate, add ENROLLINSECURETLS=true to either command.

    Warning: This setting turns off certificate verification, so the collector accepts whatever certificate the server presents. Install a trusted certificate on your Graylog server before running collectors in production.

The installer stores the endpoint and token in the registry, so an upgrade keeps the existing enrollment settings without you supplying them again.

Graylog Collector installs a launchd system daemon labelled org.graylog.collector. One package covers both Intel and Apple silicon.

  1. Download graylog-collector-<version>-darwin-universal.pkg from the Graylog Collector releases page.

  2. Install the package, either by opening it in Finder or by running the following command:

    Copy 
    sudo installer -pkg graylog-collector-<version>-darwin-universal.pkg -target /

  3. Create /Library/Application Support/Graylog/Collector/supervisor.yaml with your enrollment settings:

    Copy 
    server:
      auth:
        enrollment_endpoint: https://graylog.example.com:9000
        enrollment_token: eyJhb...

    If your Graylog server uses a self-signed certificate, also add insecure_tls: true under auth.

    Warning: This setting turns off certificate verification, so the collector accepts whatever certificate the server presents. Install a trusted certificate on your Graylog server before running collectors in production.

  4. Restrict access to the file:

    Copy 
    sudo chown root:wheel "/Library/Application Support/Graylog/Collector/supervisor.yaml"
    sudo chmod 0600 "/Library/Application Support/Graylog/Collector/supervisor.yaml"

  5. Restart the daemon:

    Copy 
    sudo launchctl kickstart -k system/org.graylog.collector

The installer starts the daemon immediately. Until the configuration file exists, the daemon starts, fails to enroll, and is restarted by launchd. That behavior is expected and stops after you complete step 3.

Hint: You can enroll before starting the daemon by running graylog-collector enroll --endpoint <url> --token <token>, which keeps the token out of supervisor.yaml entirely. The command creates the keys, obtains the certificate, and stores the connection settings. Running the command again on an enrolled host reports the existing enrollment and exits without contacting the server, and a failed enrollment returns a non-zero exit code, so the command is safe to include in a configuration management run.

Verify the Installation

While the Deployment tab is open, the Enrolling Hosts panel lists each host as it checks in. Select View setup on a host's row to follow its progress through enrollment, connection, configuration, and first messages.

The first three stages complete within seconds. First Messages stays at "Listening…" until log data reaches Graylog, and is the only stage that confirms the data channel works.

Important: A new fleet has no sources, so a collector can enroll, connect, and receive its configuration while collecting nothing. If First Messages does not resolve, confirm the fleet has at least one source. See Manage Collector Fleets.

The setup panel also shows the collector's operating system, version, fleet, and when it was last seen. Select Open in search to view the messages it has sent, or Configure sources to add sources to its fleet.

To check a collector later, go to System > Collectors, then select the Instances tab. The collector appears with its hostname, operating system, version, and a status of Online.

To check the service on the host, use the command for your platform.

Run the following command on Linux:

Copy 
sudo systemctl status graylog-collector

Run the following command on Windows:

Copy 
Get-Service graylog-collector

Run the following command on macOS:

Copy 
sudo launchctl print system/org.graylog.collector

Troubleshooting and Common Issues

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

Install Stops on an Untrusted Certificate

If your Graylog server presents a certificate the host does not trust, the generated command stops before installing anything and reports that you must rerun it with a flag that skips certificate verification. The flag is --skip-tls-verify on Linux and macOS and -SkipTlsVerify on Windows.

The better fix is to install the CA certificate in the host's system trust store, which leaves verification intact. Use the flag when the server has a self-signed certificate and you need the collector running now. Typically, the untrusted certificate option is used in test environments or for evaluation purposes and should not be used in production environments.

Windows Install Command Fails

Command Prompt reports & was unexpected at this time. The Windows command is PowerShell, not a Command Prompt command, so running it in cmd.exe fails before anything is downloaded. Open PowerShell as an administrator and run the command there.

Windows Security Blocks the Install

The generated Windows command downloads and launches an installer from a script, which endpoint protection policies on managed hosts frequently block. Windows Security reports that your administrator blocked the action. Install from the .msi package instead, either interactively or through your existing software distribution.

Collector Does Not Appear in Graylog

Confirm the service is running, then read the collector log on the host, where enrollment failures are recorded.

Platform

Collector log

Linux

/var/lib/graylog-collector/logs/supervisor.log

Windows

C:\ProgramData\Graylog\Collector\logs\supervisor.log

macOS

/Library/Application Support/Graylog/Collector/logs/supervisor.log

The common causes are as follows.

Cause

What to check

Wrong enrollment endpoint

The endpoint is the URL you use to reach Graylog in a browser. Copy it from the Deploy sub-tab rather than composing it by hand. Pointing it at the REST API path, .../api, fails.

Expired or deleted token

Check the token on the Enrollment tokens sub-tab and generate a new one if needed.

Untrusted server certificate

If Graylog uses a private CA or a self-signed certificate, install the CA certificate in the host's system trust store, or skip certificate verification as described under Install Stops on an Untrusted Certificate.

Enrollment settings not applied

On Linux, confirm the values in /etc/graylog/collector/enrollment.env are uncommented and that you restarted the service after editing.

Server unreachable

Confirm the host can reach the Graylog server URL over HTTPS.

To test enrollment on its own without starting the collector, run the following command on the collector host:

Copy 
graylog-collector enroll --endpoint https://graylog.example.com:9000 --token <token>

The command reports the reason if enrollment fails.

Further Reading

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