From e0fc82203d677a6f1e808e9a1a46176c109d89be Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 15 Dec 2014 23:08:59 +0000 Subject: Initial commit --- doc/s6-ipcserver-access.html | 172 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 doc/s6-ipcserver-access.html (limited to 'doc/s6-ipcserver-access.html') diff --git a/doc/s6-ipcserver-access.html b/doc/s6-ipcserver-access.html new file mode 100644 index 0000000..817425b --- /dev/null +++ b/doc/s6-ipcserver-access.html @@ -0,0 +1,172 @@ + + + + + s6-networking: 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-ipcserver 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 +s6net_accessrules_keycheck_uidgid() +function. In other words, it tries to match: + +

uid/uid
gid/gid
uid/default

+ +

+ in that order. If no S6NET_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. +

+ +

An env subdirectory is interpreted as if the +s6-envdir +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.