Access logging to a syslog server in the RFC 5424 format of 2009 instead of the BSD format of RFC 3164 that nginx speaks.
nginx logs to syslog in the old format only: a priority, a month, a day, a clock without a year, a hostname and a tag. RFC 5424 adds what a current collector expects, a version, an RFC 3339 timestamp with time zone, an explicit process id, a message id and structured data.
http {
server {
location / {
syslog5424 syslog:server=10.0.0.5:514,facility=local1,severity=notice,tag=shop
msgid=access
'sd=[request@32473 status="$status" bytes="$body_bytes_sent"]'
'message=$remote_addr "$request" $http_referer';
}
location /health {
syslog5424 off;
}
}
}A line on the wire then reads
<141>1 2026-10-19T20:17:38+00:00 shopfront shop 19079 access [request@32473 status="200" bytes="612"] 192.0.2.7 "GET / HTTP/1.1" -
syntax: syslog5424 syslog:server=<address>[,facility=][,severity=][,tag=][,nohostname] [msgid=<value>] [sd=<value>] message=<value>
syntax: syslog5424 off
context: http, server, location, if in location
The first parameter is the destination and is parsed by nginx itself, so
server=, facility=, severity=, tag= and nohostname mean what they
mean in access_log and error_log. The tag becomes the RFC 5424
APP-NAME, and nohostname sends the NIL value in place of the hostname.
msgid=, sd= and message= take variables. message= is required,
msgid= and sd= default to the NIL value -. A hostname, tag or msgid
that is not printable ASCII without spaces, or longer than RFC 5424 allows
for that field (255, 48 and 32 octets), is replaced by -, since a value
containing a space would shift every field behind it.
Several targets may be configured in one place; each is sent its own
datagram. syslog5424 off silences the targets inherited from an enclosing
block; a block that names a target of its own is not silenced by an off
further out, and off next to a target in the same block is a configuration
error.
A parameter whose value contains a space has to be quoted as a whole, the
way nginx quotes: 'message=$remote_addr $status', not
message='$remote_addr $status'.
Client bytes. A variable carries whatever the client sent, so the value
of a variable is escaped and the text around it is not. In sd= the module
knows which is which: the element, its brackets, names and quotes are taken
as written, and every variable inside it is escaped the way RFC 5424 section
6.3.3 asks for, " as \", ] as \] and \ as \\. Control
characters are written as \xHH in both sd= and message=, so a line
feed from a request cannot end the record and have the bytes behind it read
as a second, forged entry.
Length. A line is cut at 2048 bytes, the size RFC 5424 section 6.1 asks a receiver to accept. Structured data that does not fit is sent as the NIL value rather than cut in half; a message is cut at the end.
- No TCP (RFC 6587) and no TLS (RFC 5425) transport. The socket is nginx's own syslog code, which speaks UDP and unix datagram sockets.
- No UTF-8 byte order mark in front of the message.
- No
error_login the new format: the error log belongs to nginx and is out of reach of a module.
On FreeBSD, syslogd starts with -s by default and binds no UDP socket,
so a destination on the local machine needs syslogd_flags without it, or
a collector that listens itself.
./configure --add-module=/path/to/nginx-syslog5424-moduleor as a loadable module
./configure --add-dynamic-module=/path/to/nginx-syslog5424-modulewith load_module modules/ngx_http_syslog5424_module.so; in the main
context.
ci/build.sh 1.30.5 /tmp/nginx-test
TEST_NGINX_BINARY=/tmp/nginx-test/sbin/nginx prove -r t/
ci/syslog.sh /tmp/nginx-test/sbin/nginx
ci/reload.sh /tmp/nginx-test/sbin/nginxci/syslog.sh binds a UDP port, drives a few requests through nginx and
matches every field of every datagram against the grammar.
BSD 2-Clause, see LICENSE.