diff options
Diffstat (limited to 'doc')
33 files changed, 1976 insertions, 98 deletions
diff --git a/doc/fifodir.html b/doc/fifodir.html index 99805ed..c45dea5 100644 --- a/doc/fifodir.html +++ b/doc/fifodir.html @@ -31,13 +31,13 @@ create fifodirs in a RAM filesystem. <ul> <li> You can create fifodirs via the <tt>ftrigw_fifodir_create()</tt> function in -<a href="libftrigw.html">libftrig</a>. </li> +<a href="libs6/ftrigw.html">libftrig</a>. </li> <li> You can send an event to a fifodir via the <tt>ftrigw_notify()</tt> function in -<a href="libftrigw.html">libftrig</a>. </li> +<a href="libs6/ftrigw.html">libftrig</a>. </li> <li> You can clean up a fifodir via the <tt>ftrigw_clean()</tt> function in -<a href="libftrigw.html">libftrig</a>. </li> +<a href="libs6/ftrigw.html">libftrig</a>. </li> <li> You can destroy fifodirs via the <tt>rm_rf()</tt> function in <a href="http://skarnet.org/software/skalibs/doc/libstddjb/djbunix.html">libstddjb</a>. </li> @@ -115,7 +115,7 @@ can write to the fifo </li> </ul> <p> - The <a href="libftrig.html">libftrig<a/> interface takes care of all + The <a href="ftrig.html">libftrig<a/> interface takes care of all the subtleties. </p> diff --git a/doc/libftrig.html b/doc/ftrig.html index da4c25b..f4c4d6e 100644 --- a/doc/libftrig.html +++ b/doc/ftrig.html @@ -18,7 +18,7 @@ <h1> libftrig </h1> <p> -<t>libftrig</t> is a portable Unix C programming interface allowing a +<tt>libftrig</tt> is a portable Unix C programming interface allowing a process (the <em>subscriber</em> or <em>listener</em>) to be instantly notified when another process (the <em>notifier</em> or <em>writer</em>) signals an event. @@ -169,15 +169,15 @@ maintainable than D-Bus. <h2> How to use libftrig </h2> <p> - <tt>libftrig</tt> is really a part of <tt>libs6</tt>: all the functions + <tt>libftrig</tt> is really a part of <a href="libs6/">libs6</a>: all the functions are implemented in the <tt>libs6.a</tt> archive, or the <tt>libs6.so</tt> dynamic shared object. However, the interfaces are different for notifiers and listeners: </p> <ul> -<li> Notifiers use the <a href="libftrigw.html">libftrigw</a> interface. </li> -<li> Listeners use the <a href="libftrigr.html">libftrigr</a> interface. </li> +<li> Notifiers use the <a href="libs6/ftrigw.html">ftrigw</a> interface. </li> +<li> Listeners use the <a href="libs6/ftrigr.html">ftrigr</a> interface. </li> </ul> </body> diff --git a/doc/index.html b/doc/index.html index 1507705..9e3dde3 100644 --- a/doc/index.html +++ b/doc/index.html @@ -37,7 +37,8 @@ supervision that might help you understand the basics. <ul> <li> <a href="why.html">Why another supervision suite?</a> Isn't <a href="http://smarden.org/runit/">runit</a> good enough?</li> -<li> What is instant notification? What does the <a href="libftrig.html">libftrig</a> do exactly?</li> +<li> What is <a href="ftrig.html">instant notification</a>? What does the +<a href="libs6/ftrigr.html">ftrigr library</a> do exactly?</li> <li> How to run a s6-svscan-based supervision tree <a href="s6-svscan-not-1.html">without replacing init</a> </li> <li> How to <a href="s6-svscan-1.html">replace init</a> </li> </ul> @@ -67,7 +68,7 @@ supervision that might help you understand the basics. <h3> Download </h3> <ul> - <li> The current released version of s6 is <a href="s6-2.0.1.0.tar.gz">2.0.1.0</a>. </li> + <li> The current released version of s6 is <a href="s6-2.0.2.0.tar.gz">2.0.2.0</a>. </li> <li> Alternatively, you can checkout a copy of the s6 git repository: <pre> git clone git://git.skarnet.org/s6 </pre> </li> </ul> @@ -151,7 +152,7 @@ counterpart. These programs are a clean rewrite of the obsolete "pipe-tools" package; they are now based on a properly designed notification library. They provide a command-line interface to -<a href="libftrig.html#notification">inter-process notification and +<a href="ftrig.html#notification">inter-process notification and synchronization</a>. </p> @@ -172,21 +173,51 @@ synchronization</a>. <li><a href="s6-ftrig-listen.html">The <tt>s6-ftrig-listen</tt> program</a></li> </ul> +<h4> Local service management and access control </h4> + +<ul> +<li><a href="s6-ipcclient.html">The <tt>s6-ipcclient</tt> program</a></li> +<li><a href="s6-ipcserver.html">The <tt>s6-ipcserver</tt> program</a></li> +<li><a href="s6-ipcserver-socketbinder.html">The <tt>s6-ipcserver-socketbinder</tt> program</a></li> +<li><a href="s6-ipcserverd.html">The <tt>s6-ipcserverd</tt> program</a></li> +<li><a href="s6-ioconnect.html">The <tt>s6-ioconnect</tt> program</a></li> +</ul> +<p></p> +<ul> +<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> +</ul> +<p></p> +<ul> +<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> Internal commands </h4> <ul> <li><a href="s6-ftrigrd.html">The <tt>s6-ftrigrd</tt> internal program</a></li> -<li><a href="libs6lock/s6lockd.html">The <tt>s6lockd</tt> internal program</a></li> -<li><a href="libs6lock/s6lockd-helper.html">The <tt>s6lockd-helper</tt> internal program</a></li> +<li><a href="libs6/s6lockd.html">The <tt>s6lockd</tt> internal program</a></li> +<li><a href="libs6/s6lockd-helper.html">The <tt>s6lockd-helper</tt> internal program</a></li> </ul> <h3> Libraries </h3> <ul> -<li><a href="libftrigw.html">The <tt>ftrigw</tt> library interface</a></li> -<li><a href="libftrigr.html">The <tt>ftrigr</tt> library interface</a></li> -<li><a href="libs6lock/">The <tt>s6lock</tt> library interface</a></li> +<li><a href="libs6/"><tt>s6/s6.h</tt>, the main entry point</a></li> +<li><a href="libs6/ftrigw.html">The <tt>ftrigw</tt> library interface</a></li> +<li><a href="libs6/ftrigr.html">The <tt>ftrigr</tt> library interface</a></li> +<li><a href="libs6/s6lock.html">The <tt>s6lock</tt> library interface</a></li> +<li><a href="libs6/accessrules.html">The <tt>accessrules</tt> library interface</a></li> </ul> <h3> Definitions </h3> @@ -195,7 +226,8 @@ synchronization</a>. <li> What is a <a href="fifodir.html">fifodir</a></li> <li> What is a <a href="servicedir.html">service directory</a></li> <li> What is a <a href="scandir.html">scan directory</a></li> -<li> Why are the <a href="libftrig.html">libftrigw and libftrigr</a> needed </li> +<li> What is a <a href="localservice.html">local service</a></li> +<li> Why are the <a href="ftrig.html">libftrigw and libftrigr</a> needed </li> </ul> <hr /> diff --git a/doc/libs6/accessrules.html b/doc/libs6/accessrules.html new file mode 100644 index 0000000..bd98b5f --- /dev/null +++ b/doc/libs6/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: the accessrules library interface</title> + <meta name="Description" content="s6: the accessrules library interface" /> + <meta name="Keywords" content="s6 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">libs6</a><br /> +<a href="../">s6</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/accessrules.h</tt> header, +and implemented in the <tt>libs6.a</tt> or <tt>libs6.so</tt> library. +</p> + +<h2> General information </h2> + +<p> + <tt>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/accessrules.h</tt> header for the exact definitions. +</p> + +<h2> Data structures </h2> + +<ul> + <li> A <tt>s6_accessrules_result_t</tt> is a scalar that +can have the following values: S6_ACCESSRULES_ERROR, +S6_ACCESSRULES_DENY, S6_ACCESSRULES_ALLOW or S6_ACCESSRULES_NOTFOUND. </li> + <li> A <tt>s6_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>s6_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>s6_accessrules_result_t f (char const *key, unsigned int keylen, void *handle, s6_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 s6_accessrules_backend_func_t functions are natively implemented: +</p> + +<ul> + <li> <tt>s6_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>s6_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>s6_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>s6_accessrules_backend_func_t</tt> function until it finds +a match. Namely: +</p> + +<p> +<code>s6_accessrules_result_t f (void const *key, void *handle, s6_accessrules_params_t *params, s6_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 S6_ACCESSRULES_NOTFOUND. If no match can be found in the whole list, +<em>f</em> finally returns S6_ACCESSRULES_NOTFOUND. +</p> + +<p> + Five s6_accessrules_keycheck_func_t functions are natively implemented: +</p> + +<ul> + <li> +<a name="uidgid" /> + <tt>s6_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>s6_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>s6_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>s6_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>s6_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 s6_accessrules_keycheck_ip6 or s6_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> s6_accessrules_result_t s6_accessrules_uidgid_cdb +(unsigned int u, unsigned int g, struct cdb *c, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +<p> +<code> s6_accessrules_result_t s6_accessrules_uidgid_fs +(unsigned int u, unsigned int g, char const *dir, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +<p> +<code> s6_accessrules_result_t s6_accessrules_reversedns_cdb +(char const *name, struct cdb *c, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +<p> +<code> s6_accessrules_result_t s6_accessrules_reversedns_fs +(char const *name, char const *dir, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +<p> +<code> s6_accessrules_result_t s6_accessrules_ip4_cdb +(char const *ip4, struct cdb *c, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +<p> +<code> s6_accessrules_result_t s6_accessrules_ip4_fs +(char const *ip4, char const *dir, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +<p> +<code> s6_accessrules_result_t s6_accessrules_ip6_cdb +(char const *ip6, struct cdb *c, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +<p> +<code> s6_accessrules_result_t s6_accessrules_ip6_fs +(char const *ip6, char const *dir, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +<p> +<code> s6_accessrules_result_t s6_accessrules_ip46_cdb +(ip46_t *ip, struct cdb *c, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +<p> +<code> s6_accessrules_result_t s6_accessrules_ip46_fs +(ip46_t const *ip, char const *dir, +s6_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 S6_ACCESSRULES_ALLOW, additional +information may be stored into <em>params</em>. +</p> + +</body> +</html> diff --git a/doc/libftrigr.html b/doc/libs6/ftrigr.html index 79c7694..2c9bf88 100644 --- a/doc/libftrigr.html +++ b/doc/libs6/ftrigr.html @@ -10,7 +10,8 @@ <body> <p> -<a href="index.html">s6</a><br /> +<a href="index.html">libs6</a><br /> +<a href="../">s6</a><br /> <a href="http://skarnet.org/software/">Software</a><br /> <a href="http://skarnet.org/">skarnet.org</a> </p> @@ -23,22 +24,6 @@ programs that want to subscribe to fifodirs and be instantly notified when the proper sequence of events happens. </p> -<h2> Compiling </h2> - -<ul> - <li> Make sure the s6 headers, as well as the skalibs headers, -are visible in your header search path. </li> - <li> Use <tt>#include <s6/ftrigr.h></tt> </li> -</ul> - -<h2> Linking </h2> - -<ul> - <li> Make sure the s6 libraries, as well as the skalibs libraries, -are visible in your library search path. </li> - <li> Link against <tt>-ls6</tt> and <tt>-lskarnet</tt>. </li> -</ul> - <h2> Programming </h2> <p> @@ -51,7 +36,7 @@ exact function prototypes. know it has. This means paying some attention to the SIGCHLD handler, if any, and to the way you perform <tt>waitpid()</tt>s. The best practice is to use a -<a href="http://www.skarnet.org/software/skalibs/libstddjb/selfpipe.html">self-pipe</a> +<a href="http://skarnet.org/software/skalibs/libstddjb/selfpipe.html">self-pipe</a> to handle SIGCHLD (as well as other signals the application needs to trap), and to <em>always</em> use <tt>wait_nohang()</tt> to reap children, simply ignoring pids you don't know. diff --git a/doc/libftrigw.html b/doc/libs6/ftrigw.html index d625f2b..b0feb31 100644 --- a/doc/libftrigw.html +++ b/doc/libs6/ftrigw.html @@ -10,7 +10,8 @@ <body> <p> -<a href="index.html">s6</a><br /> +<a href="index.html">libs6</a><br /> +<a href="../">s6</a><br /> <a href="http://skarnet.org/software/">Software</a><br /> <a href="http://skarnet.org/">skarnet.org</a> </p> @@ -28,22 +29,6 @@ filesystem, and document its location. Listeners will then be able to subscribe to that fifodir, and receive the events. </p> -<h2> Compiling </h2> - -<ul> - <li> Make sure the s6 headers, as well as the skalibs headers, -are visible in your header search path. </li> - <li> Use <tt>#include <s6/ftrigw.h></tt> </li> -</ul> - -<h2> Linking </h2> - -<ul> - <li> Make sure the s6 libraries, as well as the skalibs libraries, -are visible in your library search path. </li> - <li> Link against <tt>-ls6</tt> and <tt>-lskarnet</tt>. </li> -</ul> - <h2> Programming </h2> <p> diff --git a/doc/libs6/index.html b/doc/libs6/index.html new file mode 100644 index 0000000..9fe7e65 --- /dev/null +++ b/doc/libs6/index.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: the s6 library interface</title> + <meta name="Description" content="s6: the s6 library interface" /> + <meta name="Keywords" content="s6 s6 libs6 library libs6net" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="../">s6</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6</tt> library interface </h1> + +<h2> General information </h2> + +<p> + <tt>libs6</tt> is a collection of utility +C interfaces, used in the s6 executables. +</p> + +<h2> Compiling </h2> + +<ul> + <li> Make sure the s6 headers, as well as the skalibs headers, +are visible in your header search path. </li> + <li> Use <tt>#include <s6/s6.h></tt> </li> +</ul> + +<h2> Linking </h2> + +<ul> + <li> Make sure the s6 libraries, as well as the skalibs +libraries, are visible in your library search path. </li> + <li> Link against <tt>-ls6</tt> and <tt>-lskarnet</tt>. +If you're using socket functions (which is the case with +<a href="ftrigr.html">libftrigr</a>, for instance, add +<tt>`cat $sysdeps/socket.lib`</tt> to your command line. +If you're using timed functions involving TAI timestamps +(which is also the case with <a href="ftrigr.html">libftrigr</a> +for instance), add +<tt>`cat $sysdeps/tainnow.lib`</tt>. <tt>$sysdeps</tt> +stands for your skalibs sysdeps directory. </li> +</ul> + +<h2> Programming </h2> + +<p> + The <tt>s6/s6.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/accessrules.h</a> header +provides functions to check credentials against configuration files. </li> + <li> The <a href="ftrigr.html">s6/ftrigr.h</a> header provides +functions to subscribe to fifodirs and be notified of events. </li> + <li> The <a href="ftrigw.html">s6/ftrigw.h</a> header provides +functions to manage fifodirs and send notifications to them. </li> + <li> The <a href="s6lock.html">s6/s6lock.h</a> header provides +functions to acquire locks with a timeout. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-ftrigrd.html b/doc/libs6/s6-ftrigrd.html index 049164d..4bbfc69 100644 --- a/doc/s6-ftrigrd.html +++ b/doc/libs6/s6-ftrigrd.html @@ -10,7 +10,8 @@ <body> <p> -<a href="index.html">s6</a><br /> +<a href="index.html">libs6</a><br /> +<a href="../">s6</a><br /> <a href="http://skarnet.org/software/">Software</a><br /> <a href="http://skarnet.org/">skarnet.org</a> </p> @@ -20,7 +21,7 @@ <p> s6-ftrigrd is a helper program that manages a set of subscriptions to fifodirs as well as regular expressions on events. It takes orders from its client program that controls -it via the <a href="libftrigr.html">ftrigr library</a>, and notifies it when desired +it via the <a href="ftrigr.html">ftrigr library</a>, and notifies it when desired events happen. </p> @@ -37,9 +38,9 @@ stdout is a pipe writing to the client; its stderr is the same as the client's; there's an additional pipe from s6-ftrigrd to the client, used for asynchronous notifications. </li> <li> If the client program uses <tt>ftrigr_start()</tt>, then it tries to connect -to a Unix domain socket. A <em>ftrigrd service</em> should be listening to that +to a Unix domain socket. A ftrigrd <a href="../localservice.html">local service</a> should be listening to that socket, i.e. a Unix domain superserver such as -<a href="http://www.skarnet.org/software/s6-networking/s6-ipcserver.html">s6-ipcserver</a> +<a href="s6-ipcserver.html">s6-ipcserver</a> spawning a s6-ftrigrd program on every connection. Then a s6-ftrigrd instance is created for the client. </li> <li> When the client uses <tt>ftrigr_end()</tt>, or closes s6-ftrigrd's stdin in @@ -58,7 +59,7 @@ the client. <p> The connection management between the client and s6-ftrigrd is entirely done -by the <a href="http://www.skarnet.org/software/skalibs/libunixonacid/skaclient.html">skaclient</a> +by the <a href="http://skarnet.org/software/skalibs/libunixonacid/skaclient.html">skaclient</a> library. </p> diff --git a/doc/libs6lock/index.html b/doc/libs6/s6lock.html index 7237823..ca22fe4 100644 --- a/doc/libs6lock/index.html +++ b/doc/libs6/s6lock.html @@ -4,12 +4,13 @@ <meta http-equiv="Content-Language" content="en" /> <title>s6: the s6lock library interface</title> <meta name="Description" content="s6: the s6lock library interface" /> - <meta name="Keywords" content="s6 timed lock s6lock libs6lock library interface" /> + <meta name="Keywords" content="s6 timed lock s6lock libs6 library interface" /> <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> </head> <body> <p> +<a href="index.html">libs6</a><br /> <a href="../">s6</a><br /> <a href="http://skarnet.org/software/">Software</a><br /> <a href="http://skarnet.org/">skarnet.org</a> @@ -20,31 +21,12 @@ <h2> General information </h2> <p> - <tt>libs6lock</tt> is a C interface to timed locks. Unix natively provides + <tt>s6lock</tt> is a C interface to timed locks. Unix natively provides locks, but the locking primitives are synchronous, so either they are -unbounded in execution time or they require polling. libs6lock provides +unbounded in execution time or they require polling. s6lock provides poll-free locks that can timeout during attempted acquisition. </p> -<h2> Compiling </h2> - -<ul> - <li> Make sure the s6 headers, as well as the skalibs headers, -are visible in your header search path. </li> - <li> Use <tt>#include <s6/s6lock.h></tt> </li> -</ul> - -<h2> Linking </h2> - -<ul> - <li> Make sure the s6 libraries, as well as the skalibs libraries, -are visible in your library search path. </li> - <li> Link against <tt>-ls6</tt>, <tt>-lskarnet</tt>, -<tt>`cat $sysdeps/socket.lib`</tt>, and -<tt>`cat $sysdeps/tainnow.lib`</tt>, -if <tt>$sysdeps</tt> is your skalibs installation's sysdeps directory. </li> -</ul> - <h2> Programming </h2> <ul> @@ -54,7 +36,7 @@ often simplified macros, for instance relying on the STAMP global variable to hold the current time. Fully reentrant functions with more control options are usually available. </li> <li> Given the nature of the s6lock library, it makes sense to use a -<a href="http://skarnet.org/software/s6-networking/localservice.html">s6lockd service</a> concurrently +<a href="../localservice.html">s6lockd service</a> concurrently accessed by several applications using such locks to gate shared resources. </li> <li> If you're not using a s6lockd service, diff --git a/doc/libs6lock/s6lockd-helper.html b/doc/libs6/s6lockd-helper.html index 839dce4..2c54e5c 100644 --- a/doc/libs6lock/s6lockd-helper.html +++ b/doc/libs6/s6lockd-helper.html @@ -9,7 +9,7 @@ </head> <body> -<a href="index.html">libs6lock</a><br /> +<a href="index.html">libs6</a><br /> <a href="../">s6</a><br /> <a href="http://skarnet.org/software/">Software</a><br /> <a href="http://skarnet.org/">skarnet.org</a><p /> diff --git a/doc/libs6lock/s6lockd.html b/doc/libs6/s6lockd.html index 726d2f8..7db76be 100644 --- a/doc/libs6lock/s6lockd.html +++ b/doc/libs6/s6lockd.html @@ -9,7 +9,7 @@ </head> <body> -<a href="index.html">libs6lock</a><br /> +<a href="index.html">libs6</a><br /> <a href="../">s6</a><br /> <a href="http://skarnet.org/software/">Software</a><br /> <a href="http://skarnet.org/">skarnet.org</a><p /> @@ -27,7 +27,7 @@ a set of lock files in a given directory, and associated timeouts. s6lockd does not fork, does not background itself automatically, and does not use syslog. It is not meant to be run directly by the user: it will be spawned by the -<a href="index.html">s6lock client library</a>. +<a href="s6lock.html">s6lock client library</a>. </p> <p> @@ -44,7 +44,7 @@ a s6lockd instance might not be able to open a lock file created by a former instance run by another client with different permissions. </li> <li> Use the <tt>s6lock_start()</tt> library call, together with a -<a href="http://skarnet.org/software/s6-networking/localservice.html">s6lockd service</a>. +<a href="../localservice.html">s6lockd service</a>. For once, <em>this is the recommended setup</em>: s6lockd creates empty lock files, and having all s6lockd instances run under the same user simplifies permissions management considerably. </li> @@ -55,7 +55,7 @@ simplifies permissions management considerably. </li> When run as a service, s6lockd has no "standalone" mode: it is designed to work with a Unix domain superserver, like -<a href="http://skarnet.org/software/s6-networking/s6-ipcserver.html">s6-ipcserver</a>. +<a href="../s6-ipcserver.html">s6-ipcserver</a>. s6lockd follows the <a href="http://cr.yp.to/proto/ucspi.txt">UCSPI</a> interface, it can be directly executed from the superserver. </p> diff --git a/doc/localservice.html b/doc/localservice.html new file mode 100644 index 0000000..3b555fd --- /dev/null +++ b/doc/localservice.html @@ -0,0 +1,153 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: what is a local service</title> + <meta name="Description" content="s6: what is a local service" /> + <meta name="Keywords" content="s6 local service s6-ipcserver" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</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 +<a href="http://skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a>, +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="libs6/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="libs6/s6lockd.html">s6lockd</a>, +handling time-constrained lock acquisition on client behalf. </li> + <li> <a href="http://skarnet.org/software/s6-dns/skadns/skadnsd.html">skadnsd</a>, +performing asynchronous DNS queries and only waking up the client process +when an answer arrives. </li> +</ul> + +<p> + Those processes are usually spawned from a client, via the corresponding +<tt>*_startf*()</tt> library call. But they can also be spawned from a +s6-ipcserver program in a local service configuration. In both cases, they +need an additional control channel to be passed from the server to +the client: the main socket is used for synchronous commands from the client +to the server and their answers, whereas the additional channel, which is +now implemented as a socket as well (but created by the server on-demand +and not bound to a local path), is used for asynchronous +notifications from the server to the client. The fd-passing mechanism +is used to transfer the additional channel from the server to the client. +</p> + +</body> +</html> diff --git a/doc/s6-accessrules-cdb-from-fs.html b/doc/s6-accessrules-cdb-from-fs.html new file mode 100644 index 0000000..f7b6be0 --- /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: the s6-accessrules-cdb-from-fs program</title> + <meta name="Description" content="s6: the s6-accessrules-cdb-from-fs program" /> + <meta name="Keywords" content="s6 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</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="http://skarnet.org/software/s6-networking/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="http://skarnet.org/software/s6-networking/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="http://skarnet.org/software/s6-networking/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="libs6/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="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://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="http://skarnet.org/software/s6-networking/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..b8c6b12 --- /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: the s6-accessrules-fs-from-cdb program</title> + <meta name="Description" content="s6: the s6-accessrules-fs-from-cdb program" /> + <meta name="Keywords" content="s6 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</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="http://skarnet.org/software/s6-networking/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 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-cleanfifodir.html b/doc/s6-cleanfifodir.html index 5724666..cfbbc90 100644 --- a/doc/s6-cleanfifodir.html +++ b/doc/s6-cleanfifodir.html @@ -34,7 +34,7 @@ That means it removes all stale FIFOs in <em>fifodir</em>. <p> In normal use, it is not necessary to call s6-cleanfifodir. However, stale -FIFOs can be left by <a href="s6-ftrigrd.html">s6-ftrigrd</a> processes that +FIFOs can be left by <a href="libs6/s6-ftrigrd.html">s6-ftrigrd</a> processes that were violently killed, so it's good practice to regularly clean up fifodirs. </p> diff --git a/doc/s6-connlimit.html b/doc/s6-connlimit.html new file mode 100644 index 0000000..fc316cf --- /dev/null +++ b/doc/s6-connlimit.html @@ -0,0 +1,107 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-connlimit program</title> + <meta name="Description" content="s6: the s6-connlimit program" /> + <meta name="Keywords" content="s6 connection limit s6-connlimit" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-connlimit</tt> program </h1> + +<p> +<tt>s6-connlimit</tt> is a small utility to perform IP-based +control on the number of client connections to a TCP socket, and +uid-based control on the number of client connections to a Unix +domain socket. +</p> + +<h2> Interface </h2> + +<pre> + s6-connlimit <em>prog...</em> +</pre> + +<ul> + <li> <tt>s6-connlimit</tt> reads its environment for the PROTO +environment variable, and then for ${PROTO}CONNNUM and ${PROTO}CONNMAX, +which must contain integers. </li> + <li> If the value of ${PROTO}CONNNUM is superior or equal to the value +of ${PROTO}CONNMAX, s6-connlimit exits 1 with an error message. </li> + <li> Else it execs into <em>prog...</em>. </li> + <li> If ${PROTO}CONNMAX is unset, s6-connlimit directly execs into +<em>prog...</em> without performing any check: +no maximum number of connections has been defined. </li> +</ul> + +<h2> Usage </h2> + +<p> + The <a href="http://skarnet.org/software/s6-networking/s6-tcpserver4.html">s6-tcpserver4</a> and +<a href="http://skarnet.org/software/s6-networking/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="http://skarnet.org/software/s6-networking/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> + +<h2> Notes </h2> + +<ul> + <li> The s6-connlimit utility was once part of the +<a href=""http://skarnet.org/software/s6-networking/">s6-networking</a> +suite, and is mostly useful with TCP connections, which is why the +examples here involve TCP. Nevertheless, it can be used with connections +across Unix domain sockets, and that is why it has been moved to the s6 +package. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-ftrig-notify.html b/doc/s6-ftrig-notify.html index 4f881eb..c10bf71 100644 --- a/doc/s6-ftrig-notify.html +++ b/doc/s6-ftrig-notify.html @@ -37,7 +37,7 @@ with all the characters in <em>message</em>. <p> s6-ftrig-notify cannot be used to send the null character (event 0x00). If you need to send the null character, use the C API: -<a href="libftrigw.html">ftrigw_notify()</a>. +<a href="libs6/ftrigw.html">ftrigw_notify()</a>. </p> </body> diff --git a/doc/s6-ioconnect.html b/doc/s6-ioconnect.html new file mode 100644 index 0000000..9972222 --- /dev/null +++ b/doc/s6-ioconnect.html @@ -0,0 +1,90 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-ioconnect program</title> + <meta name="Description" content="s6: the s6-ioconnect program" /> + <meta name="Keywords" content="s6 ioconnect ucspi tcpconnect ipcconnect" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</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="http://skarnet.org/software/s6-networking/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> + <li> The s6-ioconnect utility was once part of the +<a href=""http://skarnet.org/software/s6-networking/">s6-networking</a> +suite, which is why the +examples here involve TCP. Nevertheless, it can be used with connections +across Unix domain sockets as well, and has its place in the s6 +package. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-ipcclient.html b/doc/s6-ipcclient.html new file mode 100644 index 0000000..fee6e52 --- /dev/null +++ b/doc/s6-ipcclient.html @@ -0,0 +1,74 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-ipcclient program</title> + <meta name="Description" content="s6: the s6-ipcclient program" /> + <meta name="Keywords" content="s6 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</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> + +<h2> Notes </h2> + +<ul> + <li> s6-ipcclient is mostly used to connect a client to a +<a href="localservice.html">local service</a> without having +to implement networking in the client. For instance, the +<a href="s6-sudo">s6-sudo</a> program does this. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-ipcserver-access.html b/doc/s6-ipcserver-access.html new file mode 100644 index 0000000..a462c4f --- /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: the s6-ipcserver-access program</title> + <meta name="Description" content="s6: the s6-ipcserver-access program" /> + <meta name="Keywords" content="s6 s6-ipcserver-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</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-ipcserver-access</tt> program </h1> + +<p> +<tt>s6-ipcserver-access</tt> is a command-line access +control tool for Unix domain sockets on systems where the +<a href="http://www.superscript.com/ucspi-ipc/getpeereid.html">getpeereid()</a> system call can be implemented. +It is meant to be run after +<a href="s6-ipcserverd.html">s6-ipcserverd</a> and before +the application program on the s6-ipcserver command line. +</p> + +<h2> Interface </h2> + +<pre> + s6-ipcserver-access [ -v <em>verbosity</em> ] [ -E | -e ] [ -l <em>localname</em> ] [ -i <em>rulesdir</em> | -x <em>rulesfile</em> ] <em>prog...</em> +</pre> + +<ul> + <li> s6-ipcserver-access checks it is run under a UCSPI server tool +such as <a href="s6-ipcserver.html">s6-ipcserver</a>. + <li> It checks that the remote end of the connection fits the +accepted criteria defined by the database contained in <em>rulesdir</em> +or <em>rulesfile</em>. If the database tells it to reject the connection, +the program exits 1. </li> + <li> It sets up a few additional environment variables. </li> + <li> It executes into <em>prog...</em>, +unless the first matching rule in the rule database +includes instructions to override <em>prog...</em>. </li> +</ul> + +<h2> Environment variables </h2> + +<p> +s6-ipcserver-access expects to inherit some environment variables from +its parent: +</p> + +<ul> + <li> PROTO: normally IPC, but could be anything else, like UNIX. </li> + <li> ${PROTO}REMOTEEUID: the effective UID of the client program connecting to the socket. </li> + <li> ${PROTO}REMOTEEGID: the effective GID of the client program connecting to the socket. </li> +</ul> + +<p> + Additionally, it exports the following variables before executing into +<em>prog...</em>: +</p> + +<ul> + <li> ${PROTO}LOCALPATH: set to the local "address" of the socket, as +reported by the +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html">getsockname()</a> +system call, truncated to 99 characters max. </li> +</ul> + +<p> + Also, the access rules database can instruct s6-ipcserver-access to set +up, or unset, more environment variables, depending on the client address. +</p> + +<h2> Options </h2> + +<ul> + <li> <tt>-v <em>verbosity</em></tt> : be more or less verbose, i.e. +print more or less information to stderr: + <ul> + <li> 0: only log error messages. </li> + <li> 1: only log error and warning messages, and accepted connections. +This is the default. </li> + <li> 2: also log rejected connections and more warning messages. </li> + </ul> </li> + <li> <tt>-E</tt> : no environment. All environment variables potentially +set by s6-ipcserver-access, as well as those set by +<a href="s6-ipcserver.html">s6-ipcserver</a>, will be unset instead. </li> + <li> <tt>-e</tt> : set up environment variables normally. +This is the default. </li> + <li> <tt>-l <em>localname</em></tt> : use <em>localname</em> +as the value for the ${PROTO}LOCALPATH environment variable, instead of +looking it up via getsockname(). </li> + <li> <tt>-i <em>rulesdir</em></tt> : check client credentials +against a filesystem-based database in the <em>rulesdir</em> directory. </li> + <li> <tt>-x <em>rulesfile</em></tt> : check client credentials +against a <a href="http://en.wikipedia.org/wiki/Cdb_(software)">cdb</a> +database in the <em>rulesfile</em> file. <tt>-i</tt> and <tt>-x</tt> are +mutually exclusive. If none of those options is given, no credential checking will be +performed, and a warning will be emitted on every connection if +<em>verbosity</em> is 2 or more. </li> +</ul> + +<h2> Access rule checking </h2> + +<p> + s6-ipcserver-access checks its client connection against +a ruleset. This ruleset can be implemented: +</p> + +<ul> + <li> either in the filesystem as an arborescence of directories and files, +if the <tt>-i</tt> option has been given. This option is the most flexible +one: the directory format is simple enough for scripts to understand and +modify it, and the ruleset can be changed dynamically. This is practical, +for instance, for roaming users. </li> +<li> or in a <a href="http://en.wikipedia.org/wiki/Cdb_(software)">CDB +file</a>, if the <tt>-x</tt> option has been given. This option is the most +efficient one if the ruleset is static enough: a lot less system calls are +needed to perform searches in a CDB than in the filesystem. </li> +</ul> + +<p> + The exact format of the ruleset is described on the +<a href="s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> page. +</p> + +<p> +s6-ipcserver-access first reads the client UID <em>uid</em> and +GID <em>gid</em> from the +${PROTO}REMOTEEUID and ${PROTO}REMOTEEGID environment variables, and checks +them with the +<a href="libs6/accessrules.html#uidgid">s6_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 S6_ACCESSRULES_ALLOW result can be obtained, +the connection is denied. +</p> + +<h2> Environment and executable modifications </h2> + +<p> + s6-ipcserver-access interprets non-empty <tt>env</tt> subdirectories +and <tt>exec</tt> files +it finds in the first matching rule of the ruleset, as explained +in the <a href="s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> +page. +</p> + +<ul> + <li> An <tt>env</tt> subdirectory is interpreted as if the +<a href="http://skarnet.org/software/s6/s6-envdir.html">s6-envdir</a> +command had been called before executing <em>prog</em>: the environment +is modified according to the contents of <tt>env</tt>. </li> + <li> An <tt>exec</tt> file containing <em>newprog</em> completely +bypasses the rest of s6-ipcserver-access' command line. After +environment modifications, if any, s6-ipcserver-access execs into +<tt><a href="http://skarnet.org/software/execline/execlineb.html">execlineb</a> -c <em>newprog</em></tt>. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-ipcserver-socketbinder.html b/doc/s6-ipcserver-socketbinder.html new file mode 100644 index 0000000..1edfe19 --- /dev/null +++ b/doc/s6-ipcserver-socketbinder.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: the s6-ipcserver-socketbinder program</title> + <meta name="Description" content="s6: the s6-ipcserver-socketbinder program" /> + <meta name="Keywords" content="s6 s6-ipcserver-socketbinder ipcserver ucspi socket bind listen" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-ipcserver-socketbinder</tt> program </h1> + +<p> +<tt>s6-ipcserver-socketbinder</tt> binds a Unix domain +socket, then executes a program. +</p> + +<h2> Interface </h2> + +<pre> + s6-ipcserver-socketbinder [ -d | -D ] [ -b <em>backlog</em> ] <em>path</em> <em>prog...</em> +</pre> + +<ul> + <li> s6-ipcserver-socketbinder creates a Unix domain socket of type SOCK_STREAM +and binds it to <em>path</em>. It prepares the socket to accept +connections by calling +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html">listen()</a>. </li> + <li> It then execs into <em>prog...</em> with the open socket +as its standard input. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-d</tt> : allow instant rebinding to the same path +even if it has been used not long ago - this is the SO_REUSEADDR flag to +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">setsockopt()</a> +and is generally used with server programs. This is the default. Note that +<em>path</em> will be deleted if it already exists at program start time. </li> + <li> <tt>-D</tt> : disallow instant rebinding to the same path. </li> + <li> <tt>-b <em>backlog</em></tt> : set a maximum of +<em>backlog</em> backlog connections on the socket. Extra +connection attempts will rejected by the kernel. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> s6-ipcserver-socketbinder is part of a set of basic blocks used to +build a flexible Unix super-server. It normally should be given a +command line crafted to make it execute into +<a href="s6-ipcserverd.html">s6-ipcserverd</a> to accept connections +from clients, or into a program such as +<a href="s6-applyuidgid.html">s6-applyuidgid</a> +to drop privileges before doing so. </li> + <li> The <a href="s6-ipcserver.html">s6-ipcserver</a> program does +exactly this. It implements +a full Unix super-server by building a command line starting with +s6-ipcserver-socketbinder and ending with s6-ipcserverd followed by the +application program, and executing into it. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-ipcserver.html b/doc/s6-ipcserver.html new file mode 100644 index 0000000..855fe4b --- /dev/null +++ b/doc/s6-ipcserver.html @@ -0,0 +1,173 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-ipcserver program</title> + <meta name="Description" content="s6: the s6-ipcserver program" /> + <meta name="Keywords" content="s6 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</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-ipcserver</tt> program </h1> + +<p> +<tt>s6-ipcserver</tt> is an +<a href="http://cr.yp.to/proto/ucspi.txt">UCSPI server tool</a> for +Unix domain sockets, i.e. a super-server. +It accepts connections from clients, and forks a +program to handle each connection. +</p> + +<h2> Interface </h2> + +<pre> + s6-ipcserver [ -1 ] [ -q | -Q | -v ] [ -d | -D ] [ -P | -p ] [ -c <em>maxconn</em> ] [ -C <em>localmaxconn</em> ] [ -b <em>backlog</em> ] [ -G <em>gidlist</em> ] [ -g <em>gid</em> ] [ -u <em>uid</em> ] [ -U ] <em>path</em> <em>prog...</em> +</pre> + +<ul> + <li> s6-ipcserver binds a Unix domain socket to <em>path</em>. </li> + <li> It can drop its root privileges. </li> + <li> It closes its stdin and stdout. </li> + <li> For every client connection to this socket, it +forks. The child sets some environment variables, then +executes <em>prog...</em> with stdin reading from the socket and +stdout writing to it. </li> + <li> Depending on the verbosity level, it logs what it does to stderr. </li> + <li> It runs until killed by a signal. Depending on the received +signal, it may kill its children before exiting. </li> + <li> s6-ipcserver actually doesn't do any of this itself. It is +a wrapper, rewriting the command line and executing into a chain +of programs that perform those duties. </li> +</ul> + +<h2> Implementation </h2> + +<ul> + <li> s6-ipcserver parses the options and arguments it is given, and +builds a new command line with them. It then executes into that new +command line. </li> + <li> The first program s6-ipcserver executes into is +<a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>. +It will create and bind a Unix domain socket to <em>path</em>, then +execute into the rest of the command line. </li> + <li> If a privilege-dropping operation has been requested, the +program that s6-ipcserver-socketbinder executes into is +<a href="s6-applyuidgid.html">s6-applyuidgid</a>. +It will drop the root privileges, then execute into the rest of the +command line. </li> + <li> The next program in the chain is +<a href="s6-ipcserverd.html">s6-ipcserverd</a>. It is executed into +by s6-applyuidgid, or directly by s6-ipcserver-socketbinder if no +privilege-dropping operation has been requested. s6-ipcserverd is +the long-lived process, the "daemon" itself, accepting connections +from clients. </li> + <li> For every client, s6-ipcserverd will spawn an instance of +<em>prog...</em>, the remainder of the command line. </li> +</ul> + + +<h2> Options </h2> + +<ul> + <li> <tt>-1</tt> : write <em>path</em>, followed by a newline, +to stdout, before +closing it, right after binding and listening to the Unix socket. +If stdout is suitably redirected, this can be used by monitoring +programs to check when the server is ready to accept connections. </li> + <li> <tt>-q</tt> : be quiet. </li> + <li> <tt>-Q</tt> : be normally verbose. This is the default. </li> + <li> <tt>-v</tt> : be verbose. </li> + <li> <tt>-d</tt> : allow instant rebinding to the same path +even if it has been used not long ago - this is the SO_REUSEADDR flag to +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">setsockopt()</a> +and is generally used with server programs. This is the default. Note that +<em>path</em> will be deleted if it already exists at program start time. </li> + <li> <tt>-D</tt> : disallow instant rebinding to the same path. </li> + <li> <tt>-P</tt> : disable client credentials lookups. The +IPCREMOTEEUID and IPCREMOTEEGID environment variables will be unset +in every instance of <em>prog...</em>. This is the portable option, +because not every system supports credential lookup across Unix domain +sockets; but it is not as secure. </li> + <li> <tt>-p</tt> : enable client credentials lookups. This +is the default; it works at least on Linux, Solaris, and +*BSD systems. On systems that do not support it, every connection +attempt will fail with a warning message. </li> + <li> <tt>-c <em>maxconn</em></tt> : accept at most +<em>maxconn</em> concurrent connections. Default is 40. It is +impossible to set it higher than 1000. </li> + <li> <tt>-C <em>localmaxconn</em></tt> : accept at most +<em>localmaxconn</em> connections from the same user ID. +Default is 40. It is impossible to set it higher than <em>maxconn</em>. </li> + <li> <tt>-b <em>backlog</em></tt> : set a maximum of +<em>backlog</em> backlog connections on the socket. Extra +connection attempts will rejected by the kernel. </li> + <li> <tt>-G <em>gidlist</em></tt> : change s6-ipcserver's +supplementary group list to <em>gidlist</em> after binding the socket. +This is only valid when run as root. <em>gidlist</em> must be a +comma-separated list of numerical group IDs. </li> + <li> <tt>-g <em>gid</em></tt> : change s6-ipcserver's groupid +to <em>gid</em> after binding the socket. This is only valid when run +as root. </li> + <li> <tt>-u <em>uid</em></tt> : change s6-ipcserver's userid +to <em>uid</em> after binding the socket. This is only valid when run +as root. </li> + <li> <tt>-U</tt> : change s6-ipcserver's user id, group id and +supplementary group list +according to the values of the UID, GID and GIDLIST environment variables +after binding the socket. This is only valid when run as root. +This can be used with the +<a href="s6-envuidgid.html">s6-envuidgid</a> +program to easily script a service that binds to a privileged socket +then drops its privileges to those of a named non-root account. </li> +</ul> + +<h2> Implementation </h2> + +<ul> + <li> s6-ipcserver parses the options and arguments it is given, and +builds a new command line with them. It then executes into that new +command line. </li> + <li> The first program s6-ipcserver executes into is +<a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>. +It will create and bind a Unix domain socket to <em>path</em>, then +execute into the rest of the command line. </li> + <li> If a privilege-dropping operation has been requested, the +program that s6-ipcserver-socketbinder executes into is +<a href="s6-applyuidgid.html">s6-applyuidgid</a>. +It will drop the root privileges, then execute into the rest of the +command line. </li> + <li> The next program in the chain is +<a href="s6-ipcserverd.html">s6-ipcserverd</a>. It is executed into +by s6-applyuidgid, or directly by s6-ipcserver-socketbinder if no +privilege-dropping operation has been requested. s6-ipcserverd is +the long-lived process, the "daemon" itself, accepting connections +from clients. </li> + <li> For every client, s6-ipcserverd will spawn an instance of +<em>prog...</em>, the remainder of the command line. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> s6-ipcserver does not interpret its options itself. It just +dispatches them to the appropriate program on the command line that +it builds. </li> + <li> Previous versions of s6-ipcserver were +monolithic: it did the work of s6-ipcserver-socketbinder, +s6-applyuidgid and s6-ipcserverd itself. The functionality has now +been split into several different programs because some service startup +schemes require the daemon to get its socket from an external +program instead of creating and binding it itself. The most obvious +application of this is upgrading a long-lived process without +losing existing connections. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-ipcserverd.html b/doc/s6-ipcserverd.html new file mode 100644 index 0000000..8bf5ea4 --- /dev/null +++ b/doc/s6-ipcserverd.html @@ -0,0 +1,131 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-ipcserverd program</title> + <meta name="Description" content="s6: the s6-ipcserverd program" /> + <meta name="Keywords" content="s6 s6-ipcserverd ipcserver ucspi unix server super-server" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-ipcserverd</tt> program </h1> + +<p> +<tt>s6-ipcserverd</tt> is the serving part of the +<a href="s6-ipcserver.html">s6-ipcserver</a> super-server. +It assumes that its stdin is a bound and listening Unix +domain socket, and +it accepts connections from clients connecting to it, forking a +program to handle each connection. +</p> + +<h2> Interface </h2> + +<pre> + s6-ipcserverd [ -1 ] [ -v verbosity ] [ -P | -p ] [ -c <em>maxconn</em> ] [ -C <em>localmaxconn</em> ] <em>prog...</em> +</pre> + +<ul> + <li> s6-ipcserverd accepts connections from clients to an already +bound and listening SOCK_STREAM Unix domain socket which is its +standard input. </li> + <li> For every client connection to this socket, it +forks. The child sets some environment variables, then +executes <em>prog...</em> with stdin reading from the socket and +stdout writing to it. </li> + <li> Depending on the verbosity level, it logs what it does to stderr. </li> + <li> It runs until killed by a signal. Depending on the received +signal, it may kill its children before exiting. </li> +</ul> + +<h2> Environment variables </h2> + +<p> + For each connection, an instance of <em>prog...</em> is spawned with +the following variables set: +</p> + +<ul> + <li> PROTO: always set to IPC </li> + <li> IPCREMOTEEUID: set to the effective UID of the client, +unless credentials lookups have been disabled </li> + <li> IPCREMOTEEGID: set to the effective GID of the client, +unless credentials lookups have been disabled </li> + <li> IPCREMOTEPATH: set to the path associated with the remote socket, +if any. Be aware that it may contain arbitrary characters. </li> + <li> IPCCONNNUM: set to the number of connections originating from +the same user (i.e. same uid) </li> +</ul> + +<p> + If client credentials lookup has been disabled, IPCREMOTEEUID and +IPCREMOTEEUID will be set, but empty. +</p> + + +<h2> Options </h2> + +<ul> + <li> <tt>-1</tt> : write a newline to stdout, and close stdout, +right before entering the client-accepting loop. +If stdout is suitably redirected, this can be used by monitoring +programs to check when the server is accepting connections. +The <a href="s6-notifywhenup.html">s6-notifywhenup</a> +program can be used before the s6-ipcserver +invocation to notify listeners when the server is ready. </li> + <li> <tt>-v <em>verbosity</em></tt> : be more or less +verbose. <em>verbosity</em> can be 0 (quiet), 1 (normal), or 2 +(verbose). </li> + <li> <tt>-P</tt> : disable client credentials lookups. The +IPCREMOTEEUID and IPCREMOTEEGID environment variables will be unset +in every instance of <em>prog...</em>. This is the portable option, +because not every system supports credential lookup across Unix domain +sockets; but it is not as secure. </li> + <li> <tt>-p</tt> : enable client credentials lookups. This +is the default; it works at least on Linux, Solaris, and +*BSD systems. On systems that do not support it, every connection +attempt will fail with a warning message. </li> + <li> <tt>-c <em>maxconn</em></tt> : accept at most +<em>maxconn</em> concurrent connections. Default is 40. It is +impossible to set it higher than 1000. </li> + <li> <tt>-C <em>localmaxconn</em></tt> : accept at most +<em>localmaxconn</em> connections from the same user ID. +Default is 40. It is impossible to set it higher than <em>maxconn</em>. </li> +</ul> + +<h2> Signals </h2> + +<ul> + <li> SIGTERM: exit. </li> + <li> SIGHUP: send a SIGTERM and a SIGCONT to all children. </li> + <li> SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit. </li> + <li> SIGABRT: send a SIGKILL to all children, then exit. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> Unlike his close cousin +<a href="http://www.superscript.com/ucspi-ipc/ipcserver.html">ipcserver</a>, +s6-ipcserverd does not perform operations such as access control. Those are +delegated to the +<a href="s6-ipcserver-access.html">s6-ipcserver-access</a> program. </li> + <li> s6-ipcserverd can be used to set up +<a href="localservice.html">local services</a>. </li> + <li> s6-ipcserverd is meant to be execve'd into by a program that gets +the listening socket. That program is normally +<a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>, +which creates the socket itself; but it can be a different one if the +socket is to be retrieved by another means, for instance by fd-passing +from a fd-holding daemon (some people call this "socket activation"). </li> +</ul> + +</body> +</html> diff --git a/doc/s6-notifywhenup.html b/doc/s6-notifywhenup.html index b772925..054e0f5 100644 --- a/doc/s6-notifywhenup.html +++ b/doc/s6-notifywhenup.html @@ -68,11 +68,11 @@ Default is 0, meaning infinite. </li> for <em>prog</em> to keep the same pid, which is vital for supervised processes. </li> <li> s6-notifywhenup can be used, for instance, with -<a href="http://skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a> +<a href="s6-ipcserver.html">s6-ipcserver</a> and its <tt>-1</tt> option, so that reliable startup notification is -achieved. <tt>s6-notifywhenup -f s6-tcpserver -1 <em>args</em></tt> will -send a 'U' event to <tt>./event</tt> when s6-tcpserver is actually -listening to its network socket. </li> +achieved. <tt>s6-notifywhenup -f s6-ipcserver -1 <em>args</em></tt> will +send a 'U' event to <tt>./event</tt> when s6-ipcserver is actually +listening to its socket. </li> <li> The <a href="s6-svwait.html">s6-svwait</a> program can be used to wait for 'U' events. </li> </ul> diff --git a/doc/s6-setlock.html b/doc/s6-setlock.html index f425656..f163336 100644 --- a/doc/s6-setlock.html +++ b/doc/s6-setlock.html @@ -55,7 +55,7 @@ execution. This is intended: the fd holds the lock, which is released when <em>prog</em> exits. <em>prog</em> must not touch fds it does not know about. </li> <li> If the timed lock option is chosen, s6-setlock does not acquire the lock -itself. Instead, it spawns a <a href="libs6lock/s6lockd-helper.html">s6lockd-helper</a> +itself. Instead, it spawns a <a href="libs6/s6lockd-helper.html">s6lockd-helper</a> process that acquires the lock while s6-setlock controls the timeout; the s6lockd-helper process then holds the lock and lives as long as <em>prog</em>. </li> diff --git a/doc/s6-sudo.html b/doc/s6-sudo.html new file mode 100644 index 0000000..0120816 --- /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: the s6-sudo program</title> + <meta name="Description" content="s6: the s6-sudo program" /> + <meta name="Keywords" content="s6 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</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..0eec1c9 --- /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: the s6-sudoc program</title> + <meta name="Description" content="s6: the s6-sudoc program" /> + <meta name="Keywords" content="s6 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</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-sudoc</tt> program </h1> + +<p> +<tt>s6-sudoc</tt> talks to a peer <a href="s6-sudod.html">s6-sudod</a> +program over a Unix socket, passing it command-line arguments, environment +variables and standard descriptors. +</p> + +<h2> Interface </h2> + +<pre> + s6-sudoc [ -e ] [ -t <em>timeoutconn</em> ] [ -T <em>timeoutrun</em> ] [ <em>args...</em> ] +</pre> + +<ul> + <li> s6-sudoc transmits its standard input, standard output and standard error +via fd-passing over a Unix socket that must be open on its descriptors 6 and 7. + It expects a <a href="s6-sudod.html">s6-sudod</a> process to be receiving them +on the other side. </li> +<li> It also transmits its command-line arguments <em>args</em>, and also its +environment by default. Note that s6-sudod will not necessarily accept all the +environment variables that s6-sudoc tries to transmit. </li> + <li> s6-sudoc waits for the server program run by s6-sudod to finish. It exits +the same exit code as the server program. If the server program is killed by a +signal, s6-sudoc kills itself with the same signal. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-e</tt> : do not attempt to transmit any environment variables +to <a href="s6-sudod.html">s6-sudod</a>. </li> + <li> <tt>-t <em>timeoutconn</em></tt> : if s6-sudod has not +managed to process the given information and start the server program after +<em>timeoutconn</em> milliseconds, give up. By default, <em>timeoutconn</em> +is 0, meaning infinite. Note that there is no reason to set up a nonzero +<em>timeoutconn</em> with a large value: s6-sudod is not supposed to block. +The option is only there to protect against ill-written services. </li> + <li> <tt>-T <em>timeoutrun</em></tt> : if the server program +has not exited after <em>timeoutrun</em> milliseconds, give up. By +default, <em>timeoutrun</em> is 0, meaning infinite. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> If s6-sudoc is killed, or exits after <em>timeoutrun</em> milliseconds, +while the server program is still running, s6-sudod will send a SIGTERM and a +SIGCONT to the server program - but this does not guarantee that it will die. +If the server program keeps running, it might still read from the file that +was s6-sudoc's stdin, or write to the files that were s6-sudoc's stdout or +stderr. <strong>This is a potential security risk</strong>. +Administrators should audit their server programs to make sure this does not +happen. </li> + <li> More generally, anything using signals or terminals will not be +handled transparently by the s6-sudoc + s6-sudod mechanism. The mechanism +was designed to allow programs to gain privileges in specific situations: +short-lived, simple, noninteractive processes. It was not designed to emulate +the full suid functionality and will not go out of its way to do so. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-sudod.html b/doc/s6-sudod.html new file mode 100644 index 0000000..37ac996 --- /dev/null +++ b/doc/s6-sudod.html @@ -0,0 +1,170 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-sudod program</title> + <meta name="Description" content="s6: the s6-sudod program" /> + <meta name="Keywords" content="s6 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</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="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="servicedir.html">service directory</a>, +will set up a privileged program: +</p> + +<pre> +#!/command/execlineb -P +fdmove -c 2 1 +s6-envuidgid serveruser +s6-notifywhenup -f +s6-ipcserver -U -1 -- 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="s6-envuidgid.html">s6-envuidgid</a> +sets the UID, GID and GIDLIST environment variables for s6-ipcserver to interpret. </li> + <li> <a href="s6-notifywhenup.html">s6-notifywhenup</a> primes the +service for readiness notification (and the +<tt>-1</tt> option to s6-ipcserver tells the daemon to actually +notify when it's ready). </li> + <li> <a href="s6-ipcserver.html">s6-ipcserver</a> binds to <em>serversocket</em>, +drops its privileges to those of <em>serveruser</em>, and announces its +readiness. Then, for every client connecting to <em>serversocket</em>: + <ul> + <li> <a href="s6-ipcserver-access.html">s6-ipcserver-access</a> checks the +client's credentials according to the rules in directory <em>rules</em>. + <li> <a href="http://skarnet.org/software/execline/exec.html">exec -c</a> +clears the environment. </li> + <li> <a href="http://skarnet.org/software/s6/s6-envdir.html">s6-envdir</a> +sets environment variables according to the directory <em>env</em>. You can +make sure that a variable VAR will be present but empty by performing +<tt>echo > env/VAR</tt>. (A single newline is interpreted by s6-envdir as +an empty variable; whereas if <tt>env/VAR</tt> is totally empty, then the +VAR variable will be removed from the environment.) </li> + <li> s6-sudod reads a command line <em>cargv</em>, a client environment +and file descriptors over the socket. </li> + <li> s6-sudod spawns <tt>sargv cargv</tt>. </li> + </ul> + (Actually, <a href="s6-ipcserver.html">s6-ipcserver</a> does not do this +itself: it executes into other programs that each do one of the tasks. But for +our example, it does not matter.) </li> +</ul> + +<p> + This means that user <em>clientuser</em> running +<tt><a href="s6-sudo.html">s6-sudo</a> serversocket cargv</tt> will be +able, if authorized by the configuration in <em>rules</em>, to run +<tt>sargv cargv</tt> as user <em>serveruser</em>, with stdin, +stdout, stderr and the environment variables properly listed in <em>env</em> +transmitted to <em>sargv</em>. +</p> + +<h2> Notes </h2> + +<ul> + <li> If s6-sudoc is killed, or exits after <em>timeoutrun</em> milliseconds, +while the server program is still running, s6-sudod will send a SIGTERM and a +SIGCONT to its child, then exit 1. However, sending a SIGTERM to the child +does not guarantee that it will die; and +if it keeps running, it might still read from the file that +was s6-sudoc's stdin, or write to the files that were s6-sudoc's stdout or +stderr. <strong>This is a potential security risk</strong>. +Administrators should audit their server programs to make sure this does not +happen. </li> + <li> More generally, anything using signals or terminals will not be +handled transparently by the s6-sudoc + s6-sudod mechanism. The mechanism +was designed to allow programs to gain privileges in specific situations: +short-lived, simple, noninteractive processes. It was not designed to emulate +the full suid functionality and will not go out of its way to do so. </li> + <li> <em>sargv</em> may be empty. In that case, the client is in complete +control of the command line executed as <em>serveruser</em>. This setup is +permitted by s6-sudod, but it is very dangerous, and extreme attention should +be paid to the construction of the s6-ipcserver-access rules. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-supervise.html b/doc/s6-supervise.html index 60c72b5..b080626 100644 --- a/doc/s6-supervise.html +++ b/doc/s6-supervise.html @@ -39,7 +39,7 @@ being a leaf. s6-supervise creates it and allows subscriptions to it from processes having the same effective group id as the s6-supervise process. If it already exists, it uses it as is, without modifying the subscription rights. </li> - <li> It <a href="libftrigw.html">sends</a> a <tt>'s'</tt> event to <tt>./event</tt>. </li> + <li> It <a href="libs6/ftrigw.html">sends</a> a <tt>'s'</tt> event to <tt>./event</tt>. </li> <li> If the default service state is up, s6-supervise spawns <tt>./run</tt>. </li> <li> s6-supervise sends a <tt>'u'</tt> event to <tt>./event</tt> whenever it successfully spawns <tt>./run</tt>. </li> diff --git a/doc/s6-svc.html b/doc/s6-svc.html index 72f0776..606cc16 100644 --- a/doc/s6-svc.html +++ b/doc/s6-svc.html @@ -57,7 +57,7 @@ a SIGTERM and a SIGCONT. Do not restart it. </li> <li> <tt>-u</tt> : up. If the supervised process is down, start it. Automatically restart it when it dies. </li> <li> <tt>-x</tt> : exit. When the service is asked to be down and -the supervised process dies, supervise will exit too. This command should +the supervised process dies, s6-supervise will exit too. This command should normally never be used on a working system. </li> <li> <tt>-O</tt> : Once at most. Do not restart the supervised process when it dies. If it is down when the command is received, do not even start diff --git a/doc/s6-svwait.html b/doc/s6-svwait.html index 5f3cb08..11e9821 100644 --- a/doc/s6-svwait.html +++ b/doc/s6-svwait.html @@ -55,7 +55,7 @@ See the explanation on <a href="notifywhenup.html">this page</a>. </li> given services comes up or down. </li> <li> <tt>-a</tt> : and. s6-svwait will wait until <em>all</em> of the given services come up or down. This is the default. </li> - <li> <tt>-t <em>timeout</em></tt> : if the requested events have not + <li> <tt>-t <em>timeout</em></tt> : if the requested events have not happened after <em>timeout</em> milliseconds, s6-svwait will print a message to stderr and exit 1. By default, <em>timeout</em> is 0, which means no time limit. </li> @@ -64,7 +64,7 @@ limit. </li> <h2> Internals </h2> <p> -s6-svwait spawns a <a href="s6-ftrigrd.html">s6-ftrigrd</a> child to +s6-svwait spawns a <a href="libs6/s6-ftrigrd.html">s6-ftrigrd</a> child to listen to notifications sent by <a href="s6-supervise.html">s6-supervise</a>. It also checks <tt>supervise/status</tt> files, as well as the <tt>supervise/ready</tt> files if necessary, to get the current service diff --git a/doc/upgrade.html b/doc/upgrade.html index 0851534..5a1b1ec 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -17,6 +17,14 @@ <h1> What has changed in s6 </h1> +<h2> in 2.0.2.0 </h2> + +<ul> + <li> Unix domain socket utilities moved from the +<a href="http://skarnet.org/software/s6-networking/">s6-networking</a> +package to s6. </li> +</ul> + <h2> in 2.0.1.0 </h2> <ul> diff --git a/doc/why.html b/doc/why.html index 1901259..946040c 100644 --- a/doc/why.html +++ b/doc/why.html @@ -143,8 +143,8 @@ provided. </li> themselves. Again, this is not good design: service management has nothing to do with init or process supervision, and should be implemented on top of it, not as a part of it. </li> - <li> s6 comes with <a href="libftrig.html">libftrig</a>, an event notification -library, and command-line tools based on this library, thus providing a simple + <li> s6 comes with <a href="ftrig.html">an event notification +library</a>, and command-line tools based on this library, thus providing a simple API for future service management tools to build upon. </li> </ul> |