Complete conversion of s6-ipcserver and s6-tcpserver (4 and 6)

to socketbinder + d model. With documentation (!)
author: Laurent Bercot <ska-skaware@skarnet.org> 2015-01-07 19:01:26 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2015-01-07 19:01:26 +0000
commit: e9be34c9b798141dd6c224cf33934904935c49b2 (patch)
tree: 969c243f85ef02d88bc4f54d9ab14cd323b7e9aa /doc
parent: e3aeb3b63b9996bd06c20861e1dac1c9421d9312 (diff)
download: s6-networking-e9be34c9b798141dd6c224cf33934904935c49b2.tar.xz
10 files changed, 634 insertions, 37 deletions
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
 <a href="http://www.superscript.com/ucspi-ipc/getpeereid.html">getpeereid()</a> system call can be implemented.
 It is meant to be run after
-<a href="s6-ipcserver.html">s6-ipcserver</a> and before
+<a href="s6-ipcserverd.html">s6-ipcserverd</a> and before
 the application program on the s6-ipcserver command line.
 </p>
 
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 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-networking: the s6-ipcserver-socketbinder program</title>
+    <meta name="Description" content="s6-networking: the s6-ipcserver-socketbinder program" />
+    <meta name="Keywords" content="s6-networking s6-ipcserver-socketbinder ipcserver ucspi socket bind listen" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>s6-ipcserver-socketbinder</tt> program </h1>
+
+<p>
+<tt>s6-ipcserver-socketbinder</tt> binds a Unix domain
+socket, then executes a program.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-ipcserver-socketbinder [ -d | -D ] [ -b <em>backlog</em> ] <em>path</em> <em>prog...</em>
+</pre>
+
+<ul>
+ <li> s6-ipcserver-socketbinder creates a Unix domain socket of type SOCK_STREAM
+and binds it to <em>path</em>. It prepares the socket to accept
+connections by calling
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html">listen()</a>. </li>
+ <li> It then execs into <em>prog...</em> with the open socket
+as its standard input. </li>
+
+<h2> Options </h2>
+
+<ul>
+ <li> <tt>-d</tt>&nbsp;: allow instant rebinding to the same path
+even if it has been used not long ago - this is the SO_REUSEADDR flag to
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">setsockopt()</a>
+and is generally used with server programs. This is the default. Note that
+<em>path</em> will be deleted if it already exists at program start time. </li>
+ <li> <tt>-D</tt>&nbsp;: disallow instant rebinding to the same path. </li>
+ <li> <tt>-b&nbsp;<em>backlog</em></tt>&nbsp;: set a maximum of
+<em>backlog</em> backlog connections on the socket. Extra
+connection attempts will rejected by the kernel. </li>
+</ul>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> 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
+<a href="s6-ipcserverd.html">s6-ipcserverd</a> to accept connections
+from clients, or into a program such as
+<a href="http://skarnet.org/software/s6/s6-applyuidgid.html">s6-applyuidgid</a>
+to drop privileges before doing so. </li>
+ <li> The <a href="s6-ipcserver.html">s6-ipcserver</a> 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. </li>
+</ul>
+
+</body>
+</html>
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.
 </pre>
 
 <ul>
- <li> s6-ipcserver binds to a Unix domain socket on <em>path</em>. </li>
+ <li> s6-ipcserver binds a Unix domain socket to <em>path</em>. </li>
+ <li> It can drop its root privileges. </li>
  <li> It closes its stdin and stdout. </li>
  <li> For every client connection to this socket, it
 forks. The child sets some environment variables, then
@@ -41,32 +42,36 @@ stdout writing to it. </li>
  <li> Depending on the verbosity level, it logs what it does to stderr. </li>
  <li> It runs until killed by a signal. Depending on the received
 signal, it may kill its children before exiting. </li>
+ <li> 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. </li>
 </ul>
 
-<h2> Environment variables </h2>
-
-<p>
- For each connection, an instance of <em>prog...</em> is spawned with
-the following variables set:
-</p>
+<h2> Implementation </h2>
 
 <ul>
