s6: the s6-ipcserver-access program

The `s6-ipcserver-access` program

s6-ipcserver-access is a command-line access control tool for Unix domain sockets on systems where the getpeereid() system call can be implemented. It is meant to be run after s6-ipcserverd and before the application program on the s6-ipcserver command line.

Interface

     s6-ipcserver-access [ -v verbosity ] [ -E | -e ] [ -l localname ] [ -i rulesdir | -x rulesfile ] prog...

s6-ipcserver-access checks it is run under a UCSPI server tool such as s6-ipcserver.
It checks that the remote end of the connection fits the accepted criteria defined by the database contained in rulesdir or rulesfile. If the database tells it to reject the connection, the program exits 1.
It sets up a few additional environment variables.
It executes into prog..., unless the first matching rule in the rule database includes instructions to override prog....

Environment variables

s6-ipcserver-access expects to inherit some environment variables from its parent:

PROTO: normally IPC, but could be anything else, like UNIX.
${PROTO}REMOTEEUID: the effective UID of the client program connecting to the socket.
${PROTO}REMOTEEGID: the effective GID of the client program connecting to the socket.

Additionally, it exports the following variables before executing into prog...:

${PROTO}LOCALPATH: set to the local "address" of the socket, as reported by the getsockname() system call, truncated to 99 characters max.

Also, the access rules database can instruct s6-ipcserver-access to set up, or unset, more environment variables, depending on the client address.

Options

-v verbosity : be more or less verbose, i.e. print more or less information to stderr:
- 0: only log error messages.
- 1: only log error and warning messages, and accepted connections. This is the default.
- 2: also log rejected connections and more warning messages.
-E : no environment. All environment variables potentially set by s6-ipcserver-access, as well as those set by s6-ipcserver, will be unset instead.
-e : set up environment variables normally. This is the default.
-l localname : use localname as the value for the ${PROTO}LOCALPATH environment variable, instead of looking it up via getsockname().
-i rulesdir : check client credentials against a filesystem-based database in the rulesdir directory.
-x rulesfile : check client credentials against a cdb database in the rulesfile file. -i and -x are mutually exclusive. If none of those options is given, no credential checking will be performed, and a warning will be emitted on every connection if verbosity is 2 or more.

Access rule checking

s6-ipcserver-access checks its client connection against a ruleset. This ruleset can be implemented:

either in the filesystem as an arborescence of directories and files, if the -i option has been given. This option is the most flexible one: the directory format is simple enough for scripts to understand and modify it, and the ruleset can be changed dynamically. This is practical, for instance, for roaming users.
or in a CDB file, if the -x option has been given. This option is the most efficient one if the ruleset is static enough: a lot less system calls are needed to perform searches in a CDB than in the filesystem.

The exact format of the ruleset is described on the s6-accessrules-cdb-from-fs page.

s6-ipcserver-access first reads the client UID uid and GID gid from the ${PROTO}REMOTEEUID and ${PROTO}REMOTEEGID environment variables, and checks them with the s6_accessrules_keycheck_uidgid() function. In other words, it tries to match:

(if the client's effective uid is the same as s6-ipcserver-access's effective uid) uid/self
uid/uid
(if the client's effective gid is the same as s6-ipcserver-access's effective gid) gid/self
gid/gid
uid/default

in that order. If no S6_ACCESSRULES_ALLOW result can be obtained, the connection is denied.

Environment and executable modifications

s6-ipcserver-access interprets non-empty env subdirectories and exec files it finds in the first matching rule of the ruleset, as explained in the s6-accessrules-cdb-from-fs page.