tipidee
Software
skarnet.org

The tipidee-config program

tipidee-config is a tool that compiles a text configuration file into a binary cdb file that is used by the tipideed web server.

Interface

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

• tipidee-config reads the /etc/tipidee.conf configuration file, parses it, and outputs a cdb file to /etc/tipidee.conf.cdb. (The /etc default can be changed at build time with the --sysconfdir option to configure.)
• It then exits 0.

Exit codes

0

success

1

syntax error

2

invalid inclusion (cycle or unauthorized duplicate)

100

wrong usage

111

system call failed

129+

tipidee-config-preprocess was killed

Options

-i textfile

Use textfile as input instead of /etc/tipidee.conf

-o cdbfile

Use cdbfile as output instead of /etc/tipidee.conf.cdb. You can then use the -f cdbfile option to tipideed.

-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 is started as. If tipideed is started as root and drops its privileges itself, the file can be made private.

Detailed operation

• tipidee-config spawns a tipidee-config-preprocess helper that reads /etc/tipidee.conf, takes care of all the inclusions, and feeds it a single stream of data. If tipidee-config-preprocess 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 was killed by a signal.
• It reads the data and parses it, expecting it to follow the /etc/tipidee.conf 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, /etc/tipidee.conf.cdb. A previously existing file is replaced atomically.
• Running instances of tipideed will keep using the old /etc/tipidee.conf.cdb data until their connection is closed; new instances will use the new one.

Notes

• 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 would have to do it on startup, and there is an instance of tipideed for every HTTP connection. Pre-parsing the configuration makes the initial server response faster.
  • Data parsed by tipideed 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 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, /etc/tipidee.conf.cdb), from the working configuration, which is the one that humans can tinker with (here, /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.