s6-networking: the s6-tcpserver-socketbinder 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/index.html | 10 +-- doc/s6-tcpserver-access.html | 28 +++----- doc/s6-tcpserver-socketbinder.html | 86 ++++++++++++++++++++++ doc/s6-tcpserver.html | 124 ++++++++++++++++++++++++-------- doc/s6-tcpserver4-socketbinder.html | 82 --------------------- doc/s6-tcpserver4.html | 137 ------------------------------------ doc/s6-tcpserver4d.html | 113 ----------------------------- doc/s6-tcpserver6-socketbinder.html | 82 --------------------- doc/s6-tcpserver6.html | 136 ----------------------------------- doc/s6-tcpserver6d.html | 112 ----------------------------- doc/s6-tcpserverd.html | 113 +++++++++++++++++++++++++++++ doc/upgrade.html | 21 +++++- 12 files changed, 326 insertions(+), 718 deletions(-) create mode 100644 doc/s6-tcpserver-socketbinder.html delete mode 100644 doc/s6-tcpserver4-socketbinder.html delete mode 100644 doc/s6-tcpserver4.html delete mode 100644 doc/s6-tcpserver4d.html delete mode 100644 doc/s6-tcpserver6-socketbinder.html delete mode 100644 doc/s6-tcpserver6.html delete mode 100644 doc/s6-tcpserver6d.html create mode 100644 doc/s6-tcpserverd.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index 37da351..8cd5f2e 100644 --- a/doc/index.html +++ b/doc/index.html @@ -91,7 +91,7 @@ run-time requirement if you link against its shared version.

The current released version of s6-networking is -2.5.1.4.

2.6.0.0

Alternatively, you can checkout a copy of the s6-networking git repository: @@ -143,12 +143,8 @@ relevant page.
UCSPI tools for secure communication (TLS protocol) over TCP
diff --git a/doc/s6-tcpserver-access.html b/doc/s6-tcpserver-access.html index 15f4246..4ef3302 100644 --- a/doc/s6-tcpserver-access.html +++ b/doc/s6-tcpserver-access.html @@ -35,12 +35,8 @@ just like tcpwrappers' tcpd program.
- s6-tcpserver-access checks it is run under a UCSPI server tool -such as s6-tcpserver, - s6-tcpserver4 or - s6-tcpserver6, or their - stripped-down versions - s6-tcpserver4d or - s6-tcpserver6d.
- It checks that the remote end of the connection fits the accepted criteria defined by the database contained in rulesdir or rulesfile. If the database tells it to reject the connection, @@ -59,9 +55,11 @@ its parent:
  - PROTO: normally TCP, but could be anything else, like SSL.
  - PROTO: normally TCP, but could be anything else.
  - ${PROTO}LOCALIP: the local address of the socket.
  - ${PROTO}LOCALPORT: the local port of the socket.
  - ${PROTO}REMOTEIP: the remote address of the socket, i.e. the client's -IP address. This can be IPv4 or (if the underlying skalibs supports it) IPv6.
  - ${PROTO}REMOTEPORT: the remote port of the socket.
  @@ -71,16 +69,14 @@ IP address. This can be IPv4 or (if the underlying skalibs supports it) IPv6.
  - ${PROTO}LOCALIP: set to the local address of the socket.
  - ${PROTO}LOCALPORT: set to the local port of the socket.
  - ${PROTO}REMOTEINFO: normally unset, but set to the information -retrieved from ${PROTO}REMOTEIP via the IDENT protocol if the -r -option has been given.
  - ${PROTO}REMOTEHOST: set to the remote host name obtained from a DNS lookup. Unset if the -H option has been given.
  - ${PROTO}LOCALHOST: set to the local host name obtained from a DNS lookup. If the -l option has been given, set to localname instead.
  - ${PROTO}REMOTEINFO: normally unset, but set to the information +retrieved from ${PROTO}REMOTEIP via the IDENT protocol if the -r +option has been given.
  @@ -227,12 +223,6 @@ environment modifications, if any, s6-tcpserver-access execs into
  Notes
  - s6-tcpserver-access works with -s6-tcpserver4d, handling IPv4 addresses, -as well as -s6-tcpserver6d, handling IPv6 addresses. -It will automatically detect the remote address type and match it against the -correct subdatabase.
  - s6-tcpserver-access may perform several DNS queries. For efficiency purposes, it does as many of them as possible in parallel. However, if asked to do an IDENT query, it does not parallelize it with DNS queries. Take diff --git a/doc/s6-tcpserver-socketbinder.html b/doc/s6-tcpserver-socketbinder.html new file mode 100644 index 0000000..8e7135d --- /dev/null +++ b/doc/s6-tcpserver-socketbinder.html @@ -0,0 +1,86 @@ + + + + + + s6-networking: the s6-tcpserver-socketbinder program + + + + + + +
    +s6-networking
    +Software
    +skarnet.org +
    + +
    The s6-tcpserver-socketbinder program
    + +
    +s6-tcpserver-socketbinder binds an INET domain +socket to an IPv4 or IPv6 address and port, then executes a program. +
    + +
    Interface
    + +
