S6-SOCKLOG(8)

NAME
s6-socklog - minimal syslog daemon

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

DESCRIPTION
s6-socklog is a reimplementation of the socklog(8) program with a few more features.

s6-socklog 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 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.

  Signals
s6-socklog reacts to the following signals:

SIGTERM
    Exit as soon as possible.

  Typical use
s6-socklog can be paired with s6-log(8) 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(8) 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(8) is typically a logging pipe automatically provided by s6-svscan(8) when the s6-log(8) 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.

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

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-notifywhenup(7) 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 id.

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

EXIT STATUS

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.

SEE ALSO
s6-ipcserver(8), s6-log(8), s6-svscan(8), socklog(8), ucspilogd(8)

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-socklog.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)