S6-TCPSERVER-ACCESS(8)

NAME
s6-tcpserver-access - command-line TCP access control tool

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
s6-tcpserver-access is meant to be run after s6-tcpserver(8) and before the application program on the s6-tcpserver(8) command line, just like tcpwrappers' tcpd program. It additionally performs some fine-tuning on a TCP socket.

s6-tcpserver-access checks it is run under a UCSPI server tool such as s6-tcpserver(8) or its stripped-down version s6-tcpserverd(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....

s6-tcpserver-access may perform several DNS queries. For efficiency purposes, it does as many of them as possible in parallel. However, if asked to do an IDENT query, it does not parallelize it with DNS queries. Take that into account when estimating a proper timeout value.

  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.

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. 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 the 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 is the result is anything else than S6_ACCESSRULES_ALLOW.

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.

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

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.

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

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

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

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

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)