s6-networking
Software
skarnet.org
The s6-ipcserver program
s6-ipcserver is an
UCSPI server tool for
Unix domain sockets, i.e. a super-server.
It accepts connections from clients, and forks a
program to handle each connection.
Interface
s6-ipcserver [ -1 ] [ -q | -Q | -v ] [ -d | -D ] [ -P | -p ] [ -c maxconn ] [ -C localmaxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] path prog...
- s6-ipcserver binds to a Unix domain socket on path.
- It closes its stdin and stdout.
- For every client connection to this socket, it
forks. The child sets some environment variables, then
executes prog... with stdin reading from the socket and
stdout writing to it.
- Depending on the verbosity level, it logs what it does to stderr.
- It runs until killed by a signal. Depending on the received
signal, it may kill its children before exiting.
Environment variables
For each connection, an instance of prog... is spawned with
the following variables set:
- PROTO: always set to IPC
- IPCREMOTEEUID: set to the effective UID of the client,
unless credentials lookups have been disabled
- IPCREMOTEEGID: set to the effective GID of the client,
unless credentials lookups have been disabled
- IPCREMOTEPATH: set to the path associated with the remote socket,
if any. Be aware that it may contain arbitrary characters.
- IPCCONNNUM: set to the number of connections originating from
the same user (i.e. same uid)
If client credentials lookup has been disabled, IPCREMOTEEUID and
IPCREMOTEEUID will be set, but empty.
Options
- -1 : write path, followed by a newline,
to stdout, before
closing it, right after binding and listening to the Unix socket.
If stdout is suitably redirected, this can be used by monitoring
programs to check when the server is ready to accept connections.
- -q : be quiet.
- -Q : be normally verbose. This is the default.
- -v : be verbose.
- -d : allow instant rebinding to the same path
even if it has been used not long ago - this is the SO_REUSEADDR flag to
setsockopt()
and is generally used with server programs. This is the default. Note that
path will be deleted if it already exists at program start time.
- -D : disallow instant rebinding to the same path.
- -P : disable client credentials lookups. The
IPCREMOTEEUID and IPCREMOTEEGID environment variables will be unset
in every instance of prog.... This is the portable option,
because not every system supports credential lookup across Unix domain
sockets; but it is not as secure.
- -p : enable client credentials lookups. This
is the default; it works at least on Linux, Solaris, and
*BSD systems. On systems that do not support it, every connection
attempt will fail with a warning message.
- -c maxconn : accept at most
maxconn concurrent connections. Default is 40. It is
impossible to set it higher than 1000.
- -C localmaxconn : accept at most
localmaxconn connections from the same user ID.
Default is 40. It is impossible to set it higher than maxconn.
- -b backlog : set a maximum of
backlog backlog connections on the socket. Extra
connection attempts will rejected by the kernel.
- -G gidlist : change s6-ipcserver's
supplementary group list to gidlist after binding the socket.
This is only valid when run as root. gidlist must be a
comma-separated list of numerical group IDs.
- -g gid : change s6-ipcserver's groupid
to gid after binding the socket. This is only valid when run
as root.
- -u uid : change s6-ipcserver's userid
to uid after binding the socket. This is only valid when run
as root.
- -U : change s6-ipcserver's user id, group id and
supplementary group list
according to the values of the UID, GID and GIDLIST environment variables
after binding the socket. This is only valid when run as root.
This can be used with the
s6-envuidgid
program to easily script a service that binds to a privileged socket
then drops its privileges to those of a named non-root account.
Signals
- SIGTERM: exit.
- SIGHUP: send a SIGTERM and a SIGCONT to all children.
- SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit.
- SIGABRT: send a SIGKILL to all children, then exit.
Notes