TIPIDEE-CONFIG(8)

NAME
tipidee-config - compile a text configuration file into a binary cdb file that is used by the tipideed web server

SYNOPSIS
tipidee-config [-i textfile] [-o cdbfile] [-m mode]

DESCRIPTION
tipidee-config reads the /usr/pkg/etc/tipidee.conf configuration file, parses it, and outputs a cdb file to /usr/pkg/etc/tipidee.conf.cdb.

( The /etc default can be changed at build time with the ‘--sysconfdir’ option to configure.)

It then exits 0.

tipidee-config spawns a tipidee-config-preprocess(8) helper that reads /usr/pkg/etc/tipidee.conf, takes care of all the inclusions, and feeds it a single stream of data. If tipidee-config-preprocess(8) dies with a nonzero exit code at any point, tipidee-config exits with the same error code, or 128 plus the signal number if tipidee-config-preprocess(8) was killed by a signal.

It reads the data and parses it, expecting it to follow the tipidee.conf(5) file format.

On failure, it exits nonzero with an error message.

It supplies sane defaults for configuration values that have not been provided.

It writes the data as a cdb file, /usr/pkg/etc/tipidee.conf.cdb. A previously existing file is replaced atomically.

Running instances of tipideed(8) will keep using the old /usr/pkg/etc/tipidee.conf.cdb data until their connection is closed; new instances will use the new one.

It is by design that tipidee uses this unconventional “compile the configuration file” approach. There are several benefits to it:

•   Parsing a configuration file is not very efficient. Every instance of tipideed(8) would have to do it on startup, and there is an instance of tipideed(8) for every HTTP connection. Pre-parsing the configuration makes the initial server response faster.

•   Data parsed by tipideed(8) needs to use private dirty memory for every instance, even if the data is static — and that means incompressible RAM. By contrast, a cdb file is mapped read-only, so its pages are shared clean, which means it's essentially free.

•   tipideed(8) is exposed to the network. You want its attack surface to be as small as possible. Taking the parsing code out of it goes a long way — admittedly, having to parse HTTP in the first place is more attack surface than a simple config file can ever hope to be, but every little bit helps.

•   Run time is the worst time to detect errors. Nobody wants their service to go down because Bob edited the live config file and made a typo. Having the parsing done offline prevents that: tipidee-config doubles as a syntax checker, and when it runs successfully, you know the service will pick up the new config and be fine.

•   In general, decoupling the live configuration, which is the one used by live services ( here, /usr/pkg/etc/tipidee.conf.cdb), from the working configuration, which is the one that humans can tinker with ( here, /usr/pkg/etc/tipidee.conf), is a good idea. Don't touch production until you're ready to flip the switch atomically; tipidee-config is the switch.

Just remember to run tipidee-config whenever you make a modification to your config file, and you'll be set.

OPTIONS

-i textfile
    Use textfile as input instead of /usr/pkg/etc/tipidee.conf.

-o cdbfile
    Use cdbfile as output instead of /usr/pkg/etc/tipidee.conf.cdb. You can then use the -f cdbfile option to tipideed(8).

-m mode
    Create the output file with permissions mode ( given in octal). Default is 0644. Note that the output file should be readable by the user tipideed(8) is started as. If tipideed(8) is started as root and drops its privileges itself, the file can be made private.

EXIT STATUS

0   Success.

1   Syntax error.

2   Invalid inclusion ( cycle or unauthorized duplicate).

100 Wrong usage.

111 System call failed.

129+
    tipidee-config-preprocess(8) was killed.

SEE ALSO
tipidee.conf(5), tipidee-config-preprocess(8), tipideed(8)

This man page is ported from the authoritative documentation at: https://skarnet.org/software/tipidee/tipidee-config.html

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