Forwarder Configuration Settings Reference

Graylog Forwarder uses a central configuration file to define how it connects to Graylog, manages message transport, and handles local buffering and control-plane behavior. The Forwarder configuration file is located by default at /etc/graylog/forwarder/forwarder.conf. The settings described in this article help administrators customize Forwarder behavior to fit a wide range of deployment environments.

General Properties

These properties define the base directory that Graylog Forwarder uses for local state, including files, sockets, and other runtime artifacts. Correct sizing and placement of this directory is important for performance and reliability.

Parameter	Default Value	Description
`data_dir`	`yes`	Required. Specifies the directory where the Forwarder stores its local files, sockets, and internal state. Ensure that this directory has sufficient disk capacity and reliable I/O performance.

API Access and Control Properties

These properties enable and secure the local Forwarder API. This API can be used for debugging, health checks, and automation workflows that interact directly with the Forwarder process.

Parameter	Default Value	Description
`forwarder_api_enabled`	`false`	Enables the local REST API endpoint for the Forwarder. When enabled, the API can be used for debugging, health monitoring, and automation against the Forwarder process.
`forwarder_api_socket_path`	`<data>/forwarder-api.sock`	Defines the path of the UNIX domain socket used by the Forwarder API. Adjust this path if you need to relocate the socket for security or operational reasons.
`forwarder_api_tcp_bind_address`	None	Specifies the IP address and port on which the Forwarder API listens over TCP (for example, `127.0.0.1:9001`). Configure this value only if you need TCP access to the API.
`forwarder_api_socket_permissions`	`rw-------`	Controls the file system permissions applied to the Forwarder API UNIX socket. This setting restricts which local users or processes can communicate with the API (by default, only the owner is allowed).

Communication and TLS Properties

These properties configure how the Forwarder communicates with Graylog over gRPC, including whether transport encryption is used and how the Forwarder authenticates to Graylog.

Parameter	Default Value	Description
`forwarder_grpc_enable_tls`	`true`	Enables TLS encryption for log transport between the Forwarder and Graylog. This should remain enabled in almost all environments and typically is disabled only in non-production test scenarios.
`forwarder_grpc_tls_trust_chain_cert_file`	None	(Optional). Specifies the path to a trust-chain certificate file used to validate the Graylog Server TLS certificate. Configure this when using a private certificate authority or self-signed certificates.
`forwarder_grpc_api_token`	None	Required. Defines the API token used by the Forwarder to authenticate against Graylog over gRPC. This token is required and must be created in the Graylog web interface and copied into this configuration.

Message Transfer Properties

These properties control the ports, batch sizes, and timeouts used when the Forwarder sends log messages to Graylog. They are the primary tuning levers for throughput, latency, and resilience during message delivery.

Parameter	Default Value	Description
`forwarder_message_transmission_port`	`13301`	Specifies the port used by the Forwarder to send log messages to Graylog. Do not reuse existing input ports (for example, `514`) for this purpose.
`forwarder_grpc_message_batch_size`	`100KB`	Defines the approximate batch size threshold at which accumulated log messages are sent to Graylog. Reducing this value can improve delivery latency at the cost of increased overhead.
`forwarder_grpc_max_message_size`	`4MB`	Specifies the maximum allowed size of a single message sent over gRPC. Messages larger than this limit are dropped. Increase this value if your environment produces large structured events such as big JSON payloads.
`forwarder_grpc_message_flush_interval`	`1s`	Defines the maximum time the Forwarder waits before sending a batch of log messages, even if the batch size threshold has not been reached. Lower values can reduce end-to-end latency.
`forwarder_grpc_call_timeout`	`60s`	Sets the timeout for gRPC send calls to Graylog. Lowering this value causes calls to fail faster during network or service issues, which can help reactive monitoring.
`forwarder_grpc_message_sending_thread_pool_size`	`5`	Specifies the number of worker threads used for sending batches of messages in parallel. Increase this value to support high-throughput environments, taking into account available CPU resources.

Configuration and Heartbeat Properties

These properties control how the Forwarder receives configuration updates from Graylog and how frequently it reports its state and heartbeat information back to the server.

Parameter	Default Value	Description
`forwarder_configuration_port`	`13302`	Defines the port on which the Forwarder receives configuration updates from Graylog.
`forwarder_configuration_polling_interval`	`10s`	Determines how frequently the Forwarder polls Graylog for new or updated configuration. Lower values provide faster rollout of configuration changes but increase control-plane traffic.
`forwarder_state_reporting_interval`	`10s`	Specifies how often the Forwarder reports its current state and metrics back to Graylog. This helps operators monitor Forwarder health and activity.
`forwarder_heartbeat_interval`	`2s`	Defines the interval between heartbeat messages sent from the Forwarder to Graylog. In very large environments, increasing this value can reduce control-plane load.

Journal Management Properties

These properties control how long unsent messages are retained locally and how much disk space the Forwarder can use for its message journal. Tuning them helps balance reliability, retention, and disk usage.

Parameter	Default Value	Description
`message_journal_max_age`	`12h`	Specifies the maximum age for unsent messages in the local journal before they are purged. Adjust this value to balance delivery resilience against local storage consumption.
`message_journal_max_size`	`5GB`	Defines the maximum disk space that the Forwarder’s message journal may consume. When this limit is reached, older entries are dropped. Increase this value for high-volume environments if sufficient disk capacity is available.