```
+     s6-tcpserver-socketbinder [ -d | -D ] [ -b backlog ] [ -M | -m ] [ -B ] ip port prog...
+
```
    + +
    - s6-tcpserver-socketbinder creates a TCP socket +and binds it to IP address ip, port port. +It prepares the socket to accept connections by calling +listen().
    - It then execs into prog... with the open socket +as its standard input.
    + +
    Options
    + +
    - -d : allow instant rebinding to the same IP and port +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.
    - -D : disallow instant rebinding to the same path.
    - -b backlog : set a maximum of +backlog backlog connections on the socket - extra +connection attempts will rejected by the kernel. The default is the maximum +number allowed by the system. If backlog +is 0, then the socket will be created, but it will not be +listening.
    - -M : create a TCP socket. This is the default.
    - -m : create a UDP socket. Note +that by default UDP sockets are not connection-mode, and listen() +will fail - so you should always give the -b0 option to +s6-tcpserver-socketbinder along with -m.
    - -B : create a blocking socket. Default is non-blocking.
    + +
    Notes
    + +
    - The socket is provided non-blocking by default.
    - s6-tcpserver-socketbinder is part of a set of basic blocks used to +build a flexible TCP/IP super-server. It normally should be given a +command line crafted to make it execute into +s6-tcpserverd to accept connections +from clients, or into a program such as +s6-applyuidgid +to drop privileges before doing so.
    - The s6-tcpserver program does +exactly this. It implements +a full TCP/IP super-server by building a command line starting with +s6-tcpserver-socketbinder and ending with s6-tcpserverd followed by the +application program, and executing into it.
    - For s6-tcpserver-socketbinder, :: means "all IPv6 addresses", +and 0.0.0.0 means "all IPv4 addresses". It does not provide a way +to bind a socket to all addresses regardless of protocol; instead, you +should use two sockets, one for IPv4 and one for IPv6.
    + + + 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 ::.
    diff --git a/doc/s6-tcpserver4-socketbinder.html b/doc/s6-tcpserver4-socketbinder.html deleted file mode 100644 index 6bf1c58..0000000 --- a/doc/s6-tcpserver4-socketbinder.html +++ /dev/null @@ -1,82 +0,0 @@ - - - - - - s6-networking: the s6-tcpserver4-socketbinder program - - - - - - -
    -s6-networking
    -Software
    -skarnet.org -
    - -
    The s6-tcpserver4-socketbinder program
    - -
    -s6-tcpserver4-socketbinder binds an INET domain -socket to an IPv4 address and port, then executes a program. -
    - -
    Interface
    - -
