summaryrefslogtreecommitdiff
path: root/doc/s6-ipcserver.html
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2014-12-15 23:08:59 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2014-12-15 23:08:59 +0000
commite0fc82203d677a6f1e808e9a1a46176c109d89be (patch)
treee9609209b755e3f7a8480aea86601ffe9d4ca540 /doc/s6-ipcserver.html
downloads6-networking-e0fc82203d677a6f1e808e9a1a46176c109d89be.tar.xz
Initial commit
Diffstat (limited to 'doc/s6-ipcserver.html')
-rw-r--r--doc/s6-ipcserver.html148
1 files changed, 148 insertions, 0 deletions
diff --git a/doc/s6-ipcserver.html b/doc/s6-ipcserver.html
new file mode 100644
index 0000000..331b139
--- /dev/null
+++ b/doc/s6-ipcserver.html
@@ -0,0 +1,148 @@
+<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 program</title>
+ <meta name="Description" content="s6-networking: the s6-ipcserver program" />
+ <meta name="Keywords" content="s6-networking s6-ipcserver 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-ipcserver</tt> program </h1>
+
+<p>
+<tt>s6-ipcserver</tt> is an
+<a href="http://cr.yp.to/proto/ucspi.txt">UCSPI server tool</a> for
+Unix domain sockets, i.e. a super-server.
+It accepts connections from clients, and forks a
+program to handle each connection.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+ s6-ipcserver [ -1 ] [ -q | -Q | -v ] [ -d | -D ] [ -P | -p ] [ -c <em>maxconn</em> ] [ -C <em>localmaxconn</em> ] [ -b <em>backlog</em> ] [ -G <em>gidlist</em> ] [ -g <em>gid</em> ] [ -u <em>uid</em> ] [ -U ] <em>path</em> <em>prog...</em>
+</pre>
+
+<ul>
+ <li> s6-ipcserver binds to a Unix domain socket on <em>path</em>. </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
+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 <em>path</em>, followed by a newline,
+to stdout, before
+closing it, right after binding and listening to the Unix socket.
+If stdout is suitably redirected, this can be used by monitoring
+programs to check when the server is ready to accept connections. </li>
+ <li> <tt>-q</tt>&nbsp;: be quiet. </li>
+ <li> <tt>-Q</tt>&nbsp;: be normally verbose. This is the default. </li>
+ <li> <tt>-v</tt>&nbsp;: be verbose. </li>
+ <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>-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>
+ <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>
+ <li> <tt>-G&nbsp;<em>gidlist</em></tt>&nbsp;: change s6-ipcserver's
+supplementary group list to <em>gidlist</em> after binding the socket.
+This is only valid when run as root. <em>gidlist</em> must be a
+comma-separated list of numerical group IDs. </li>
+ <li> <tt>-g&nbsp;<em>gid</em></tt>&nbsp;: change s6-ipcserver's groupid
+to <em>gid</em> after binding the socket. This is only valid when run
+as root. </li>
+ <li> <tt>-u&nbsp;<em>uid</em></tt>&nbsp;: change s6-ipcserver's userid
+to <em>uid</em> after binding the socket. This is only valid when run
+as root. </li>
+ <li> <tt>-U</tt>&nbsp;: change s6-ipcserver'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
+<a href="http://skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a>
+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>
+
+<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-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>
+</ul>
+
+</body>
+</html>