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.

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.