```
-     s6-tcpserver4-socketbinder [ -d | -D ] [ -b backlog ] [ -M | -m ] [ -B ] ip port prog...
-
```
    - -
    - s6-tcpserver4-socketbinder creates a TCP socket -and binds it to IPv4 address ip, port port. -It prepares the socket to accept connections by calling -listen().
    - It then execs into prog... with the open socket -as its standard input.
    - -
    Options
    - -
    - -d : allow instant rebinding to the same IP and port -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.
    - -D : disallow instant rebinding to the same path.
    - -b backlog : set a maximum of -backlog backlog connections on the socket - extra -connection attempts will rejected by the kernel. The default is SOMAXCONN, -i.e. the maximum number allowed by the system. If backlog -is 0, then the socket will be created, but it will not be -listening.
    - -M : create a TCP socket. This is the default.
    - -m : create a UDP socket. Note -that by default UDP sockets are not connection-mode, and listen() -will fail - so you should always give the -b0 option to -s6-tcpserver4-socketbinder along with -m.
    - -B : create a blocking socket. Default is non-blocking.
    - -
    Notes
    - -
    - The socket is provided non-blocking by default.
    - s6-tcpserver4-socketbinder is part of a set of basic blocks used to -build a flexible TCP/IPv4 super-server. It normally should be given a -command line crafted to make it execute into -s6-tcpserver4d to accept connections -from clients, or into a program such as -s6-applyuidgid -to drop privileges before doing so.
    - The s6-tcpserver4 program does -exactly this. It implements -a full TCP/IPv4 super-server by building a command line starting with -s6-tcpserver4-socketbinder and ending with s6-tcpserver4d followed by the -application program, and executing into it.
    - - - diff --git a/doc/s6-tcpserver4.html b/doc/s6-tcpserver4.html deleted file mode 100644 index bc1bd5e..0000000 --- a/doc/s6-tcpserver4.html +++ /dev/null @@ -1,137 +0,0 @@ - - - - - - s6-networking: the s6-tcpserver4 program - - - - - - -
    -s6-networking
    -Software
    -skarnet.org -
    - -
    The s6-tcpserver4 program
    - -
    -s6-tcpserver4 is a super-server for IPv4 TCP -connections. It accepts connections from clients, and forks a -program to handle each connection. -
    - -
    Interface
    - -
```
-     s6-tcpserver4 [ -1 ] [ -v verbosity ] [ -c maxconn ] [ -C localmaxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] ip port prog...
-
```
    - -
    - s6-tcpserver4 binds to local IPv4 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-tcpserver4 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
    - TCPREMOTEPORT: set to the originating port
    - TCPCONNNUM: set to the number of connections originating from -the same IP 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-tcpserver4'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-tcpserver4's group id -to gid after binding the socket. This is only valid when run -as root.
    - -u uid : change s6-tcpserver4's user id -to uid after binding the socket. This is only valid when run -as root.
    - -U : change s6-tcpserver4'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-tcpserver4 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 additional environment variables, -access control and DNS resolution are provided -via the s6-tcpserver-access -program.
    - In previous releases of s6-networking, s6-tcpserver4 was -monolithic: it did the work of -s6-tcpserver4-socketbinder, -s6-applyuidgid and -s6-tcpserver4d 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.
    - - - diff --git a/doc/s6-tcpserver4d.html b/doc/s6-tcpserver4d.html deleted file mode 100644 index a11bae1..0000000 --- a/doc/s6-tcpserver4d.html +++ /dev/null @@ -1,113 +0,0 @@ - - - - - - s6-networking: the s6-tcpserver4d program - - - - - - -
    -s6-networking
    -Software
    -skarnet.org -
    - -
    The s6-tcpserver4d program
    - -
    -s6-tcpserver4d is the serving part of the -s6-tcpserver4 super-server. -It assumes that its stdin is a bound and listening TCP/IPv4 socket, -and it accepts connections from clients connecting to it, -forking a program to handle each connection. -
    - -
    Interface
    - -
```
-     s6-tcpserver4d [ -1 ] [ -v verbosity ] [ -c maxconn ] [ -C localmaxconn ] prog...
-
```
    - -
    - s6-tcpserver4d accepts connections from clients to an already -bound and listening TCP socket which is its standard input.
    - For every TCP connection to this socket, 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.
    - -
    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
    - TCPREMOTEPORT: set to the originating port
    - TCPCONNNUM: set to the number of connections originating from -the same IP address
    - -
    Options
    - -
    - -1 : write a newline to stdout, and close stdout, -right before entering the client-accepting loop. -If stdout is suitably redirected, this can be used by monitoring -programs to check when the server is accepting connections. This can be -used with s6's readiness -notification mechanism to make sure subsequent services do not start -before the server is ready.
    - -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.
    - -
    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-tcpserver4d 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 additional environment variables, -access control and DNS resolution are provided -via the s6-tcpserver-access -program.
    - s6-tcpserver4d is meant to be execve'd into by a program that gets -the listening socket. That program is normally -s6-tcpserver4-socketbinder, -which creates the socket itself; but it can be a different one if the -socket is to be retrieved by another means, for instance by fd-passing -from a fd-holding daemon (some people call this "socket activation").
    - - - diff --git a/doc/s6-tcpserver6-socketbinder.html b/doc/s6-tcpserver6-socketbinder.html deleted file mode 100644 index 5bb2ae5..0000000 --- a/doc/s6-tcpserver6-socketbinder.html +++ /dev/null @@ -1,82 +0,0 @@ - - - - - - s6-networking: the s6-tcpserver6-socketbinder program - - - - - - -
    -s6-networking
    -Software
    -skarnet.org -
    - -
    The s6-tcpserver6-socketbinder program
    - -
    -s6-tcpserver6-socketbinder binds an INET domain -socket to an IPv6 address and port, then executes a program. -
    - -
    Interface
    - -
