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/skabus-dynteed.html | 154 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 doc/skabus-dynteed.html (limited to 'doc/skabus-dynteed.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 @@ + + + + + + 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.

+ + + -- cgit v1.3.1