s6-ipcserver.html (7145B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>s6: the s6-ipcserver program</title> 7 <meta name="Description" content="s6: the s6-ipcserver program" /> 8 <meta name="Keywords" content="s6 s6-ipcserver ipcserver ucspi unix server super-server" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">s6</a><br /> 15 <a href="//skarnet.org/software/">Software</a><br /> 16 <a href="//skarnet.org/">skarnet.org</a> 17 </p> 18 19 <h1> The <tt>s6-ipcserver</tt> program </h1> 20 21 <p> 22 <tt>s6-ipcserver</tt> is an 23 <a href="https://cr.yp.to/proto/ucspi.txt">UCSPI server tool</a> for 24 Unix domain sockets, i.e. a super-server. 25 It accepts connections from clients, and forks a 26 program to handle each connection. 27 </p> 28 29 <h2> Interface </h2> 30 31 <pre> 32 s6-ipcserver [ -1 ] [ -q | -Q | -v ] [ -d | -D ] [ -P | -p ] [ -a <em>perms</em> ] [ -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> 33 </pre> 34 35 <ul> 36 <li> s6-ipcserver binds a Unix domain socket to <em>path</em>. </li> 37 <li> It can drop its root privileges. </li> 38 <li> It closes its stdin and stdout. </li> 39 <li> For every client connection to this socket, it 40 forks. The child sets some environment variables, then 41 executes <em>prog...</em> with stdin reading from the socket and 42 stdout writing to it. </li> 43 <li> Depending on the verbosity level, it logs what it does to stderr. </li> 44 <li> It runs until killed by a signal. Depending on the received 45 signal, it may kill its children before exiting. </li> 46 <li> s6-ipcserver actually doesn't do any of this itself. It is 47 a wrapper, rewriting the command line and executing into a chain 48 of programs that perform those duties. </li> 49 </ul> 50 51 <h2> Implementation </h2> 52 53 <ul> 54 <li> s6-ipcserver parses the options and arguments it is given, and 55 builds a new command line with them. It then executes into that new 56 command line. </li> 57 <li> The first program s6-ipcserver executes into is 58 <a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>. 59 It will create and bind a Unix domain socket to <em>path</em>, then 60 execute into the rest of the command line. </li> 61 <li> If a privilege-dropping operation has been requested, the 62 program that s6-ipcserver-socketbinder executes into is 63 <a href="s6-applyuidgid.html">s6-applyuidgid</a>. 64 It will drop the root privileges, then execute into the rest of the 65 command line. </li> 66 <li> The next program in the chain is 67 <a href="s6-ipcserverd.html">s6-ipcserverd</a>. It is executed into 68 by s6-applyuidgid, or directly by s6-ipcserver-socketbinder if no 69 privilege-dropping operation has been requested. s6-ipcserverd is 70 the long-lived process, the "daemon" itself, accepting connections 71 from clients. </li> 72 <li> For every client, s6-ipcserverd will spawn an instance of 73 <em>prog...</em>, the remainder of the command line. </li> 74 </ul> 75 76 77 <h2> Options </h2> 78 79 <ul> 80 <li> <tt>-1</tt> : write a newline to stdout, before 81 closing it, right after binding and listening to the Unix socket. 82 If stdout is suitably redirected, this can be used by monitoring 83 programs to check when the server is ready to accept connections. </li> 84 <li> <tt>-q</tt> : be quiet. </li> 85 <li> <tt>-Q</tt> : be normally verbose. This is the default. </li> 86 <li> <tt>-v</tt> : be verbose. </li> 87 <li> <tt>-d</tt> : allow instant rebinding to the same path 88 even if it has been used not long ago - this is the SO_REUSEADDR flag to 89 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">setsockopt()</a> 90 and is generally used with server programs. This is the default. Note that 91 <em>path</em> will be deleted if it already exists at program start time. </li> 92 <li> <tt>-D</tt> : disallow instant rebinding to the same path. </li> 93 <li> <tt>-P</tt> : disable client credentials lookups. The 94 IPCREMOTEEUID and IPCREMOTEEGID environment variables will be unset 95 in every instance of <em>prog...</em>. This is the portable option, 96 because not every system supports credential lookup across Unix domain 97 sockets; but it is not as secure. </li> 98 <li> <tt>-p</tt> : enable client credentials lookups. This 99 is the default; it works at least on Linux, Solaris, and 100 *BSD systems. On systems that do not support it, every connection 101 attempt will fail with a warning message. </li> 102 <li> <tt>-c <em>maxconn</em></tt> : accept at most 103 <em>maxconn</em> concurrent connections. Default is 40. It is 104 impossible to set it higher than 1000. </li> 105 <li> <tt>-C <em>localmaxconn</em></tt> : accept at most 106 <em>localmaxconn</em> connections from the same user ID. 107 Default is 40. It is impossible to set it higher than <em>maxconn</em>. </li> 108 <li> <tt>-b <em>backlog</em></tt> : set a maximum of 109 <em>backlog</em> backlog connections on the socket. Extra 110 connection attempts will rejected by the kernel. </li> 111 <li> <tt>-a <em>perms</em></tt> : create the socket with 112 permissions <em>perms</em>, which is an octal number from 0000 to 0777. 113 Default is 0777, meaning everyone can connect to it. 0700 means only processes having the 114 same uid as the s6-ipcserver process can connect to it. </li> 115 <li> <tt>-G <em>gidlist</em></tt> : change s6-ipcserver's 116 supplementary group list to <em>gidlist</em> after binding the socket. 117 This is only valid when run as root. <em>gidlist</em> must be a 118 comma-separated list of numerical group IDs. </li> 119 <li> <tt>-g <em>gid</em></tt> : change s6-ipcserver's groupid 120 to <em>gid</em> after binding the socket. This is only valid when run 121 as root. </li> 122 <li> <tt>-u <em>uid</em></tt> : change s6-ipcserver's userid 123 to <em>uid</em> after binding the socket. This is only valid when run 124 as root. </li> 125 <li> <tt>-U</tt> : change s6-ipcserver's user id, group id and 126 supplementary group list 127 according to the values of the UID, GID and GIDLIST environment variables 128 after binding the socket. This is only valid when run as root. 129 This can be used with the 130 <a href="s6-envuidgid.html">s6-envuidgid</a> 131 program to easily script a service that binds to a privileged socket 132 then drops its privileges to those of a named non-root account. </li> 133 </ul> 134 135 <h2> Notes </h2> 136 137 <ul> 138 <li> s6-ipcserver does not interpret its options itself. It just 139 dispatches them to the appropriate program on the command line that 140 it builds. </li> 141 <li> Previous versions of s6-ipcserver were 142 monolithic: it did the work of s6-ipcserver-socketbinder, 143 s6-applyuidgid and s6-ipcserverd itself. The functionality has now 144 been split into several different programs because some service startup 145 schemes require the daemon to get its socket from an external 146 program instead of creating and binding it itself. The most obvious 147 application of this is upgrading a long-lived process without 148 losing existing connections. </li> 149 </ul> 150 151 </body> 152 </html>