s6-networking: the s6-tcpserver program

From bef76b45f480aa41209efdec09fc6bb0bfde7cbe Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 30 Sep 2023 05:40:04 +0000 Subject: Great Tcpserver Unification. Prepare for 2.6.0.0. Signed-off-by: Laurent Bercot --- doc/s6-tcpserver.html | 124 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 96 insertions(+), 28 deletions(-) (limited to 'doc/s6-tcpserver.html') diff --git a/doc/s6-tcpserver.html b/doc/s6-tcpserver.html index 362dbf5..561c00f 100644 --- a/doc/s6-tcpserver.html +++ b/doc/s6-tcpserver.html @@ -5,7 +5,7 @@ s6-networking: the s6-tcpserver program - + @@ -22,51 +22,119 @@ s6-tcpserver is an UCSPI tool for TCP connections, i.e. a super-server. It accepts connections from -clients, and forks a program to handle each connection. +clients, and spawns a program to handle each connection.

Interface

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

s6-tcpserver executes into -s6-tcpserver4 or -s6-tcpserver6 depending on whether -ip is an IPv4 or IPv6 address. It modifies some of its -option syntax to match s6-tcpserver4 and s6-tcpserver6's.
s6-tcpserver4 or s6-tcpserver6 handles the connection itself.
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. This is converted into -v 0 -for s6-tcpserver4 or s6-tcpserver6.
-Q : be normally quiet. This is converted into -v 1 -for s6-tcpserver4 or s6-tcpserver6. This is the default.
-v : be verbose. This is converted into -v 2 -for s6-tcpserver4 or s6-tcpserver6.
-4 : IPv4 only. Interpret ip as IPv4; if it is -invalid, exit 100.
-6 : IPv6 only. Interpret ip as IPv6; if it is -invalid, exit 100. If neither the -4 nor the -6 option is -given, s6-tcpserver will parse ip to determine its family.
Every other option is passed verbatim to s6-tcpserver4 or s6-tcpserver6.
-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

s6-tcpserver executes either into s6-tcpserver4, which only serves -IPv4, or into s6-tcpserver6, which only serves IPv6. It will not bind to every -available IP address of the machine whether they are v4 or v6; on the -other hand, it can bind to every available IPv4 address (if ip -is 0.0.0.0) or to every available IPv6 address (if ip -is ::). Two instances of s6-tcpserver can cover every -available address.
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 ::.

-- cgit v1.2.3