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.