From 6432cead1941d5305bc2d7f22821ca8a98f43f78 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 24 Nov 2017 18:54:03 +0000 Subject: Add skabus-rpc-daemon, skabus-rpcd and the skabus_rpc library --- doc/skabus-rpc-daemon.html | 137 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 doc/skabus-rpc-daemon.html (limited to 'doc') diff --git a/doc/skabus-rpc-daemon.html b/doc/skabus-rpc-daemon.html new file mode 100644 index 0000000..bd9b575 --- /dev/null +++ b/doc/skabus-rpc-daemon.html @@ -0,0 +1,137 @@ + + + + + + skabus: the skabus-rpc-daemon program + + + + + + +

+skabus
+Software
+skarnet.org +

+ +

The `skabus-rpc-daemon` program

+ +

+skabus-rpc-daemon is a RPC mapper daemon, i.e. a +long-lived program. +It listens on a Unix domain socket, then +accepts client connections. It allows clients to register interfaces +and methods; it transmits queries from a client Q to the appropriate +client R that can handle them; it then transmits the answer back to +client Q. +

+ +

Interface

+ +

+     skabus-rpc-daemon [ -1 ] [ -v verbosity ] [ -D | -d ] [ -c maxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] [ -t clienttimeout ] [ -T lameducktimeout ] [ -i rulesdir | -x rulesfile ] [ -S | -s ] [ -J | -j ] path
+

+ +

skabus-rpc-daemon binds to the Unix domain socket at path.
If applicable, it drops root privileges.
It listens to its socket and accepts client connections.
Clients are handled as described in the +skabus-rpcd page.

+ +

+ skabus-rpc-daemon is just a wrapper that binds to its socket and drops +privileges before executing into +skabus-rpcd. For details of the daemon's +operation, see the skabus-rpcd documentation. +

+ +

Options

+ +

-1 : write a newline to stdout, before +closing it, right after binding and listening to the Unix socket. +If stdout is suitably redirected, this can be used by monitoring +programs to check when the server is ready to accept connections.
-v verbosity : be quiet, normally +verbose, or more verbose, depending on if verbosity is 0, +1, or more. The default is 1.
-d : allow instant rebinding to the same path +even if it has been used not long ago - this is the SO_REUSEADDR flag to +setsockopt() +and is generally used with server programs. This is the default. Note that +path will be deleted if it already exists at program start time.
-D : disallow instant rebinding to the same path.
-c maxconn : accept at most +maxconn concurrent client connections. Default is 40. It is +impossible to set it higher than the value of the SKABUS_RPC_MAX macro, +which is 1000. Client connections to this server are usually long-lived; +make sure to correctly tune that number to your needs.
-b backlog : set a maximum of +backlog backlog connections on the socket. Extra +connection attempts will rejected by the kernel.
-G gidlist : change skabus-rpc-daemon's +supplementary group list to gidlist after binding the socket. +This is only valid when run as root. gidlist must be a +comma-separated list of numerical group IDs.
-g gid : change skabus-rpc-daemon's groupid +to gid after binding the socket. This is only valid when run +as root.
-u uid : change skabus-rpc-daemon's userid +to uid after binding the socket. This is only valid when run +as root.
-U : change skabus-rpc-daemon's user id, group id and +supplementary group list +according to the values of the UID, GID and GIDLIST environment variables +after binding the socket. This is only valid when run as root. +This can be used with the +s6-envuidgid +program to easily script a service that binds to a privileged socket +then drops its privileges to those of a named non-root account.
-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 operation +before exiting after skabus-rpc-daemon has received 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 : paranoid identification mode. Disallows +unspecified clients from registering +under any identifier. This is the default.
-s : free registration. Allows unspecified clients +to register with any identifier.
-J : paranoid interface registration. Disallows +unspecified clients from registering interfaces. This is the default.
-j : free interface registration. Allows unspecified clients +to register any interface name.

+ +

Notes

+ +

skabus-rpc-daemon does not interpret its options itself. It just +dispatches them to the appropriate program on the command line that +it builds.
From the user's point of view, skabus-rpc-daemon behaves like a +long-lived process, even if the long-lived process itself is called +skabus-rpcd. Every operational detail +of skabus-rpcd applies to skabus-rpc-daemon as well; in particular, +make sure to properly +configure the clients' +access rights.
skabus-rpc-daemon is meant to be used in a s6 run script, as +a supervised local service. It does not fork itself or write to syslog. +However, it can be run under any infrastructure, including other +supervision infrastructures, OpenRC, systemd, or SysV scripts.

+ + + -- cgit v1.2.3

The skabus-rpc-daemon program

Interface

Options

Notes

The `skabus-rpc-daemon` program