- <li> PROTO: always set to IPC </li>
- <li> IPCREMOTEEUID: set to the effective UID of the client,
-unless credentials lookups have been disabled </li>
- <li> IPCREMOTEEGID: set to the effective GID of the client,
-unless credentials lookups have been disabled </li>
- <li> IPCREMOTEPATH: set to the path associated with the remote socket,
-if any. Be aware that it may contain arbitrary characters. </li>
- <li> IPCCONNNUM: set to the number of connections originating from
-the same user (i.e. same uid) </li>
+ <li> 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. </li>
+ <li> The first program s6-ipcserver executes into is
+<a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>.
+It will create and bind a Unix domain socket to <em>path</em>, then
+execute into the rest of the command line. </li>
+ <li> If a privilege-dropping operation has been requested, the
+program that s6-ipcserver-socketbinder executes into is
+<a href="http://skarnet.org/software/s6/s6-applyuidgid.html">s6-applyuidgid</a>.
+It will drop the root privileges, then execute into the rest of the
+command line. </li>
+ <li> The next program in the chain is
+<a href="s6-ipcserverd.html">s6-ipcserverd</a>. 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. </li>
+ <li> For every client, s6-ipcserverd will spawn an instance of
+<em>prog...</em>, the remainder of the command line. </li>
 </ul>
 
-<p>
- If client credentials lookup has been disabled, IPCREMOTEEUID and
-IPCREMOTEEUID will be set, but empty.
-</p>
-
 
 <h2> Options </h2>
 
@@ -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. </li>
 </ul>
 
-<h2> Signals </h2>
+<h2> Implementation </h2>
 
 <ul>
- <li> SIGTERM: exit. </li>
- <li> SIGHUP: send a SIGTERM and a SIGCONT to all children. </li>
- <li> SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit. </li>
- <li> SIGABRT: send a SIGKILL to all children, then exit. </li>
+ <li> 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. </li>
+ <li> The first program s6-ipcserver executes into is
+<a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>.
+It will create and bind a Unix domain socket to <em>path</em>, then
+execute into the rest of the command line. </li>
+ <li> If a privilege-dropping operation has been requested, the
+program that s6-ipcserver-socketbinder executes into is
+<a href="http://skarnet.org/software/s6/s6-applyuidgid.html">s6-applyuidgid</a>.
+It will drop the root privileges, then execute into the rest of the
+command line. </li>
+ <li> The next program in the chain is
+<a href="s6-ipcserverd.html">s6-ipcserverd</a>. 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. </li>
+ <li> For every client, s6-ipcserverd will spawn an instance of
+<em>prog...</em>, the remainder of the command line. </li>
 </ul>
 
 <h2> Notes </h2>
 
 <ul>
