diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2014-12-15 23:08:59 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska-skaware@skarnet.org> | 2014-12-15 23:08:59 +0000 |
| commit | e0fc82203d677a6f1e808e9a1a46176c109d89be (patch) | |
| tree | e9609209b755e3f7a8480aea86601ffe9d4ca540 /doc | |
| download | s6-networking-e0fc82203d677a6f1e808e9a1a46176c109d89be.tar.xz | |
Initial commit
Diffstat (limited to 'doc')
30 files changed, 3293 insertions, 0 deletions
diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..93d68ce --- /dev/null +++ b/doc/index.html @@ -0,0 +1,182 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-networking - small networking utilities</title> + <meta name="Description" content="s6-networking - small networking utilities" /> + <meta name="Keywords" content="s6-networking network utilities tcpclient tcpserver s6 ucspi unix linux laurent bercot ska skarnet" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">www.skarnet.org</a> +</p> + +<h1> s6-networking </h1> + +<h2> What is it ? </h2> + +<p> + s6-networking is a suite of small networking utilities for Unix systems. +It includes command-line client and server management, TCP access +control, privilege escalation across UNIX domain sockets, IDENT +protocol management and clock synchronization. +</p> + +<p> + If the underlying +<a href="http://skarnet.org/software/skalibs/">skalibs</a> has been +compiled with IPv6 support, s6-networking is IPv6-ready. +</p> + +<hr /> + +<h2> Installation </h2> + +<h3> Requirements </h3> + +<ul> + <li> A POSIX-compliant system with a standard C development environment </li> + <li> GNU make, version 3.81 or later </li> + <li> <a href="http://skarnet.org/software/skalibs/">skalibs</a> version +2.0.0.0 or later </li> + <li> <a href="http://skarnet.org/software/execline/">execline</a> version +2.0.0.0 or later </li> + <li> <a href="http://skarnet.org/software/s6-dns/">s6-dns</a> version +2.0.0.0 or later </li> +</ul> + +<h3> Licensing </h3> + +<p> + s6-networking is free software. It is available under the +<a href="http://opensource.org/licenses/ISC">ISC license</a>. +</p> + +<h3> Download </h3> + +<ul> + <li> The current released version of s6-networking is <a href="s6-networking-2.0.0.0.tar.gz">2.0.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> + +<h3> Compilation </h3> + +<ul> + <li> See the enclosed INSTALL file for installation details. </li> +</ul> + +<h3> Upgrade notes </h3> + +<ul> + <li> <a href="upgrade.html">This page</a> lists the differences to be aware of between +the previous versions of s6-networking and the current one. </li> +</ul> + +<h2> Reference </h2> + +<h3> Commands </h3> + +<p> + All these commands exit 111 if they encounter a temporary error or +hardware error, and +100 if they encounter a permanent error - such as a misuse. Short-lived +commands exit 0 on success. Other exit codes are documented in the +relevant page. +</p> + +<h4> System clock synchronization </h4> + +<ul> +<li><a href="s6-clockadd.html">The <tt>s6-clockadd</tt> program</a></li> +<li><a href="s6-clockview.html">The <tt>s6-clockview</tt> program</a></li> +<li><a href="s6-sntpclock.html">The <tt>s6-sntpclock</tt> program</a> </li> +<li><a href="s6-taiclock.html">The <tt>s6-taiclock</tt> program</a></li> +<li><a href="s6-taiclockd.html">The <tt>s6-taiclockd</tt> program</a></li> +</ul> + +<h4> UCSPI implementation </h4> + +<ul> +<li><a href="s6-tcpclient.html">The <tt>s6-tcpclient</tt> program</a></li> +<li><a href="s6-tcpserver.html">The <tt>s6-tcpserver</tt> program</a></li> +<li><a href="s6-tcpserver4.html">The <tt>s6-tcpserver4</tt> program</a></li> +<li><a href="s6-tcpserver6.html">The <tt>s6-tcpserver6</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-ioconnect.html">The <tt>s6-ioconnect</tt> program</a></li> +</ul> + +<h4> TCP and Unix 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> + +<ul> +<li><a href="s6-ident-client.html">The <tt>s6-ident-client</tt> program</a></li> +<li><a href="minidentd.html">The <tt>minidentd</tt> program</a></li> +</ul> + +<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> + +<h3> Libraries </h3> + +<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 /> + +<a name="related"> +<h2> Related resources </h2> +</a> + +<h3> s6-networking discussion </h3> + +<ul> + <li> <tt>s6-networking</tt> is discussed on the +<a href="http://skarnet.org/lists.html#skaware">skaware</a> mailing-list. </li> + <li> <tt>s6-networking</tt> has a +<a href="http://freecode.com/projects/s6-networking">freecode page</a>. + </li> +</ul> + +<h3> Similar work </h3> + +<ul> + <li> <a href="http://cr.yp.to/ucspi-tcp.html">ucspi-tcp</a> is the +original inspiration for s6-networking. +It works, but is unfortunately unmaintained by the author. s6-networking +follows <a href="http://skarnet.org/software/skalibs/djblegacy.html">the +same design principles</a>. </li> + <li> <a href="http://smarden.org/ipsvd/">ipsvd</a> is a very similar program +suite. </li> +</ul> + +</body> +</html> diff --git a/doc/libs6net/accessrules.html b/doc/libs6net/accessrules.html new file mode 100644 index 0000000..ea996b7 --- /dev/null +++ b/doc/libs6net/accessrules.html @@ -0,0 +1,331 @@ +<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/ident.html b/doc/libs6net/ident.html new file mode 100644 index 0000000..74a9217 --- /dev/null +++ b/doc/libs6net/ident.html @@ -0,0 +1,124 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-networking: the ident library interface</title> + <meta name="Description" content="s6-networking: the ident library interface" /> + <meta name="Keywords" content="s6-networking net ident library libs6net ident RFC 1413" /> + <!-- <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>ident</tt> library interface </h1> + +<p> + The following functions and structures are declared in the <tt>s6-networking/ident.h</tt> header, +and implemented in the <tt>libs6net.a</tt> or <tt>libs6net.so</tt> library. +</p> + +<h2> General information </h2> + +<p> + <tt>ident</tt> provides a C IDENT client, following RFC 1413. +</p> + +<p> + Please note that this protocol is of historical interest exclusively; +this client, as well as the <a href="../minidentd.html">minidentd</a> +server, is only provided for convenience and interoperability with +legacy systems. The IDENT protocol absolutely cannot be relied on for +any kind of authentication or secure operation. +</p> + +<h2> Functions </h2> + +<p> + Check the <tt>s6-networking/ident.h</tt> header for the exact function prototypes. +</p> + +<h3> Main interface </h3> + +<p> +<code> int s6net_ident_client (char *s, unsigned int max, ip46_t const *remoteip, uint16 remoteport, ip46_t const *localip, uint16 localport, +struct taia const *deadline, struct taia *stamp) </code> +</p> + +<p> +Makes an IDENT request to a server listening on IP <em>remoteip</em> port 113 +about the connection from IP <em>remoteip</em> port <em>remoteport</em> to +IP <em>localip</em> port <em>localport</em>. Writes the answer into +preallocated string <em>s</em> of max length <em>max</em>, and returns the +number of bytes in the answer. +</p> + +<ul> + <li> An <a href="http://skarnet.org/software/skalibs/libstddjb/ip46.html">ip46_t</a> +is a structure holding either an IPv4 address or an IPv6 address. </li> + <li> If an error occurs, the function returns -1 and sets errno to a +suitable value. If no answer can be gotten from the server, the function +returns 0 and sets errno to a suitable value. </li> + <li> If <em>max</em> is too small for <em>s</em> to hold the answer, the +function returns -1 ENAMETOOLONG. +This can be avoided by using S6NET_IDENT_REPLY_SIZE +as <em>max</em>. </li> + <li> Negative answers are mapped to errno in the following way: + <ul> + <li> INVALID-PORT is reported as EINVAL </li> + <li> NO-USER is reported as ESRCH </li> + <li> HIDDEN-USER is reported as EPERM </li> + <li> UNKNOWN-ERROR is reported as EIO </li> + <li> extended error codes are reported as EEXIST </li> + </ul> </li> + <li> *<em>deadline</em> and *<em>stamp</em> are +<a href="http://skarnet.org/software/skalibs/libstddjb/tai.h">absolute dates</a>: +*<em>stamp</em> must be an accurate enough approximation of the current time, and +is automatically updated when the function returns. If no answer has been gotten +from the server by *<em>deadline</em>, then the call is aborted and returns +-1 ETIMEDOUT. </li> +</ul> + +<p> +<code> char const *s6net_ident_error_str (int e) </code> +</p> + +<p> + Maps an error code representing a negative answer (i.e. errno when +<tt>s6net_ident_client</tt> returned 0) to a suitable string. +</p> + +<h3> Low-level functions </h3> + +<p> +<code> int s6net_ident_reply_get (char *s, ip46_t const *ra, uint16 rp, ip46_t const *la, uint16 lp, +struct taia const *deadline, struct taia *stamp) </code> +</p> + +<p> +The network part of <tt>s6net_ident_client</tt>. Connects to *<em>ra</em>:113 +and asks the server about (*<em>ra</em>:<em>rp</em>, *<em>la</em>:<em>lp</em>), +aborting if *<em>deadline</em> goes by. Writes the server answer into <em>s</em>; +at least S6NET_IDENT_REPLY_SIZE bytes must be preallocated in <em>s</em>. +Returns -1 if an error occurs, or the number of bytes written into <em>s</em>. +</p> + +<p> +<code> int s6net_ident_reply_parse (char const *s, uint16 rp, uint16 lp) </code> +</p> + +<p> +The local part of <tt>s6net_ident_client</tt>. Parses the server answer in +<em>s</em> for the connection from port <em>rp</em> to port <em>lp</em>. +Returns -1 EPROTO if the answer does not make sense, 0 if the answer is +negative, or a positive number if the answer is positive. This number is +an index where the ID can be found in <em>s</em>. +</p> + +</body> +</html> diff --git a/doc/libs6net/index.html b/doc/libs6net/index.html new file mode 100644 index 0000000..7a6a75b --- /dev/null +++ b/doc/libs6net/index.html @@ -0,0 +1,63 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-networking: the s6net library interface</title> + <meta name="Description" content="s6-networking: the s6net library interface" /> + <meta name="Keywords" content="s6-networking net s6net library libs6net" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<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>s6net</tt> library interface </h1> + +<h2> General information </h2> + +<p> + <tt>libs6net</tt> is a collection of networking-related utility +C interfaces, used in the s6-networking executables. +</p> + +<h2> Compiling </h2> + +<ul> + <li> Make sure the s6-networking headers, as well as the skalibs headers, +are visible in your header search path. </li> + <li> Use <tt>#include <s6-networking/s6net.h></tt> </li> +</ul> + +<h2> Linking </h2> + +<ul> + <li> Make sure the s6-networking libraries, as well as the skalibs +libraries, are visible in your library search path. </li> + <li> Link against <tt>-ls6net</tt>, <tt>-lskarnet</tt>, </li> +<tt>`cat $SYSDEPS/socket.lib`</tt> and +<tt>`cat $SYSDEPS/tainnow.lib`</tt>, $SYSDEPS being your skalibs +sysdeps directory. </li> +</ul> + +<h2> Programming </h2> + +<p> + The <tt>s6-networking/s6net.h</tt> header is actually a +concatenation of other headers: +the libs6net is separated into several modules, each of them with its +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> + +</body> +</html> diff --git a/doc/localservice.html b/doc/localservice.html new file mode 100644 index 0000000..af7aafb --- /dev/null +++ b/doc/localservice.html @@ -0,0 +1,151 @@ +<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/minidentd.html b/doc/minidentd.html new file mode 100644 index 0000000..e23fa86 --- /dev/null +++ b/doc/minidentd.html @@ -0,0 +1,83 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-networking: the minidentd program</title> + <meta name="Description" content="s6-networking: the minidentd program" /> + <meta name="Keywords" content="s6-networking minidentd identd ident server rfc 1413" /> + <!-- <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>minidentd</tt> program </h1> + +<p> +<tt>minidentd</tt> is a small +<a href="http://cr.yp.to/proto/ucspi.txt">UCSPI</a> server application +that answers IDENT requests. +</p> + +<h2> Interface </h2> + +<pre> + minidentd [ -v ] [ -n | -i | -r ] [ -y <em>file</em> ] [ -t <em>timeout</em> ] +</pre> + +<p> +<tt>minidentd</tt> reads a series of IDENT requests on stdin and answers +them on stdout. It logs what it's doing on stderr. The environment +variables <em>x</em>LOCALIP and <em>x</em>REMOTEIP, where <em>x</em> is +the value of the PROTO environment variable, must contain the IDENT +server address and the IDENT client address, respectively. +</p> + +<p> + minidentd exits 0 on success, 100 on a usage error and 111 on a system +call failure. +</p> + +<p> + minidentd does not contact the network directly. It's meant to +run under a superserver like +<a href="s6-tcpserver.html">s6-tcpserver</a>. minidentd will +work with IPv4 as well as IPv6. +</p> + +<h2> Options </h2> + +<ul> + <li> <tt>-v</tt> : verbose mode. Log queries and replies.. </li> + <li> <tt>-n</tt> : send ERROR : HIDDEN-USER replies if +the user has a <tt>.ident</tt> file in his home directory. </li> + <li> <tt>-i</tt> : user-defined answers. The first 14 chars of the +user's <tt>.ident</tt> file, up to EOF or newline, are used instead of +the user name. If the file exists and is empty, send +ERROR : HIDDEN-USER. If it doesn't exist, send a normal reply. </li> + <li> <tt>-r</tt> : send random replies. </li> + <li> <tt>-y <em>file</em></tt> : valid with <tt>-n</tt> or <tt>-i</tt>. +Use <em>file</em> instead of <tt>.ident</tt>. </li> + <li> <tt>-t <em>timeout</em></tt> : close connection after +<em>timeout</em> milliseconds without a client request. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> minidentd works only under Linux (2.2 or later); +on other systems, it will compile and run, but report an error for every +request. +The problem is that <em>there is no portable Unix way</em> of listing active +outgoing TCP connections with the relevant uids. On Linux, minidentd parses +the <tt>/proc/net/tcp</tt> or <tt>/proc/net/tcp6</tt> virtual file. Other +systems have their own way of doing this, if you want your system to be +supported by minidentd, please contact the author. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-accessrules-cdb-from-fs.html b/doc/s6-accessrules-cdb-from-fs.html new file mode 100644 index 0000000..26105b1 --- /dev/null +++ b/doc/s6-accessrules-cdb-from-fs.html @@ -0,0 +1,141 @@ +<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 new file mode 100644 index 0000000..91ec98e --- /dev/null +++ b/doc/s6-accessrules-fs-from-cdb.html @@ -0,0 +1,60 @@ +<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-clockadd.html b/doc/s6-clockadd.html new file mode 100644 index 0000000..a998cd1 --- /dev/null +++ b/doc/s6-clockadd.html @@ -0,0 +1,61 @@ +<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-clockadd program</title> + <meta name="Description" content="s6-networking: the s6-clockadd program" /> + <meta name="Keywords" content="s6-networking s6-clockadd tai clock tai64 tai64n tai64na clockadd setting the system clock" /> + <!-- <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-clockadd</tt> program </h1> + +<p> +<tt>s6-clockadd</tt> adjusts the system clock depending on the input +provided by a time client. +</p> + +<h2> Interface </h2> + +<pre> + s6-taiclock <em>server</em> | s6-clockadd [ -f ] [ -e <em>errmax</em> ] +</pre> + +<ul> + <li> s6-clockadd reads its stdin, expecting input from a program such +<a href="s6-taiclock.html">s6-taiclock</a> or +<a href="s6-sntpclock.html">s6-sntpclock</a> (which get time from a +time server). </li> + <li> It sets the system clock so the system time becomes the one +given by the server. Then it exits 0. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-f</tt> : force. Normally, s6-clockadd exits 1 if the +time discrepancy read from stdin is bigger than <em>errmax</em> +milliseconds. If this +option is set, it will print a warning message, but still set the +system time and exit 0. </li> + <li> <tt>-e <em>errmax</em></tt> : accept a maximum time +discrepancy of <em>errmax</em> milliseconds. By default, <em>errmax</em> +is 2000. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> s6-clockadd must be run as root. The client getting the time +from a time server, however, does not have to. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-clockview.html b/doc/s6-clockview.html new file mode 100644 index 0000000..58d8ac9 --- /dev/null +++ b/doc/s6-clockview.html @@ -0,0 +1,41 @@ +<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-clockview program</title> + <meta name="Description" content="s6-networking: the s6-clockview program" /> + <meta name="Keywords" content="s6-networking s6-clockview tai clock tai64 tai64n tai64na clockview" /> + <!-- <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-clockview</tt> program </h1> + +<p> +<tt>s6-clockview</tt> prints the time discrepancy between the local +system clock and the time provided by a time server. +</p> + +<h2> Interface </h2> + +<pre> + s6-taiclock <em>server</em> | s6-clockview +</pre> + +<ul> + <li> s6-clockview reads its stdin, expecting input from a program such +<a href="s6-taiclock.html">s6-taiclock</a> or +<a href="s6-sntpclock.html">s6-sntpclock</a> (which get time from a +time server). </li> + <li> It prints the local system time, and the time given by the +server, in human-readable form, then exits 0. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-connlimit.html b/doc/s6-connlimit.html new file mode 100644 index 0000000..f0422e6 --- /dev/null +++ b/doc/s6-connlimit.html @@ -0,0 +1,96 @@ +<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 connection 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-getservbyname.html b/doc/s6-getservbyname.html new file mode 100644 index 0000000..29a8235 --- /dev/null +++ b/doc/s6-getservbyname.html @@ -0,0 +1,48 @@ +<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-getservbyname program</title> + <meta name="Description" content="s6-networking: the s6-getservbyname program" /> + <meta name="Keywords" content="s6-networking s6-getservbyname getservbyname" /> + <!-- <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-getservbyname</tt> program </h1> + +<p> +<tt>s6-getservbyname</tt> is a simple command-line interface to the +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/getservbyname.html">getservbyname()</a> +function, converting a service name and protocole into a port number. +</p> + +<h2> Interface </h2> + +<pre> + s6-getservbyname <em>name</em> <em>proto</em> +</pre> + +<ul> + <li> <tt>s6-getservbyname</tt> looks up the network services database +for an entry containing name <em>name</em> and protocol <em>proto</em>. </li> + <li> It prints the corresponding port number to stdout, then exits 0. </li> + <li> If it cannot find a related entry, it exits 1. </li> +</ul> + +<h2> Example </h2> + +<p> + On a standard machine with a correct <tt>/etc/services</tt> file and +a non-garbled NSS configuration: + <tt>s6-getservbyname smtp tcp</tt> prints 25. +</p> + +</body> +</html> diff --git a/doc/s6-ident-client.html b/doc/s6-ident-client.html new file mode 100644 index 0000000..fb7b0bf --- /dev/null +++ b/doc/s6-ident-client.html @@ -0,0 +1,52 @@ +<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-ident-client program</title> + <meta name="Description" content="s6-networking: the s6-ident-client program" /> + <meta name="Keywords" content="s6-networking minidentd identd ident client rfc 1413" /> + <!-- <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-ident-client</tt> program </h1> + +<p> +<tt>s6-ident-client</tt> is a command-line client application that +performs IDENT (RFC 1413) queries. +</p> + +<h2> Interface </h2> + +<pre> + s6-ident-client [ -t <em>millisecs</em> ] <em>remoteaddr</em> <em>remoteport</em> <em>localaddr</em> <em>localport</em> +</pre> + +<ul> + <li> s6-ident-client contacts the IDENT server on address <em>remoteaddr</em> +port 113 and asks it about the connection from address <em>remoteaddr</em> +port <em>remoteport</em> to address <em>localaddr</em> port <em>localport</em>. </li> + <li> It prints the answer to stdout. </li> + <li> It exits 0 if the answer is positive or 1 if the answer is negative, +in which case it also prints an informative message to stderr. </li> + <li> <em>remoteaddr</em> and <em>localaddr</em> can be either IPv4 +or IPv6 addresses; however, they must both be of the same type. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-t <em>millisecs</em></tt> : if no answer has been +obtained within <em>millisecs</em> milliseconds, s6-ident-client will +exit 99 with an error message. By default, <em>millisecs</em> is 0, +which means no time limit. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-ioconnect.html b/doc/s6-ioconnect.html new file mode 100644 index 0000000..5e2b6c6 --- /dev/null +++ b/doc/s6-ioconnect.html @@ -0,0 +1,84 @@ +<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 new file mode 100644 index 0000000..2bb66aa --- /dev/null +++ b/doc/s6-ipcclient.html @@ -0,0 +1,65 @@ +<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 new file mode 100644 index 0000000..817425b --- /dev/null +++ b/doc/s6-ipcserver-access.html @@ -0,0 +1,172 @@ +<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-ipcserver.html">s6-ipcserver</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.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> : 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> 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> diff --git a/doc/s6-sntpclock.html b/doc/s6-sntpclock.html new file mode 100644 index 0000000..0d4c45b --- /dev/null +++ b/doc/s6-sntpclock.html @@ -0,0 +1,166 @@ +<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-sntpclock program</title> + <meta name="Description" content="s6-networking: the s6-sntpclock program" /> + <meta name="Keywords" content="s6-networking s6-sntpclock sntp clock sntpv4 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-sntpclock</tt> program </h1> + +<p> +<tt>s6-sntpclock</tt> is a small SNTP client. It connects to a +SNTP or NTP server, computes an estimated discrepancy between the +local clock time and the absolute time given by the server, and +outputs it on stdout. +</p> + +<h2> Interface </h2> + +<pre> + s6-sntpclock [ -f ] [ -v <em>verbosity</em> ] [ -r <em>roundtrips</em> ] [ -t <em>triptimeout</em> ] [ -h <em>throttle</em> ] [ -T <em>totaltimeout</em> ] [ -e <em>errmax</em> ] [ -p <em>port</em> ] <em>ipaddress</em> | s6-clockview +</pre> + +<ul> + <li> s6-sntpclock exchanges SNTPv4 messages with a SNTP server +listening on <em>ipaddress</em>, UDP port 123. +<em>ipaddress</em> can be IPv4 or IPv6. </li> + <li> It computes the mean difference between the absolute time +given by the system clock and the one given by the server. </li> + <li> It prints the difference to stdout in a format understood +by <a href="s6-clockadd">s6-clockadd</a> and +<a href="s6-clockview">s6-clockview</a>. It then exits 0. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-f</tt> : force. Normally, s6-sntpclock exits 111 if it cannot +compute a time with a smaller uncertainty than <em>errmax</em>. If this +option is set, it will output a time difference and exit 0 even if the +error is too big. </li> + <li> <tt>-v <em>verbosity</em></tt> : be more or less verbose. +By default, <em>verbosity</em> is 1. 0 means only print fatal error +messages; 3 means trace every exchange with the server. </li> + <li> <tt>-r <em>roundtrips</em></tt> : perform <em>roundtrips</em> +exchanges with the server. By default, <em>roundtrip</em> is 10. A lower +value yields a higher time uncertainty; a higher value puts more load on +the server. </li> + <li> <tt>-t <em>triptimeout</em></tt> : if a SNTP exchange with +the server takes more than <em>triptimeout</em> milliseconds, abort this +exchange and move on to the next one. By default, <em>triptimeout</em> +is 2000. </li> + <li> <tt>-h <em>throttle</em></tt> : wait <em>throttle</em> +milliseconds between exchanges with the server. A lower value gets the +final result earlier, but exerts more load on the server. A higher +value puts a lighter load on the server, but delays the computation. +By default, <em>throttle</em> is 0. It is recommended to set it to a +reasonable nonzero value when increasing <em>roundtrips</em>. </li> + <li> <tt>-T <em>totaltimeout</em></tt> : if the whole +operation takes more than <em>totaltimeout</em> milliseconds, abort +and exit 1. By default, <em>totaltimeout</em> is 10000. </li> + <li> <tt>-e <em>errmax</em></tt> : accept a maximum time +uncertainty of <em>errmax</em> milliseconds. By default, <em>errmax</em> +is 100. </li> + <li> <tt>-p <em>port</em></tt> : contact a server on port +<em>port</em>. By default, <em>port</em> is 123. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> There are a lot of infelicities in the NTP protocol (which SNTP is +a subset of). The biggest offender is probably that NTP cannot handle +a time difference of more than 34 years: if the time given by the NTP +server is more than 34 years away from the time given by the system clock, +then NTP just cannot compute. This is a problem for CMOS-less systems, +where the system clock is initialized to the Unix Epoch. The solution +is to first manually initialize the system clock with a program such as +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a> or +<a href="http://skarnet.org/software/s6-portable-utils/s6-clock.html">s6-clock</a> +to a closer time (such as 2013-01-01, which will be good up to 2047), then +contact the NTP server. </li> + <li> A less obvious problem with NTP is that it works with UTC time, +which means that it gives inaccurate results when close to a leap second, +up to one second off when used during a leap second, and this +is bound to the use of UTC: there is nothing you can do about it. The +only solution to get reliable results even around a leap second is to +use linear time such as TAI; the +<a href="s6-taiclock.html">s6-taiclock</a> and +<a href="s6-taiclockd.html">s6-taiclockd</a> programs provide tools to +do so. </li> +</ul> + +<a name="ntpd" /> +<h2> A word on ntpd </h2> + +<p> + From a Unix software engineering standpoint, the well-known +<a href="http://doc.ntp.org/4.1.0/ntpd.htm">ntpd</a> program is an +eldritch abomination. The main reason for it is that, just like its +lovely cousin <a href="http://www.isc.org/downloads/bind/">BIND</a>, +ntpd performs a lot of different tasks in a unique process, instead +of separating what could, and should, be separated. This is confusing +for both the programmer <em>and</em> the software user. +</p> + +<ul> + <li> The term "NTP server" means two different things: + <ul> + <li> A program that serves NTP time to the Internet and can be +accessed by NTP clients. </li> + <li> A daemon, i.e. a long-lived process, that runs on a machine +and handles NTP-related stuff such as keeping the system clock accurate. </li> + </ul> + The former is the real meaning of "NTP server". The latter is a common +usage for the term, but comes from a misuse of "server" to mean "daemon". +ntpd does not help clear the misunderstanding since it does both. It acts +as an NTP server, <em>and</em> as an NTP client getting its time from +lower-strata NTP servers, <em>and</em> as a local system clock management +daemon. Those are already 3 separate tasks. </li> + <li> Local system clock management itself involves several duties. There +is the regular setting of the system clock, which can be done with +a loop over a simple program such as <a href="s6-clockadd.html">s6-clockadd</a>. +There is also control of the clock skew, which s6-networking does not +provide because there is no portable interface for that; there is such a tool +in the <a href="http://cr.yp.to/clockspeed.html">clockspeed</a> package. </li> + <li> ntpd includes a complete cryptographic key management system for the +crypto part of NTP. NTP is not the only protocol that uses cryptography +and asymmetric keys; managing keys in a separate tool, not in the NTP +daemon itself, would be simpler and smarter. </li> + <li> ntpd provides monitoring support for client and server timekeeping +performance. This would be best implemented as a separate specific log +analyzing tool. </li> +</ul> + +<p> + And of course, no matter how many layers of complexity you add onto +ntpd, it will never be able to give accurate time in the vicinity of a +leap second, since the very <em>protocol</em> is flawed by design - but +the ntpd authors cannot be blamed for that. Also, the ntpd +<em>writers</em>, not the designers, should be praised: the history of +ntpd security flaws is remarkably small, which is quite a feat for a +huge monolithic root daemon. +</p> + +<p> + Network synchronization is important, NTP has its perks and +valid use cases, and its existence is a good thing. However, I wish that +the main NTP implementation weren't written as a big fat clumsy process +running as root. s6-sntpclock together with +<a href="s6-clockadd.html">s6-clockadd</a> aims to provide a small, simple +tool to keep system clocks, especially in embedded devices, synchronized +to a NTP server. +</p> + +</body> +</html> diff --git a/doc/s6-sudo.html b/doc/s6-sudo.html new file mode 100644 index 0000000..603ad8a --- /dev/null +++ b/doc/s6-sudo.html @@ -0,0 +1,59 @@ +<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 new file mode 100644 index 0000000..0ca9918 --- /dev/null +++ b/doc/s6-sudoc.html @@ -0,0 +1,80 @@ +<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-sudod'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 new file mode 100644 index 0000000..ac93219 --- /dev/null +++ b/doc/s6-sudod.html @@ -0,0 +1,162 @@ +<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> +</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-sudod'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-taiclock.html b/doc/s6-taiclock.html new file mode 100644 index 0000000..bbdc680 --- /dev/null +++ b/doc/s6-taiclock.html @@ -0,0 +1,114 @@ +<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-taiclock program</title> + <meta name="Description" content="s6-networking: the s6-taiclock program" /> + <meta name="Keywords" content="s6-networking s6-taiclock tai clock tai64 tai64n tai64na 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-taiclock</tt> program </h1> + +<p> +<tt>s6-taiclock</tt> is a client for the +<a href="http://cr.yp.to/proto/taiclock.txt">TAICLOCK</a> protocol. +It connects to a TAICLOCK server, computes an estimated discrepancy +between the local clock time and the absolute time given by the server, +and outputs it on stdout. +</p> + +<h2> Interface </h2> + +<pre> + s6-taiclock [ -f ] [ -v <em>verbosity</em> ] [ -r <em>roundtrips</em> ] [ -t <em>triptimeout</em> ] [ -h <em>throttle</em> ] [ -T <em>totaltimeout</em> ] [ -e <em>errmax</em> ] [ -p <em>port</em> ] <em>ipaddress</em> | s6-clockview +</pre> + +<ul> + <li> s6-taiclock exchanges TAICLOCK messages with a server such as +<a href="s6-taiclockd.html">s6-taiclockd</a> +listening on <em>ipaddress</em>, UDP port 4014. +<em>ipaddress</em> can be IPv4 or IPv6. </li> + <li> It computes the mean difference between the absolute time +given by the system clock and the one given by the server. </li> + <li> It prints the difference to stdout in a format understood +by <a href="s6-clockadd">s6-clockadd</a> and +<a href="s6-clockview">s6-clockview</a>. It then exits 0. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-f</tt> : force. Normally, s6-taiclock exits 111 if it cannot +compute a time with a smaller uncertainty than <em>errmax</em>. If this +option is set, it will output a time difference and exit 0 even if the +error is too big. </li> + <li> <tt>-v <em>verbosity</em></tt> : be more or less verbose. +By default, <em>verbosity</em> is 1. 0 means only print fatal error +messages; 2 means print advanced warnings. </li> + <li> <tt>-r <em>roundtrips</em></tt> : perform <em>roundtrips</em> +exchanges with the server. By default, <em>roundtrip</em> is 10. A lower +value yields a higher time uncertainty; a higher value puts more load on +the server. </li> + <li> <tt>-t <em>triptimeout</em></tt> : if a TAICLOCK exchange with +the server takes more than <em>triptimeout</em> milliseconds, abort this +exchange and move on to the next one. By default, <em>triptimeout</em> +is 2000. </li> + <li> <tt>-h <em>throttle</em></tt> : wait <em>throttle</em> +milliseconds between exchanges with the server. A lower value gets the +final result earlier, but exerts more load on the server. A higher +value puts a lighter load on the server, but delays the computation. +By default, <em>throttle</em> is 0. It is recommended to set it to a +reasonable nonzero value when increasing <em>roundtrips</em>. </li> + <li> <tt>-T <em>totaltimeout</em></tt> : if the whole +operation takes more than <em>totaltimeout</em> milliseconds, abort +and exit 1. By default, <em>totaltimeout</em> is 10000. </li> + <li> <tt>-e <em>errmax</em></tt> : accept a maximum time +uncertainty of <em>errmax</em> milliseconds. By default, <em>errmax</em> +is 100. </li> + <li> <tt>-p <em>port</em></tt> : contact a server on port +<em>port</em>. By default, <em>port</em> is 4014. </li> +</ul> + +<h2> Notes </h2> + +<h3> On the usage of NTP vs. TAICLOCK </h3> + +<ul> + <li> TAICLOCK is not as generic or failproof as NTP. It is not as +resistant to network latency. It has been designed to broadcast +time on a local area network, whereas NTP has been designed to +broadcast time over the whole Internet. </li> + <li> TAICLOCK will produce faster results on a LAN; moreover, the +point of TAICLOCK is to broadcast TAI instead of UTC, so it is +more accurate around a leap second. </li> + <li> The Internet is much more reliable latency-wise today +than it was when dialout connections and broken routing protocols +were the norm. So it is possible to use TAICLOCK +across a WAN if the accuracy expectations are not too strict. </li> + <li> TAICLOCK is much easier to implement. The +<a href="s6-sntpclock.html">s6-sntpclock</a> client binary code +(statically linked on a i386) is 50% bigger than the s6-taiclock +client. Also, the <a href="s6-taiclockd.html">s6-taiclockd</a> +server is extremely small (close to 50% smaller than the client), +whereas NTP servers, even SNTP servers, are behemoths requiring +a project of their own. </li> +</ul> + +<h3> Related work </h3> + +<ul> + <li> The <a href="http://cr.yp.to/clockspeed.html">clockspeed</a> package +is the original inspiration for the clock management part of s6-networking. +Unfortunately, it is unmaintained. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-taiclockd.html b/doc/s6-taiclockd.html new file mode 100644 index 0000000..915c181 --- /dev/null +++ b/doc/s6-taiclockd.html @@ -0,0 +1,51 @@ +<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-taiclockd program</title> + <meta name="Description" content="s6-networking: the s6-taiclockd program" /> + <meta name="Keywords" content="s6-networking s6-taiclock tai clock tai64 tai64n tai64na 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-taiclockd</tt> program </h1> + +<p> +<tt>s6-taiclockd</tt> is a server for the +<a href="http://cr.yp.to/proto/taiclock.txt">TAICLOCK</a> protocol. +It's a long-lived program listening to the network and answering +to TAICLOCK clients such as <a href="s6-taiclock.html">s6-taiclock</a>. +</p> + +<h2> Interface </h2> + +<pre> + s6-taiclockd [ -i <em>ip</em> ] [ -p <em>port</em> ] +</pre> + +<ul> + <li> s6-taiclockd listens to all network addresses on UDP +port 4014. </li> + <li> Whenever it receives a TAICLOCK request, it answers +immediately with the TAI time given by its local system clock. </li> + <li> It runs until killed by a signal. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-i <em>ip</em></tt> : bind to <em>ip</em> instead +of all available addresses. <em>ip</em> can be IPv4 or IPv6. </li> + <li> <tt>-p <em>port</em></tt> : bind to port +<em>port</em> instead of 4014. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-tcpclient.html b/doc/s6-tcpclient.html new file mode 100644 index 0000000..42edaa9 --- /dev/null +++ b/doc/s6-tcpclient.html @@ -0,0 +1,133 @@ +<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-tcpclient program</title> + <meta name="Description" content="s6-networking: the s6-tcpclient program" /> + <meta name="Keywords" content="s6-networking s6-tcpclient tcpclient ucspi tcp inet network tcp/ip 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-tcpclient</tt> program </h1> + +<p> +<tt>s6-tcpclient</tt> is an +<a href="http://cr.yp.to/proto/ucspi.txt">UCSPI client tool</a> for +INET domain sockets. It establishes a TCP connection to a server, +then executes into a program. +</p> + +<h2> Interface </h2> + +<pre> + s6-tcpclient [ -q | -Q | -v ] [ -4 | -6 ] [ -d | -D ] [ -r | -R ] [ -h | -H ] [ -n | -N ] [ -t <em>timeout</em> ] [ -l <em>localname</em> ] [ -T <em>timeoutconn</em> ] [ -i <em>localip</em> ] [ -p <em>localport</em> ] <em>host</em> <em>port</em> <em>prog...</em> +</pre> + +<ul> + <li> s6-tcpclient establishes a TCP connection to host <em>host</em> +port <em>port</em>. </li> + <li> It executes into <em>prog...</em> with descriptor 6 reading from +the network and descriptor 7 writing to it. </li> +</ul> + +<h2> Host address determination </h2> + +<ul> + <li> <em>host</em> may be an IP address, in which case s6-tcpclient will +connect to that IP address. If the underlying skalibs has been +compiled with IPv6 support, <em>host</em> can be an IPv6 address as +well as an IPv4 one. </li> + <li> <em>host</em> may be a domain name, in which case a DNS +resolution will be performed on it, and a connection will be tried to +all the resulting IP addresses in a round-robin fashion, twice: +first with a small timeout, then with a longer timeout. The first +address to answer wins. The connection attempt fails if no address +in the list is able to answer. </li> +</ul> + +<h2> Environment variables </h2> + +<p> + <em>prog...</em> is run with the following variables set: +</p> + +<ul> + <li> PROTO: always set to TCP </li> + <li> TCPREMOTEIP: set to the chosen IP address of <em>host</em>. </li> + <li> TCPREMOTEPORT: set to <em>port</em>. </li> + <li> TCPREMOTEHOST: if the <tt>-H</tt> has been given, set to the +name obtained by a reverse DNS resolution of the IP address chosen +for <em>host</em>. Else unset. </li> + <li> TCPLOCALHOST: if the <tt>-l</tt> option has been given, set to +<em>localname</em>. Else set to the name obtained by a reverse DNS +resolution of the IP address chosen for the local host. </li> + <li> TCPREMOTEINFO: if the <tt>-r</tt> option has been given, set +to the information given by an IDENT server on <em>host</em> about +the current connection (very unreliable). Else unset. </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>-4</tt> : (only valid if the underlying skalibs has +IPv6 support) Interpret <em>host</em> as an IPv4 address or make A +queries to determine its addresses. </li> + <li> <tt>-6</tt> : (only valid if the underlying skalibs has +IPv6 support) Interpret <em>host</em> as an IPv6 address or make +AAAA queries to determine its addresses. This option and the previous +one are not mutually exclusive: if both are given, both IPv6 and +IPv4 addresses will be tried and IPv6 addresses will be given priority. +If neither option is given, only IPv4 address will be tried. </li> + <li> <tt>-d</tt> : don't use the TCP_NODELAY socket option. This +is the default. </li> + <li> <tt>-D</tt> : use the TCP_NODELAY socket option, which disables +Nagle's algorithm. </li> + <li> <tt>-r</tt> : try and obtain a TCPREMOTEINFO string via the +IDENT protocol. This is obsolete and unreliable, and should only be used for +compatibility with legacy programs. </li> + <li> <tt>-R</tt> : do not use the IDENT protocol. This is the +default. </li> + <li> <tt>-h</tt> : try and obtain the remote host name via DNS. +This is the default. </li> + <li> <tt>-H</tt> : do not try and obtain the remote host name +via DNS. </li> + <li> <tt>-n</tt> : qualify <em>host</em> when resolving it to +find suitable IP addresses. This is the default. </li> + <li> <tt>-N</tt> : do not qualify <em>host</em>. </li> + <li> <tt>-t :<em>timeout</em></tt> : put a global timeout +on the connection attempt. If no fully functional connection has been +established after <em>timeout</em> seconds, abort the program. By +default, <em>timeout</em> is 0, which means no timeout. </li> + <li> <tt>-i <em>localip</em></tt> : use <em>localip</em> as +the local socket address for the connection. By default, address selection +is left to the operating system. </li> + <li> <tt>-p <em>localport</em></tt> : use <em>localport</em> +as the local socket port for the connection. By default, port selection +is left to the operating system. </li> + <li> <tt>-l <em>localname</em></tt> : use <em>localname</em> +as the value of the TCPLOCALPATH environment variable instead of +looking it up via the DNS. </li> + <li> <tt>-T :<em>timeoutconn</em></tt> : configure the +connection timeouts. <em>timeoutconn</em> must be of the form +<em>x</em><tt>+</tt><em>y</em>, where <em>x</em> and <em>y</em> are +integers. <em>x</em> is the first timeout and <em>y</em> is the +second one: all suitable addresses for <em>host</em> are first +tried with a timeout of <em>x</em> seconds, and if all of them +fail, then they are tried again with a timeout of <em>y</em> +seconds. (Be aware that the timeout specified with the <tt>-t</tt> +option overrides everything.) By default, <em>x</em> is 2 and +<em>y</em> is 58. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-tcpserver-access.html b/doc/s6-tcpserver-access.html new file mode 100644 index 0000000..7bf15a0 --- /dev/null +++ b/doc/s6-tcpserver-access.html @@ -0,0 +1,239 @@ +<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-tcpserver-access program</title> + <meta name="Description" content="s6-networking: the s6-tcpserver-access program" /> + <meta name="Keywords" content="s6-networking s6-tcpserver-access tcp access control tcprules tcpwrappers libwrap" /> + <!-- <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-tcpserver-access</tt> program </h1> + +<p> +<tt>s6-tcpserver-access</tt> is a command-line TCP access +control tool, and additionally performs some fine-tuning on a +TCP socket. It is meant to be run after +<a href="s6-tcpserver.html">s6-tcpserver</a> and before +the application program on the s6-tcpserver command line, +just like tcpwrappers' <tt>tcpd</tt> program. +</p> + +<h2> Interface </h2> + +<pre> + s6-tcpserver-access [ -v <em>verbosity</em> ] [ -W | -w ] [ -D | -d ] [ -H | -h ] [ -R | -r ] [ -P | -p ] [ -l <em>localname</em> ] [ -B <em>banner</em> ] [ -t <em>timeout</em> ] [ -i <em>rulesdir</em> | -x <em>rulesfile</em> ] <em>prog...</em> +</pre> + +<ul> + <li> s6-tcpserver-access checks it is run under a UCSPI server tool +such as <a href="s6-tcpserver.html">s6-tcpserver</a>, + <a href="s6-tcpserver4.html">s6-tcpserver4</a> or + <a href="s6-tcpserver6.html">s6-tcpserver6</a>. </li> + <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-tcpserver-access expects to inherit some environment variables from +its parent: +</p> + +<ul> + <li> PROTO: normally TCP, but could be anything else, like SSL. </li> + <li> ${PROTO}REMOTEIP: the remote address of the socket, i.e. the client's +IP address. This can be IPv4 or (if the underlying skalibs supports it) IPv6. </li> + <li> ${PROTO}REMOTEPORT: the remote port of the socket. </li> +</ul> + +<p> + Additionally, it exports the following variables before executing into +<em>prog...</em>: +</p> + +<ul> + <li> ${PROTO}LOCALIP: set to the local address of the socket. </li> + <li> ${PROTO}LOCALPORT: set to the local port of the socket. </li> + <li> ${PROTO}REMOTEINFO: normally unset, but set to the information +retrieved from ${PROTO}REMOTEIP via the IDENT protocol if the <tt>-R</tt> +option has been given. </li> + <li> ${PROTO}REMOTEHOST: set to the remote host name obtained from +a DNS lookup. Unset if the <tt>-H</tt> option has been given. </li> + <li> ${PROTO}LOCALHOST: set to the local host name obtained from a +DNS lookup. If the <tt>-l</tt> option has been given, set to +<em>localname</em> instead. </li> +</ul> + +<p> + Also, the access rules database can instruct s6-tcpserver-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> + <li> 3: also log detailed warning messages from DNS and IDENT resolution. </li> + </ul> </li> + <li> <tt>-W</tt> : non-fatal. If errors happen during DNS or IDENT +resolution, the connection process is not aborted. However, incorrect or +incomplete results might still prevent a legitimate connection from being +authenticated against a DNS name. This is the default. </li> + <li> <tt>-w</tt> : fatal. Errors during DNS or IDENT resolution will +drop the connection. </li> + <li> <tt>-D</tt> : disable Nagle's algorithm. Sets the TCP_NODELAY +flag on the network socket. </li> + <li> <tt>-d</tt> : enable Nagle's algorithm. This is the default. </li> + <li> <tt>-H</tt> : disable DNS lookups for the ${PROTO}LOCALHOST and +${PROTO}REMOTEHOST environment variables. </li> + <li> <tt>-h</tt> : enable DNS lookups. This is the default. </li> + <li> <tt>-R</tt> : disable IDENT lookups for the ${PROTO}REMOTEINFO +environment variable. This is the default. </li> + <li> <tt>-r</tt> : enable IDENT lookups. This should only be done +for legacy programs that need it. </li> + <li> <tt>-P</tt> : no paranoid DNS lookups. This is the default. </li> + <li> <tt>-p</tt> : paranoid. After looking up a name for the remote +host, s6-tcpserver-access will lookup IP addresses for this name, and drop +the connection if none of the results matches the address the connection +is originating from. Note that this still does not replace real +authentication via a cryptographic protocol. </li> + <li> <tt>-l <em>localname</em></tt> : use <em>localname</em> +as the value for the ${PROTO}LOCALHOST environment variable, instead of +looking it up in the DNS. </li> + <li> <tt>-B <em>banner</em></tt> : print <em>banner</em> to +the network as soon as the connection is attempted, even before +checking client credentials. The point is to speed up network protocols +that start with a server-side message. </li> + <li> <tt>-t <em>timeout</em></tt> : set a timeout on all the +operations performed by s6-tcpserver-access. If it is not able to do +its job in <em>timeout</em> milliseconds, it will instantly exit 99. +The default is 0, meaning no such timeout. </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-tcpserver-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-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> +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 +<tt>ip6/</tt><em>ip</em><tt>/128</tt> to <tt>ip6/::_0</tt> if <em>ip</em> +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> +</ul> + +<p> + In the last case, if DNS lookups have been deactivated (<tt>-H</tt>) then access +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> +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. +</p> + +<p> + Note that even if the access check succeeds, the connection can still be +denied if paranoid mode has been required (<tt>-p</tt>) and a forward DNS query +on <em>remotehost</em> does not match <em>ip</em>. +</p> + +<h2> Environment and executable modifications </h2> + +<p> + 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> +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-tcpserver-access' command line. After +environment modifications, if any, s6-tcpserver-access execs into +<tt><a href="http://skarnet.org/software/execline/execlineb.html">execlineb</a> -c <em>newprog</em></tt>. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> s6-tcpserver-access works with +<a href="s6-tcpserver4.html">s6-tcpserver4</a>, handling IPv4 addresses, +as well as +<a href="s6-tcpserver6.html">s6-tcpserver6</a>, handling IPv6 addresses. +It will automatically detect the remote address type and match it against the +correct subdatabase. </li> + <li> s6-tcpserver-access may perform several DNS queries. For efficiency +purposes, it does as many of them as possible in parallel. However, if asked +to do an IDENT query, it does not parallelize it with DNS queries. Take +that into account when estimating a proper <em>timeout</em> value. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-tcpserver.html b/doc/s6-tcpserver.html new file mode 100644 index 0000000..41eb176 --- /dev/null +++ b/doc/s6-tcpserver.html @@ -0,0 +1,72 @@ +<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-tcpserver program</title> + <meta name="Description" content="s6-networking: the s6-tcpserver program" /> + <meta name="Keywords" content="s6-networking s6-tcpserver tcpserver ucspi tcp 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-tcpserver</tt> program </h1> + +<p> +<tt>s6-tcpserver</tt> is an +<a href="http://cr.yp.to/proto/ucspi.txt">UCSPI tool</a> for +TCP connections, i.e. a super-server. It accepts connections from +clients, and forks a program to handle each connection. +</p> + +<h2> Interface </h2> + +<pre> + s6-tcpserver [ -q | -Q | -v ] [ -4 | -6 ] [ -1 ] [ -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>ip</em> <em>port</em> <em>prog...</em> +</pre> + +<ul> + <li> s6-tcpserver executes into +<a href="s6-tcpserver4.html">s6-tcpserver4</a> or +<a href="s6-tcpserver6.html">s6-tcpserver6</a> depending on whether +<em>ip</em> is an IPv4 or IPv6 address. It modifies some of its +option syntax to match s6-tcpserver4 and s6-tcpserver6's.</li> + <li> s6-tcpserver4 or s6-tcpserver6 handles the connection itself. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-q</tt> : be quiet. This is converted into <tt>-v 0</tt> +for s6-tcpserver4 or s6-tcpserver6. </li> + <li> <tt>-Q</tt> : be normally quiet. This is converted into <tt>-v 1</tt> +for s6-tcpserver4 or s6-tcpserver6. This is the default. </li> + <li> <tt>-v</tt> : be verbose. This is converted into <tt>-v 2</tt> +for s6-tcpserver4 or s6-tcpserver6. </li> + <li> <tt>-4</tt> : IPv4 only. Interpret <em>ip</em> as IPv4; if it is +invalid, exit 100. </li> + <li> <tt>-6</tt> : IPv6 only. Interpret <em>ip</em> as IPv6; if it is +invalid, exit 100. If neither the <tt>-4</tt> nor the <tt>-6</tt> option is +given, s6-tcpserver will parse <em>ip</em> to determine its family. </li> + <li> Every other option is passed verbatim to s6-tcpserver4 or s6-tcpserver6. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> s6-tcpserver executes either into s6-tcpserver4, which only serves +IPv4, or into IPv6, which only serves IPv6. It will not bind to every +available IP address of the machine whether they are v4 or v6; on the +other hand, it can bind to every available IPv4 address (if <em>ip</em> +is <tt>0.0.0.0</tt>) or to every available IPv6 address (if <em>ip</em> +is <tt>::</tt>). Two instances of s6-tcpserver can cover every +available address. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-tcpserver4.html b/doc/s6-tcpserver4.html new file mode 100644 index 0000000..e0270e0 --- /dev/null +++ b/doc/s6-tcpserver4.html @@ -0,0 +1,123 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-networking: the s6-tcpserver4 program</title> + <meta name="Description" content="s6-networking: the s6-tcpserver4 program" /> + <meta name="Keywords" content="s6-networking s6-tcpserver4 tcpserver ucspi tcp server super-server ipv4" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-networking</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-tcpserver4</tt> program </h1> + +<p> +<tt>s6-tcpserver4</tt> is a super-server for IPv4 TCP +connections. It accepts connections from clients, and forks a +program to handle each connection. +</p> + +<h2> Interface </h2> + +<pre> + s6-tcpserver4 [ -1 ] [ -v <em>verbosity</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>ip</em> <em>port</em> <em>prog...</em> +</pre> + +<ul> + <li> s6-tcpserver4 binds to local IPv4 address <em>ip</em>, +port <em>port</em>. </li> + <li> It closes its stdin and stdout. </li> + <li> For every TCP connection to this address and port, it +forks. The child sets some environment variables, then +executes <em>prog...</em> with stdin reading from the network +socket and stdout writing to it. </li> + <li> Depending on the verbosity level, it logs what it does to stderr. </li> + <li> It runs until killed by a signal. Depending on the received +signal, it may kill its children before exiting. </li> +</ul> + +<h2> Environment variables </h2> + +<p> + For each connection, an instance of <em>prog...</em> is spawned with +the following variables set: +</p> + +<ul> + <li> PROTO: always set to TCP </li> + <li> TCPREMOTEIP: set to the originating address </li> + <li> TCPREMOTEPORT: set to the originating port </li> + <li> TCPCONNNUM: set to the number of connections originating from +the same IP address </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-1</tt> : write <em>port</em> to stdout, before +closing it, right after binding and listening to the network 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>-v <em>verbosity</em></tt> : be more or less verbose. +By default, <em>verbosity</em> is 1: print warning messages to stderr. +0 means only print fatal error messages ; 2 means print status and +connection information for every client. </li> + <li> <tt>-c <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 IP address. +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-tcpserver4'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-tcpserver4'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-tcpserver4'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-tcpserver4'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 its ancestor +<a href="http://cr.yp.to/ucspi-tcp/tcpserver.html">tcpserver</a>, +s6-tcpserver4 performs just the bare minimum: the point is to have a +very small and very fast process to serve connections with the least +possible overhead. Features such as additional environment variables, +access control and DNS resolution are provided +via the <a href="s6-tcpserver-access.html">s6-tcpserver-access</a> +program. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-tcpserver6.html b/doc/s6-tcpserver6.html new file mode 100644 index 0000000..e571010 --- /dev/null +++ b/doc/s6-tcpserver6.html @@ -0,0 +1,122 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-networking: the s6-tcpserver6 program</title> + <meta name="Description" content="s6-networking: the s6-tcpserver6 program" /> + <meta name="Keywords" content="s6-networking s6-tcpserver6 tcpserver ucspi tcp server super-server ipv6" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-networking</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-tcpserver6</tt> program </h1> + +<p> +<tt>s6-tcpserver6</tt> is a super-server for IPv6 TCP +connections. It accepts connections from clients, and forks a +program to handle each connection. +</p> + +<h2> Interface </h2> + +<pre> + s6-tcpserver6 [ -1 ] [ -v <em>verbosity</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>ip</em> <em>port</em> <em>prog...</em> +</pre> + +<ul> + <li> s6-tcpserver6 binds to local IPv6 address <em>ip</em>, +port <em>port</em>. </li> + <li> It closes its stdin and stdout. </li> + <li> For every TCP connection to this address and port, it +forks. The child sets some environment variables, then +executes <em>prog...</em> with stdin reading from the network socket +and stdout writing to it. </li> + <li> Depending on the verbosity level, it logs what it does to stderr. </li> + <li> It runs until killed by a signal. Depending on the received +signal, it may kill its children before exiting. </li> +</ul> + +<h2> Environment variables </h2> + +<p> + For each connection, an instance of <em>prog...</em> is spawned with +the following variables set: +</p> + +<ul> + <li> PROTO: always set to TCP </li> + <li> TCPREMOTEIP: set to the originating address, in canonical IPv6 form </li> + <li> TCPREMOTEPORT: set to the originating port </li> + <li> TCPCONNNUM: set to the number of connections originating from +the same IPv6 address </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-1</tt> : write <em>port</em> to stdout, before +closing it, right after binding and listening to the network 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>-v <em>verbosity</em></tt> : be more or less verbose. +By default, <em>verbosity</em> is 1: print warning messages to stderr. +0 means only print fatal error messages ; 2 means print status and +connection information for every client. </li> + <li> <tt>-c <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 IP address. +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-tcpserver6'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-tcpserver6'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-tcpserver6'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-tcpserver6'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> s6-tcpserver6 will only serve real IPv6 addresses; it does not +default to an IPv4 address. The +<a href="s6-tcpserver4.html">s6-tcpserver4</a> program should be +used to serve IPv4 addresses. </li> + <li> s6-tcpserver6 will only work if the underlying +<a href="http://skarnet.org/software/skalibs/">skalibs</a> has +been compiled with IPv6 support. </li> +</ul> + +</body> +</html> diff --git a/doc/seekablepipe.html b/doc/seekablepipe.html new file mode 100644 index 0000000..cd17b2e --- /dev/null +++ b/doc/seekablepipe.html @@ -0,0 +1,36 @@ +<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> diff --git a/doc/upgrade.html b/doc/upgrade.html new file mode 100644 index 0000000..0f7e635 --- /dev/null +++ b/doc/upgrade.html @@ -0,0 +1,34 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-networking: how to upgrade</title> + <meta name="Description" content="s6-networking: how to upgrade" /> + <meta name="Keywords" content="s6-networking installation upgrade" /> + <!-- <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> What has changed in s6-networking </h1> + +<h2> n 2.0.0.0 </h2> + +<ul> + <li> The build system has completely changed. It is now a standard +<tt>./configure && make && sudo make install</tt> +build system. See the enclosed INSTALL file for details. </li> + <li> slashpackage is not activated by default. </li> + <li> shared libraries are not used by default. </li> + <li> skalibs dependency bumped to 2.0.0.0. </li> + <li> execline dependency bumped to 2.0.0.0. </li> + <li> s6-dns dependency bumped to 2.0.0.0. </li> +</ul> + +</body> +</html> |