From 678508409a92f80cacd94a70e1e51ca4a389435a Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 18 Aug 2021 18:46:40 +0000 Subject: Add s6-socklog Signed-off-by: Laurent Bercot --- doc/s6-socklog.html | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 doc/s6-socklog.html (limited to 'doc/s6-socklog.html') diff --git a/doc/s6-socklog.html b/doc/s6-socklog.html new file mode 100644 index 0000000..03f8c6b --- /dev/null +++ b/doc/s6-socklog.html @@ -0,0 +1,139 @@ + + + + + + s6: the s6-socklog program + + + + + + +

+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 (tildas)
- A <syslogcode> at the beginning of the line is converted to facility.priority:
+and 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 lesser than 3. +If this option is not given, no readiness notification is sent.
-u uid : set the process' user ID to uid
-g gid : set the process' group ID to gid
-G gidlist : set the process' supplementary group list +to gidlist, which must be given as a comma-separated list of numeric GIDs, +without spaces.
-U : set the process' 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.

+ +

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