From e9be34c9b798141dd6c224cf33934904935c49b2 Mon Sep 17 00:00:00 2001
From: Laurent Bercot
Date: Wed, 7 Jan 2015 19:01:26 +0000
Subject: Complete conversion of s6-ipcserver and s6-tcpserver (4 and 6) to
socketbinder + d model. With documentation (!)
---
doc/s6-ipcserver-access.html | 2 +-
doc/s6-ipcserver-socketbinder.html | 71 +++++++++++++++++++
doc/s6-ipcserver.html | 91 ++++++++++++++++---------
doc/s6-ipcserverd.html | 131 ++++++++++++++++++++++++++++++++++++
doc/s6-sudod.html | 3 +
doc/s6-tcpserver-access.html | 9 ++-
doc/s6-tcpserver4-socketbinder.html | 70 +++++++++++++++++++
doc/s6-tcpserver4d.html | 112 ++++++++++++++++++++++++++++++
doc/s6-tcpserver6-socketbinder.html | 70 +++++++++++++++++++
doc/s6-tcpserver6d.html | 112 ++++++++++++++++++++++++++++++
10 files changed, 634 insertions(+), 37 deletions(-)
create mode 100644 doc/s6-ipcserver-socketbinder.html
create mode 100644 doc/s6-ipcserverd.html
create mode 100644 doc/s6-tcpserver4-socketbinder.html
create mode 100644 doc/s6-tcpserver4d.html
create mode 100644 doc/s6-tcpserver6-socketbinder.html
create mode 100644 doc/s6-tcpserver6d.html
(limited to 'doc')
diff --git a/doc/s6-ipcserver-access.html b/doc/s6-ipcserver-access.html
index 817425b..515138c 100644
--- a/doc/s6-ipcserver-access.html
+++ b/doc/s6-ipcserver-access.html
@@ -22,7 +22,7 @@
control tool for Unix domain sockets on systems where the
getpeereid() system call can be implemented.
It is meant to be run after
-s6-ipcserver and before
+s6-ipcserverd and before
the application program on the s6-ipcserver command line.
diff --git a/doc/s6-ipcserver-socketbinder.html b/doc/s6-ipcserver-socketbinder.html
new file mode 100644
index 0000000..04670cd
--- /dev/null
+++ b/doc/s6-ipcserver-socketbinder.html
@@ -0,0 +1,71 @@
+
+
+
+
+ s6-networking: the s6-ipcserver-socketbinder program
+
+
+
+
+
+
+
+s6-networking
+Software
+skarnet.org
+
+
+ The s6-ipcserver-socketbinder program
+
+
+s6-ipcserver-socketbinder binds a Unix domain
+socket, then executes a program.
+
+
+ Interface
+
+
+ s6-ipcserver-socketbinder [ -d | -D ] [ -b backlog ] path prog...
+
+
+
+ - s6-ipcserver-socketbinder creates a Unix domain socket of type SOCK_STREAM
+and binds it to path. 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 path
+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. Note that
+path will be deleted if it already exists at program start time.
+ - -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.
+
+
+ Notes
+
+
+ - s6-ipcserver-socketbinder is part of a set of basic blocks used to
+build a flexible Unix super-server. It normally should be given a
+command line crafted to make it execute into
+s6-ipcserverd to accept connections
+from clients, or into a program such as
+s6-applyuidgid
+to drop privileges before doing so.
+ - The s6-ipcserver program does
+exactly this. It implements
+a full Unix super-server by building a command line starting with
+s6-ipcserver-socketbinder and ending with s6-ipcserverd followed by the
+application program, and executing into it.
+
+
+
+
diff --git a/doc/s6-ipcserver.html b/doc/s6-ipcserver.html
index 331b139..4b52888 100644
--- a/doc/s6-ipcserver.html
+++ b/doc/s6-ipcserver.html
@@ -32,7 +32,8 @@ program to handle each connection.
- - s6-ipcserver binds to a Unix domain socket on path.
+ - s6-ipcserver binds a Unix domain socket to path.
+ - It can drop its root privileges.
- It closes its stdin and stdout.
- For every client connection to this socket, it
forks. The child sets some environment variables, then
@@ -41,32 +42,36 @@ 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-ipcserver 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:
-
+ Implementation
- - PROTO: always set to IPC
- - IPCREMOTEEUID: set to the effective UID of the client,
-unless credentials lookups have been disabled
- - IPCREMOTEEGID: set to the effective GID of the client,
-unless credentials lookups have been disabled
- - IPCREMOTEPATH: set to the path associated with the remote socket,
-if any. Be aware that it may contain arbitrary characters.
- - IPCCONNNUM: set to the number of connections originating from
-the same user (i.e. same uid)
+ - s6-ipcserver parses the options and arguments it is given, and
+builds a new command line with them. It then executes into that new
+command line.
+ - The first program s6-ipcserver executes into is
+s6-ipcserver-socketbinder.
+It will create and bind a Unix domain socket to path, then
+execute into the rest of the command line.
+ - If a privilege-dropping operation has been requested, the
+program that s6-ipcserver-socketbinder executes into is
+s6-applyuidgid.
+It will drop the root privileges, then execute into the rest of the
+command line.
+ - The next program in the chain is
+s6-ipcserverd. It is executed into
+by s6-applyuidgid, or directly by s6-ipcserver-socketbinder if no
+privilege-dropping operation has been requested. s6-ipcserverd is
+the long-lived process, the "daemon" itself, accepting connections
+from clients.
+ - For every client, s6-ipcserverd will spawn an instance of
+prog..., the remainder of the command line.
-
- If client credentials lookup has been disabled, IPCREMOTEEUID and
-IPCREMOTEEUID will be set, but empty.
-
-
Options
@@ -123,25 +128,45 @@ 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
+ Implementation
- - 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.
+ - s6-ipcserver parses the options and arguments it is given, and
+builds a new command line with them. It then executes into that new
+command line.
+ - The first program s6-ipcserver executes into is
+s6-ipcserver-socketbinder.
+It will create and bind a Unix domain socket to path, then
+execute into the rest of the command line.
+ - If a privilege-dropping operation has been requested, the
+program that s6-ipcserver-socketbinder executes into is
+s6-applyuidgid.
+It will drop the root privileges, then execute into the rest of the
+command line.
+ - The next program in the chain is
+s6-ipcserverd. It is executed into
+by s6-applyuidgid, or directly by s6-ipcserver-socketbinder if no
+privilege-dropping operation has been requested. s6-ipcserverd is
+the long-lived process, the "daemon" itself, accepting connections
+from clients.
+ - For every client, s6-ipcserverd will spawn an instance of
+prog..., the remainder of the command line.
Notes
- - Unlike his close cousin
-ipcserver,
-s6-ipcserver does not perform operations such as access control. Those are
-delegated to the
-s6-ipcserver-access program.
- - s6-ipcserver can be used to set up
-local services.
+ - s6-ipcserver does not interpret its options itself. It just
+dispatches them to the appropriate program on the command line that
+it builds.
+ - In previous releases of s6-networking, s6-ipcserver was
+monolithic: it did the work of s6-ipcserver-socketbinder,
+s6-applyuidgid and s6-ipcserverd 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.
+
+
+s6-networking
+Software
+skarnet.org
+
+
+ The s6-ipcserverd program
+
+
+s6-ipcserverd is the serving part of the
+s6-ipcserver super-server.
+It assumes that its stdin is a bound and listening Unix
+domain socket, and
+it accepts connections from clients connecting to it, forking a
+program to handle each connection.
+
+
+ Interface
+
+
+ s6-ipcserverd [ -1 ] [ -v verbosity ] [ -P | -p ] [ -c maxconn ] [ -C localmaxconn ] prog...
+
+
+
+ - s6-ipcserverd accepts connections from clients to an already
+bound and listening SOCK_STREAM Unix domain socket which is its
+standard input.
+ - For every client connection to this socket, it
+forks. The child sets some environment variables, then
+executes prog... with stdin reading from the 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 IPC
+ - IPCREMOTEEUID: set to the effective UID of the client,
+unless credentials lookups have been disabled
+ - IPCREMOTEEGID: set to the effective GID of the client,
+unless credentials lookups have been disabled
+ - IPCREMOTEPATH: set to the path associated with the remote socket,
+if any. Be aware that it may contain arbitrary characters.
+ - IPCCONNNUM: set to the number of connections originating from
+the same user (i.e. same uid)
+
+
+
+ If client credentials lookup has been disabled, IPCREMOTEEUID and
+IPCREMOTEEUID will be set, but empty.
+
+
+
+ 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.
+The s6-notifywhenup
+program can be used before the s6-ipcserver
+invocation to notify listeners when the server is ready.
+ - -v verbosity : be more or less
+verbose. verbosity can be 0 (quiet), 1 (normal), or 2
+(verbose).
+ - -P : disable client credentials lookups. The
+IPCREMOTEEUID and IPCREMOTEEGID environment variables will be unset
+in every instance of prog.... This is the portable option,
+because not every system supports credential lookup across Unix domain
+sockets; but it is not as secure.
+ - -p : enable client credentials lookups. This
+is the default; it works at least on Linux, Solaris, and
+*BSD systems. On systems that do not support it, every connection
+attempt will fail with a warning message.
+ - -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 user ID.
+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 his close cousin
+ipcserver,
+s6-ipcserverd does not perform operations such as access control. Those are
+delegated to the
+s6-ipcserver-access program.
+ - s6-ipcserverd can be used to set up
+local services.
+ - s6-ipcserverd is meant to be execve'd into by a program that gets
+the listening socket. That program is normally
+s6-ipcserver-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-ipcserverd.html b/doc/s6-ipcserverd.html
new file mode 100644
index 0000000..916de12
--- /dev/null
+++ b/doc/s6-ipcserverd.html
@@ -0,0 +1,131 @@
+
+