```
-     s6-tcpserver6-socketbinder [ -d | -D ] [ -b backlog ] [ -M | -m ] [ -B ] ip port prog...
-
```
    - -
    - s6-tcpserver6-socketbinder creates an TCP socket -and binds it to IPv6 address ip, port port. -It prepares the socket to accept connections by calling -listen().
    - It then execs into prog... with the open socket -as its standard input.
    - -
    Options
    - -
    - -d : allow instant rebinding to the same IP and port -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.
    - -D : disallow instant rebinding to the same path.
    - -b backlog : set a maximum of -backlog backlog connections on the socket - extra -connection attempts will rejected by the kernel. The default is SOMAXCONN, -i.e. the maximum number allowed by the system. If backlog -is 0, then the socket will be created, but it will not be -listening.
    - -M : create a TCP socket. This is the default.
    - -m : create a UDP socket. Note -that by default UDP sockets are not connection-mode, and listen() -will fail - so you should always give the -b0 option to -s6-tcpserver6-socketbinder along with -m.
    - -B : create a blocking socket. Default is non-blocking.
    - -
    Notes
    - -
    - The socket is provided non-blocking by default.
    - s6-tcpserver6-socketbinder is part of a set of basic blocks used to -build a flexible TCP/IPv6 super-server. It normally should be given a -command line crafted to make it execute into -s6-tcpserver6d to accept connections -from clients, or into a program such as -s6-applyuidgid -to drop privileges before doing so.
    - The s6-tcpserver6 program does -exactly this. It implements -a full TCP/IPv6 super-server by building a command line starting with -s6-tcpserver6-socketbinder and ending with s6-tcpserver6d followed by the -application program, and executing into it.
    - - - diff --git a/doc/s6-tcpserver6.html b/doc/s6-tcpserver6.html deleted file mode 100644 index 01be274..0000000 --- a/doc/s6-tcpserver6.html +++ /dev/null @@ -1,136 +0,0 @@ - - - - - - s6-networking: the s6-tcpserver6 program - - - - - - -
    -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.
    - - - diff --git a/doc/s6-tcpserver6d.html b/doc/s6-tcpserver6d.html deleted file mode 100644 index 585fa41..0000000 --- a/doc/s6-tcpserver6d.html +++ /dev/null @@ -1,112 +0,0 @@ - - - - - - s6-networking: the s6-tcpserver6d program - - - - - - -
    -s6-networking
    -Software
    -skarnet.org -
    - -
    The s6-tcpserver6d program
    - -
    -s6-tcpserver6d is the serving part of the -s6-tcpserver6 super-server. -It assumes that its stdin is a bound and listening TCP/IPv6 socket, -and it accepts connections from clients connecting to it, -forking a program to handle each connection. -
    - -
    Interface
    - -
```
-     s6-tcpserver6d [ -1 ] [ -v verbosity ] [ -c maxconn ] [ -C localmaxconn ] prog...
-
```
    - -
    - s6-tcpserver6d accepts connections from clients to an already -bound and listening TCP socket which is its standard input.
    - For every TCP connection to this socket, 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.
    - -
    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
    - TCPREMOTEPORT: set to the originating port
    - TCPCONNNUM: set to the number of connections originating from -the same IP address
    - -
    Options
    - -
    - -1 : write a newline to stdout, and close stdout, -right before entering the client-accepting loop. -If stdout is suitably redirected, this can be used by monitoring -programs to check when the server is accepting connections, for instance -s6's readiness -notification mechanism.
    - -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.
    - -
    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-tcpserver6d 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 additional environment variables, -access control and DNS resolution are provided -via the s6-tcpserver-access -program.
    - s6-tcpserver6d is meant to be execve'd into by a program that gets -the listening socket. That program is normally -s6-tcpserver6-socketbinder, -which creates the socket itself; but it can be a different one if the -socket is to be retrieved by another means, for instance by fd-passing -from a fd-holding daemon (some people call this "socket activation").
    - - - diff --git a/doc/s6-tcpserverd.html b/doc/s6-tcpserverd.html new file mode 100644 index 0000000..6600a7b --- /dev/null +++ b/doc/s6-tcpserverd.html @@ -0,0 +1,113 @@ + + + + + + s6-networking: the s6-tcpserverd program + + + + + + +
    +s6-networking
    +Software
    +skarnet.org +
    + +
    The s6-tcpserverd program
    + +
    +s6-tcpserverd is the serving part of the +s6-tcpserver super-server. +It assumes that its stdin is a bound and listening TCP/IP socket, +and it accepts connections from clients connecting to it, +spawning a program to handle each connection. +
    + +
    Interface
    + +
