From 38c9492b4fb971fe08e4ac0167e06e5dccb3eb2e Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 24 Nov 2017 22:46:28 +0000 Subject: A bit more documentation --- doc/skabus-rpcd.html | 259 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) create mode 100644 doc/skabus-rpcd.html (limited to 'doc/skabus-rpcd.html') diff --git a/doc/skabus-rpcd.html b/doc/skabus-rpcd.html new file mode 100644 index 0000000..11fe596 --- /dev/null +++ b/doc/skabus-rpcd.html @@ -0,0 +1,259 @@ + + + + + + skabus: the skabus-rpcd program + + + + + + +

+skabus
+Software
+skarnet.org +

+ +

The `skabus-rpcd` program

+ +

+skabus-rpcd is the serving part of the +skabus-rpc-daemon +RPC mapper daemon. +It assumes that its stdin is a bound and listening Unix +domain socket; +it accepts connections from clients connecting to that socket, +and transmits messages between clients. +

+ +

Overview and terminology

+ +

Every program connecting to skabus-rpcd, for instance using the +skabus_rpc library, is called a +client. This is standard Unix client-server terminology.
A client can have two functions: +
- It can implement and register an interface.
- It can perform queries to an interface +provided by another client.
+ A client can perform both functions.
skabus-rpcd is the RPC mapper. It accepts interface +registrations, and client queries. It directs queries made to an +interface to the client that implements that interface, and directs +the reply to the client that made the query.
A client making a query is called a qclient. A +client replying to a query is called a rclient. skabus-rpcd +tries to be as transparent and out-of-the-way as possible: all a qclient +is interested in is getting its query to the corresponding rclient, and +getting the reply from said rclient. skabus-rpcd's only job is to get +the queries and replies to the appropriate processes.

+ + +

Interface

+ +

+     skabus-rpcd [ -1 ] [ -v verbosity ] [ -c maxconn ] [ -t clienttimeout ] [ -T lameducktimeout ] [ -i rulesdir | -x rulesfile ] [ -S | -s ] [ -J | -j ]
+

+ +

skabus-rpcd accepts connections from clients to an already +bound and listening SOCK_STREAM Unix domain socket which is its +standard input.
It runs until it receives a SIGTERM, in which case it will +stop accepting new client operations, and exit 0 when the pending +operations have completed.
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-rpcd forcibly disconnects the client.
Clients can perform operations by calling the appropriate +functions in the skabus_rpc library.

+ +

Operation

+ +

A client connects to skabus-rpcd.
A client registers itself to skabus-rpcd, giving it +the identifier it wishes to acquire. This identifier can +be any string, up to SKABUS_RPC_IDSTR_SIZE (254) characters. +Depending on skabus-rpcd's configuration, not every client is +allowed to use any string, see below.
A client may register interfaces. For every +interface it wishes to register, it gives skabus-rpcd an +interface name, which is the name qclients will access +that interface under. It also provides an interface body, +which contains pointers to functions that will be called to serve +queries made to that interface. (The interface body is not sent to +skabus-rpcd: it's only relevant inside the rclient's address space.)
A qclient can send queries to an interface. A query is +just an array of bytes, possibly coupled with an array of file +descriptors (if the qclient is authorized to send file descriptors). +skabus-rpcd routes the query to the rclient that has registered +the interface.
The rclient receives the query, with a little additional +information from skabus-rpcd: a timestamp, the qclient's identifier, +the qclient's credentials. The appropriate callback declared in +the interface body is run, and the reply is sent to +skabus-rpcd, which routes it back to the qclient.

+ +

+ skabus-rpcd only performs low-level operations and message routing. +Client identifiers, interface names and queries are strings or arrays +of bytes - they are not structured. It's up to the client programs +to decide on a structure for the queries, a protocol between qclient +and rclient. +

