diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 26 | ||||
| -rw-r--r-- | doc/libs6net/accessrules.html | 331 | ||||
| -rw-r--r-- | doc/libs6net/index.html | 2 | ||||
| -rw-r--r-- | doc/localservice.html | 151 | ||||
| -rw-r--r-- | doc/s6-accessrules-cdb-from-fs.html | 141 | ||||
| -rw-r--r-- | doc/s6-accessrules-fs-from-cdb.html | 60 | ||||
| -rw-r--r-- | doc/s6-connlimit.html | 96 | ||||
| -rw-r--r-- | doc/s6-ioconnect.html | 84 | ||||
| -rw-r--r-- | doc/s6-ipcclient.html | 65 | ||||
| -rw-r--r-- | doc/s6-ipcserver-access.html | 172 | ||||
| -rw-r--r-- | doc/s6-ipcserver-socketbinder.html | 72 | ||||
| -rw-r--r-- | doc/s6-ipcserver.html | 173 | ||||
| -rw-r--r-- | doc/s6-ipcserverd.html | 131 | ||||
| -rw-r--r-- | doc/s6-sudo.html | 59 | ||||
| -rw-r--r-- | doc/s6-sudoc.html | 80 | ||||
| -rw-r--r-- | doc/s6-sudod.html | 165 | ||||
| -rw-r--r-- | doc/s6-tcpserver-access.html | 18 | ||||
| -rw-r--r-- | doc/seekablepipe.html | 36 |
18 files changed, 13 insertions, 1849 deletions
diff --git a/doc/index.html b/doc/index.html index 3b65640..c6d61fa 100644 --- a/doc/index.html +++ b/doc/index.html @@ -45,7 +45,7 @@ compiled with IPv6 support, s6-networking is IPv6-ready. <li> <a href="http://skarnet.org/software/execline/">execline</a> version 2.0.1.1 or later </li> <li> <a href="http://skarnet.org/software/s6/">s6</a> version -2.0.1.0 or later </li> +2.0.2.0 or later </li> <li> <a href="http://skarnet.org/software/s6-dns/">s6-dns</a> version 2.0.0.2 or later </li> </ul> @@ -60,7 +60,7 @@ compiled with IPv6 support, s6-networking is IPv6-ready. <h3> Download </h3> <ul> - <li> The current released version of s6-networking is <a href="s6-networking-2.0.1.0.tar.gz">2.0.1.0</a>. </li> + <li> The current released version of s6-networking is <a href="s6-networking-2.1.0.0.tar.gz">2.1.0.0</a>. </li> <li> Alternatively, you can checkout a copy of the s6-networking git repository: <pre> git clone git://git.skarnet.org/s6-networking </pre> </li> </ul> @@ -102,7 +102,7 @@ relevant page. <li><a href="s6-taiclockd.html">The <tt>s6-taiclockd</tt> program</a></li> </ul> -<h4> UCSPI implementation </h4> +<h4> UCSPI TCP implementation </h4> <ul> <li><a href="s6-tcpclient.html">The <tt>s6-tcpclient</tt> program</a></li> @@ -113,29 +113,13 @@ relevant page. <li><a href="s6-tcpserver6.html">The <tt>s6-tcpserver6</tt> program</a></li> <li><a href="s6-tcpserver6-socketbinder.html">The <tt>s6-tcpserver6-socketbinder</tt> program</a></li> <li><a href="s6-tcpserver6d.html">The <tt>s6-tcpserver6d</tt> program</a></li> -<li><a href="s6-ipcclient.html">The <tt>s6-ipcclient</tt> program</a></li> -<li><a href="s6-ipcserver.html">The <tt>s6-ipcserver</tt> program</a></li> -<li><a href="s6-ipcserver-socketbinder.html">The <tt>s6-ipcserver-socketbinder</tt> program</a></li> -<li><a href="s6-ipcserverd.html">The <tt>s6-ipcserverd</tt> program</a></li> -<li><a href="s6-ioconnect.html">The <tt>s6-ioconnect</tt> program</a></li> </ul> -<h4> TCP and Unix access control </h4> +<h4> TCP access control </h4> <ul> <li><a href="s6-tcpserver-access.html">The <tt>s6-tcpserver-access</tt> program</a></li> <li><a href="s6-ipcserver-access.html">The <tt>s6-ipcserver-access</tt> program</a></li> -<li><a href="s6-connlimit.html">The <tt>s6-connlimit</tt> program</a></li> -<li><a href="s6-accessrules-cdb-from-fs.html">The <tt>s6-accessrules-cdb-from-fs</tt> program</a></li> -<li><a href="s6-accessrules-fs-from-cdb.html">The <tt>s6-accessrules-fs-from-cdb</tt> program</a></li> -</ul> - -<h4> suidless privilege gain </h4> - -<ul> -<li><a href="s6-sudo.html">The <tt>s6-sudo</tt> program</a></li> -<li><a href="s6-sudoc.html">The <tt>s6-sudoc</tt> program</a></li> -<li><a href="s6-sudod.html">The <tt>s6-sudod</tt> program</a></li> </ul> <h4> IDENT protocol implementation </h4> @@ -148,7 +132,6 @@ relevant page. <h4> Miscellaneous utilities </h4> <ul> -<li><a href="seekablepipe.html">The <tt>seekablepipe</tt> program</a></li> <li><a href="s6-getservbyname.html">The <tt>s6-getservbyname</tt> program</a></li> </ul> @@ -157,7 +140,6 @@ relevant page. <ul> <li> The <a href="libs6net/">s6net</a> library, containing: </li> <li> <a href="libs6net/ident.html">The <tt>ident</tt> library interface</a> </li> -<li> <a href="libs6net/accessrules.html">The <tt>accessrules</tt> library interface</a> </li> </ul> <hr /> diff --git a/doc/libs6net/accessrules.html b/doc/libs6net/accessrules.html deleted file mode 100644 index ea996b7..0000000 --- a/doc/libs6net/accessrules.html +++ /dev/null @@ -1,331 +0,0 @@ -<html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6-networking: the accessrules library interface</title> - <meta name="Description" content="s6-networking: the accessrules library interface" /> - <meta name="Keywords" content="s6-networking net accessrules library libs6net unix tcp access control dns ipv4 ipv6" /> - <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">libs6net</a><br /> -<a href="../">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>accessrules</tt> library interface </h1> - -<p> - The following functions and structures are declared in the <tt>s6-networking/accessrules.h</tt> header, -and implemented in the <tt>libs6net.a</tt> or <tt>libs6net.so</tt> library. -</p> - -<h2> General information </h2> - -<p> - <tt>s6net_accessrules</tt> is an access control library. It looks up -a key in a user-specified database, then returns a code depending on -whether the database allows access (in which case additional information -can also be returned), denies access, or does not contain the key. -</p> - -<p> - <tt>accessrules</tt> has been designed to be easily extensible to any -database format and any key format. -</p> - -<p> - Check the <tt>s6-networking/accessrules.h</tt> header for the exact definitions. -</p> - -<h2> Data structures </h2> - -<ul> - <li> A <tt>s6net_accessrules_result_t</tt> is a scalar that -can have the following values: S6NET_ACCESSRULES_ERROR, -S6NET_ACCESSRULES_DENY, S6NET_ACCESSRULES_ALLOW or S6NET_ACCESSRULES_NOTFOUND. </li> - <li> A <tt>s6net_accessrules_params_t</tt> is a structure containing two -<a href="http://skarnet.org/software/skalibs/libstddjb/stralloc.html">strallocs</a>, -<em>.env</em> and <em>.exec</em>, used to return data contained in the -database when a key has been allowed. The interpretation of this data is -application-defined. </li> -</ul> - -<h2> Function types </h2> - -<h3> Backend lookups </h3> - -<p> - A <tt>s6net_accessrules_backend_func_t</tt> is the type of a function -that takes a single key, looks it up in a database, and returns the result. -Namely: -</p> - -<p> -<code>s6net_accessrules_result_t f (char const *key, unsigned int keylen, void *handle, s6net_accessrules_params_t *params) </code> -</p> - -<p> - <em>f</em> looks up key <em>key</em> of length <em>keylen</em> in the database -represented by <em>handle</em> in an implementation-defined way. It returns a -number that says the key has been allowed, denied or not found, or an error -occurred. If the key has been allowed, <em>f</em> stores additional information -from the database into *<em>params</em>. -</p> - -<p> - Two s6net_accessrules_backend_func_t functions are natively implemented: -</p> - -<ul> - <li> <tt>s6net_accessrules_backend_fs</tt> takes a <tt>char const *</tt> -<em>handle</em> and interprets it as a base directory to look up <em>key</em> -under, in the format understood by -<a href="../s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a>. </li> - <li> <tt>s6net_accessrules_backend_cdb</tt> takes a <tt>struct cdb *</tt> -<em>handle</em> and looks up <em>key</em> in the -<a href="http://cr.yp.to/cdb.html">CDB</a> it points to. <em>handle</em> must -already be mapped to a CDB file. Such a file can be built with the -<a href="../s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> -utility. </li> -</ul> - -<h3> Frontend key checking </h3> - -<p> - A <tt>s6net_accessrules_keycheck_func_t</tt> is the type of a function that -takes a user-level key, makes a list of corresponding backend-level keys and -calls a <tt>s6net_accessrules_backend_func_t</tt> function until it finds -a match. Namely: -</p> - -<p> -<code>s6net_accessrules_result_t f (void const *key, void *handle, s6net_accessrules_params_t *params, s6net_accessrules_backend_func_t *backend) </code> -</p> - -<p> - <em>f</em> derives a list of low-level keys to check from <em>key</em>. -Then, for each key <em>k</em> of length <em>klen</em> in this list, it calls -<tt>(*backend)(k, klen, handle, params)</tt>, returning *<em>backend</em>'s result if it -is not S6NET_ACCESSRULES_NOTFOUND. If no match can be found in the whole list, -<em>f</em> finally returns S6NET_ACCESSRULES_NOTFOUND. -</p> - -<p> - Five s6net_accessrules_keycheck_func_t functions are natively implemented: -</p> - -<ul> - <li> -<a name="uidgid" /> - <tt>s6net_accessrules_keycheck_uidgid</tt> interprets <em>key</em> as a -<a href="http://skarnet.org/software/skalibs/libstddjb/">diuint</a>, i.e. a -structure containing two unsigned ints. The first one is interpreted as an -uid <em>u</em>, the second one as a gid <em>g</em>. The function first looks -for a <tt>uid/<em>u</em></tt> match; if it cannot find one, it looks for a -<tt>gid/<em>g</em></tt> match. If it cannot find one either, it checks -<tt>uid/default</tt> and returns the result. </li> - <li> -<a name="reversedns" /> - <tt>s6net_accessrules_keycheck_reversedns</tt> interprets <em>key</em> -as a string containing a FQDN. Then for each suffix <em>k</em> of <em>key</em>, -starting with <em>key</em> itself and ending with <em>key</em>'s TLD, -it looks up <tt>reversedns/<em>k</em></tt>. The final dot is excluded from -<em>k</em>. If no match can be found, the function checks <tt>reversedns/@</tt> -and returns the result. For instance, if <em>key</em> is "foo.bar.com", -the following strings are looked up, in that order: - <ul> - <li> reversedns/foo.bar.com </li> - <li> reversedns/bar.com </li> - <li> reversedns/com </li> - <li> reversedns/@ </li> - </ul> </li> - <li> -<a name="ip4" /> - <tt>s6net_accessrules_keycheck_ip4</tt> interprets <em>key</em> as -4 network-byte-order characters containing an IPv4 address. Then for each -netmask <em>mask</em> from 32 to 0, it constructs the IPv4 network -prefix <em>addr</em> corresponding to that address, and looks up -<tt>ip4/<em>addr</em>_<em>mask</em></tt>. For instance, if <em>key</em> -is "\300\250\001\007", representing the 192.168.1.7 address, the following -strings are looked up, in that order: - <ul> - <li> ip4/192.168.1.7_32 </li> - <li> ip4/192.168.1.6_31 </li> - <li> ip4/192.168.1.4_30 </li> - <li> ip4/192.168.1.0_29 </li> - <li> ip4/192.168.0.0_28 </li> - <li> ip4/192.168.0.0_27 </li> - </ul> - and so on, down to: - <ul> - <li> ip4/192.0.0.0_3 </li> - <li> ip4/192.0.0.0_2 </li> - <li> ip4/128.0.0.0_1 </li> - <li> ip4/0.0.0.0_0 </li> - </ul> - Note that the <tt>ip4/0.0.0.0_0</tt> string is a catch-all key that -matches everything. </li> - <li> -<a name="ip6" /> - <tt>s6net_accessrules_keycheck_ip6</tt> interprets <em>key</em> as -16 network-byte-order characters containing an IPv6 address. Then for each -netmask <em>mask</em> from 128 to 0, it constructs the IPv6 network -prefix <em>addr</em> corresponding to that address, -<strong>in canonical form</strong>, -and looks up -<tt>ip6/<em>addr</em>_<em>mask</em></tt>. For instance, if <em>key</em> -is "*\0\024P@\002\b\003\0\0\0\0\0\0\020\006", representing the -2a00:1450:4002:803::1006 address, the following -strings are looked up, in that order: - <ul> - <li> ip6/2a00:1450:4002:803::1006_128 </li> - <li> ip6/2a00:1450:4002:803::1006_127 </li> - <li> ip6/2a00:1450:4002:803::1004_126 </li> - <li> ip6/2a00:1450:4002:803::1000_125 </li> - <li> ip6/2a00:1450:4002:803::1000_124 </li> - <li> ip6/2a00:1450:4002:803::1000_123 </li> - <li> ip6/2a00:1450:4002:803::1000_122 </li> - <li> ip6/2a00:1450:4002:803::1000_121 </li> - <li> ip6/2a00:1450:4002:803::1000_120 </li> - <li> ip6/2a00:1450:4002:803::1000_119 </li> - <li> ip6/2a00:1450:4002:803::1000_118 </li> - <li> ip6/2a00:1450:4002:803::1000_117 </li> - <li> ip6/2a00:1450:4002:803::1000_116 </li> - <li> ip6/2a00:1450:4002:803::1000_115 </li> - <li> ip6/2a00:1450:4002:803::1000_114 </li> - <li> ip6/2a00:1450:4002:803::1000_113 </li> - <li> ip6/2a00:1450:4002:803::_112 </li> - <li> ip6/2a00:1450:4002:803::_111 </li> - </ul> - and so on, down to: - <ul> - <li> ip6/2a00::_11 </li> - <li> ip6/2800::_10 </li> - <li> ip6/2800::_9 </li> - <li> ip6/2000::_8 </li> - <li> ip6/2000::_7 </li> - <li> ip6/2000::_6 </li> - <li> ip6/2000::_5 </li> - <li> ip6/2000::_4 </li> - <li> ip6/2000::_3 </li> - <li> ip6/::_2 </li> - <li> ip6/::_1 </li> - <li> ip6/::_0 </li> - </ul> - Note that the <tt>ip6/::_0</tt> string is a catch-all key that -matches everything. </li> - <li> -<a name="ip46" /> - <tt>s6net_accessrules_keycheck_ip46</tt> interprets <em>key</em> as a pointer to an -<a href="http://skarnet.org/software/skalibs/libstddjb/ip46.html">ip46_t</a>, and -behaves either as s6net_accessrules_keycheck_ip6 or s6net_accessrules_keycheck_ip4, -depending on the type of address *<em>key</em> contains. </li> -</ul> - -<h2> Ready-to-use functions </h2> - - Those functions are mostly macros; they're built by associating a frontend -function with a backend function. - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_uidgid_cdb -(unsigned int u, unsigned int g, struct cdb *c, -s6net_accessrules_params_t *params) </code> <br /> -Checks the *<em>c</em> CDB database for an authorization for uid <em>u</em> -and gid <em>g</em>. If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_uidgid_fs -(unsigned int u, unsigned int g, char const *dir, -s6net_accessrules_params_t *params) </code> <br /> -Checks the <em>dir</em> base directory for an authorization for uid <em>u</em> -and gid <em>g</em>. If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_reversedns_cdb -(char const *name, struct cdb *c, -s6net_accessrules_params_t *params) </code> <br /> -Checks the *<em>c</em> CDB database for an authorization for the -<em>name</em> FQDN. If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_reversedns_fs -(char const *name, char const *dir, -s6net_accessrules_params_t *params) </code> <br /> -Checks the <em>dir</em> base directory for an authorization for the -<em>name</em> FQDN. If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_ip4_cdb -(char const *ip4, struct cdb *c, -s6net_accessrules_params_t *params) </code> <br /> -Checks the *<em>c</em> CDB database for an authorization for the -<em>ip4</em> IPv4 address (4 network byte order characters). -If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_ip4_fs -(char const *ip4, char const *dir, -s6net_accessrules_params_t *params) </code> <br /> -Checks the <em>dir</em> base directory for an authorization for the -<em>ip4</em> IPv4 address (4 network byte order characters). -If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_ip6_cdb -(char const *ip6, struct cdb *c, -s6net_accessrules_params_t *params) </code> <br /> -Checks the *<em>c</em> CDB database for an authorization for the -<em>ip6</em> IPv6 address (16 network byte order characters). -If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_ip6_fs -(char const *ip6, char const *dir, -s6net_accessrules_params_t *params) </code> <br /> -Checks the <em>dir</em> base directory for an authorization for the -<em>ip6</em> IPv6 address (16 network byte order characters). -If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_ip46_cdb -(ip46_t *ip, struct cdb *c, -s6net_accessrules_params_t *params) </code> <br /> -Checks the *<em>c</em> CDB database for an authorization for the -<em>ip</em> IP address. -If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -<p> -<code> s6net_accessrules_result_t s6net_accessrules_ip46_fs -(ip46_t const *ip, char const *dir, -s6net_accessrules_params_t *params) </code> <br /> -Checks the <em>dir</em> base directory for an authorization for the -<em>ip</em> IP address. -If the result is S6NET_ACCESSRULES_ALLOW, additional -information may be stored into <em>params</em>. -</p> - -</body> -</html> diff --git a/doc/libs6net/index.html b/doc/libs6net/index.html index 4fb35ff..36440ac 100644 --- a/doc/libs6net/index.html +++ b/doc/libs6net/index.html @@ -53,8 +53,6 @@ own header. </p> <ul> - <li> The <a href="accessrules.html">s6-networking/accessrules.h</a> header -provides function to check credentials against configuration files. </li> <li> The <a href="ident.html">s6-networking/ident.h</a> header provides a small IDENT client (RFC 1413). </li> </ul> diff --git a/doc/localservice.html b/doc/localservice.html deleted file mode 100644 index af7aafb..0000000 --- a/doc/localservice.html +++ /dev/null @@ -1,151 +0,0 @@ -<html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6-networking: what is a local service</title> - <meta name="Description" content="s6-networking: what is a local service" /> - <meta name="Keywords" content="s6-networking local service s6-ipcserver" /> - <!-- <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> Local services </h1> - -<p> - A <em>local service</em> is a daemon that listens to incoming connections -on a Unix domain socket. Clients of the service are programs connecting to -this socket: the daemon performs operations on their behalf. -</p> - -<p> - The service is called <em>local</em> because it is not accessible to -clients from the network. -</p> - -<p> - A widely known example of a local service is the <tt>syslogd</tt> daemon. -On most implementations, it listens to the <tt>/dev/log</tt> socket. -Its clients connect to it and send their logs via the socket. The -<tt>openlog()</tt> function is just a wrapper arround the <tt>connect()</tt> -system call, the <tt>syslog()</tt> function a wrapper around <tt>write()</tt>, -and so on. -</p> - -<h2> Benefits </h2> - -<h3> Privileges </h3> - -<p> - The most important benefit of a local service is that it permits -<strong>controlled privilege gains without using setuid programs</strong>. -The daemon is run as user S; a client running as user C and connecting to -the daemon asks it to perform operations: those will be done as user S. -</p> - -<p> - Standard Unix permissions on the listening socket can be used to implement -some basic access control: to restrict access to clients belonging to group -G, change the socket to user S and group G, and give it 0420 permissions. -This is functionally equivalent to the basic access control for setuid -programs: a program having user S, group G and permissions 4750 will be -executable by group G and run with S rights. -</p> - -<p> - But modern systems implement the -<a href="http://www.superscript.com/ucspi-ipc/getpeereid.html">getpeereid()</a> -system call or library function. This function allows the server to know the -client's credentials: so fine-grained access control is possible. On those -systems, <strong>local services can do as much authentication as setuid programs, -in a much more controlled environment</strong>. -</p> - -<h3> fd-passing </h3> - -<p> - The most obvious difference between a local service and a network service -is that a local service does not serve network clients. But local services -have another nice perk: while network services usually only provide you -with a single channel (a TCP or UDP socket) of communication between the -client and the server, forcing you to multiplex your data into that -channel, local services allow you to have as many -communication channels as you want. -</p> - -<p> -(The SCTP transport layer provides a way for network services to use -several communication channels. Unfortunately, it is not widely deployed -yet, and a lot of network services still depend on TCP.) -</p> - -<p> - The <em>fd-passing</em> mechanism is Unix domain socket black magic -that allows one peer of the socket to send open file descriptors to -the other peer. So, if the server opens a pipe and sends one end of -this pipe to a client via this mechanism, there is effectively a -socket <em>and</em> a pipe between the client and the server. -</p> - -<h2> UCSPI </h2> - -<p> - The <a href="http://cr.yp.to/proto/ucspi.txt">UCSPI</a> protocol -is an easy way of abstracting clients and servers from the network. -A server written as a UCSPI server, just as it can be run -under inetd or s6-tcpserver, can be run under -<a href="s6-ipcserver.html">s6-ipcserver</a>: choose a socket -location and you have a local service. -</p> - -<p> - Fine-grained access control can be added by inserting -<a href="s6-ipcserver-access.html">s6-ipcserver-access</a> in -your server command line after s6-ipcserver. -</p> - -<p> - A client written as an UCSPI client, i.e. assuming it has descriptor -6 (resp. 7) open and reading from (resp. writing to) the server socket, -can be run under <a href="s6-ipcclient.html">s6-ipcclient</a>. -</p> - -<h2> Use in skarnet.org software </h2> - -<p> - skarnet.org libraries often use a separate process to handle -asynchronicity and background work in a way that's invisible to -the user. Among them are: -</p> - -<ul> - <li> <a href="http://skarnet.org/software/s6/s6-ftrigrd.html">s6-ftrigrd</a>, -managing the reception of notifications and only waking up the client process -when the notification pattern matches a regular expression. </li> - <li> <a href="http://skarnet.org/software/s6/libs6lock/s6lockd.html">s6lockd</a>, -handling time-constrained lock acquisition on client behalf. </li> - <li> <a href="http://skarnet.org/software/s6-dns/skadns/skadnsd.html">skadnsd</a>, -performing asynchronous DNS queries and only waking up the client process -when an answer arrives. </li> -</ul> - -<p> - Those processes are usually spawned from a client, via the corresponding -<tt>*_startf*()</tt> library call. But they can also be spawned from a -s6-ipcserver program in a local service configuration. In both cases, they -need an additional control channel to be passed from the server to -the client: the main socket is used for synchronous commands from the client -to the server and their answers, whereas the additional channel, which is -now implemented as a socket as well (but created by the server on-demand -and not bound to a local path), is used for asynchronous -notifications from the server to the client. The fd-passing mechanism -is used to transfer the additional channel from the server to the client. -</p> - -</body> -</html> diff --git a/doc/s6-accessrules-cdb-from-fs.html b/doc/s6-accessrules-cdb-from-fs.html deleted file mode 100644 index 26105b1..0000000 --- a/doc/s6-accessrules-cdb-from-fs.html +++ /dev/null @@ -1,141 +0,0 @@ -<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-accessrules-cdb-from-fs program</title> - <meta name="Description" content="s6-networking: the s6-accessrules-cdb-from-fs program" /> - <meta name="Keywords" content="s6-networking s6-accessrules-cdb-from-fs tcp unix access control ipcrules tcprules cdb filesystem" /> - <!-- <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-accessrules-cdb-from-fs</tt> program </h1> - -<p> -<tt>s6-accessrules-cdb-from-fs</tt> compiles a directory -containing a ruleset suitable for -<a href="s6-ipcserver-access.html">s6-ipcserver-access<a> or -<a href="s6-tcpserver-access.html">s6-tcpserver-access<a> into a -<a href="http://en.wikipedia.org/wiki/Cdb_(software)">CDB file</a>. -</p> - -<h2> Interface </h2> - -<pre> - s6-accessrules-cdb-from-fs <em>cdbfile</em> <em>dir</em> -</pre> - -<ul> - <li> s6-accessrules-cdb-from-fs compiles the <em>dir</em> -directory containing a ruleset into a -<a href="http://en.wikipedia.org/wiki/Cdb_(software)">CDB file</a> -<em>cdbfile</em> then exits 0. </li> -</ul> - -<h2> Ruleset directory format </h2> - -<p> - To be understood by s6-accessrules-cdb-from-fs, -<a href="s6-ipcserver-access.html">s6-ipcserver-access<a>, or -<a href="s6-tcpserver-access.html">s6-tcpserver-access<a>, -<em>dir</em> must have a specific format. -</p> - -<p> - <em>dir</em> contains a series of directories: -</p> - -<ul> - <li> <tt>ip4</tt> for rules on IPv4 addresses </li> - <li> <tt>ip6</tt> for rules on IPv6 addresses </li> - <li> <tt>reversedns</tt> for rules on host names </li> - <li> <tt>uid</tt> for rules on user IDs </li> - <li> <tt>gid</tt> for rules on group IDs </li> -</ul> - -<p> -Depending on the application, other directories can appear in <em>dir</em> -and be compiled into <em>cdbfile</em>, but -<a href="s6-tcpserver-access.html">s6-tcpserver-access<a> only -uses the first three, and -<a href="s6-ipcserver-access.html">s6-ipcserver-access<a> only -uses the last two. -</p> - -<p> - Each of those directories contains a set of rules. A rule is -a subdirectory named after the set of keys it matches, and containing -actions that will be executed if the rule is the first matching rule -for the tested key. -</p> - -<p> - The syntax for the rule name is dependent on the nature of keys, and -fully documented on the -<a href="libs6net/accessrules.html">accessrules</a> -library page. For instance, a subdirectory named <tt>192.168.0.0_27</tt> -in the <tt>ip4</tt> directory will match every IPv4 address in the -192.168.0.0/27 network that does not match a more precise rule. -</p> - -<p> - The syntax for the actions, however, is the same for every type of key. -A rule subdirectory can contain the following elements: -</p> - -<ul> - <li> a file (that can be empty) named <tt>allow</tt>. If such a file exists, -a key matching this rule will be immediately accepted. </li> - <li> a file (that can be empty) named <tt>deny</tt>. If such a file exists and -no <tt>allow</tt> file exists, a key matching this rule will be immediately -denied. </li> - <li> a subdirectory named <tt>env</tt>. If such a directory exists along -with an <tt>allow</tt> file, then its contents represent environment -modifications that will be applied after accepting the connection and -before executing the next program in the chain, as if the -<a href="http://www.skarnet.org/software/s6/s6-envdir.html">s6-envdir</a> -program, without options, was applied to <tt>env</tt>. <tt>env</tt> -has exactly the same format as a directory suitable for s6-envdir; -however, if the modifications take up more than 4096 bytes when -compiled into <em>cdbfile</em>, then s6-accessrules-cdb-from-fs will -complain and exit 100. </li> - <li> a file named <tt>exec</tt>. If such a file exists along with an -<tt>allow</tt> file, then its contents represent a command line that, -interpreted by the -<a href="http://www.skarnet.org/software/execline/execlineb.html">execlineb</a> -launcher, will be executed after accepting the connection, totally bypassing the -original command line. s6-accessrules-cdb-from-fs truncates the <tt>exec</tt> -file to 4096 bytes max when embedding it into <em>cdbfile</em>, so make -sure it is not larger than that. </li> -</ul> - -<h2> Notes </h2> - -<ul> - <li> <em>cdbfile</em> can exist prior to, and during, the compilation, -which actually works in a temporary file in the same directory as -<em>cdbfile</em> and performs an atomic replacement when it is done. -So it is not necessary to interrupt a running service during the -compilation. </li> - <li> If s6-accessrules-cdb-from-fs fails at some point, the temporary -file is removed. However, this doesn't happen if -s6-accessrules-cdb-from-fs is interrupted by a signal. </li> - <li> After the program successfully completes, if <em>dir</em> -was a suitable candidate for the <tt>-i</tt> option of -<a href="s6-ipcserver-access.html">s6-ipcserver-access</a> or -<a href="s6-tcpserver-access.html">s6-tcpserver-access</a>, then -<em>cdbfile</em> will be a suitable candidate for the <tt>-x</tt> option -of the same program, implementing the same ruleset. </li> - <li> <em>cdbfile</em> can be decompiled by the -<a href="s6-accessrules-fs-from-cdb.html">s6-accessrules-fs-from-cdb</a> -program. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-accessrules-fs-from-cdb.html b/doc/s6-accessrules-fs-from-cdb.html deleted file mode 100644 index 91ec98e..0000000 --- a/doc/s6-accessrules-fs-from-cdb.html +++ /dev/null @@ -1,60 +0,0 @@ -<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-accessrules-fs-from-cdb program</title> - <meta name="Description" content="s6-networking: the s6-accessrules-fs-from-cdb program" /> - <meta name="Keywords" content="s6-networking s6-accessrules-fs-from-cdb tcp unix access control ipcrules tcprules cdb filesystem" /> - <!-- <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-accessrules-fs-from-cdb</tt> program </h1> - -<p> -<tt>s6-accessrules-fs-from-cdb</tt> decompiles a CDB database -containing a ruleset suitable for -<a href="s6-ipcserver-access.html">s6-ipcserver-access<a> or -<a href="s6-tcpserver-access.html">s6-tcpserver-access<a> and -that has been compiled with -<a href="s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs<a>. -</p> - -<h2> Interface </h2> - -<pre> - s6-accessrules-fs-from-cdb <em>dir</em> <em>cdbfile</em> -</pre> - -<ul> - <li> s6-accessrules-fs-from-cdb decompiles the -<a href="http://en.wikipedia.org/wiki/Cdb_(software)">CDB file</a> -<em>cdbfile</em> into the directory <em>dir</em>, then exits 0. </li> -</ul> - -<h2> Notes </h2> - -<ul> - <li> <em>dir</em> must not exist prior to the decompilation. </li> - <li> <em>dir</em> must be considered as a work in progress as long as -s6-accessrules-fs-from-cdb is running. It is only safe to use <em>dir</em> -as a ruleset once the program has exited. </li> - <li> If s6-accessrules-fs-from-cdb fails at some point, the partial -arborescence at <em>dir</em> is removed. However, this doesn't happen if -s6-accessrules-fs-from-cdb is interrupted by a signal. </li> - <li> After the program successfully completes, if <em>cdbfile</em> -was a suitable candidate for the <tt>-x</tt> option of -<a href="s6-ipcserver-access.html">s6-ipcserver-access</a> or -<a href="s6-tcpserver-access.html">s6-tcpserver-access</a>, then -<em>dir</em> will be a suitable candidate for the <tt>-i</tt> option -of the same program, implementing the same ruleset. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-connlimit.html b/doc/s6-connlimit.html deleted file mode 100644 index 5008b4d..0000000 --- a/doc/s6-connlimit.html +++ /dev/null @@ -1,96 +0,0 @@ -<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-connlimit program</title> - <meta name="Description" content="s6-networking: the s6-connlimit program" /> - <meta name="Keywords" content="s6-networking connection limit s6-connlimit" /> - <!-- <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-connlimit</tt> program </h1> - -<p> -<tt>s6-connlimit</tt> is a small utility to perform IP-based -control on the number of client connections to a TCP socket, and -uid-based control on the number of client connections to a Unix -domain socket. -</p> - -<h2> Interface </h2> - -<pre> - s6-connlimit <em>prog...</em> -</pre> - -<ul> - <li> <tt>s6-connlimit</tt> reads its environment for the PROTO -environment variable, and then for ${PROTO}CONNNUM and ${PROTO}CONNMAX, -which must contain integers. </li> - <li> If the value of ${PROTO}CONNNUM is superior or equal to the value -of ${PROTO}CONNMAX, s6-connlimit exits 1 with an error message. </li> - <li> Else it execs into <em>prog...</em>. </li> - <li> If ${PROTO}CONNMAX is unset, s6-connlimit directly execs into -<em>prog...</em> without performing any check: -no maximum number of connections has been defined. </li> -</ul> - -<h2> Usage </h2> - -<p> - The <a href="s6-tcpserver4.html">s6-tcpserver4</a> and -<a href="s6-tcpserver6.html">s6-tcpserver6</a> define the PROTO environment -variable to "TCP", and spawn every child server with the TCPCONNNUM environment -variable set to the number of connections from the same IP address. - The <a href="s6-tcpserver-access.html">s6-tcpserver-access</a> program -can set environment variables depending on the client's IP address. If the -s6-tcpserver-access database is configured to set the TCPCONNMAX environment -variable for a given set of IP addresses, and s6-tcpserver-access execs into -s6-connlimit, then s6-connlimit will drop connections if there already are -${TCPCONNMAX} connections from the same client IP address. -</p> - -<p> - The <a href="s6-ipcserver.html">s6-ipcserver</a> and -<a href="s6-ipcserver-access.html">s6-ipcserver-access</a> programs can -be used the same way, with "IPC" instead of "TCP", to limit the number -of client connections by UID. -</p> - -<h2> Example </h2> - -<p> - The following command line: -</p> - -<pre> - s6-tcpserver4 -v2 -c1000 -C40 1.2.3.4 80 \ - s6-tcpserver-access -v2 -RHl0 -i <em>dir</em> \ - s6-connlimit \ - <em>prog...</em> -</pre> - -<p> - will run a server listening to IPv4 address 1.2.3.4, on port 80, -serving up to 1000 concurrent connections, and up to 40 concurrent -connections from the same IP address, no matter what the IP address. -For every client connection, it will look up the database set up -in <em>dir</em>; if the connection is accepted, it will run <em>prog...</em>. -</p> - -<p> - If the <tt><em>dir</em>/ip4/5.6.7.8_32/env/TCPCONNMAX</tt> file -exists and contains the string <tt>30</tt>, then at most 30 concurrent -connections from 5.6.7.8 will execute <em>prog...</em>, instead of the -default of 40. -</p> - -</body> -</html> diff --git a/doc/s6-ioconnect.html b/doc/s6-ioconnect.html deleted file mode 100644 index 5e2b6c6..0000000 --- a/doc/s6-ioconnect.html +++ /dev/null @@ -1,84 +0,0 @@ -<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-ioconnect program</title> - <meta name="Description" content="s6-networking: the s6-ioconnect program" /> - <meta name="Keywords" content="s6-networking ioconnect ucspi tcpconnect ipcconnect" /> - <!-- <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-ioconnect</tt> program </h1> - -<p> -<tt>s6-ioconnect</tt> performs full-duplex data transmission -between two sets of open file descriptors. -</p> - -<h2> Interface </h2> - -<pre> - s6-ioconnect [ -t <em>millisecs</em> ] [ -r <em>fdr</em> ] [ -w <em>fdw</em> ] [ -0 ] [ -1 ] [ -6 ] [ -7 ] -</pre> - -<ul> - <li> s6-ioconnect reads data from its stdin and writes it as is to -file descriptor 7, which is assumed to be open. </li> - <li> It also reads data from its file descriptor 6, which is assumed -to be open, and writes it as is to its stdout. </li> - <li> When both sides have transmitted EOF and s6-ioconnect has -flushed its buffers, it exits 0. </li> -</ul> - -<h2> Options </h2> - -<ul> - <li> <tt>-t <em>millisecs</em></tt> : if no activity on -either side happens for <em>millisecs</em> milliseconds, s6-ioconnect -closes the connection on both ends and exits 1. By default, -<em>millisecs</em> is 0, which means no such timeout. </li> - <li> <tt>-r <em>fdr</em></tt> : Use fd <em>fdr</em> for -"remote" reading instead of fd 6. </li> - <li> <tt>-w <em>fdw</em></tt> : Use fd <em>fdw</em> for -"remote" writing instead of fd 7. </li> - <li> <tt>-0</tt>: assume stdin is a socket and needs to be shut down -for reading after an EOF. </li> - <li> <tt>-1</tt>: assume stdout is a socket and needs to be shut down -for writing to correctly transmit an EOF. </li> - <li> <tt>-6</tt>: assume the remote reading fd is a socket and needs to be shut down -for reading after an EOF. </li> - <li> <tt>-7</tt>: assume the remote writing fd is a socket and needs to be shut down -for writing to correctly transmit an EOF. </li> -</ul> - -<h2> Notes </h2> - -<ul> - <li> Transmitting EOF across full-duplex sockets -<a href="http://cr.yp.to/tcpip/twofd.html">is ugly</a>. The right thing -in every case cannot be automatically determined, so it is up to the user -to mention that a socket must be shut down. Most of the time, though, -shutting down sockets after EOF <em>is</em> the right thing to do, so -<tt>s6-ioconnect -67</tt> should be the common use case. </li> - <li> The point of s6-ioconnect is to be used together with -<a href="s6-tcpclient.html">s6-tcpclient</a> or -<a href="s6-ipcclient.html">s6-ipcclient</a> to establish a full- -duplex connection between the client and the server, for instance -for testing purposes. <tt>s6-ioconnect</tt> is to s6-tcpclient as -<tt>cat</tt> is to s6-tcpserver: a program that will just echo -what it gets. </li> - <li> On modern Linux systems, s6-ioconnect will perform zero-copy -data transmission, via the -<a href="http://man7.org/linux/man-pages/man2/splice.2.html">splice</a> -system call. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-ipcclient.html b/doc/s6-ipcclient.html deleted file mode 100644 index 2bb66aa..0000000 --- a/doc/s6-ipcclient.html +++ /dev/null @@ -1,65 +0,0 @@ -<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-ipcclient program</title> - <meta name="Description" content="s6-networking: the s6-ipcclient program" /> - <meta name="Keywords" content="s6-networking s6-ipcclient ipcclient ucspi unix client" /> - <!-- <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-ipcclient</tt> program </h1> - -<p> -<tt>s6-ipcclient</tt> is an -<a href="http://cr.yp.to/proto/ucspi.txt">UCSPI client tool</a> for -Unix domain sockets. It connects to a socket, then executes into -a program. -</p> - -<h2> Interface </h2> - -<pre> - s6-ipcclient [ -q | -Q | -v ] [ -p bindpath ] [ -l localname ] <em>path</em> <em>prog...</em> -</pre> - -<ul> - <li> s6-ipcclient connects to a Unix domain socket on <em>path</em>. </li> - <li> It executes into <em>prog...</em> with descriptor 6 reading from -the socket and descriptor 7 writing to it. </li> -</ul> - -<h2> Environment variables </h2> - -<p> - <em>prog...</em> is run with -the following variables set: -</p> - -<ul> - <li> PROTO: always set to IPC </li> - <li> IPCLOCALPATH: set to the path associated with the local socket, -if any. Be aware that it may contain arbitrary characters. </li> -</ul> - -<h2> Options </h2> - -<ul> - <li> <tt>-q</tt> : be quiet. </li> - <li> <tt>-Q</tt> : be normally verbose. This is the default. </li> - <li> <tt>-v</tt> : be verbose. </li> - <li> <tt>-p <em>localpath</em></tt> : bind the local -socket to <em>localpath</em> before connecting to <em>path</em>. </li> - <li> <tt>-l <em>localname</em></tt> : use <em>localname</em> -as the value of the IPCLOCALPATH environment variable. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-ipcserver-access.html b/doc/s6-ipcserver-access.html deleted file mode 100644 index 515138c..0000000 --- a/doc/s6-ipcserver-access.html +++ /dev/null @@ -1,172 +0,0 @@ -<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-access program</title> - <meta name="Description" content="s6-networking: the s6-ipcserver-access program" /> - <meta name="Keywords" content="s6-networking s6-tcpserver-access unix access control ipcrules" /> - <!-- <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-access</tt> program </h1> - -<p> -<tt>s6-ipcserver-access</tt> is a command-line access -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-ipcserverd.html">s6-ipcserverd</a> and before -the application program on the s6-ipcserver command line. -</p> - -<h2> Interface </h2> - -<pre> - s6-ipcserver-access [ -v <em>verbosity</em> ] [ -E | -e ] [ -l <em>localname</em> ] [ -i <em>rulesdir</em> | -x <em>rulesfile</em> ] <em>prog...</em> -</pre> - -<ul> - <li> s6-ipcserver-access checks it is run under a UCSPI server tool -such as <a href="s6-ipcserver.html">s6-ipcserver</a>. - <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, -the program exits 1. </li> - <li> It sets up a few additional environment variables. </li> - <li> It executes into <em>prog...</em>, -unless the first matching rule in the rule database -includes instructions to override <em>prog...</em>. </li> -</ul> - -<h2> Environment variables </h2> - -<p> -s6-ipcserver-access expects to inherit some environment variables from -its parent: -</p> - -<ul> - <li> PROTO: normally IPC, but could be anything else, like UNIX. </li> - <li> ${PROTO}REMOTEEUID: the effective UID of the client program connecting to the socket. </li> - <li> ${PROTO}REMOTEEGID: the effective GID of the client program connecting to the socket. </li> -</ul> - -<p> - Additionally, it exports the following variables before executing into -<em>prog...</em>: -</p> - -<ul> - <li> ${PROTO}LOCALPATH: set to the local "address" of the socket, as -reported by the -<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html">getsockname()</a> -system call, truncated to 99 characters max. </li> -</ul> - -<p> - Also, the access rules database can instruct s6-ipcserver-access to set -up, or unset, more environment variables, depending on the client address. -</p> - -<h2> Options </h2> - -<ul> - <li> <tt>-v <em>verbosity</em></tt> : be more or less verbose, i.e. -print more or less information to stderr: - <ul> - <li> 0: only log error messages. </li> - <li> 1: only log error and warning messages, and accepted connections. -This is the default. </li> - <li> 2: also log rejected connections and more warning messages. </li> - </ul> </li> - <li> <tt>-E</tt> : no environment. All environment variables potentially -set by s6-ipcserver-access, as well as those set by -<a href="s6-ipcserver.html">s6-ipcserver</a>, will be unset instead. </li> - <li> <tt>-e</tt> : set up environment variables normally. -This is the default. </li> - <li> <tt>-l <em>localname</em></tt> : use <em>localname</em> -as the value for the ${PROTO}LOCALPATH environment variable, instead of -looking it up via getsockname(). </li> - <li> <tt>-i <em>rulesdir</em></tt> : check client credentials -against a filesystem-based database in the <em>rulesdir</em> directory. </li> - <li> <tt>-x <em>rulesfile</em></tt> : check client credentials -against a <a href="http://en.wikipedia.org/wiki/Cdb_(software)">cdb</a> -database in the <em>rulesfile</em> file. <tt>-i</tt> and <tt>-x</tt> are -mutually exclusive. If none of those options is given, no credential checking will be -performed, and a warning will be emitted on every connection if -<em>verbosity</em> is 2 or more. </li> -</ul> - -<h2> Access rule checking </h2> - -<p> - s6-ipcserver-access checks its client connection against -a ruleset. This ruleset can be implemented: -</p> - -<ul> - <li> either in the filesystem as an arborescence of directories and files, -if the <tt>-i</tt> option has been given. This option is the most flexible -one: the directory format is simple enough for scripts to understand and -modify it, and the ruleset can be changed dynamically. This is practical, -for instance, for roaming users. </li> -<li> or in a <a href="http://en.wikipedia.org/wiki/Cdb_(software)">CDB -file</a>, if the <tt>-x</tt> option has been given. This option is the most -efficient one if the ruleset is static enough: a lot less system calls are -needed to perform searches in a CDB than in the filesystem. </li> -</ul> - -<p> - The exact format of the ruleset is described on the -<a href="s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> page. -</p> - -<p> -s6-ipcserver-access first reads the client UID <em>uid</em> and -GID <em>gid</em> from the -${PROTO}REMOTEEUID and ${PROTO}REMOTEEGID environment variables, and checks -them with the -<a href="libs6net/accessrules.html#uidgid">s6net_accessrules_keycheck_uidgid()</a> -function. In other words, it tries to match: - -<ul> - <li> <tt>uid/</tt><em>uid</em> </li> - <li> <tt>gid/</tt><em>gid</em> </li> - <li> <tt>uid/default</tt> </li> -</ul> - -<p> - in that order. If no S6NET_ACCESSRULES_ALLOW result can be obtained, -the connection is denied. -</p> - -<h2> Environment and executable modifications </h2> - -<p> - s6-ipcserver-access interprets non-empty <tt>env</tt> subdirectories -and <tt>exec</tt> files -it finds in the first matching rule of the ruleset, as explained -in the <a href="s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> -page. -</p> - -<ul> - <li> An <tt>env</tt> subdirectory is interpreted as if the -<a href="http://skarnet.org/software/s6/s6-envdir.html">s6-envdir</a> -command had been called before executing <em>prog</em>: the environment -is modified according to the contents of <tt>env</tt>. </li> - <li> An <tt>exec</tt> file containing <em>newprog</em> completely -bypasses the rest of s6-ipcserver-access' command line. After -environment modifications, if any, s6-ipcserver-access execs into -<tt><a href="http://skarnet.org/software/execline/execlineb.html">execlineb</a> -c <em>newprog</em></tt>. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-ipcserver-socketbinder.html b/doc/s6-ipcserver-socketbinder.html deleted file mode 100644 index 2c8d993..0000000 --- a/doc/s6-ipcserver-socketbinder.html +++ /dev/null @@ -1,72 +0,0 @@ -<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> -</ul> - -<h2> Options </h2> - -<ul> - <li> <tt>-d</tt> : 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> : disallow instant rebinding to the same path. </li> - <li> <tt>-b <em>backlog</em></tt> : 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 deleted file mode 100644 index 4b52888..0000000 --- a/doc/s6-ipcserver.html +++ /dev/null @@ -1,173 +0,0 @@ -<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 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 -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> - <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> Implementation </h2> - -<ul> - <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> Options </h2> - -<ul> - <li> <tt>-1</tt> : 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> : be quiet. </li> - <li> <tt>-Q</tt> : be normally verbose. This is the default. </li> - <li> <tt>-v</tt> : be verbose. </li> - <li> <tt>-d</tt> : 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> : disallow instant rebinding to the same path. </li> - <li> <tt>-P</tt> : 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> : 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 <em>maxconn</em></tt> : accept at most -<em>maxconn</em> concurrent connections. Default is 40. It is -impossible to set it higher than 1000. </li> - <li> <tt>-C <em>localmaxconn</em></tt> : 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 <em>backlog</em></tt> : set a maximum of -<em>backlog</em> backlog connections on the socket. Extra -connection attempts will rejected by the kernel. </li> - <li> <tt>-G <em>gidlist</em></tt> : 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 <em>gid</em></tt> : 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 <em>uid</em></tt> : 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> : 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> Implementation </h2> - -<ul> - <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> 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> -</html> diff --git a/doc/s6-ipcserverd.html b/doc/s6-ipcserverd.html deleted file mode 100644 index 916de12..0000000 --- a/doc/s6-ipcserverd.html +++ /dev/null @@ -1,131 +0,0 @@ -<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> : 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 <em>verbosity</em></tt> : be more or less -verbose. <em>verbosity</em> can be 0 (quiet), 1 (normal), or 2 -(verbose). </li> - <li> <tt>-P</tt> : 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> : 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 <em>maxconn</em></tt> : accept at most -<em>maxconn</em> concurrent connections. Default is 40. It is -impossible to set it higher than 1000. </li> - <li> <tt>-C <em>localmaxconn</em></tt> : 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-sudo.html b/doc/s6-sudo.html deleted file mode 100644 index 603ad8a..0000000 --- a/doc/s6-sudo.html +++ /dev/null @@ -1,59 +0,0 @@ -<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-sudo program</title> - <meta name="Description" content="s6-networking: the s6-sudo program" /> - <meta name="Keywords" content="s6-networking s6-sudo sudo setuid suid unix privilege gain getpeereid" /> - <!-- <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-sudo</tt> program </h1> - -<p> -<tt>s6-sudo</tt> connects to a Unix domain socket and passes -its standard file descriptors, command-line arguments and -environment to a program running on the server side, potentially -with different privileges. -</p> - -<h2> Interface </h2> - -<pre> - s6-sudo [ -q | -Q | -v ] [ -p <em>bindpath</em> ] [ -l <em>localname</em> ] [ -e ] [ -t <em>timeoutconn</em> ] [ -T <em>timeoutrun</em> ] <em>path</em> [ <em>args...</em> ] -</pre> - -<ul> - <li> s6-sudo executes into <tt><a href="s6-ipcclient.html">s6-ipcclient</a> <em>path</em> -<a href="s6-sudoc.html">s6-sudoc</a> args...</tt> It does nothing else: it is just a -convenience program. The <a href="s6-ipcclient.html">s6-ipcclient</a> program connects -to a Unix socket at <em>path</em>, and the -<a href="s6-sudoc.html">s6-sudoc program</a> transmits the desired elements over the -socket. </li> - <li> It should be used to connect to a -<a href="localservice.html">local service</a> running the -<a href="s6-sudod.html">s6-sudod</a> program, which will run a server program on the -client's behalf. </li> -</ul> - -<h2> Options </h2> - -<ul> - <li> The <tt>-q</tt>, <tt>-Q</tt>, <tt>-v</tt>, <tt>-p</tt> and </tt>-l</tt> -options are passed to <a href="s6-ipcclient.html">s6-ipcclient</a>. </li> - <li> The <tt>-e</tt>, <tt>-t</tt> and <tt>-T</tt> options are passed to -<a href="s6-sudoc.html">s6-sudoc</a>. </li> - <li> Command-line arguments, if any, are also passed to -<a href="s6-sudoc.html">s6-sudoc</a>, which will transmit them to -<a href="s6-sudod.html">s6-sudod</a> over the socket. -</ul> - -</body> -</html> diff --git a/doc/s6-sudoc.html b/doc/s6-sudoc.html deleted file mode 100644 index def09a9..0000000 --- a/doc/s6-sudoc.html +++ /dev/null @@ -1,80 +0,0 @@ -<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-sudoc program</title> - <meta name="Description" content="s6-networking: the s6-sudoc program" /> - <meta name="Keywords" content="s6-networking s6-sudoc sudo setuid suid unix privilege gain getpeereid client" /> - <!-- <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-sudoc</tt> program </h1> - -<p> -<tt>s6-sudoc</tt> talks to a peer <a href="s6-sudod.html">s6-sudod</a> -program over a Unix socket, passing it command-line arguments, environment -variables and standard descriptors. -</p> - -<h2> Interface </h2> - -<pre> - s6-sudoc [ -e ] [ -t <em>timeoutconn</em> ] [ -T <em>timeoutrun</em> ] [ <em>args...</em> ] -</pre> - -<ul> - <li> s6-sudoc transmits its standard input, standard output and standard error -via fd-passing over a Unix socket that must be open on its descriptors 6 and 7. - It expects a <a href="s6-sudod.html">s6-sudod</a> process to be receiving them -on the other side. </li> -<li> It also transmits its command-line arguments <em>args</em>, and also its -environment by default. Note that s6-sudod will not necessarily accept all the -environment variables that s6-sudoc tries to transmit. </li> - <li> s6-sudoc waits for the server program run by s6-sudod to finish. It exits -the same exit code as the server program. If the server program is killed by a -signal, s6-sudoc kills itself with the same signal. </li> -</ul> - -<h2> Options </h2> - -<ul> - <li> <tt>-e</tt> : do not attempt to transmit any environment variables -to <a href="s6-sudod.html">s6-sudod</a>. </li> - <li> <tt>-t <em>timeoutconn</em></tt> : if s6-sudod has not -managed to process the given information and start the server program after -<em>timeoutconn</em> milliseconds, give up. By default, <em>timeoutconn</em> -is 0, meaning infinite. Note that there is no reason to set up a nonzero -<em>timeoutconn</em> with a large value: s6-sudod is not supposed to block. -The option is only there to protect against ill-written services. </li> - <li> <tt>-T <em>timeoutrun</em></tt> : if the server program -has not exited after <em>timeoutrun</em> milliseconds, give up. By -default, <em>timeoutrun</em> is 0, meaning infinite. </li> -</ul> - -<h2> Notes </h2> - -<ul> - <li> If s6-sudoc is killed, or exits after <em>timeoutrun</em> milliseconds, -while the server program is still running, s6-sudod will send a SIGTERM and a -SIGCONT to the server program - but this does not guarantee that it will die. -If the server program keeps running, it might still read from the file that -was s6-sudoc's stdin, or write to the files that were s6-sudoc's stdout or -stderr. <strong>This is a potential security risk</strong>. -Administrators should audit their server programs to make sure this does not -happen. </li> - <li> More generally, anything using signals or terminals will not be -handled transparently by the s6-sudoc + s6-sudod mechanism. The mechanism -was designed to allow programs to gain privileges in specific situations: -short-lived, simple, noninteractive processes. It was not designed to emulate -the full suid functionality and will not go out of its way to do so. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-sudod.html b/doc/s6-sudod.html deleted file mode 100644 index c783736..0000000 --- a/doc/s6-sudod.html +++ /dev/null @@ -1,165 +0,0 @@ -<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-sudod program</title> - <meta name="Description" content="s6-networking: the s6-sudod program" /> - <meta name="Keywords" content="s6-networking s6-sudod sudo setuid suid unix privilege gain getpeereid 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-sudod</tt> program </h1> - -<p> -<tt>s6-sudod</tt> receives command-line arguments, environment variables -and standard descriptors from a peer <a href="s6-sudoc.html">s6-sudoc</a> -program over a Unix socket, then forks another program. -</p> - -<h2> Interface </h2> - -<pre> - s6-sudod [ -0 ] [ -1 ] [ -2 ] [ -s ] [ -t <em>timeout</em> ] [ <em>sargv...</em> ] -</pre> - -<ul> - <li> s6-sudod gets 3 file descriptors via fd-passing over a Unix socket that -must be open on its descriptors 0 and 1. (The received descriptors will be the -stdin, stdout and stderr of the server program.) It expects a -<a href="s6-sudoc.html">s6-sudoc</a> process to be sending them on the -client side. </li> - <li> It also receives a list of command-line arguments <em>cargv...</em>, and -an environment <em>clientenv</em>. </li> - <li> s6-sudod forks and executes <em>sargv...</em> <em>cargv</em>... -The client command line is appended to the server command line. </li> - <li> s6-sudod waits for its child to exit and transmits its exit code -to the peer <a href="s6-sudoc.html">s6-sudoc</a> process. It then exits 0. </li> -</ul> - -<h2> Environment </h2> - -<p> -s6-sudod transmits its own environment to its child, plus the environment sent -by <a href="s6-sudoc.html">s6-sudoc</a>, filtered in the following manner: -for every variable sent by <a href="s6-sudoc.html">s6-sudoc</a>, if the -variable is <strong>present but empty</strong> in s6-sudod's environment, then -its value is overriden by the value given by s6-sudoc. A variable that is -already nonempty, or that doesn't exist, in s6-sudod's environment, will not -be transmitted to the child. -</p> - -<h2> Options </h2> - -<ul> - <li> <tt>-0</tt> : do not inherit stdin from s6-sudoc. The child will be -run with its stdin pointing to <tt>/dev/null</tt> instead. </li> - <li> <tt>-1</tt> : do not inherit stdout from s6-sudoc. The child will be -run with its stdout pointing to <tt>/dev/null</tt> instead. </li> - <li> <tt>-2</tt> : do not inherit stderr from s6-sudoc. The child will be -run with its stderr being a copy of s6-sudod's stderr instead. (This is useful -to still log the child's error messages without sending them to the client.) </li> - <li> <tt>-t <em>timeout</em></tt> : if s6-sudod has not -received all the needed data from the client after <em>timeout</em> -milliseconds, it will exit without spawning a child. By default, <em>timeout</em> -is 0, meaning infinite. This mechanism exists to protect the server from -malicious or buggy clients that would uselessly consume resources. </li> -</ul> - -<h2> Usage example </h2> - -<p> - The typical use of s6-sudod is in a -<a href="localservice.html">local service</a> with a -<a href="s6-ipcserver.html">s6-ipcserver</a> process listening on a Unix -socket, a <a href="s6-ipcserver-access.html">s6-ipcserver-access</a> process -performing client authentication and access control, and possibly a -<a href="http://skarnet.org/software/s6/s6-envdir.html">s6-envdir</a> -process setting up the environment variables that will be accepted by -s6-sudod. The following script, meant to be a <em>run script</em> in a -<a href="http://skarnet.org/software/s6/servicedir.html">service directory</a>, -will set up a privileged program: -</p> - -<pre> -#!/command/execlineb -P -fdmove -c 2 1 -s6-envuidgid serveruser -s6-ipcserver -U -- serversocket -s6-ipcserver-access -v2 -l0 -i rules -- -exec -c -s6-envdir env -s6-sudod -sargv -</pre> - -<ul> - <li> <a href="http://skarnet.org/software/execline/execlineb.html">execlineb</a> -executes the script. </li> - <li> <a href="http://skarnet.org/software/execline/fdmove.html">fdmove</a> makes -sure the script's error messages are sent to the service's logger. </li> - <li> <a href="http://skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a> -sets the UID, GID and GIDLIST environment variables for s6-ipcserver to interpret. </li> - <li> <a href="s6-ipcserver.html">s6-ipcserver</a> binds to <em>serversocket</em> -and drops its privileges to those of <em>serveruser</em>. Then, for every client -connecting to <em>serversocket</em>: - <ul> - <li> <a href="s6-ipcserver-access.html">s6-ipcserver-access</a> checks the -client's credentials according to the rules in directory <em>rules</em>. - <li> <a href="http://skarnet.org/software/execline/exec.html">exec -c</a> -clears the environment. </li> - <li> <a href="http://skarnet.org/software/s6/s6-envdir.html">s6-envdir</a> -sets environment variables according to the directory <em>env</em>. You can -make sure that a variable VAR will be present but empty by performing -<tt>echo > env/VAR</tt>. (A single newline is interpreted by s6-envdir as -an empty variable; whereas if <tt>env/VAR</tt> is totally empty, then the -VAR variable will be removed from the environment.) </li> - <li> s6-sudod reads a command line <em>cargv</em>, a client environment -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> - This means that user <em>clientuser</em> running -<tt><a href="s6-sudo.html">s6-sudo</a> serversocket cargv</tt> will be -able, if authorized by the configuration in <em>rules</em>, to run -<tt>sargv cargv</tt> as user <em>serveruser</em>, with stdin, -stdout, stderr and the environment variables properly listed in <em>env</em> -transmitted to <em>sargv</em>. -</p> - -<h2> Notes </h2> - -<ul> - <li> If s6-sudoc is killed, or exits after <em>timeoutrun</em> milliseconds, -while the server program is still running, s6-sudod will send a SIGTERM and a -SIGCONT to its child, then exit 1. However, sending a SIGTERM to the child -does not guarantee that it will die; and -if it keeps running, it might still read from the file that -was s6-sudoc's stdin, or write to the files that were s6-sudoc's stdout or -stderr. <strong>This is a potential security risk</strong>. -Administrators should audit their server programs to make sure this does not -happen. </li> - <li> More generally, anything using signals or terminals will not be -handled transparently by the s6-sudoc + s6-sudod mechanism. The mechanism -was designed to allow programs to gain privileges in specific situations: -short-lived, simple, noninteractive processes. It was not designed to emulate -the full suid functionality and will not go out of its way to do so. </li> - <li> <em>sargv</em> may be empty. In that case, the client is in complete -control of the command line executed as <em>serveruser</em>. This setup is -permitted by s6-sudod, but it is very dangerous, and extreme attention should -be paid to the construction of the s6-ipcserver-access rules. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-tcpserver-access.html b/doc/s6-tcpserver-access.html index a89d9e3..435c92d 100644 --- a/doc/s6-tcpserver-access.html +++ b/doc/s6-tcpserver-access.html @@ -163,13 +163,13 @@ needed to perform searches in a CDB than in the filesystem. </li> <p> The exact format of the ruleset is described on the -<a href="s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> page. +<a href="http://skarnet.org/software/s6/s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> page. </p> <p> s6-tcpserver-access first gets the remote address <em>ip</em> of the client and converts it to canonical form. Then it checks it with the -<a href="libs6net/accessrules.html#ip4">s6net_accessrules_keycheck_ip46()</a> +<a href="http://skarnet.org/software/s6/libs6/accessrules.html#ip4">s6_accessrules_keycheck_ip46()</a> function. In other words, it tries to match broader and broader network prefixes of <em>ip</em>, from <tt>ip4/</tt><em>ip</em><tt>_32</tt> to <tt>ip4/0.0.0.0_0</tt> if <em>ip</em> is v4, or from @@ -177,10 +177,10 @@ prefixes of <em>ip</em>, from <tt>ip4/</tt><em>ip</em><tt>_32</tt> to is v6. If the result is: </p> - <li> S6NET_ACCESSRULES_ERROR: it immediately exits 111. </li> - <li> S6NET_ACCESSRULES_DENY: it immediately exits 1. </li> - <li> S6NET_ACCESSRULES_ALLOW: it grants access. </li> - <li> S6NET_ACCESSRULES_NOTFOUND: more information is needed. </li> + <li> S6_ACCESSRULES_ERROR: it immediately exits 111. </li> + <li> S6_ACCESSRULES_DENY: it immediately exits 1. </li> + <li> S6_ACCESSRULES_ALLOW: it grants access. </li> + <li> S6_ACCESSRULES_NOTFOUND: more information is needed. </li> </ul> <p> @@ -188,12 +188,12 @@ is v6. If the result is: is denied. But if s6-tcpserver-access is authorized to perform DNS lookups, then it gets the remote name of the client, <em>remotehost</em>, and checks it with the -<a href="libs6net/accessrules.html#reversedns">s6net_accessrules_keycheck_reversedns()</a> +<a href="http://skarnet.org/software/s6/libs6/accessrules.html#reversedns">s6_accessrules_keycheck_reversedns()</a> function. In other words, it tries to match shorter and shorter suffixes of <em>remotehost</em>, from <tt>reversedns/</tt><em>remotehost</em> to <tt>reversedns/@</tt>. This time, the connection is denied is the result is anything else than -S6NET_ACCESSRULES_ALLOW. +S6_ACCESSRULES_ALLOW. </p> <p> @@ -208,7 +208,7 @@ query on <em>remotehost</em> does not match <em>ip</em>. s6-tcpserver-access interprets non-empty <tt>env</tt> subdirectories and <tt>exec</tt> files it finds in the matching rule of the ruleset, as explained -in the <a href="s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> +in the <a href="http://skarnet.org/software/s6/s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> page. </p> diff --git a/doc/seekablepipe.html b/doc/seekablepipe.html deleted file mode 100644 index cd17b2e..0000000 --- a/doc/seekablepipe.html +++ /dev/null @@ -1,36 +0,0 @@ -<html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6-networking: the seekablepipe program</title> - <meta name="Description" content="s6-networking: the seekablepipe program" /> - <meta name="Keywords" content="s6-networking seekablepipe pipe seekablepipe-io" /> - <!-- <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>seekablepipe</tt> program </h1> - -<tt>seekablepipe</tt> turns the reading end of a pipe into a seekable -file descriptor, using a temporary file. - -<h2> Interface </h2> - -<pre> - <em>writer</em> | seekablepipe <em>tmpfile reader [ args ... ]</em> -</pre> - -<p> -<tt>seekablepipe</tt> writes <em>writer</em>'s output to <em>tmpfile</em>, -which is unlinked as soon as it is created. Then it execs into -<em>reader</em>, reading from a file descriptor on <em>tmpfile</em>. -</p> - -</body> -</html> |