S6-IPCSERVER-ACCESS(8)

NAME
s6-ipcserver-access - control tool for Unix domain sockets on systems where the getpeereid() system call can be implemented

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

DESCRIPTION
s6-ipcserver-access is meant to be run after s6-ipcserverd(8) and before the application program on the s6-ipcserver(8) command line.

s6-ipcserver-access checks it is run under a UCSPI server tool such as s6-ipcserver(8).

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

  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[1] 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 in the s6-accessrules-cdb-from-fs(8) 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 - refer to s6-accessrules(7). In other words, it tries to match:

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

•   uid/ uid

•   (if the client's effective gid is the same as s6-ipcserver-access' 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(8) page.

•   An env subdirectory is interpreted as if the s6-envdir(8) command had been called before executing prog: the environment is modified according to the contents of env.

•   An exec file containing newprog completely bypasses the rest of s6-ipcserver-access' command line. After environment modifications, if any, s6-ipcserver-access execs into ‘execlineb -c newprog’. Please be aware that the exec file functionality is only supported when s6 has been built with execline support. Otherwise, a warning message is printed and executable diversion is not performed.

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(8), 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(2).

-i rulesdir
    Check client credentials against a filesystem-based database in the rulesdir directory.

-x rulesfile
    Check client credentials against a CDB[1] 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.

ENVIRONMENT
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 variable before executing into prog...:

${PROTO}LOCALPATH
    Set to the local “address” of the socket, as reported by the getsockname(2) 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.

SEE ALSO
s6-accessrules-cdb-from-fs(8), s6-accessrules-fs-from-cdb(8), s6-connlimit(8), s6-ioconnect(8), s6-ipcclient(8), s6-ipcserver(8), s6-ipcserver-socketbinder(8), s6-ipcserverd(8)

[1] https://en.wikipedia.org/wiki/Cdb_(software)

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-ipcserver-access.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)