S6-TCPSERVER-ACCESS(8)

📦 version 2.8.0.1, in nixpkgs unstable

💖 S6-TCPSERVER-ACCESS(8) — command-line TCP access control tool 💖

okay so bestie, this is the s6-tcpserver-access page from the System Manager's Manual, and honestly? it's a little bouncer for your TCP connections and it slays. let's get into it 🫶

✨ SYNOPSIS ✨

s6-tcpserver-access [-v verbosity] [-W | -w] [-D | -d] [-H] [-h]
                    [-R | -r] [-P | -p] [-l localname] [-B banner]
                    [-t timeout] [-i rulesdir | -x rulesfile] prog...

🌸 DESCRIPTION 🌸

so s6-tcpserver-access is meant to be run after s6-tcpserver(8) and before the application program on the s6-tcpserver(8) command line — literally the exact same slot where tcpwrappers' tcpd goes, iykyk. and it also does some fine-tuning on a TCP socket while it's there. multitasking icon 💅

it first makes sure it's running under a UCSPI server tool like s6-tcpserver(8) or its stripped-down little sibling s6-tcpserverd(8). vibe check passed or it's not playing.

then it checks that the remote end of the connection fits the accepted criteria defined by the database sitting in rulesdir or rulesfile. if the database says "no bestie", the program exits 1. periodt.

it also sets up a few additional environment variables.

and then it executes into prog... — unless the first matching rule in the rule database includes instructions to override prog... in which case, plot twist, that happens instead 🙈

one thing to know: s6-tcpserver-access may perform several DNS queries. for efficiency purposes it does as many of them as possible in parallel (efficient queen ✨). however, if it's asked to do an IDENT query, it does not parallelize that with DNS queries. keep that in mind when you're estimating a proper timeout value, fr fr.

🔍 Access rule checking 🔍

s6-tcpserver-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[1], 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(8) page. go read it, bestie, it's giving essential lore.

so the flow is: s6-tcpserver-access first gets the remote address ip of the client and converts it to canonical form. then it checks it with the s6_accessrules_keycheck_ip46() function. (refer to s6-accessrules(7).) in other words, it tries to match broader and broader network prefixes of ip, from ip4/ip_32 to ip4/0.0.0.0_0 if ip is v4, or from ip6/ip_128 to ip6/::_0 if ip is v6. and if the result is:

  • S6_ACCESSRULES_ERROR — it immediately exits 111.
  • S6_ACCESSRULES_DENY — it immediately exits 1.
  • S6_ACCESSRULES_ALLOW — it grants access. 💖
  • S6_ACCESSRULES_NOTFOUND — more information is needed.

in that last case, if DNS lookups have been deactivated (-H) then access is denied. but if s6-tcpserver-access is authorized to perform DNS lookups, then it gets the remote name of the client, remotehost, and checks it with the s6_accessrules_keycheck_reversedns() function. (refer to s6-accessrules(7).) in other words, it tries to match shorter and shorter suffixes of remotehost, from reversedns/remotehost to reversedns/@. this time, the connection is denied if the result is anything else than S6_ACCESSRULES_ALLOW. no partial credit, bestie 😭

note that even if the access check succeeds, the connection can still be denied if paranoid mode has been requested (-p) and a forward DNS query on remotehost does not match ip. trust issues, honestly. valid though.

🧚 Environment and executable modifications 🧚

s6-tcpserver-access interprets non-empty env subdirectories and exec files it finds in the 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-tcpserver-access' command line. after environment modifications, if any, s6-tcpserver-access execs into execlineb -c newprog. main character energy, it just takes over 👑

🎀 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.
    • 3 — also log detailed warning messages from DNS and IDENT resolution.
  • -W — non-fatal. if errors happen during DNS or IDENT resolution, the connection process is not aborted. however, incorrect or incomplete results might still prevent a legitimate connection from being authenticated against a DNS name. this is the default.
  • -w — fatal. errors during DNS or IDENT resolution will drop the connection. harsh but honest 💀
  • -D — disable Nagle's algorithm. sets the TCP_NODELAY flag on the network socket.
  • -d — enable Nagle's algorithm. this is the default.
  • -H — disable DNS lookups for the ${PROTO}LOCALHOST and ${PROTO}REMOTEHOST environment variables. the default, when this option is not given, is to try and read them from DNS.
  • -h — consult /etc/hosts before DNS. the default, when this option is not given, is to ignore /etc/hosts. note 1: the -H option overrides this one — no DNS lookups means that the hosts database won't be consulted either. note 2: if a name is obtained via the hosts database instead of DNS, any -p checks will be disabled for it.
  • -R — disable IDENT lookups for the ${PROTO}REMOTEINFO environment variable. this is the default.
  • -r — enable IDENT lookups. this should only be done for legacy programs that need it. like, legacy legacy 🫠
  • -P — no paranoid DNS lookups. this is the default.
  • -p — paranoid. after looking up a name for the remote host, s6-tcpserver-access will lookup IP addresses for this name, and drop the connection if none of the results matches the address the connection is originating from. note that this still does not replace real authentication via a cryptographic protocol. (say it louder for the people in the back 📢)
  • -l localname — use localname as the value for the ${PROTO}LOCALHOST environment variable, instead of looking it up in the DNS.
  • -B banner — print banner to the network as soon as the connection is attempted, even before checking client credentials. the point is to speed up network protocols that start with a server-side message. first impressions, literally 💅
  • -t timeout — set a timeout on all the operations performed by s6-tcpserver-access. if it is not able to do its job in timeout milliseconds, it will instantly exit 99. the default is 0, meaning no such timeout.
  • -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.

🦋 ENVIRONMENT 🦋

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

  • PROTO — normally TCP, but could be anything else.
  • ${PROTO}LOCALIP — the local address of the socket.
  • ${PROTO}LOCALPORT — the local port of the socket.
  • ${PROTO}REMOTEIP — the remote address of the socket, i.e. the client's IP address.
  • ${PROTO}REMOTEPORT — the remote port of the socket.

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

  • ${PROTO}REMOTEIP — via the IDENT protocol if the -r option has been given.
  • ${PROTO}REMOTEHOST — set to the remote host name obtained from a DNS lookup. unset if the -H option has been given.
  • ${PROTO}LOCALHOST — set to the local host name obtained from a DNS lookup. if the -l option has been given, set to localname instead.
  • ${PROTO}REMOTEINFO — normally unset, but set to the information retrieved from ${PROTO}REMOTEIP via the IDENT protocol if the -r option has been given.

also, the access rules database can instruct s6-tcpserver-access to set up, or unset, more environment variables, depending on the client address. so many little knobs, obsessed 🌸

👑 SEE ALSO 👑

s6-accessrules(7), s6-accessrules-cdb-from-fs(8), s6-envdir(8), s6-tcpserver(8), s6-tcpserverd(8)

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

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

💜 AUTHORS 💜

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

and that's the whole page, bestie, no cap 🫶 so much love to the Debian crew — this one's from Debian, dated November 20, 2023, and it's the S6-TCPSERVER-ACCESS(8) page, now serving looks. go forth and configure responsibly ✨🎀💖

📦 where this page comes from