From 587a3eb1ae3f4e39ba293b5f397b5241c0fee54d Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 2 Sep 2023 05:21:42 +0000 Subject: More doc; unify tipidee-config exit codes Signed-off-by: Laurent Bercot --- doc/tipidee-config.html | 91 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 86 insertions(+), 5 deletions(-) (limited to 'doc/tipidee-config.html') diff --git a/doc/tipidee-config.html b/doc/tipidee-config.html index d6a6f56..66953ab 100644 --- a/doc/tipidee-config.html +++ b/doc/tipidee-config.html @@ -27,7 +27,7 @@ web server.

Interface 

-     tipidee-config [ -i ifile ] [ -o ofile ]
+     tipidee-config [ -i textfile ] [ -o cdbfile ] [ -m mode ]
-

- TODO: write this page. -

-

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 to 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. It not insurmountable. +

+ -- cgit v1.3.1