How Graylog Sidecar manages Filebeat and Winlogbeat on server and Windows hosts
When many Linux and Windows hosts each have a hand-edited Filebeat or Winlogbeat configuration, every change means logging in to every machine, and nobody can say with confidence which hosts are shipping what. Graylog Sidecar addresses this by acting as a central manager for log collectors. It runs on each host, registers with Graylog using an API token, and then keeps the collectors it manages in line with the configurations you define in Graylog, including *Filebeat*, *Winlogbeat* and *Auditbeat*. The collectors themselves do not send logs through Sidecar. Each one ships data directly to a Beats input on your Graylog server, so Sidecar controls how the collector is configured and started, while the log traffic follows the input path.
That split has a practical consequence: the matching input must be running before any collector is pushed. If a Beats input on port 5044 does not exist or is stopped, Sidecar can report a healthy collector while nothing arrives in Graylog, so check the input first and confirm a test event lands before you roll out configurations to a fleet. Token design matters as much as input design. The Sidecar documentation recommends one API token per environment, such as production, staging and each business unit, so you can rotate a token for one environment without touching the others and see in your audit trail which environment a host belongs to. Confirm with your Graylog administrator how tokens are created, stored and revoked in your version, since the exact steps differ between releases.
Before you deploy, confirm that each host can reach the Graylog REST API over HTTPS on port 9000 for Sidecar, and that it can reach the Beats input port on your Graylog nodes for log shipping. Those are two separate network paths, and firewall teams often approve only one of them. Windows hosts also need the Winlogbeat binary and Sidecar service installed under an account that can read the event logs you plan to collect. Ask your security team which Windows event channels are in scope before you write the collector configuration, because that decision determines how much data the hosts send.
What each host and the Graylog side need before installing Sidecar
Sidecar, Filebeat and Winlogbeat only work when the Graylog side, the network path and the host trust settings are ready first. The cards below cover the decisions and checks to complete before any collector is installed, in the order a team usually needs them.
Graylog version and deployment
Confirm the Graylog version, MongoDB version and search backend against the current compatibility matrix before choosing a Sidecar release. Graylog 7.0 to 7.2 document support for MongoDB 7.x up to 8.2.x and OpenSearch 1.1.x up to 3.7.x, and OpenSearch 1.x use is deprecated since 7.0. Record the exact versions you run, because the Sidecar and collector versions you pick must match what your Graylog release supports.
Beats input on port 5044
Sidecar manages collectors, but Filebeat and Winlogbeat send logs directly to a Graylog input, so a Beats input must be running and listening before any host is enrolled. Port 5044 is the conventional Beats port in the Sidecar guide. Confirm the input is bound to the right interface, is started on every node that hosts it, and is reachable from the subnets where your servers sit.
REST API reachability from hosts
Every host running Sidecar must reach the Graylog REST API over HTTPS, for example on port 9000 in the Sidecar guide. Check this from the host itself, not only from your workstation, because firewall rules and load balancer listeners often differ by subnet. If Graylog runs behind a load balancer, confirm the API path is routed and that health checks do not hide a failed backend.
One API token per environment
Create a separate Graylog API token for each environment, such as production, staging and test, instead of sharing one token across all hosts. Separate tokens make rotation possible without touching every host, and they make audit entries traceable to an environment. Store each token in your secrets manager and record which hosts were enrolled with it, so a rotation can be planned.
Linux host readiness
On Linux servers, confirm the Sidecar and Filebeat packages can be installed from your approved repository, that the service account can read the log paths you plan to collect, and that outbound and inbound rules match the Beats and API ports above. Check time synchronization, since skewed clocks make log timestamps hard to correlate. Confirm package versions with the Sidecar guide before you pin them.
Windows host and certificate trust
On Windows hosts, confirm the Sidecar service and Winlogbeat can run under an account that can read the Security, System and Application event logs. If Graylog uses an internal certificate authority, install that root into the Windows trust store, because the collector will reject an untrusted HTTPS endpoint. Confirm the exact Winlogbeat and Sidecar versions with the Sidecar guide before deployment.
Installing Sidecar and deploying Filebeat or Winlogbeat from Graylog
This sequence connects each host to Graylog through a managed collector: a Beats input receives the data, per-environment tokens register Sidecar, and collector configurations pushed from Graylog start Filebeat or Winlogbeat. Each step ends with a check so the team knows the path works before rolling it out to more hosts.
Create the Beats input first
Open the Graylog web interface as an administrator, go to System, Inputs, and launch a Beats input on the node or nodes your hosts can reach. Confirm the listening port, which is 5044 in the default example, and set the input to run on a node whose address the hosts can resolve. Collectors send logs directly to this input, so it must be running before any collector starts. Done means the input shows as running in the Inputs list and the port is reachable from a test host.
Create one API token per environment
Under the administrator account's user profile, create a Graylog API token for each environment, such as production, staging and development, and name each one after its environment. Sidecar uses the token to register with the Graylog REST API, and separate tokens let you rotate or revoke one environment without touching the others, which also makes audit trails easier to read. Store each token in your secrets manager, not in configuration files in source control. Done means each token appears in the list with its own name and you have recorded which hosts will use it.
Install Sidecar and register each host
On each Linux or Windows host, install Graylog Sidecar using the package or installer your team has approved, then edit the Sidecar configuration file to point at the Graylog REST API address and the token for that host's environment. Confirm that the host can reach the API over HTTPS on the port your Graylog deployment uses, which the Graylog Sidecar guide cites as 9000 in its example. Start the Sidecar service. Done means the host appears in the Sidecars list in Graylog with a recent status update.
Define collector configurations in Graylog
In Graylog, go to System, Sidecars, and open Configurations to create a collector configuration for each collector you plan to run. For Filebeat, define the log file paths and the Beats output that targets the Beats input from step one. For Winlogbeat, define the Windows Event Log channels, such as Security, System and Application, and the same output. Keep each configuration narrow, with one collector and one purpose, so changes are easy to review. Done means each configuration saves without validation errors in the editor.
Assign configurations to Sidecars
Open the Sidecars list, select the registered hosts that should run each collector, and attach the matching configuration. Sidecar polls Graylog for its assignments and applies them without manual edits on the host. Assign to a small pilot group first, so an error in a path or port shows up on a few machines. Done means the assigned collector shows a running status for the pilot hosts in the Sidecars list.
Start the collector and confirm the collector status
Once a configuration is applied, Sidecar starts Filebeat or Winlogbeat on the host. Check the collector status in the Sidecars view and, on the host, confirm the collector process is running and has no connection errors in its own log output. If the status reports an error, check that the Beats port from step one is reachable from the host and that the input is still running. Done means the collector reports running and shows no repeated connection failures.
Verify events arrive in a stream
Create or choose a stream that routes Beats messages from the pilot hosts, then open Search for that stream over a recent time range. Generate a known event on a pilot host, such as a test log line written to a monitored file or a Windows event triggered by a test logon, and look for it in the results with the expected host and source fields. Only after this check passes should you widen the assignment to more hosts. Done means the test event appears in the stream within the search window you set.
How Linux and Windows hosts differ when using Sidecar
On Linux servers, Filebeat is the collector that Sidecar typically manages for log files. The Beats input documentation describes Filebeat as the Beat that ships log file contents to Graylog, so the collector configuration focuses on which paths to read and how to parse them. Sidecar keeps the collector running and applies configuration pushed from Graylog, but the files themselves are read by the local process.
- Log file paths: Define the files to read, such as application logs and service logs, in the collector configuration rather than assuming a default set.
- File read permissions: The collector process must be able to read each file, so confirm the account that runs it can access the target directories.
- Multiline handling: Stack traces and wrapped messages need multiline rules in the configuration before they reach Graylog as single events.
- Beats input port: Hosts send to a Beats input, which conventionally listens on port 5044, and that input must be running before the collector starts.
- Network path: The host needs a route to the Graylog REST API for registration and to the Beats input port for log delivery.
Confirm the Filebeat and Sidecar versions your distribution packages, and check the Beats input documentation for the settings your version supports.",
On Windows, Winlogbeat is the collector for Windows Event Logs, and the Beats input documentation names it alongside Filebeat for files. Winlogbeat reads event channels through Windows APIs rather than tailing text files, so the decisions shift toward which channels to subscribe to and which account runs the Sidecar service. Sidecar still registers with Graylog using the API token and pushes the collector configuration.
- Event channels: Select channels such as Security, System and Application in the configuration, and add others only where a use case needs them.
- Service account: The Sidecar and collector services need an account with rights to read the event channels, and that choice is set by your Windows security policy.
- Beats input port: Winlogbeat sends to the same Beats input type on port 5044 in the default layout, so the input must exist before rollout.
- Firewall rules: Windows Firewall or host-based policy must allow outbound traffic to the Graylog REST API and the Beats input.
- Field naming: Windows events arrive with their own field structure, so confirm the parsing and prefix settings you rely on for searches.
Confirm the Winlogbeat version, the service account model and the event channel names against your Windows build and policy before rollout.
The most common difference between the two platforms is the identity each collector runs under. A Linux collector usually reads files with a dedicated service user and file permissions, while a Windows collector runs as a service account that needs event log read rights. Both must reach the Graylog endpoints, but the way you grant access, audit it and rotate it differs. Plan these identities before the first host is enrolled.
- Dedicated identities: Give each collector its own least-privilege account rather than reusing an administrative account.
- Read rights: Grant file read on Linux and event log read on Windows, and document the group or ACL used.
- Token handling: The Sidecar registration token is separate from operating system accounts, so store it in your secrets process and rotate per environment.
- Change control: Record which account each host runs under so audits can trace collection to an identity.
- Group policy or configuration management: Enforce the account and permission settings through your existing management tooling.
Ask your security team which account model applies to your hosts and confirm the exact rights each collector needs in your environment.
Auditbeat is the third Beat named in the Sidecar context, and it is the one most often considered alongside the others for security-focused collection. The Beats input documentation covers Filebeat, Winlogbeat and Metricbeat as shipping data to Graylog, so confirm from current documentation how Auditbeat is handled in your Graylog version and whether a dedicated configuration path is available. Treat Auditbeat as an addition to the host baseline, not a replacement for Filebeat or Winlogbeat.
- Scope: Auditbeat monitors audit-relevant activity on the host, which differs from the application and event logs the other two collectors cover.
- Platform support: Confirm which operating systems and Auditbeat modules your versions support before planning Linux and Windows coverage.
- Volume: Audit data can add meaningful ingest, so size the input and retention with that in mind.
- Ownership: Decide whether the security or platform team manages the Auditbeat configuration.
- Verification: Test that audit events arrive and parse as expected before relying on them for alerts.
Confirm Auditbeat support, module availability and configuration steps with Graylog's current documentation and your host versions.
How Beats fields and Sidecar settings map to Graylog messages
This table maps each Beat (Filebeat, Winlogbeat, Auditbeat, Metricbeat) to the data it ships, the Graylog Beats input it targets and the fields you will search on. Field names vary by Beats version, Graylog version and any prefix settings you apply, so confirm them against a sample message from your own cluster before writing alerts or dashboards. The main takeaway is that Sidecar only manages the collectors, while the matching Beats input must exist before data appears.
| Collector | Data source on the host | Graylog input and search fields to confirm |
|---|---|---|
| Filebeat | Log files such as application, web server and syslog files read from disk | Beats input on port 5044. Check fields such as message, source, log file path and host metadata in a sample message |
| Winlogbeat | Windows Event Log channels such as Security, System and Application | Beats input on port 5044. Check event ID, channel, provider name and log level fields, and whether a Beats prefix is applied |
| Auditbeat | Linux audit framework, file integrity and system audit data on the host | Beats input on port 5044. Confirm module-specific field names in your Auditbeat version before building searches |
| Metricbeat | System and service metrics such as CPU, memory and service status | Beats input on port 5044. Confirm metric field naming and whether metrics suit log searches or belong in a separate tool |
| Sidecar role | Registers the host with Graylog using an API token, then installs and configures the collectors | Not a log source. Confirm the token environment label and the configuration name shown in Graylog for each host group |
| Input must exist first | Collectors send data directly to the Beats input, not through Sidecar | Start a Beats input in Graylog before deploying configurations, or events will be dropped at the connection |
| Network path | Host must reach the Graylog REST API over HTTPS 9000 and the Beats input port 5044 | Confirm both paths with your firewall rules and the ports your Graylog deployment actually uses |
| Field prefixes | Beats can add a prefix to field names, which changes how searches and content packs match | Confirm the prefix setting in each Sidecar configuration and keep it consistent across hosts |
Securing API tokens, collector configurations and host traffic
Sidecar gives every Linux and Windows host a credential to Graylog and a configuration that decides what gets collected. The four controls below cover who holds those credentials, how they are rotated, who can change collector settings, and how log traffic is protected in transit.
Scope tokens per environment
Graylog Sidecar registers each host with a Graylog API token, so a leaked token exposes every host that uses it. The Graylog Sidecar guide recommends one token per environment, for example separate tokens for production, staging and development. This keeps rotation contained and makes audit entries easier to tie to one environment. Ask your team to confirm which token each host group uses before rollout.
Rotate and audit tokens
Rotation is only practical if each token maps to a known group of hosts. Plan a rotation procedure before go-live: create the new token, update Sidecar configuration on each host, confirm registration, then revoke the old token. Review Graylog's audit and user activity records for token use to spot unexpected registrations. Confirm with your Graylog administrators how revocation affects hosts that have not yet been updated.
Protect the token on each host
The Sidecar configuration file on each host holds the token, so file permissions and ownership matter as much as the token itself. Restrict read access to the service account that runs Sidecar and to administrators. On Windows, confirm the service account and the configuration file ACL before deploying to a server fleet. Remove tokens from golden images and deployment scripts so they are not copied to other hosts.
Limit who edits collector configurations
Anyone who can edit a Sidecar collector configuration can change what a host sends and where it sends it. Restrict Graylog roles so that only designated administrators can create or modify collector configurations, and separate that right from general search access. Review configuration changes as part of your normal change process, and check that a change to a Beats input or log path is traceable to a ticket. Confirm how your Graylog version records configuration history.
Encrypt host-to-Graylog traffic
Hosts send logs to Beats inputs such as port 5044 and reach the Graylog REST API on HTTPS port 9000 for Sidecar registration. Enable TLS on the Beats input and use HTTPS for the API so tokens and log content are not sent in clear text across the network. Confirm certificate trust on each host, including Windows hosts that use a different certificate store, and plan renewal before certificates expire. Keep the network path limited to the ports each host actually needs.
Why Sidecar hosts register but no logs reach Graylog
This table lists the failures that most often leave a host registered in Graylog Sidecar with no log data arriving. Each row gives the likely cause and the check to run, so you can work from the Graylog side first and then the host. Start with the input and the token, since those are the most common causes.
| Failure | Likely cause | Check to run |
|---|---|---|
| Input not running | The matching Beats input was not started before the collectors began sending, so Sidecar deployed Filebeat or Winlogbeat into a port with no listener. | In Graylog, open System, Inputs and confirm the Beats input is in the running state on the expected port, then restart the collector on the host. |
| Blocked port 5044 | A host firewall, cloud security group or network ACL between the host and the Graylog input blocks the Beats port. | From the host, test a TCP connection to the Graylog node on port 5044 and review firewall rules on both ends. |
| Blocked REST API port | Sidecar cannot reach the Graylog REST API (for example HTTPS 9000), so it cannot fetch configuration or report status, even though it shows as registered earlier. | Confirm the host can reach the API address from the Sidecar configuration, and check the Sidecar service log for timeouts or certificate errors. |
| Wrong or rotated token | The Sidecar configuration holds a token that was rotated, revoked or copied from a different environment. | Compare the token in the Sidecar configuration with the one in Graylog for that environment, and confirm it matches the environment the host belongs to. |
| Collector configuration not assigned | The host is registered, but no Filebeat, Winlogbeat or Auditbeat configuration is attached to it in Graylog, so nothing is started. | In Graylog's Sidecar view, open the host and confirm a collector configuration is assigned and its status is running, not pending or stopped. |
| File permission gaps on Linux | The Filebeat process runs under a service account that cannot read the log files, or cannot traverse their parent directories. | Run the file read as the Filebeat service user, for example with a test read of a log path, and check the Filebeat log for permission denied errors. |
| Windows event channel access | The Winlogbeat service account lacks rights to read the Security or other event channels, or the channel name in the configuration is misspelled. | Check the Winlogbeat log for access errors, confirm the service account's event log permissions, and verify channel names match those shown in Event Viewer. |
Questions teams ask before rolling Sidecar out
What drives the effort of a Sidecar rollout?
The effort follows the number of hosts, the mix of operating systems, the number of log sources per host and how strict your change control is. Each host needs the Sidecar agent, a collector such as Filebeat or Winlogbeat, and a configuration that matches a running Beats input in Graylog. Linux and Windows hosts follow different install and service paths, so a mixed fleet takes more planning than a single OS. Change control adds time because each new collector configuration usually needs review, testing on a sample host and a rollback plan. Ask any partner to size the work from a written inventory of hosts, OS versions, log sources and approval steps, not from a host count alone.
Can our own team deploy Sidecar without outside help?
Yes, if you have people who already run Linux and Windows fleet tooling, know your log sources and can administer Graylog. The work is mostly repeatable: install Sidecar, install the collector, register the host with a token and apply a configuration. The harder parts are planning the inputs, deciding which log types to collect, handling Windows audit policy and testing that events parse correctly. Many teams do a pilot with their own staff, then ask for help on the template design and the change process. Graylog Open is licensed under SSPL-1.0, which is not an OSI-approved open source license, and it is free to use, but support is community based. Confirm your internal skills and support expectations before deciding.
What access does the rollout need from our team?
Expect to provide four kinds of access. First, network paths from each host to the Graylog REST API, commonly on HTTPS port 9000, and from each host to the Beats input port, commonly 5044, on your network. Second, a Graylog administrator account that can create inputs, API tokens and Sidecar configurations. Third, administrative access on each host so the Sidecar service and collector can be installed and run. Fourth, change approval for the hosts and log sources in scope. Confirm the exact ports with your network team, because your firewalls, proxies and segmentation may differ from the defaults shown in Graylog's guide.
How does one API token per environment affect rotation?
Graylog's guidance is to use one Sidecar API token per environment, such as production, staging and a lab, so that each group of hosts can be rotated or revoked without touching the others. A token is tied to the hosts that register with it, so rotating a production token means updating every production host to use the new value, which should be planned as a change window. Keeping tokens separate also makes audit trails easier to read. Store tokens in your secrets tooling rather than in shared scripts, and record which hosts use which token so a rotation does not leave systems unable to report.
Can Sidecar scale with configuration templates?
Sidecar configurations are created in Graylog and pushed to hosts, so a small set of templates can cover many hosts that share the same role, such as web servers or domain controllers. The practical limit is design: templates work well when hosts with the same role share the same log paths, collector settings and input. Hosts with unusual paths or extra sources need their own configuration. Plan naming, ownership and review for each template before scaling, and test every template on a sample host first. Ask whether your Graylog version and collector versions support the template features you plan to use, since the Sidecar guide and Graylog's documentation for your release define what is available.
Does Enterprise licensing apply to Filebeat and Winlogbeat?
No. The Beats inputs used with Sidecar, Filebeat, Winlogbeat and Auditbeat, do not require a Graylog Enterprise or Security license, so they work on Graylog Open. Graylog Open is licensed under SSPL-1.0, which is not an OSI-approved open source license, so review that license with your legal team before deploying it in your environment. Some other Graylog inputs, such as cloud audit connectors, do require Enterprise licensing. Confirm the license needs for each input in your current Graylog documentation before you commit to a source list.
What breaks most often during a Sidecar rollout?
The most common problems are sequencing and network issues. Sidecar manages collectors, but the collectors send logs directly to a Graylog input, so a matching Beats input must be running before a host is configured. Blocked ports between hosts and Graylog, wrong tokens and configurations that point to paths that do not exist on a host are also frequent. On Windows, logs may be missing because audit policy is not enabled, so verify that events are generated before you blame the pipeline. Test each configuration on one host, confirm messages appear in the expected stream, and keep a rollback path for every change.
How DeployOpen scopes and delivers Sidecar rollouts
DeployOpen plans Graylog Sidecar with Filebeat and Winlogbeat as a fixed-scope piece of work inside your own infrastructure, starting with the host inventory, network paths and token model. We build and test the Beats inputs, collector configurations and Windows and Linux host packages against your environment, then hand over documented runbooks your team can operate.
How we scope
- Inventory Linux and Windows hosts, their log sources and the collectors each needs
- Map network paths from each host to the Graylog REST API and Beats input ports
- Agree one API token per environment and the rotation and audit process for it
- Confirm the Graylog version, Sidecar release and Beats versions in writing before build
How we build
- Create Beats inputs and confirm they run before any collector configuration is pushed
- Write Sidecar collector configurations for Filebeat, Winlogbeat and Auditbeat per host group
- Package Sidecar installation for Linux and Windows using your existing deployment tooling
- Test log arrival, parsing and stream routing on representative hosts before wider rollout
How we hand over
- Deliver the written configuration set, input definitions and host group mapping
- Document token rotation, collector upgrade steps and firewall rules for each environment
- Run a handover session with the engineers who will manage Sidecar day to day
- Provide a rollback procedure for collector configurations pushed from Graylog
How we support
- Offer ongoing support, collector upgrades and testing as a retainer after handover
- Review collector configuration changes and network path changes before they reach production hosts
- Keep the rollout documentation current as your Graylog and Beats versions change
- Scope any further work, such as Windows Security content or new inputs, as a separate written engagement
