The `s6-socklog` program

s6-socklog is a minimal syslog daemon. It reads datagrams from the /dev/log Unix domain socket, or from a Unix domain or Internet domain socket of the user's choice, converts the encoded syslog facility and priority names to their human-readable equivalents, and prints the logs to its stdout.

s6-socklog is a reimplementation of the socklog program with a few more features.

Interface

     s6-socklog [ -d notif ] [ -r ] [ -U | -u uid -g gid -G gidlist ] [ -l linelen ] [ -t lameducktimeout ] [ -x unixsocket | -i ipport ]

s6-socklog binds to /dev/log.
It drops its root privileges.
For every datagram it reads, it turns its content into a log line:
- Messages are truncated to 1024 characters
- Trailing nulls or newlines are removed
- Embedded nulls or newlines are converted to ~ characters (tildes)
- A <syslogcode> at the beginning of the line is converted to facility.priority:
It prints the log line to its stdout, terminated by a newline.
It exits 0 on a SIGTERM.

Exit codes

0: SIGTERM received, clean exit
99: SIGTERM received but the buffer could not be flushed in time, some logs may be lost
100: wrong usage
111: system call failed

Signals

s6-socklog reacts to the following signals:

SIGTERM: exit as soon as possible

Options

-r : raw logging. <syslogcode> codes will not be converted to facility/priority names.
-d notif : when ready (actually bound to its socket), write a newline to file descriptor notif then close it. This allows s6-socklog to use the s6 mechanism to notify readiness. notif cannot be less than 3. If this option is not given, no readiness notification is sent.
-u uid : drop user id to uid
-g gid : drop group id to gid
-G gidlist : set supplementary group list to gidlist, which must be given as a comma-separated list of numeric gids, without spaces.
-U : set user id, group id and supplementary group list to the values of the UID, GID and GIDLIST environment variables. If a -u, -g or -G option is given after -U, the command line value overrides the environment variable.
-l linelen : Set the maximum datagram size to linelen. Default is 1024. It cannot be set to less than 76 or more than 1048576. If a datagram is bigger than linelen, it will be truncated to linelen characters, and the logged line will end with a ... ellipsis to show the truncation.
-t lameducktimeout : on receipt of a SIGTERM, give s6-socklog a grace period of lameducktimeout milliseconds to flush any log lines that are still in its buffer. Default is 0, which means infinite: the program will only exit when its buffer is empty, and may wait forever. If lameducktimeout is nonzero and the timeout expires, the program will exit 99.
-x unixsocket : bind to a Unix domain socket at unixsocket. Default is /dev/log.
-i ipport : bind to a UDP socket. ipport is a combination of ip, which must be an IPv4 or IPv6 address, and port, which must be an integer. port may be omitted, in which case it defaults to 514. If port is given, ip and port must be separated by a _ character (an underscore). If ip is IPv4, a : (colon) can be used instead of an underscore. When this option is used, s6-socklog will prepend every log line with clientip_clientport: , clientip and clientport being the IP address and port of the client that sent the log datagram.

Typical use

s6-socklog can be paired with s6-log to implement syslogd functionality. s6-socklog acts as the frontend: it reads the log lines and processes them, then pipes them to an s6-log instance that acts as the backend, i.e. sorts the log lines depending on regular expressions that typically involve the facility and priority names, then stores them into the filesystem.

The pipe between s6-socklog and s6-log is typically a logging pipe automatically provided by s6-svscan when the s6-log instance is declared as a logger service for the s6-socklog instance.

The examples/ subdirectory of the s6 package contains a turnkey syslogd service that implements this pattern.

Notes

s6-socklog cannot be used under s6-ipcserver or another super-server. It does not implement the socklog ucspi functionality, which is provided by the ucspilogd program instead.