s6: the s6-accessrules-cdb-from-fs program
Keywords: s6 s6-accessrules-cdb-from-fs tcp unix access control ipcrules tcprules cdb filesystem

s6
Software
skarnet.org

# The `s6-accessrules-cdb-from-fs` program

`s6-accessrules-cdb-from-fs` compiles a directory containing a ruleset suitable for s6-ipcserver-access or s6-tcpserver-access into a CDB file.

## Interface

         s6-accessrules-cdb-from-fs cdbfile dir

- s6-accessrules-cdb-from-fs compiles the dir directory containing a ruleset into a CDB file cdbfile then exits 0.

## Ruleset directory format

To be understood by s6-accessrules-cdb-from-fs, s6-ipcserver-access, or s6-tcpserver-access, dir must have a specific format.

dir contains a series of directories:

- `ip4` for rules on IPv4 addresses
- `ip6` for rules on IPv6 addresses
- `reversedns` for rules on host names
- `uid` for rules on user IDs
- `gid` for rules on group IDs

Depending on the application, other directories can appear in dir and be compiled into cdbfile, but s6-tcpserver-access only uses the first three, and s6-ipcserver-access only uses the last two.

Each of those directories contains a set of rules. A rule is a subdirectory named after the set of keys it matches, and containing actions that will be executed if the rule is the first matching rule for the tested key.

The syntax for the rule name is dependent on the nature of keys, and fully documented on the accessrules library page. For instance, a subdirectory named `192.168.0.0_27` in the `ip4` directory will match every IPv4 address in the 192.168.0.0/27 network that does not match a more precise rule.

The syntax for the actions, however, is the same for every type of key. A rule subdirectory can contain the following elements:

- a file (that can be empty) named `allow`. If such a file exists, a key matching this rule will be immediately accepted.
- a file (that can be empty) named `deny`. If such a file exists and no `allow` file exists, a key matching this rule will be immediately denied.
- a subdirectory named `env`. If such a directory exists along with an `allow` file, then its contents represent environment modifications that will be applied after accepting the connection and before executing the next program in the chain, as if the s6-envdir program, without options, was applied to `env`. `env` has exactly the same format as a directory suitable for s6-envdir; however, if the modifications take up more than 4096 bytes when compiled into cdbfile, then s6-accessrules-cdb-from-fs will complain and exit 100.
- a file named `exec`. If such a file exists along with an `allow` file, then its contents represent a command line that, interpreted by the execlineb launcher, will be executed after accepting the connection, totally bypassing the original command line. s6-accessrules-cdb-from-fs truncates the `exec` file to 4096 bytes max when embedding it into cdbfile, so make sure it is not larger than that.

## Notes

- cdbfile can exist prior to, and during, the compilation, which actually works in a temporary file in the same directory as cdbfile and performs an atomic replacement when it is done. So it is not necessary to interrupt a running service during the compilation.
- If s6-accessrules-cdb-from-fs fails at some point, the temporary file is removed. However, this doesn't happen if s6-accessrules-cdb-from-fs is interrupted by a signal.
- After the program successfully completes, if dir was a suitable candidate for the `-i` option of s6-ipcserver-access or s6-tcpserver-access, then cdbfile will be a suitable candidate for the `-x` option of the same program, implementing the same ruleset.
- cdbfile can be decompiled by the s6-accessrules-fs-from-cdb program.