s6: the s6-socklog program
Keywords: s6 syslog syslogd log logging daemon root utilities socket unix inet udp datagram protocol

s6
Software
skarnet.org

# 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.