doc/ucw/config

   1 Configuration files
   2 ===================
   3
   4 This document describes run-time configuration of Sherlock using
   5 config files. For compile-time configuration, see doc/configure.
   6
   7 Terminology :
   8 -------------
   9
  10 Configuration items of all Sherlock modules are organized into sections.
  11 The sections form a tree structure with top-level sections corresponding
  12 to program modules.
  13
  14 Each configuration item belongs to one of the following classes:
  15
  16   1. single value or a fixed-length array of values
  17   2. variable-length array of values
  18   3. subsection with several nested attributes
  19   4. list of nodes, each being an instance of a subsection
  20   5. bitmap of small integers (0..31) or fixed list of strings
  21   6. exceptions (items with irregular syntax; however, they always
  22      appear as a sequence of strings, only the semantics differ)
  23
  24 Both fixed- and variable-length arrays consist of items of the same
  25 type.  The basic types supported by the configuration mechanism are:
  26
  27   1. 32-bit integer
  28   2. 64-bit integer
  29   3. floating point number
  30   4. IP address
  31   5. string
  32   6. choice (one of a fixed list of strings)
  33
  34 Program modules can define their own special types (such as network
  35 masks or attribute names) and decide how are they parsed.
  36
  37 Format of configuration files :
  38 -------------------------------
  39
  40 Configuration files are text files that usually set one attribute per
  41 line, though it is possible to split one assignment into multiple lines
  42 and/or assign several attributes in one line.  The basic format of an
  43 assignment command is
  44
  45   name value1 value2 ... valueN
  46
  47 or
  48
  49   name=value1 value2 ... valueN
  50
  51 The end of line means also end of a command unless it is preceded by a
  52 backslash.  On the other hand, a semicolon terminates the command and
  53 another command can start after the semicolon.  A hash starts a comment
  54 that lasts until the end of the line.  A value can be enclosed in
  55 apostrophes or quotation marks and then it can contain spaces and/or
  56 control characters, otherwise the first space or control character
  57 denotes the end of the value.  Values enclosed in quotation marks are
  58 interpreted as C-strings.  For example, the following are valid
  59 assignment commands:
  60
  61   Database "main db\x2b"; Directory='index/'; Weights 100 20 30 \
  62     40 50 80                            # a comment that is ignored
  63
  64 Numerical values can be succeeded by a unit.  The following units are
  65 supported:
  66
  67         d=86400         k=1000          K=1024
  68         h=3600          m=1000000       M=1048576
  69         %=0.01          g=1000000000    G=1073741824
  70
  71 Attributes of a section or a list node can be set in two ways.  First,
  72 you can write the name of the section or list, open a bracket, and then
  73 set the attributes inside the section.  For example,
  74
  75   Section1 {
  76     Attr1       value1
  77     Attr2       value2
  78     ListNode {          #creates a list and adds its first node
  79       Attr3     value3
  80       Attr4     value4
  81     }
  82     ListNode { Attr3=value5; Attr4=value6 }
  83                         #appends a new node; this is still the same syntax
  84   }
  85
  86 The second possibility is using a shorter syntax when all attributes of a
  87 section are set on one line in a fixed order.  The above example could
  88 be as well written as
  89
  90   Section1 {
  91     Attr1       value1
  92     Attr2       value2
  93     ListNode    value3 value4
  94     ListNode    value5 value6
  95   }
  96
  97 Of course, you cannot use the latter syntax when the attributes allow
  98 variable numbers of parameters.  The parser of the configuration files
  99 checks this possibility.
 100
 101 If you want to set a single attribute in some section, you can also
 102 refer to the attribute as Section.Attribute.
 103
 104 Lists support several operations besides adding a new node.  You just
 105 have to write a colon immediately after the attribute name, followed by
 106 the name of the operation.  The following operations are supported:
 107
 108   List:clear                            # removes all nodes
 109   List:append { attr1=value1; ... }     # adds a new node at the end
 110   List:prepend { attr1=value1; ... }    # adds a new node at the beginning
 111   List:remove { attr1=search1 }         # find a node and delete it
 112   List:edit { attr1=search1 } { attr1=value1; ... }
 113                                         # find a node and edit it
 114   List:after { attr1=search1 } { ... }  # insert a node after a found node
 115   List:before { attr1=search1 } { ... } # insert a node before a found node
 116   List:copy { attr1=search1 } { ... }   # duplicate a node and edit the copy
 117
 118 You can specify several attributes in the search condition and the nodes
 119 are tested for equality in all these attributes.  In the editing
 120 commands, you can either open a second block with overridden attributes,
 121 or specify the new values using the shorter one-line syntax.
 122
 123 The commands :clear, :append, and :prepend are also supported by var-length
 124 arrays.  The command :clear can also be used on string values.  The following
 125 operations can be used on bitmaps: :set, :remove, :clear, and :all.
 126
 127 Configuration files :
 128 ---------------------
 129
 130 The default configuration file is stored in cf/sherlock and it uses
 131 the include directive to load nested configuration files:
 132
 133   include another/file
 134
 135 (Beware that this command has to be the last one on the line.)
 136
 137 If you want to modify the configuration, the preferred form is by editing
 138 the file cf/local, which is included at the end of cf/sherlock, so you
 139 can override anything there.
 140
 141 Command-line parameters :
 142 -------------------------
 143
 144 The default configuration file (cf_def_file possibly overriden
 145 by environment variable cf_env_file) is read before the program is started.
 146 You can use a -C option to override the name of the configuration file.
 147 If you use this parameter several times, then all those files are loaded
 148 consecutively. A parameter -S can be used to execute a configuration
 149 command directly (after loading the default or specified configuration
 150 file).  Example:
 151
 152   bin/program -Ccf/my-config -S'module.trace=2;module.logfile:clear' ...
 153
 154 If the program is compiled with debugging information, then one more
 155 parameter --dumpconfig is supported.  It prints all parsed configuration
 156 items and exits.
 157
 158 All these switches must be used before any other parameters of the
 159 program.
 160
 161 Preprocessing :
 162 ---------------
 163
 164 During compilation, all configuration files are pre-processed by a simple
 165 C-like preprocessor, which supports #ifdef, #ifndef, #if, #elsif, #else and #endif
 166 directives referring to compile-time configuration variables. #if and #elsif
 167 can contain any Perl expression where each CONFIG_xyz configuration variable
 168 is substituted to 0 or 1 depending on its value.
 169
 170 The preprocessor also substitutes `@VARIABLE@' by the value of the variable,
 171 which must be defined.
 172
 173 Caveats :
 174 ---------
 175
 176 Trying to access an unknown attribute causes an error, but unrecognized
 177 top-level sections are ignored.  The reason is that a common config file
 178 is used for a lot of programs which recognize only their own sections.
 179
 180 Names of sections, attributes and choices are case-insensitive. Units are
 181 case-sensitive.