S6-IPCSERVER-ACCESS(8)

📦 version 2.15.1.0, in nixpkgs unstable

💅 s6-ipcserver-access(8) — the manual, but make it make sense

okay so real talk: this is the System Manager's Manual page for s6-ipcserver-access, a control tool for Unix domain sockets on systems where the getpeereid() system call can be implemented. yes that's a mouthful, no i will not be apologizing 🫶

✨ SYNOPSIS ✨

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

like, that's the whole vibe. flags first, then prog... does the actual work. periodt 💅

🌸 DESCRIPTION 🌸

so s6-ipcserver-access is designed to be run after s6-ipcserverd(8) and before the application program that shows up on the s6-ipcserver(8) command line. it's the middle child and honestly it's carrying the whole family.

first thing it does: it checks it's actually running under a UCSPI server tool like s6-ipcserver(8). vibe check ✅

then it checks that the remote end of the connection matches the accepted criteria defined by the database inside rulesdir or rulesfile. and if the database says "reject ha", the program exits 1. no cap, it will absolutely do that.

it also sets up a few extra environment variables for you (we'll get to those, don't worry bestie).

finally it executes into prog... — unless the first matching rule in the rule database includes instructions to override prog.... plot twist 🌀

🔍 Access rule checking

s6-ipcserver-access checks its client connection against a ruleset, and that ruleset can be implemented in one of two iconic ways:

  • either in the filesystem as an arborescence of directories and files, if you passed the -i option. this one is the most flexible — the directory format is simple enough for scripts to understand and modify, and the ruleset can be changed dynamically. super practical, for instance, for roaming users 🧚
  • or in a CDB[1] file, if you passed the -x option. this one is the most efficient if your ruleset is static enough: a lot less system calls are needed to perform searches in a CDB than in the filesystem. speedrun strats 🔥

the exact format of the ruleset is described in the s6-accessrules-cdb-from-fs(8) page. go read it, i'll wait 🎀

so here's the actual flow: 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 these, in this exact order:

  • (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

order matters, bestie. it's giving priority queue energy 👑

and if no S6_ACCESSRULES_ALLOW result can be obtained? connection is denied. sorry not sorry 💀

🛠️ Environment and executable modifications

s6-ipcserver-access also interprets non-empty env subdirectories and exec files it finds in the first matching rule of the ruleset, exactly as explained in the s6-accessrules-cdb-from-fs(8) page. let's break it down:

  • 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. cute, right?
  • 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.
⚠️ okay important warning time: 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. so like… don't come for me if it doesn't work on your build 🙈

🎀 OPTIONS 🎀

  • -v verbosity — be more or less verbose, i.e. print more or less information to stderr. the levels are:
    • 0 — only log error messages.
    • 1 — only log error and warning messages, and accepted connections. this is the default, and it's a whole mood.
    • 2 — also log rejected connections and more warning messages. nosy bestie mode 🕵️
  • -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. everything must go 🧹
  • -e — set up environment variables normally. this is the default, so you literally don't have to do anything. slay.
  • -l localname — use localname as the value for the ${PROTO}LOCALPATH environment variable, instead of looking it up via getsockname(2). manual override, we love her 💜
  • -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. pick one. and 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. consider yourself warned, bestie.

🌈 ENVIRONMENT 🌈

s6-ipcserver-access expects to inherit some environment variables from its parent. it's not a "bring your own" situation, it's a "your parent brings it" situation:

  • PROTO — normally IPC, but could be anything else, like UNIX. flexible icon ✨
  • ${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. yeah, 99. not 100. don't ask, it's iconic 💅

also (and this is the fun part): the access rules database can instruct s6-ipcserver-access to set up, or unset, more environment variables depending on the client address. so the rules really do be running the whole show 👑

💖 SEE ALSO 💖

go read these, i'm serious, they're all iconic in their own way:

[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)

and that's the page, bestie ✨ this masterpiece comes to you from the Debian crew, dated September 29, 2021, and it's the S6-IPCSERVER-ACCESS(8) System Manager's Manual in all her glory. go forth and socket responsibly 💅🦋💖

📦 where this page comes from