From 5abe508bfef8372472d66adf69cf08e07125820c Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 21 Nov 2017 16:12:18 +0000 Subject: Initial commit --- doc/index.html | 134 ++++++++++++++++++++++++++++++++++++ doc/skabus-dyntee-client.html | 57 ++++++++++++++++ doc/skabus-dyntee.html | 123 +++++++++++++++++++++++++++++++++ doc/skabus-dynteed.html | 154 ++++++++++++++++++++++++++++++++++++++++++ doc/upgrade.html | 28 ++++++++ 5 files changed, 496 insertions(+) create mode 100644 doc/index.html create mode 100644 doc/skabus-dyntee-client.html create mode 100644 doc/skabus-dyntee.html create mode 100644 doc/skabus-dynteed.html create mode 100644 doc/upgrade.html (limited to 'doc') 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 @@ + + + + + + skabus - a Unix bus system + + + + + + +

+Software
+skarnet.org +

+ +

skabus

+ +

What is it ?

+ +

+ 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. +

+ +

+ 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. +

+ +

+ + +

An overview of skabus

+ + +

+--> + +

Installation

+ +

Requirements

+ +

A POSIX-compliant system with a standard C development environment
GNU make, version 3.81 or later
skalibs version +2.6.1.0 or later
execline version +2.3.0.3 or later
s6 version +2.6.1.1 or later

+ +

Licensing

+ +

+ skabus is free software. It is available under the +ISC license. +

+ +

Download

+ +

The current released version of skabus is 0.0.1.0.
Alternatively, you can checkout a copy of the skabus git repository: +
```
 git clone git://git.skarnet.org/skabus 
```

+ +

Compilation

+ +

See the enclosed INSTALL file for installation details.

+ +

Upgrade notes

+ +

This page lists the differences to be aware of between +the previous versions of skabus and the current one.

+ +

Reference

+ +

Commands

+ +

+ 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. +

+ +

Publication/subscription

+ +

The skabus-dyntee program
The skabus-dynteed program
The skabus-dyntee-client program

+ +

+ + +

Related resources

+ + +

skabus discussion

+ +

skabus is discussed on the +skaware mailing-list.

+ +

Similar work

+ +

D-Bus is +the most widely used Linux bus. It's also a horrible, inefficient mess.
ubus is +OpenWrt's micro-bus architecture.

+ + + 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 @@ + + + + + + skabus: the skabus-dyntee-client program + + + + + + +

+skabus
+Software
+skarnet.org +

+ +

The `skabus-dyntee-client` program

+ +

+skabus-dyntee-client is a client for the +skabus-dyntee server. +It connects to a Unix domain socket where a +skabus-dyntee instance is listening, +then executes into a program with the data stream from skabus-dyntee +on its standard input. +

+ +

Interface

+ +

+     skabus-dyntee-client path prog...
+

+ +

skabus-dyntee-client connects to the Unix domain socket at path. +It assumes the other end of the socket is a skabus-dyntee +(or skabus-dynteed, which is the same) instance.
It executes into the prog... command line with the +socket as prog's standard input.

+ +

Notes

+ +

It is possible for prog 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.
The socket is shut down for writing, so prog can +only read on its stdin; attempts to write will always fail.

+ + + 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 @@ + + + + + + skabus: the skabus-dyntee program + + + + + + +

+skabus
+Software
+skarnet.org +

+ +

The `skabus-dyntee` program

+ +

+skabus-dyntee is a dynamic tee, 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. +

+ +

Interface

+ +

+     skabus-dyntee [ -1 ] [ -D | -d ] [ -c maxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] [ -t clienttimeout ] [ -T lameducktimeout ] [ -i rulesdir | -x rulesfile ] path
+

+ +

skabus-dyntee binds to the Unix domain socket at path.
If applicable, it drops root privileges.
It listens to its socket and accepts client connections.
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 dynamic tee.
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.

+ +

+ skabus-dyntee is just a wrapper that binds to its socket and +drops privileges before executing into +skabus-dynteed. For details of +the daemon's operation, see the +skabus-dynteed documentation. +

+ +

Options

+ +

-1 : 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.
-d : allow instant rebinding to the same path +even if it has been used not long ago - this is the SO_REUSEADDR flag to +setsockopt() +and is generally used with server programs. This is the default. Note that +path will be deleted if it already exists at program start time.
-D : disallow instant rebinding to the same path.
-c maxconn : accept at most +maxconn 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. +
-b backlog : set a maximum of +backlog backlog connections on the socket. Extra +connection attempts will rejected by the kernel.
-G gidlist : change skabus-dyntee's +supplementary group list to gidlist after binding the socket. +This is only valid when run as root. gidlist must be a +comma-separated list of numerical group IDs.
-g gid : change skabus-dyntee's groupid +to gid after binding the socket. This is only valid when run +as root.
-u uid : change skabus-dyntee's userid +to uid after binding the socket. This is only valid when run +as root.
-U : 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 +s6-envuidgid +program to easily script a service that binds to a privileged socket +then drops its privileges to those of a named non-root account.
-t clienttimeout : disconnect a client +that has not read its data after clienttimeout milliseconds. +By default, clienttimeout is 0, which means infinite.
-T lameducktimeout : after +skabus-dyntee has been told to exit, clients will have +lameducktimeout milliseconds to read their pending data, +after which skabus-dyntee will exit anyway. +By default, lameducktimeout is 0, which means infinite.
-x rulesfile : read access rights +configuration from CDB file rulesfile.
-i rulesdir : read access rights +configuration from the filesystem in directory rulesdir.

