s6-networking
Software
skarnet.org

The s6-tcpserver6 program

s6-tcpserver6 is a super-server for IPv6 TCP connections. It accepts connections from clients, and forks a program to handle each connection.

Interface

     s6-tcpserver6 [ -1 ] [ -v verbosity ] [ -c maxconn ] [ -C localmaxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] ip port prog...

• s6-tcpserver6 binds to local IPv6 address ip, port port.
• It closes its stdin and stdout.
• For every TCP connection to this address and port, it forks. The child sets some environment variables, then executes prog... with stdin reading from the network 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.
• s6-tcpserver6 actually doesn't do any of this itself. It is a wrapper, rewriting the command line and executing into a chain of programs that perform those duties.

Environment variables

For each connection, an instance of prog... is spawned with the following variables set:

• PROTO: always set to TCP
• TCPREMOTEIP: set to the originating address, in canonical IPv6 form
• TCPREMOTEPORT: set to the originating port
• TCPCONNNUM: set to the number of connections originating from the same IPv6 address

Options

• -1 : write port to stdout, before closing it, right after binding and listening to the network socket. If stdout is suitably redirected, this can be used by monitoring programs to check when the server is ready to accept connections.
• -v verbosity : be more or less verbose. By default, verbosity is 1: print warning messages to stderr. 0 means only print fatal error messages ; 2 means print status and connection information for every client.
• -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 IP address. 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-tcpserver6'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-tcpserver6's group id to gid after binding the socket. This is only valid when run as root.
• -u uid : change s6-tcpserver6's user id to uid after binding the socket. This is only valid when run as root.
• -U : change s6-tcpserver6'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

• s6-tcpserver6 will only serve real IPv6 addresses; it does not default to an IPv4 address. The s6-tcpserver4 program should be used to serve IPv4 addresses.
• s6-tcpserver6 will only work if the underlying skalibs has been compiled with IPv6 support.
• In previous releases of s6-networking, s6-tcpserver6 was monolithic: it did the work of s6-tcpserver6-socketbinder, s6-applyuidgid and s6-tcpserver6d itself. The functionality has now been split into several different programs because some service startup schemes require the daemon to get its socket from an external program instead of creating and binding it itself. The most obvious application of this is upgrading a long-lived process without losing existing connections.