- <li> Unlike his close cousin
-<a href="http://www.superscript.com/ucspi-ipc/ipcserver.html">ipcserver</a>,
-s6-ipcserver does not perform operations such as access control. Those are
-delegated to the
-<a href="s6-ipcserver-access.html">s6-ipcserver-access</a> program. </li>
- <li> s6-ipcserver can be used to set up
-<a href="localservice.html">local services</a>. </li>
+ <li> s6-ipcserver does not interpret its options itself. It just
+dispatches them to the appropriate program on the command line that
+it builds. </li>
+ <li> 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. </li>
 </ul>
 
 </body>
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 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-networking: the s6-ipcserverd program</title>
+    <meta name="Description" content="s6-networking: the s6-ipcserverd program" />
+    <meta name="Keywords" content="s6-networking s6-ipcserverd ipcserver ucspi unix server super-server" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>s6-ipcserverd</tt> program </h1>
+
+<p>
+<tt>s6-ipcserverd</tt> is the serving part of the
+<a href="s6-ipcserver.html">s6-ipcserver</a> 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.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-ipcserverd [ -1 ] [ -v verbosity ] [ -P | -p ] [ -c <em>maxconn</em> ] [ -C <em>localmaxconn</em> ] <em>prog...</em>
+</pre>
+
+<ul>
+ <li> s6-ipcserverd accepts connections from clients to an already
+bound and listening SOCK_STREAM Unix domain socket which is its
+standard input. </li>
+ <li> For every client connection to this socket, it
+forks. The child sets some environment variables, then
+executes <em>prog...</em> with stdin reading from the socket and
+stdout writing to it. </li>
+ <li> Depending on the verbosity level, it logs what it does to stderr. </li>
+ <li> It runs until killed by a signal. Depending on the received
+signal, it may kill its children before exiting. </li>
+</ul>
+
+<h2> Environment variables </h2>
+
+<p>
+ For each connection, an instance of <em>prog...</em> is spawned with
+the following variables set:
+</p>
+
+<ul>
+ <li> PROTO: always set to IPC </li>
+ <li> IPCREMOTEEUID: set to the effective UID of the client,
+unless credentials lookups have been disabled </li>
+ <li> IPCREMOTEEGID: set to the effective GID of the client,
+unless credentials lookups have been disabled </li>
+ <li> IPCREMOTEPATH: set to the path associated with the remote socket,
+if any. Be aware that it may contain arbitrary characters. </li>
+ <li> IPCCONNNUM: set to the number of connections originating from
+the same user (i.e. same uid) </li>
+</ul>
+
+<p>
+ If client credentials lookup has been disabled, IPCREMOTEEUID and
+IPCREMOTEEUID will be set, but empty.
+</p>
+
+
+<h2> Options </h2>
+
+<ul>
+ <li> <tt>-1</tt>&nbsp;: 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 <a href="http://skarnet.org/software/s6/s6-notifywhenup.html">s6-notifywhenup</a>
+program can be used before the s6-ipcserver
+invocation to notify listeners when the server is ready. </li>
+ <li> <tt>-v&nbsp;<em>verbosity</em></tt>&nbsp;: be more or less
+verbose. <em>verbosity</em> can be 0 (quiet), 1 (normal), or 2
+(verbose). </li>
+ <li> <tt>-P</tt>&nbsp;: disable client credentials lookups. The
+IPCREMOTEEUID and IPCREMOTEEGID environment variables will be unset
+in every instance of <em>prog...</em>. This is the portable option,
+because not every system supports credential lookup across Unix domain
+sockets; but it is not as secure. </li>
+ <li> <tt>-p</tt>&nbsp;: 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. </li>
+ <li> <tt>-c&nbsp;<em>maxconn</em></tt>&nbsp;: accept at most
+<em>maxconn</em> concurrent connections. Default is 40. It is
+impossible to set it higher than 1000. </li>
+ <li> <tt>-C&nbsp;<em>localmaxconn</em></tt>&nbsp;: accept at most
+<em>localmaxconn</em> connections from the same user ID.
+Default is 40. It is impossible to set it higher than <em>maxconn</em>. </li>
+</ul>
+
+<h2> Signals </h2>
+
+<ul>
+ <li> SIGTERM: exit. </li>
+ <li> SIGHUP: send a SIGTERM and a SIGCONT to all children. </li>
+ <li> SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit. </li>
+ <li> SIGABRT: send a SIGKILL to all children, then exit. </li>
+</ul>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> Unlike his close cousin
+<a href="http://www.superscript.com/ucspi-ipc/ipcserver.html">ipcserver</a>,
+s6-ipcserverd does not perform operations such as access control. Those are
+delegated to the
+<a href="s6-ipcserver-access.html">s6-ipcserver-access</a> program. </li>
+ <li> s6-ipcserverd can be used to set up
+<a href="localservice.html">local services</a>. </li>
+ <li> s6-ipcserverd is meant to be execve'd into by a program that gets
+the listening socket. That program is normally
+<a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>,
+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"). </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/s6-sudod.html b/doc/s6-sudod.html
index d896d87..c783736 100644
--- a/doc/s6-sudod.html
+++ b/doc/s6-sudod.html
@@ -124,6 +124,9 @@ VAR variable will be removed from the environment.) </li>
 and file descriptors over the socket. </li>
    <li> s6-sudod spawns <tt>sargv cargv</tt>. </li>
   </ul>
+ (Actually, <a href="s6-ipcserver.html">s6-ipcserver</a> does not do this
+itself: it executes into other programs that each do one of the tasks. But for
+our example, it does not matter.) </li>
 </ul>
 
 <p>
diff --git a/doc/s6-tcpserver-access.html b/doc/s6-tcpserver-access.html
index cb758d9..a89d9e3 100644
--- a/doc/s6-tcpserver-access.html
+++ b/doc/s6-tcpserver-access.html
@@ -36,7 +36,10 @@ just like tcpwrappers' <tt>tcpd</tt> program.
  <li> s6-tcpserver-access checks it is run under a UCSPI server tool
 such as <a href="s6-tcpserver.html">s6-tcpserver</a>,
  <a href="s6-tcpserver4.html">s6-tcpserver4</a> or
- <a href="s6-tcpserver6.html">s6-tcpserver6</a>. </li>
+ <a href="s6-tcpserver6.html">s6-tcpserver6</a>, or their
+ stripped-down versions
+ <a href="s6-tcpserver4d.html">s6-tcpserver4d</a> or
+ <a href="s6-tcpserver6d.html">s6-tcpserver6d</a>. </li>
  <li> It checks that the remote end of the connection fits the
 accepted criteria defined by the database contained in <em>rulesdir</em>
 or <em>rulesfile</em>. If the database tells it to reject the connection,