+ +

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.
-v verbosity : be more or less +verbose. verbosity can be 0 (quiet), 1 (normal), or 2 or more +(verbose).
-c maxconn : accept at most +maxconn concurrent connections. Default is 40. It is +impossible to set it higher than the value of the SKABUS_RPC_MAX macro, +i.e. 1000.
-t clienttimeout : disconnect a client +if it's in the middle of an operation and it has not written or read any +data in clienttimeout milliseconds. By default, clienttimeout +is 0, which means infinite.
-T lameducktimeout : give clients +lameducktimeout milliseconds to finish their current operations +before exiting after receiving a SIGTERM. 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.
-S : no open registration. Clients that cannot find +a matching env/SKABUS_RPC_ID_REGEX entry in their accepted +ruleset are forbidden to register themselves. This is the default.
-s : open registration. If the accepted ruleset +for the client does not contain a env/SKABUS_RPC_ID_REGEX entry, +the client is authorized to register itself with any identifier.
-J : no open interface registration. If the accepted +ruleset for the client does not contain a env/SKABUS_RPC_INTERFACES_REGEX entry, +the client will be unable to register interfaces. This is the default.
-j : open interface registration. If the accepted ruleset +for the client does not contain a env/SKABUS_RPC_ID_REGEX entry, +the client is authorized to register interfaces with any name.

+ +

Signals

+ +

SIGTERM: enter lameduck mode (stop accepting new clients and new +operations), then exit when no more operation is pending.
SIGHUP: reopen rulesfile, if skabus-rpcd has been run +with the -x option. It is not necessary to send skabus-rpcd +a SIGHUP when the -i option is used instead: configuration +changes in the filesystem are automatically picked up.

+ + +

Configuration

+ + +

+ Before running skabus-rpcd (or its wrapper +skabus-rpc-daemon), it is necessary +to configure it. This is done by a series of rules, or ruleset, +stored in either a rulesfile in the +CDB format, +or in a rulesdir, i.e. a directory in the filesystem following a +certain format. skabus-rpcd will refuse to run if neither the -i +nor the -x option has been provided. +

+ +

+ 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-rpcd matches the uid +and gid of the client against the provided ruleset, and determines what +the client is authorized to do. +

+ +

+ By default, no client is allowed to do anything - not even +connect to the server. Even root, the super-user, will be denied +access. That is why +it is essential to create a sensible ruleset prior to running the server +in order to do anything useful. +

+ +

+ Here is how to configure a rulesdir for a client running as uid u. +It is also possible to configure rules for clients running under gid +g by replacing uid/u with gid/g +il all the examples below. The default behaviour can be configured under +uid/default. It is also possible to use a rulesfile instead +by writing a rulesdir and converting it to a rulesfile with the +s6-accessrules-cdb-from-fs +program. +

+ +

If the uid/u/allow file exists, the client will be +authorized to connect to the server. This is a prerequisite for +doing anything.
The uid/u/env/SKABUS_RPC_ID_REGEX file +should contain a regular expression. The client will be authorized to +register itself using an identifier that matches that regular +expression. If the file does not exist, the default behaviour is +given by the -S or -s option to skabus-rpcd.
The uid/u/env/SKABUS_RPC_INTERFACES_REGEX file +should contain a regular expression. The client will be authorized to +register interfaces with names that match that regular +expression. If the file does not exist, the default behaviour is +given by the -J or -j option to skabus-rpcd.
If the uid/u/env/SKABUS_RPC_QSENDFDS file +exists and is not empty, the client will be allowed to send +queries containing open file descriptors. If the file exists and is +empty, the client will be explicitly denied this right: it will only +be allowed to send purely textual queries.
If the uid/u/env/SKABUS_RPC_RSENDFDS file +exists and is not empty, the client will be allowed to send +replies containing open file descriptors to the queries it gets. +If the file exists and is +empty, the client will be explicitly denied this right: it will only +be allowed to reply with purely textual answers.

+ +

Notes

+ +

skabus-rpcd 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.

+ + + -- cgit v1.3.1

The skabus-rpcd program

Overview and terminology

Interface

Operation

Options

Signals

Configuration

Rules format

Notes

The `skabus-rpcd` program