s6
Software
skarnet.org

# The `ucspilogd` program

`ucspilogd` acts as a filter, converting syslog facility numbers and alert levels into names.

## Interface

         ucspilogd [ -d undef ] [ var ... ]

- ucspilogd reads a stream of syslog-like messages on stdin. Those messages can be newline-terminated or null-terminated.
- For every line it reads: if it has been given var arguments, it writes the value of every var environment variable, followed by a colon and a space.
- If the line begins with a syslog facility number and/or alert level in the syslog format, it converts them into a human-readable name in the syslogd fashion.
- It then writes the processed line to stdout.

## Options

- `-d undef` : when a variable var given on the command line is actually undefined at ucspilogd execution time, print undef in place of what would be the variable's value on every line. Default is the string `<undefined>`.

## Common use

You can emulate the whole syslogd behaviour by combining the following components:

- A Unix stream super-server such as s6-ipcserver listening to the Unix domain socket `/dev/log`, to connect to the kernel log-reading interface.
- `ucspilogd` running under that super-server, to read the logs and perform adequate transformations.
- A logger such as s6-log to store the logs into the filesystem.
- A supervision mechanism such as s6, to ensure ease of use and reliability of the whole chain.

The resulting suite of programs is still smaller, and way more reliable, than a standard syslogd.

In the `examples/syslogd-linux` subdirectory of the s6 package, you will find a suitable ucspilogd service directory. The run scripts are written in the execline language.

## Using `ucspilogd` as a klogd replacement

Certain Unix kernels offer a nice interface to the kernel logs. For instance, the Linux kernel provides the `/proc/kmsg` fake file, that can be opened and read like a normal file, excepts that it gives the kernel logs when they are available and blocks otherwise. You can use `ucspilogd` to process data from those interfaces.

The `examples/klogd-linux` subdirectory of the s6 package is a service directory providing such a klogd service for Linux, using the `/proc/kmsg` interface.