@@ -224,9 +227,9 @@ environment modifications, if any, s6-tcpserver-access execs into
 
 <ul>
  <li> s6-tcpserver-access works with
-<a href="s6-tcpserver4.html">s6-tcpserver4</a>, handling IPv4 addresses,
+<a href="s6-tcpserver4d.html">s6-tcpserver4d</a>, handling IPv4 addresses,
 as well as
-<a href="s6-tcpserver6.html">s6-tcpserver6</a>, handling IPv6 addresses.
+<a href="s6-tcpserver6d.html">s6-tcpserver6d</a>, handling IPv6 addresses.
 It will automatically detect the remote address type and match it against the
 correct subdatabase. </li>
  <li> s6-tcpserver-access may perform several DNS queries. For efficiency
diff --git a/doc/s6-tcpserver4-socketbinder.html b/doc/s6-tcpserver4-socketbinder.html
new file mode 100644
index 0000000..5cbbb07
--- /dev/null
+++ b/doc/s6-tcpserver4-socketbinder.html
@@ -0,0 +1,70 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-networking: the s6-tcpserver4-socketbinder program</title>
+    <meta name="Description" content="s6-networking: the s6-tcpserver4-socketbinder program" />
+    <meta name="Keywords" content="s6-networking s6-tcpserver4-socketbinder tcpserver ucspi inet ipv4 socket bind listen" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>s6-tcpserver4-socketbinder</tt> program </h1>
+
+<p>
+<tt>s6-tcpserver4-socketbinder</tt> binds an INET domain
+socket to an IPv4 address and port, then executes a program.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-tcpserver4-socketbinder [ -d | -D ] [ -b <em>backlog</em> ] <em>ip</em> <em>port</em> <em>prog...</em>
+</pre>
+
+<ul>
+ <li> s6-tcpserver4-socketbinder creates an TCP socket
+and binds it to IPv4 address <em>ip</em>, port <em>port</em>.
+It prepares the socket to accept connections by calling
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html">listen()</a>. </li>
+ <li> It then execs into <em>prog...</em> with the open socket
+as its standard input. </li>
+
+<h2> Options </h2>
+
+<ul>
+ <li> <tt>-d</tt>&nbsp;: 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
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">setsockopt()</a>
+and is generally used with server programs. This is the default. </li>
+ <li> <tt>-D</tt>&nbsp;: disallow instant rebinding to the same path. </li>
+ <li> <tt>-b&nbsp;<em>backlog</em></tt>&nbsp;: set a maximum of
+<em>backlog</em> backlog connections on the socket. Extra
+connection attempts will rejected by the kernel. </li>
+</ul>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> 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
+<a href="s6-tcpserver4d.html">s6-tcpserver4d</a> to accept connections
+from clients, or into a program such as
+<a href="http://skarnet.org/software/s6/s6-applyuidgid.html">s6-applyuidgid</a>
+to drop privileges before doing so. </li>
+ <li> The <a href="s6-tcpserver4.html">s6-tcpserver4</a> 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. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/s6-tcpserver4d.html b/doc/s6-tcpserver4d.html
new file mode 100644
index 0000000..018b921
--- /dev/null
+++ b/doc/s6-tcpserver4d.html
@@ -0,0 +1,112 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-networking: the s6-tcpserver4d program</title>
+    <meta name="Description" content="s6-networking: the s6-tcpserver4d program" />
+    <meta name="Keywords" content="s6-networking s6-tcpserver4d tcpserver ucspi tcp server super-server ipv4" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>s6-tcpserver4d</tt> program </h1>
+
+<p>
+<tt>s6-tcpserver4d</tt> is the serving part of the
+<a href="s6-tcpserver4.html">s6-tcpserver4</a> 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.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-tcpserver4d [ -1 ] [ -v <em>verbosity</em> ] [ -c <em>maxconn</em> ] [ -C <em>localmaxconn</em> ] <em>prog...</em>
+</pre>
+
+<ul>
+ <li> s6-tcpserver4d accepts connections from clients to an already
+bound and listening TCP socket which is its standard input. </li>
+ <li> For every TCP connection to this socket, it
+forks. The child sets some environment variables, then
+executes <em>prog...</em> with stdin reading from the network
+socket and stdout writing to it. </li>
+ <li> Depending on the verbosity level, it logs what it does to stderr. </li>
+ <li> It runs until killed by a signal. Depending on the received
+signal, it may kill its children before exiting. </li>
+</ul>
+
+<h2> Environment variables </h2>
+
+<p>
+ For each connection, an instance of <em>prog...</em> is spawned with
+the following variables set:
+</p>
+
+<ul>
+ <li> PROTO: always set to TCP </li>
+ <li> TCPREMOTEIP: set to the originating address </li>
+ <li> TCPREMOTEPORT: set to the originating port </li>
+ <li> TCPCONNNUM: set to the number of connections originating from
+the same IP address </li>
+</ul>
+
+<h2> Options </h2>
+
+<ul>
+ <li> <tt>-1</tt>&nbsp;: 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 <a href="http://skarnet.org/software/s6/s6-notifywhenup.html">s6-notifywhenup</a>
+program can be used before the s6-tcpserver
+invocation to notify listeners when the server is ready. </li>
+ <li> <tt>-v&nbsp;<em>verbosity</em></tt>&nbsp;: be more or less verbose.
+By default, <em>verbosity</em> is 1: print warning messages to stderr.
+0 means only print fatal error messages ; 2 means print status and
+connection information for every client. </li>
+ <li> <tt>-c&nbsp;<em>maxconn</em></tt>&nbsp;: accept at most
+<em>maxconn</em> concurrent connections. Default is 40. It is
+impossible to set it higher than 1000. </li>
+ <li> <tt>-C&nbsp;<em>localmaxconn</em></tt>&nbsp;: accept at most
+<em>localmaxconn</em> connections from the same IP address.
+Default is 40. It is impossible to set it higher than <em>maxconn</em>. </li>
+</ul>
+
+<h2> Signals </h2>
+
+<ul>
+ <li> SIGTERM: exit. </li>
+ <li> SIGHUP: send a SIGTERM and a SIGCONT to all children. </li>
+ <li> SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit. </li>
+ <li> SIGABRT: send a SIGKILL to all children, then exit. </li>
+</ul>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> Unlike its ancestor
+<a href="http://cr.yp.to/ucspi-tcp/tcpserver.html">tcpserver</a>,
+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 <a href="s6-tcpserver-access.html">s6-tcpserver-access</a>
+program. </li>
+ <li> s6-tcpserver4d is meant to be execve'd into by a program that gets
+the listening socket. That program is normally
+<a href="s6-tcpserver4-socketbinder.html">s6-tcpserver4-socketbinder</a>,
+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"). </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/s6-tcpserver6-socketbinder.html b/doc/s6-tcpserver6-socketbinder.html
new file mode 100644
index 0000000..0c0f8ee
--- /dev/null
+++ b/doc/s6-tcpserver6-socketbinder.html
@@ -0,0 +1,70 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-networking: the s6-tcpserver6-socketbinder program</title>
+    <meta name="Description" content="s6-networking: the s6-tcpserver6-socketbinder program" />
+    <meta name="Keywords" content="s6-networking s6-tcpserver6-socketbinder tcpserver ucspi inet ipv6 socket bind listen" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>s6-tcpserver6-socketbinder</tt> program </h1>
+
+<p>
+<tt>s6-tcpserver6-socketbinder</tt> binds an INET domain
+socket to an IPv6 address and port, then executes a program.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-tcpserver6-socketbinder [ -d | -D ] [ -b <em>backlog</em> ] <em>ip</em> <em>port</em> <em>prog...</em>
+</pre>
+
+<ul>
+ <li> s6-tcpserver6-socketbinder creates an TCP socket
+and binds it to IPv6 address <em>ip</em>, port <em>port</em>.
+It prepares the socket to accept connections by calling
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html">listen()</a>. </li>
+ <li> It then execs into <em>prog...</em> with the open socket
+as its standard input. </li>
+
+<h2> Options </h2>
+
+<ul>
+ <li> <tt>-d</tt>&nbsp;: 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
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">setsockopt()</a>
+and is generally used with server programs. This is the default. </li>
+ <li> <tt>-D</tt>&nbsp;: disallow instant rebinding to the same path. </li>
+ <li> <tt>-b&nbsp;<em>backlog</em></tt>&nbsp;: set a maximum of
+<em>backlog</em> backlog connections on the socket. Extra
+connection attempts will rejected by the kernel. </li>
+</ul>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> 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
+<a href="s6-tcpserver6d.html">s6-tcpserver6d</a> to accept connections
+from clients, or into a program such as
+<a href="http://skarnet.org/software/s6/s6-applyuidgid.html">s6-applyuidgid</a>
+to drop privileges before doing so. </li>
+ <li> The <a href="s6-tcpserver6.html">s6-tcpserver6</a> 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. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/s6-tcpserver6d.html b/doc/s6-tcpserver6d.html
new file mode 100644
index 0000000..46bc6c1
--- /dev/null
+++ b/doc/s6-tcpserver6d.html
@@ -0,0 +1,112 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-networking: the s6-tcpserver6d program</title>
+    <meta name="Description" content="s6-networking: the s6-tcpserver6d program" />
+    <meta name="Keywords" content="s6-networking s6-tcpserver6d tcpserver ucspi tcp server super-server ipv6" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>s6-tcpserver6d</tt> program </h1>
+
+<p>
+<tt>s6-tcpserver6d</tt> is the serving part of the
+<a href="s6-tcpserver6.html">s6-tcpserver6</a> 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.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-tcpserver6d [ -1 ] [ -v <em>verbosity</em> ] [ -c <em>maxconn</em> ] [ -C <em>localmaxconn</em> ] <em>prog...</em>
+</pre>
+
+<ul>
+ <li> s6-tcpserver6d accepts connections from clients to an already
+bound and listening TCP socket which is its standard input. </li>
+ <li> For every TCP connection to this socket, it
+forks. The child sets some environment variables, then
+executes <em>prog...</em> with stdin reading from the network
+socket and stdout writing to it. </li>
+ <li> Depending on the verbosity level, it logs what it does to stderr. </li>
+ <li> It runs until killed by a signal. Depending on the received
+signal, it may kill its children before exiting. </li>
+</ul>
+
+<h2> Environment variables </h2>
+
+<p>
+ For each connection, an instance of <em>prog...</em> is spawned with
+the following variables set:
+</p>
+
+<ul>
+ <li> PROTO: always set to TCP </li>
+ <li> TCPREMOTEIP: set to the originating address </li>
+ <li> TCPREMOTEPORT: set to the originating port </li>
+ <li> TCPCONNNUM: set to the number of connections originating from
+the same IP address </li>
+</ul>
+
+<h2> Options </h2>
+
+<ul>
+ <li> <tt>-1</tt>&nbsp;: 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 <a href="http://skarnet.org/software/s6/s6-notifywhenup.html">s6-notifywhenup</a>
+program can be used before the s6-tcpserver
+invocation to notify listeners when the server is ready. </li>
+ <li> <tt>-v&nbsp;<em>verbosity</em></tt>&nbsp;: be more or less verbose.
+By default, <em>verbosity</em> is 1: print warning messages to stderr.
+0 means only print fatal error messages ; 2 means print status and
+connection information for every client. </li>
+ <li> <tt>-c&nbsp;<em>maxconn</em></tt>&nbsp;: accept at most
+<em>maxconn</em> concurrent connections. Default is 40. It is
+impossible to set it higher than 1000. </li>
+ <li> <tt>-C&nbsp;<em>localmaxconn</em></tt>&nbsp;: accept at most
+<em>localmaxconn</em> connections from the same IP address.
+Default is 40. It is impossible to set it higher than <em>maxconn</em>. </li>
+</ul>
+
+<h2> Signals </h2>
+
+<ul>
+ <li> SIGTERM: exit. </li>
+ <li> SIGHUP: send a SIGTERM and a SIGCONT to all children. </li>
+ <li> SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit. </li>
+ <li> SIGABRT: send a SIGKILL to all children, then exit. </li>
+</ul>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> Unlike its ancestor
+<a href="http://cr.yp.to/ucspi-tcp/tcpserver.html">tcpserver</a>,
+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 <a href="s6-tcpserver-access.html">s6-tcpserver-access</a>
+program. </li>
+ <li> s6-tcpserver6d is meant to be execve'd into by a program that gets
+the listening socket. That program is normally
+<a href="s6-tcpserver6-socketbinder.html">s6-tcpserver6-socketbinder</a>,
+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"). </li>
+</ul>
+
+</body>
+</html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2015-01-07 19:01:26 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2015-01-07 19:01:26 +0000
commit	e9be34c9b798141dd6c224cf33934904935c49b2 (patch)
tree	969c243f85ef02d88bc4f54d9ab14cd323b7e9aa /doc
parent	e3aeb3b63b9996bd06c20861e1dac1c9421d9312 (diff)
download	s6-networking-e9be34c9b798141dd6c224cf33934904935c49b2.tar.xz