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-preprocess.html | 46 +++++++++++++++++-- doc/tipidee-config.html | 91 +++++++++++++++++++++++++++++++++++--- doc/tipidee.conf.html | 2 +- doc/tipideed.html | 18 ++++++++ 4 files changed, 147 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/tipidee-config-preprocess.html b/doc/tipidee-config-preprocess.html index 86fb22e..9b6ea38 100644 --- a/doc/tipidee-config-preprocess.html +++ b/doc/tipidee-config-preprocess.html @@ -49,17 +49,55 @@ appropriately included files.
  • tipidee-config-preprocess then exits 0.
    • +

    Exit codes

    +

    - TODO: write this page. +If tipidee-config-preprocess exits nonzero, +tipidee-config will immediately exit +with the same error code.

    -

    Exit codes

    - -

    Options

    +
    +
    0
    success
    +
    1
    syntax error
    +
    2
    invalid inclusion (cycle or unauthorized duplicate)
    +
    100
    wrong usage
    +
    111
    system call failed
    +

    Detailed operation

    + +

    Notes

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

    + diff --git a/doc/tipidee.conf.html b/doc/tipidee.conf.html index eb2b7f4..64e3d30 100644 --- a/doc/tipidee.conf.html +++ b/doc/tipidee.conf.html @@ -366,7 +366,7 @@ Except for domain, they can only be used after a domain direct

      - domain is a special directive in that it is stateful. Instead of +
    • domain is a special directive in that it is stateful. Instead of having a direct effect on the configuration, it merely defines the domain that the next local directives will apply to. domain example.com means that a subsequent cgi /cgi-bin/ line will declare that a resource diff --git a/doc/tipideed.html b/doc/tipideed.html index 97102c5..ce8f5e5 100644 --- a/doc/tipideed.html +++ b/doc/tipideed.html @@ -48,6 +48,18 @@ current working directory, one subdirectory for every domain it hosts.

      • Exit codes

      +
      +
      0
      clean exit. The client closed the connection after a stream of +HTTP exchanges.
      +
      100
      bad usage. tipideed has been run in an incorrect way: bad command +line options, or missing environment variables, etc.
      +
      101
      cannot happen. This signals a bug in tipideed, and comes with an +error message asking you to report the bug. Please do so.
      +
      111
      system call failed. If this happens while serving a request, +tipideed likely has sent a 500 (Internal Server Error) response to the +client before exiting.
      +
      +

      Environment variables

      Options

      @@ -56,5 +68,11 @@ current working directory, one subdirectory for every domain it hosts.

      Notes

      +
        +
      • tipideed is pronounced tipi-deed. You can also say +tipi-dee-dee, but only if you're the type of person who says +PC computer, NIC card or ATM machine.
        • +
      + -- cgit v1.3.1