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/index.html | 13 +++ doc/libskabus/index.html | 127 +++++++++++++++++++++++ doc/libskabus/rpc.html | 41 ++++++++ doc/skabus-rpcd.html | 259 +++++++++++++++++++++++++++++++++++++++++++++++ src/rpc/PROTOCOL | 6 +- 5 files changed, 443 insertions(+), 3 deletions(-) create mode 100644 doc/libskabus/index.html create mode 100644 doc/libskabus/rpc.html create mode 100644 doc/skabus-rpcd.html diff --git a/doc/index.html b/doc/index.html index f4ce0b0..d693433 100644 --- a/doc/index.html +++ b/doc/index.html @@ -108,6 +108,19 @@ relevant page.
  • The skabus-dyntee-client program
    • +

    Remote procedure calls

    + + + +

    Libraries

    + + +
    diff --git a/doc/libskabus/index.html b/doc/libskabus/index.html new file mode 100644 index 0000000..0ebcb80 --- /dev/null +++ b/doc/libskabus/index.html @@ -0,0 +1,127 @@ + + + + + + skabus: the skabus library interface + + + + + + +

    +skabus
    +Software
    +skarnet.org +

    + +

    The skabus library interface

    + +

    General information

    + +

    + libskabus is a collection of C client libraries used +to communicate with the various skabus daemons. +

    + +

    Compiling

    + + + +

    Linking

    + + + +

    Programming

    + +

    Preamble: synchronous functions

    + +

    + The bulk of libskabus functions takes two extra arguments at the +end: deadline and stamp. Their type is +tain_t. This means +they are synchronous function calls, and the extra arguments are there to ensure +those calls do not block forever. +

    + +

    +stamp must be first initialized to an +accurate enough approximation of the current time, for instance via skalibs' +tain_now() function; it will then be automatically updated by the +skabus function calls to always contain (an accurate enough approximation +of) the current time. +

    + +

    +deadline is an absolute date. The meaning is: if the function has +not returned by deadline, its operation is interrupted, and it +will immediately return with a failure code, and errno +will be set to ETIMEDOUT. +

    + +

    +deadline and stamp are used internally to compute a +timeout, because blocking functions such as +poll() +use timeouts. The functions (like most skarnet.org functions) prefer to +take a deadline and a timestamp instead of a timeout, because it's much +easier (for both the application and the library's implementation) to +work with absolute deadlines and update a timestamp regularly than it is +to recompute a bunch of timeouts after every operation that potentially +takes time. +

    + +

    + skalibs can keep track of the +timestamp for you, in the global STAMP variable. All libskabus +functions taking a deadline and stamp argument also have a +version with a name ending in _g, that does not take stamp, and +assumes the STAMP variable always contains (an accurate +enough approximation of) the current time. +

    + +

    + Those synchronous function calls normally return almost instantly: there should +be no blocking code path between the function call and its return. Nevertheless, +since they involve communication with another process, they are at the whim +of the scheduler, so it's impossible to guarantee that they will never block. +The use of the deadline and stamp arguments +ensures there is a cap on the amount of time they block. +

    + +

    skabus functions

    + +

    + The skabus/skabus.h header is actually a +concatenation of other headers: +the libskabus is separated into several modules, each of them with its +own header. +

    + + + + + diff --git a/doc/libskabus/rpc.html b/doc/libskabus/rpc.html new file mode 100644 index 0000000..486258e --- /dev/null +++ b/doc/libskabus/rpc.html @@ -0,0 +1,41 @@ + + + + + + skabus: the skabus_rpc library interface + + + + + + +

    +libskabus
    +skabus
    +Software
    +skarnet.org +

    + +

    The skabus/rpc.h library interface

    + +

    + The skabus_rpc library provides an API for clients +to the skabus-rpcd daemon. +This is the way they register interfaces and send queries to +other clients. +

    + +

    Programming

    + +

    + Check the skabus/rpc.h header for the +exact function prototypes. +

    + +

    Starting and ending a session

    + +to be continued + + + 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

    + + + + +

    Interface

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

    Operation

    + + + +

    + 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

    + + + +

    Signals

    + + + + +

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

    + + + +

    Notes

    + + + + + diff --git a/src/rpc/PROTOCOL b/src/rpc/PROTOCOL index 4022556..216c9bd 100644 --- a/src/rpc/PROTOCOL +++ b/src/rpc/PROTOCOL @@ -19,17 +19,17 @@ ifname : iflen '\0' : 1 msg : msglen - + A PM is the same as a query, except the ifname starts with a 0xff char +and contains an idstr instead of an ifname. Sending a query (server -> rclient) 'Q' : 1 ifid : 4 rinfo: SKABUS_RPC_RINFO_PACK - contains serial(8), deadline(12), timestamp(12), uid(4), gid(4), idstr(SKABUS_RPC_IDSTR_SIZE), '\0'(1) + contains serial(8), deadline(12), timestamp(12), uid(sizeof(uid_t)), gid(sizeof(gid_t)), idstr(SKABUS_RPC_IDSTR_SIZE), '\0'(1) msg : msglen - Sending a reply (rclient -> server) 'R' : 1 -- cgit v1.3.1