+ +

Notes

+ +

skabus-dyntee does not interpret its options itself. It just +dispatches them to the appropriate program on the command line that +it builds.
From the user's point of view, skabus-dyntee behaves like a +long-lived process, even if the long-lived process itself is called +skabus-dynteed. Every operational detail +of skabus-dynteed applies to skabus-dyntee as well; in particular, +make sure to properly +configure the clients' +access rights.

+ + + 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 @@ + + + + + + skabus: the skabus-dynteed program + + + + + + +

+skabus
+Software
+skarnet.org +

+ +

The `skabus-dynteed` program

+ +

+skabus-dynteed is the serving part of the +skabus-dyntee 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. +

+ +

Interface

+ +

+     skabus-dynteed [ -1 ] [ -c maxconn ] [ -t clienttimeout ] [ -T lameducktimeout ] [ -i rulesdir | -x rulesfile ]
+

+ +

skabus-dynteed accepts connections from clients to an already +bound and listening SOCK_STREAM Unix domain socket, by default on +its file descriptor 3.
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.
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.
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.

+ +

Options

+ +

-1 : 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 +this page +for more information on readiness notification.
-c maxconn : accept at most +maxconn concurrent connections. Default is 40. It is +impossible to set it higher than the value of the SKABUS_DYNTEE_MAX macro, +i.e. 1000.
-t clienttimeout : disconnect a client +if it has not read its pending data after clienttimeout milliseconds. +By default, clienttimeout is 0, which means infinite.
-T lameducktimeout : give clients +lameducktimeout milliseconds to read their pending data when +skabus-dynteed is going to exit. +By default, lameducktimeout is 0, which means infinite.
-x rulesfile : read access rights +configuration from +CDB +file rulesfile.
-i rulesdir : read access rights +configuration from the filesystem in directory rulesdir.

+ +

Signals

+ +

SIGTERM: enter lameduck mode, then exit when all clients have +read their pending data (or lameducktimeout milliseconds have +elapsed).
SIGHUP: reopen rulesfile, if skabus-dynteed has been run +with the -x option. It is not necessary to send skabus-dynteed +a SIGHUP when the -i option is used instead: configuration +changes in the filesystem are automatically picked up.

+ + +

Configuration

+ + +

+skabus-dynteed (or its wrapper skabus-dyntee) +can be instructed not to accept every client. This is achieved +via a series of rules, or ruleset, stored in either a +rulesfile in the +CDB format, +and given to skabus-dynteed with the -x option, +or in a rulesdir, i.e. a directory in the filesystem following a +certain format, and given to skabus-dynteed with the -i option. +If neither the -i nor the -x option has been provided, +skabus-dynteed will accept connections from any client. +

+ +

+ Rulesets can be converted between the rulesdir and +rulesfile formats with the +s6-accessrules-cdb-from-fs and +s6-accessrules-fs-from-cdb +conversion tools. +

+ +

Rules format

+ +

+ The rules file, or rules directory, follows the +s6 accessrules format 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 +allow file is found in one of the subdirectories checked by +s6_accessrules_keycheck_uidgid. +For instance, to allow everyone to connect, touch +rulesdir/uid/default/allow. +

+ +

+ If a rulesfile or rulesdir has been provided to +skabus-dynteed, and the client's uid and gid match no rule in the +ruleset, then the connection is denied. +

+ +

Notes

+ +

skabus-dynteed is meant to be execve'd into by a program that gets +the listening socket. That program is normally +s6-ipcserver-socketbinder, +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.
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.
The simplest way of connecting to a skabus-dynteed instance and +reading the data stream is via the +skabus-dyntee-client program.

+ + + 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 @@ + + + + + + skabus: how to upgrade + + + + + + +

+skabus
+Software
+skarnet.org +

+ +

What has changed in skabus

+ +

in 0.0.1.0

+ +

Initial release.

+ + + -- cgit v1.3.1

skabus

What is it ?

Installation

Requirements

Licensing

Download

Compilation

Upgrade notes

Reference

Commands

Publication/subscription

Related resources

skabus discussion

Similar work

The skabus-dyntee-client program

Interface

Notes

The skabus-dyntee program

Interface

Options

Notes

The skabus-dynteed program

Interface

Options

Signals

Configuration

Rules format

Notes

What has changed in skabus

in 0.0.1.0

The `skabus-dyntee-client` program

The `skabus-dyntee` program

The `skabus-dynteed` program