Graylog

SIEM Platform

Synopsis

The Graylog target forwards events, formatted as GELF, to a Graylog GELF input over TCP, TLS, UDP, or HTTP(S). It handles GELF wire framing for the chosen transport — the event payload is expected to already be a complete GELF JSON document when it reaches the target.

Schema

- name: <string>
  description: <string>
  type: graylog
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <numeric>
    protocol: <string>
    max_message_size: <numeric>
    url: <string>
    timeout: <numeric>
    tls:
      verify: <boolean>
      server_name: <string>
      ca_name: <string>
      cert_name: <string>
      key_name: <string>
      passphrase: <string>
      min_tls_version: <string>
      max_tls_version: <string>
    field_format: <string>
    debug:
      status: <boolean>
      dont_send_logs: <boolean>

Configuration

The following fields are used to define the target:

Field	Required	Default	Description
name	Y		Target name
description	N	-	Optional description
type	Y		Must be graylog
pipelines	N	-	Optional post-processor pipelines
status	N	true	Enable/disable the target

Connection

Field	Required	Default	Description
address	Y*	-	Graylog GELF input host. Required for the tcp, tls, and udp transports
port	N	12201	GELF input port. Defaults to the TLS port 12202 when protocol is tls. Valid range 1–65535
protocol	N	tcp	Transport: tcp (null-delimited) | tls | udp (chunked) | http | https
max_message_size	N	8192	UDP only: payload bytes per chunk before GELF chunking. 0 sends a single datagram. Ignored for tcp/tls/http/https
url	N*	built as scheme://address:port/gelf	http/https only: explicit endpoint override
timeout	N	30	Connection/write timeout in seconds. Bounds the stream dial and write deadline for tcp/tls/udp, and the HTTP client timeout for http/https

* = Conditionally required. address is required for tcp, tls, and udp; for http/https, either address (with port) or an explicit url must be supplied.

TLS

Field	Required	Default	Description
tls.verify	N	true	Verify the server certificate
tls.server_name	N	-	SNI / expected server hostname
tls.ca_name	N	-	Custom CA to trust. Empty uses the OS trust store
tls.cert_name	N*	-	Client certificate for mutual TLS
tls.key_name	N*	-	Client key for mutual TLS
tls.passphrase	N	-	Passphrase for an encrypted client key
tls.min_tls_version	N	tls1.2	Minimum negotiated TLS version
tls.max_tls_version	N	tls1.3	Maximum negotiated TLS version

* = Conditionally optional. tls.cert_name and tls.key_name must be supplied together to enable mutual TLS; supplying only one fails configuration validation. There is no tls.status field — TLS is engaged by setting protocol: tls or protocol: https.

note

TLS material fields (cert_name, key_name, ca_name, client_ca_name) accept any of the following:

• File name — resolved relative to the service root directory. Nested paths such as certs/prod/server.pem are supported.
• Absolute path — honored only if it resolves inside the service root. Any path that escapes the root is refused.
• Inline PEM content — used verbatim when the value contains -----BEGIN.
• Environment variable — ${ENV_VAR}.
• Vault reference — $secret{id=...} or $secret{store=...,ref=...}.

Processing

Field	Required	Default	Description
field_format	N	-	Optional target-side normalization format applied before delivery. Typically left empty, since the payload already arrives as GELF from upstream processing. See applicable Normalization section

Scheduling

See Scheduling and Pool Behavior for interval and cron fields shared by all targets.

Debug Options

Field	Required	Default	Description
debug.status	N	false	Enable debug logging
debug.dont_send_logs	N	false	Process logs but don't send to target (testing)

Details

This target is transport-only: it does not render GELF itself. It expects each event to already be a complete GELF JSON document when it reaches the target, and applies wire framing and delivery on top of that payload. There is no batching — each event is a single, complete delivery to the Graylog GELF input.

Transports

• GELF-TCP (default): the document is written null-delimited over a persistent stream.
• GELF-TLS: the same null-delimited framing, over a TLS-wrapped stream.
• GELF-UDP: the document is sent as one datagram, or split into GELF-chunked datagrams (2-byte magic 0x1e 0x0f, 8-byte message ID, sequence number, sequence count) when it exceeds max_message_size. A document that would need more than 128 chunks fails — use tcp or tls for events that large.
• GELF-HTTP(S): the document is POSTed as the request body to the GELF HTTP input.

Endpoint Resolution (HTTP/HTTPS)

An explicit url always wins. Otherwise the endpoint is built as scheme://address:port/gelf, where scheme is http or https depending on protocol.

Default Transport

Graylog defaults to plain GELF-TCP on port 12201, matching the standard Graylog GELF TCP input. Configure the corresponding GELF input type (TCP, TLS, UDP, or HTTP) on the Graylog side to match the protocol selected here.

TLS

TLS is engaged only via protocol: tls or protocol: https — there is no independent tls.status toggle. A client certificate is optional — supplying tls.cert_name without tls.key_name (or vice versa) fails configuration validation. tls.verify defaults to true.

note

The target does not perform GELF rendering or field mapping — it only frames and delivers the payload it receives. Format the event as GELF before it reaches this target.

Examples

Basic Configuration

Sending GELF events to a Graylog GELF-TCP input...

targets: - name: graylog type: graylog properties: address: "10.0.0.5" port: 12201

Chunked UDP

Delivering over GELF-UDP with chunking for events larger than the datagram size...

targets: - name: graylog-udp type: graylog properties: address: "10.0.0.5" protocol: udp max_message_size: 8192

HTTP Endpoint

Posting GELF events to an explicit HTTP input URL...

targets: - name: graylog-http type: graylog properties: protocol: http url: "http://graylog:12201/gelf" timeout: 30