S6-TCPSERVER(8)

NAME
s6-tcpserver - UCSPI tool[1] for TCP connections, i.e. a super-server

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

DESCRIPTION
s6-tcpserver accepts connections from clients, and spawns a program to handle each connection.

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.

Unlike its ancestor tcpserver[2], 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(8) +program.

s6-tcpserver is actually a wrapper that rewrites itself into a command line running:

•   s6-tcpserver-socketbinder(8), that binds the socket and listens to it.

•   s6-applyuidgid(8), that drops privileges.

•   s6-tcpserverd(8), the long-lived process that actually accepts the connections. So if you see in your ps(1) 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 one on ‘::’.

The option to make s6-tcpserver verbose is ‘-v’, without an argument. This is different from the s6-tcpserverd(8) interface, where that would be ‘-v 2’. The difference exists because s6-tcpserver follows the UCSPI tool[1] interface, whereas s6-tcpserverd(8) has no such constraint.

  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.

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 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(8) program to easily script a service that binds to a privileged socket then drops its privileges to those of a named non-root account.

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

SEE ALSO
ps(1), s6-applyuidgid(8), s6-envuidgid(8), s6-tcpclient(8), s6-tcpserver-access(8), s6-tcpserver-socketbinder(8), s6-tcpserverd(8)

[1] https://cr.yp.to/proto/ucspi.txt

[2] https://cr.yp.to/ucspi-tcp/tcpserver.html

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-networking/s6-tcpserver.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)