```
+     s6-tcpserverd [ -1 ] [ -v verbosity ] [ -c maxconn ] [ -C localmaxconn ] prog...
+
```
    + +
    - s6-tcpserverd accepts connections from clients to an already +bound and listening TCP socket which is its standard input.
    - For every TCP connection to this socket, 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 socket's address
    - TCPLOCALPORT: set to the server socket's port
    - TCPREMOTEIP: set to the client socket's address
    - TCPREMOTEPORT: set to the client socket's port
    - TCPCONNNUM: set to the number of connections originating from +the same IP address
    + +
    Options
    + +
    - -1 : write the local port, followed by newline, +to stdout, and close stdout, right before entering the client-accepting loop. +If stdout is suitably redirected, this can be used by monitoring +programs to check when the server is accepting connections. This can be +used with s6's readiness +notification mechanism to make sure subsequent services do not start +before the server is ready.
    - -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 16384.
    - -C localmaxconn : accept at most +localmaxconn connections from the same IP address. +Default is 40. It is impossible to set it higher than maxconn.
    + +
    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-tcpserverd performs just the bare minimum: the point is to have a +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-tcpserverd is meant to be execve'd into by a program that gets +the listening socket. That program is normally +s6-tcpserver-socketbinder, +which creates the socket itself; but it can be a different one if the +socket is to be retrieved by another means, for instance by fd-passing +from a fd-holding daemon (some people call this "socket activation").
    + + + diff --git a/doc/upgrade.html b/doc/upgrade.html index 7b2c27b..0f20319 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -18,7 +18,7 @@
    What has changed in s6-networking
    -
    in 2.5.1.4
    +
    in 2.6.0.0
    - skalibs @@ -35,7 +35,24 @@ optional dependency bumped to 1.1.1w
    - s6-tcpserver-access does not print a warning on -v 2 or more when it is run without -the -i or -x option.
    - The tcpserver chain has been unified! +s6-tcpserver4, s6-tcpserver6, +s6-tcpserver4-socketbinder, s6-tcpserver6-socketbinder, +s6-tcpserver4d and s6-tcpserver6d have all +disappeared. Instead, there are just 3 programs: +
      - s6-tcpserver-socketbinder, +for socket binding
      - s6-tcpserverd, the long-lived +process. It now exports TCPLOCALIP and TCPLOCALPORT in addition to PROTO, +TCPREMOTEIP, TCPREMOTEPORT and TCPCONNNUM.
      - s6-tcpserver, which still has +the same interface except that the -4 and -6 options +have been removed, and that is still a wrapper around the others.
      +
    in 2.5.1.3
    -- cgit v1.3.1

UCSPI tools for secure communication (TLS protocol) over TCP

Notes

The s6-tcpserver-socketbinder program

Interface

Options

Notes

Interface

Environment variables

Options

Signals

Notes

The s6-tcpserver4-socketbinder program

Interface

Options

Notes

The s6-tcpserver4 program

Interface

Environment variables

Options

Signals

Notes

The s6-tcpserver4d program

Interface

Environment variables

Options

Signals

Notes

The s6-tcpserver6-socketbinder program

Interface

Options

Notes

The s6-tcpserver6 program

Interface

Environment variables

Options

Signals

Notes

The s6-tcpserver6d program

Interface

Environment variables

Options

Signals

Notes

The s6-tcpserverd program

Interface

Environment variables

Options

Signals

Notes

What has changed in s6-networking

in 2.5.1.4

in 2.6.0.0

in 2.5.1.3

The `s6-tcpserver-socketbinder` program

The `s6-tcpserver4-socketbinder` program

The `s6-tcpserver4` program

The `s6-tcpserver4d` program

The `s6-tcpserver6-socketbinder` program

The `s6-tcpserver6` program

The `s6-tcpserver6d` program

The `s6-tcpserverd` program