s6-networking
Software
skarnet.org

The s6-tcpserver program

s6-tcpserver is an UCSPI tool for TCP connections, i.e. a super-server. It accepts connections from clients, and spawns a program to handle each connection.

Interface

     s6-tcpserver [ -q | -Q | -v ] [ -1 ] [ -c maxconn ] [ -C localmaxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] ip port prog...

• s6-tcpserver binds to local IP address ip (which can be IPv4 or IPv6), port port.
• It closes its stdin and stdout.
• For every TCP connection to this address and port, it spawns a prog... child 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.

Environment variables

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

• PROTO: always set to TCP
• TCPLOCALIP: set to the server's address
• TCPLOCALPORT: set to the server's port
• TCPREMOTEIP: set to the client's address
• TCPREMOTEPORT: set to the client's port
• TCPCONNNUM: set to the number of connections originating from the same IP address

Options

• -q : be quiet. Only print fatal error messages to stderr.
• -Q : be normally quiet. Print warnings and fatal error messages to stderr. This is the default.
• -v : be verbose. Additionally to fatal errors and warnings, also print status and connection information for every client.
• -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.
• -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-tcpserver'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-tcpserver's group id to gid after binding the socket. This is only valid when run as root.
• -u uid : change s6-tcpserver's user id to uid after binding the socket. This is only valid when run as root.
• -U : change s6-tcpserver'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

• Unlike its ancestor tcpserver, s6-tcpserver performs just the bare minimum: the point is to have a very small and very fast process to serve connections with the least possible overhead. Features such as access control and DNS resolution are provided via the s6-tcpserver-access program.
• s6-tcpserver is actually a wrapper that rewrites itself into a command line running
  • s6-tcpserver-socketbinder, that binds the socket and listens to it
  • s6-applyuidgid, that drops privileges
  • s6-tcpserverd, the long-lived process that actually accepts the connections. So if you see in your ps output that the name of the process is s6-tcpserverd, that's why.
• s6-tcpserver treats IPv4 and IPv6 separately. If you want to listen on all the addresses of a machine no matter whether v4 or v6, then you need to run two s6-tcpserver processes: one on 0.0.0.0 and and one on ::.
• The option to make s6-tcpserver verbose is -v, without an argument. This is different from the s6-tcpserverd interface, where that would be -v 2. The difference exists because s6-tcpserver follows the UCSPI tool interface, whereas s6-tcpserverd has no such constraint.