diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2017-11-21 16:12:18 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska-skaware@skarnet.org> | 2017-11-21 16:12:18 +0000 |
| commit | 5abe508bfef8372472d66adf69cf08e07125820c (patch) | |
| tree | 4fc1feeb088d2fc1a3a1d02d20240d05a606c1bb /doc | |
| download | skabus-5abe508bfef8372472d66adf69cf08e07125820c.tar.xz | |
Initial commit
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 134 | ||||
| -rw-r--r-- | doc/skabus-dyntee-client.html | 57 | ||||
| -rw-r--r-- | doc/skabus-dyntee.html | 123 | ||||
| -rw-r--r-- | doc/skabus-dynteed.html | 154 | ||||
| -rw-r--r-- | doc/upgrade.html | 28 |
5 files changed, 496 insertions, 0 deletions
diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..140f1e5 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,134 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>skabus - a Unix bus system</title> + <meta name="Description" content="skabus - a Unix bus system" /> + <meta name="Keywords" content="skabus bus unix linux laurent bercot ska skarnet dbus ubus" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> skabus </h1> + +<h2> What is it ? </h2> + +<p> + skabus is a suite of programs and libraries for Unix systems +that aim to implement a bus, i.e. a many-to-many interprocess +communication mechanism. +</p> + +<p> + It is very much a work in progress, and won't be complete for a long time. +For now, it looks like a random collection of tools, even though there is +a consistent vision behind them. +</p> + +<hr /> + +<!-- +<ul> + <li> <a href="why.html">Why skabus ?</a> Why not just use D-Bus ?</li> --> + <li> <a href="overview.html">An overview of skabus</a> </li> +</ul> + +<hr /> +--> + +<h2> Installation </h2> + +<h3> Requirements </h3> + +<ul> + <li> A POSIX-compliant system with a standard C development environment </li> + <li> GNU make, version 3.81 or later </li> + <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version +2.6.1.0 or later </li> + <li> <a href="//skarnet.org/software/execline/">execline</a> version +2.3.0.3 or later </li> + <li> <a href="//skarnet.org/software/s6/">s6</a> version +2.6.1.1 or later </li> + +</ul> + +<h3> Licensing </h3> + +<p> + skabus is free software. It is available under the +<a href="http://opensource.org/licenses/ISC">ISC license</a>. +</p> + +<h3> Download </h3> + +<ul> + <li> The current released version of skabus is <a href="skabus-0.0.1.0.tar.gz">0.0.1.0</a>. </li> + <li> Alternatively, you can checkout a copy of the skabus git repository: +<pre> git clone git://git.skarnet.org/skabus </pre> </li> +</ul> + +<h3> Compilation </h3> + +<ul> + <li> See the enclosed INSTALL file for installation details. </li> +</ul> + +<h3> Upgrade notes </h3> + +<ul> + <li> <a href="upgrade.html">This page</a> lists the differences to be aware of between +the previous versions of skabus and the current one. </li> +</ul> + +<hr /> + +<h2> Reference </h2> + +<h3> Commands </h3> + +<p> + All these commands exit 111 if they encounter a temporary error or +hardware error, and +100 if they encounter a permanent error - such as a misuse. Short-lived +commands exit 0 on success. Other exit codes are documented in the +relevant page. +</p> + +<h4> Publication/subscription </h4> + +<ul> + <li> The <a href="skabus-dyntee.html">skabus-dyntee</a> program </li> + <li> The <a href="skabus-dynteed.html">skabus-dynteed</a> program </li> + <li> The <a href="skabus-dyntee-client.html">skabus-dyntee-client</a> program </li> +</ul> + +<hr /> + +<a name="related"> +<h2> Related resources </h2> +</a> + +<h3> skabus discussion </h3> + +<ul> + <li> <tt>skabus</tt> is discussed on the +<a href="//skarnet.org/lists.html#skaware">skaware</a> mailing-list. </li> +</ul> + +<h3> Similar work </h3> + +<ul> + <li> <a href="http://www.freedesktop.org/wiki/Software/dbus/">D-Bus</a> is +the most widely used Linux bus. It's also a horrible, inefficient mess. </li> + <li> <a href="http://wiki.openwrt.org/doc/techref/ubus">ubus</a> is +OpenWrt's micro-bus architecture. </li> +</ul> + +</body> +</html> diff --git a/doc/skabus-dyntee-client.html b/doc/skabus-dyntee-client.html new file mode 100644 index 0000000..1f54a8b --- /dev/null +++ b/doc/skabus-dyntee-client.html @@ -0,0 +1,57 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>skabus: the skabus-dyntee-client program</title> + <meta name="Description" content="skabus: the skabus-dyntee-client program" /> + <meta name="Keywords" content="skabus dynamic tee dyntee skabus-dyntee-client unix linux socket pubsub client" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">skabus</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>skabus-dyntee-client</tt> program </h1> + +<p> +<tt>skabus-dyntee-client</tt> is a client for the +<a href="skabus-dyntee.html">skabus-dyntee</a> server. +It connects to a Unix domain socket where a +<a href="skabus-dyntee.html">skabus-dyntee</a> instance is listening, +then executes into a program with the data stream from skabus-dyntee +on its standard input. +</p> + +<h2> Interface </h2> + +<pre> + skabus-dyntee-client <em>path</em> <em>prog...</em> +</pre> + +<ul> + <li> skabus-dyntee-client connects to the Unix domain socket at <em>path</em>. +It assumes the other end of the socket is a <a href="skabus-dyntee.html">skabus-dyntee</a> +(or <a href="skabus-dynteed.html">skabus-dynteed</a>, which is the same) instance. </li> + <li> It executes into the <em>prog...</em> command line with the +socket as <em>prog</em>'s standard input. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> It is possible for <em>prog</em> to immediately get EOF on its +standard input. This likely means that the server has denied the +connection (skabus-dyntee-client did not run with an authorized uid +or gid). But it could also mean that the stream ended right after +the client connected. </li> + <li> The socket is shut down for writing, so <em>prog</em> can +only read on its stdin; attempts to write will always fail. </li> +</ul> + +</body> +</html> diff --git a/doc/skabus-dyntee.html b/doc/skabus-dyntee.html new file mode 100644 index 0000000..57b34f3 --- /dev/null +++ b/doc/skabus-dyntee.html @@ -0,0 +1,123 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>skabus: the skabus-dyntee program</title> + <meta name="Description" content="skabus: the skabus-dyntee program" /> + <meta name="Keywords" content="skabus dynamic tee dyntee skabus-dyntee unix linux socket pubsub server daemon" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">skabus</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>skabus-dyntee</tt> program </h1> + +<p> +<tt>skabus-dyntee</tt> is a <em>dynamic tee</em>, which is the +simplest publisher daemon possible. +It listens on a Unix domain socket, accepts client connections, and +publishes to its clients everything it reads on its standard +input, as a byte stream. It only writes to clients and never reads +from them. +</p> + +<h2> Interface </h2> + +<pre> + skabus-dyntee [ -1 ] [ -D | -d ] [ -c <em>maxconn</em> ] [ -b <em>backlog</em> ] [ -G <em>gidlist</em> ] [ -g <em>gid</em> ] [ -u <em>uid</em> ] [ -U ] [ -t <em>clienttimeout</em> ] [ -T <em>lameducktimeout</em> ] [ -i <em>rulesdir</em> | -x <em>rulesfile</em> ] <em>path</em> +</pre> + +<ul> + <li> skabus-dyntee binds to the Unix domain socket at <em>path</em>. </li> + <li> If applicable, it drops root privileges. </li> + <li> It listens to its socket and accepts client connections. </li> + <li> Whenever it has data available on its standard input, it reads +that data and writes it to every client it has. It duplicates its +stdin stream to all its clients, hence the name <em>dynamic tee</em>. </li> + <li> When it reads EOF on its stdin, or when it receives a SIGTERM, +it waits for its clients to read their pending data, then exits 0. </li> +</ul> + +<p> + skabus-dyntee is just a wrapper that binds to its socket and +drops privileges before executing into +<a href="skabus-dynteed.html">skabus-dynteed</a>. For details of +the daemon's operation, see the +<a href="skabus-dynteed.html">skabus-dynteed</a> documentation. +</p> + +<h2> Options </h2> + +<ul> + <li> <tt>-1</tt> : write 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>-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>-c <em>maxconn</em></tt> : accept at most +<em>maxconn</em> concurrent client connections. Default is 40. It is +impossible to set it higher than the value of the SKABUS_DYNTEE_MAX macro, +which is 1000. + <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 skabus-dyntee'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 skabus-dyntee'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 skabus-dyntee's userid +to <em>uid</em> after binding the socket. This is only valid when run +as root. </li> + <li> <tt>-U</tt> : change skabus-dyntee'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> + <li> <tt>-t <em>clienttimeout</em></tt> : disconnect a client +that has not read its data after <em>clienttimeout</em> milliseconds. +By default, <em>clienttimeout</em> is 0, which means infinite. </li> + <li> <tt>-T <em>lameducktimeout</em></tt> : after +skabus-dyntee has been told to exit, clients will have +<em>lameducktimeout</em> milliseconds to read their pending data, +after which skabus-dyntee will exit anyway. +By default, <em>lameducktimeout</em> is 0, which means infinite. </li> + <li> <tt>-x <em>rulesfile</em></tt> : read access rights +configuration from CDB file <em>rulesfile</em>. </li> + <li> <tt>-i <em>rulesdir</em></tt> : read access rights +configuration from the filesystem in directory <em>rulesdir</em>. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> skabus-dyntee does not interpret its options itself. It just +dispatches them to the appropriate program on the command line that +it builds. </li> + <li> From the user's point of view, skabus-dyntee behaves like a +long-lived process, even if the long-lived process itself is called +<a href="skabus-dynteed.html">skabus-dynteed</a>. Every operational detail +of skabus-dynteed applies to skabus-dyntee as well; in particular, +make sure to properly +<a href="skabus-dynteed.html#configuration">configure the clients' +access rights</a>. </li> +</ul> + +</body> +</html> diff --git a/doc/skabus-dynteed.html b/doc/skabus-dynteed.html new file mode 100644 index 0000000..7573f3b --- /dev/null +++ b/doc/skabus-dynteed.html @@ -0,0 +1,154 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>skabus: the skabus-dynteed program</title> + <meta name="Description" content="skabus: the skabus-dynteed program" /> + <meta name="Keywords" content="skabus skabus-dynteed publisher dynamic tee daemon publication unix linux server daemon" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">skabus</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>skabus-dynteed</tt> program </h1> + +<p> +<tt>skabus-dynteed</tt> is the serving part of the +<a href="skabus-dyntee.html">skabus-dyntee</a> program. +It assumes that one of its file descriptors (3 or above) is a +bound, listening, non-blocking domain socket; +it accepts connections from clients connecting to that socket, +and copies its stdin stream to all its clients. +</p> + +<h2> Interface </h2> + +<pre> + skabus-dynteed [ -1 ] [ -c <em>maxconn</em> ] [ -t <em>clienttimeout</em> ] [ -T <em>lameducktimeout</em> ] [ -i <em>rulesdir</em> | -x <em>rulesfile</em> ] +</pre> + +<ul> + <li> skabus-dynteed accepts connections from clients to an already +bound and listening SOCK_STREAM Unix domain socket, by default on +its file descriptor 3. </li> + <li> It runs until it receives a SIGTERM or until it reads EOF +on its stdin. In that case, it stops accepting new client connections, +and exits 0 when all clients have read their pending data. </li> + <li> Client connections last as long as the client wants to, unless an +error occurs, or unless the server is told to exit - in which cases +skabus-dynteed forcibly disconnects the client. </li> + <li> Clients cannot write anything to skabus-dynteed. They can only +read a stream of bytes on their socket, which is a copy of what +skabus-dynteed reads on its standard input. </li> +</ul> + +<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. See +<a href="//skarnet.org/software/s6/notifywhenup.html">this page</a> +for more information on readiness notification. </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 the value of the SKABUS_DYNTEE_MAX macro, +i.e. 1000. </li> + <li> <tt>-t <em>clienttimeout</em></tt> : disconnect a client +if it has not read its pending data after <em>clienttimeout</em> milliseconds. +By default, <em>clienttimeout</em> is 0, which means infinite. </li> + <li> <tt>-T <em>lameducktimeout</em></tt> : give clients +<em>lameducktimeout</em> milliseconds to read their pending data when +skabus-dynteed is going to exit. +By default, <em>lameducktimeout</em> is 0, which means infinite. </li> + <li> <tt>-x <em>rulesfile</em></tt> : read access rights +configuration from +<a href="http://en.wikipedia.org/wiki/Cdb_%28software%29">CDB</a> +file <em>rulesfile</em>. </li> + <li> <tt>-i <em>rulesdir</em></tt> : read access rights +configuration from the filesystem in directory <em>rulesdir</em>. </li> +</ul> + +<h2> Signals </h2> + +<ul> + <li> SIGTERM: enter lameduck mode, then exit when all clients have +read their pending data (or <em>lameducktimeout</em> milliseconds have +elapsed). </li> + <li> SIGHUP: reopen <em>rulesfile</em>, if skabus-dynteed has been run +with the <tt>-x</tt> option. It is not necessary to send skabus-dynteed +a SIGHUP when the <tt>-i</tt> option is used instead: configuration +changes in the filesystem are automatically picked up. </li> +</ul> + +<a name="configuration"> +<h2> Configuration </h2> +</a> + +<p> +skabus-dynteed (or its wrapper <a href="skabus-dyntee.html">skabus-dyntee</a>) +can be instructed not to accept every client. This is achieved +via a series of rules, or <em>ruleset</em>, stored in either a +<em>rulesfile</em> in the +<a href="http://en.wikipedia.org/wiki/Cdb_%28software%29">CDB</a> format, +and given to skabus-dynteed with the <tt>-x</tt> option, +or in a <em>rulesdir</em>, i.e. a directory in the filesystem following a +certain format, and given to skabus-dynteed with the <tt>-i</tt> option. +If neither the <tt>-i</tt> nor the <tt>-x</tt> option has been provided, +skabus-dynteed will accept connections from any client. +</p> + +<p> + Rulesets can be converted between the <em>rulesdir</em> and +<em>rulesfile</em> formats with the +<a href="s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> and +<a href="s6-accessrules-fs-from-cdb.html">s6-accessrules-fs-from-cdb</a> +conversion tools. +</p> + +<h3> Rules format </h3> + +<p> + The rules file, or rules directory, follows the +<a href="libs6/accessrules.html">s6 accessrules format</a> for uid and +gid checking. For every connecting client, skabus-dynteed matches the uid +and gid of the client against the provided ruleset, and determines whether +the client is authorized or not to connect. +The right to connect is given if an +<tt>allow</tt> file is found in one of the subdirectories checked by +<a href="libs6/accessrules.html#uidgid">s6_accessrules_keycheck_uidgid</a>. +For instance, to allow everyone to connect, touch +<tt><em>rulesdir</em>/uid/default/allow</tt>. +</p> + +<p> + If a <em>rulesfile</em> or <em>rulesdir</em> has been provided to +skabus-dynteed, and the client's uid and gid match no rule in the +ruleset, then the connection is denied. +</p> + +<h2> Notes </h2> + +<ul> + <li> skabus-dynteed is meant to be execve'd into by a program that gets +the listening socket. That program is normally +<a href="//skarnet.org/software/s6/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 obtained by another means, for instance if it has +been retrieved from a fd-holding daemon. </li> + <li> Clients can plug into the data stream at any time. The data stream +should have a format making it easy for clients to synchronize with it. </li> + <li> The simplest way of connecting to a skabus-dynteed instance and +reading the data stream is via the +<a href="skabus-dyntee-client.html">skabus-dyntee-client</a> program. </li> +</ul> + +</body> +</html> diff --git a/doc/upgrade.html b/doc/upgrade.html new file mode 100644 index 0000000..0827f95 --- /dev/null +++ b/doc/upgrade.html @@ -0,0 +1,28 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>skabus: how to upgrade</title> + <meta name="Description" content="skabus: how to upgrade" /> + <meta name="Keywords" content="skabus installation upgrade" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">skabus</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> What has changed in skabus </h1> + +<h2> in 0.0.1.0 </h2> + +<ul> + <li> Initial release. </li> +</ul> + +</body> +</html> |