The Configuration File(s)

Note: This is not a description for the values that can be configured. Please see the comments in the respective configfile for that. Instead this document is a description of the overall structure and organization of the configuration files.

General Mechanisms

Dsadmin configfiles are XML, with a root tag named <config> (although this element‘s name is largely irrelevant in practice). Several mechanisms are provided to make their organization easier:

Including of files

Any XML element (and the subtree defined by it) may be moved to a seperate file. Just add a <include file="(thefilename)"/> in its stead and move the element including its contents to that referenced file. When reading the configfile, all <include> tags are replaced with the root element of the referenced file.

This works with any XML element, both in the root file and all included files (recursively). It makes no difference whatsoever to the application whether any parts are included or what parts are included.

Note: Restrictions (e.g. "readable by root only") apply to all configfiles.

Note: All included files have to be in the same directory as the root file.

Referencing of elements

Common elements / subtrees can be referenced by other elements by adding an idref="(targetid)" attribute to the referencing element(s) and id="(targetid)" to the referenced one. When reading the configfile, the element containing the "idref" is replaced with the corresponding target element (same element name and matching "id" attribute).

This works with any XML element, both in the root file and all included files (recursively) as well as across included files. It makes no difference whatsoever to the application whether any parts are referenced or what parts are referenced.

"Inheritance" of elements to (complex) child elements

If an element X is (a) child of element Y and (b) has an attribute "sticky" (value irrelevant), then it is copied to all other complex child elements of element Y. "Complex" elements are in this context all elements that in turn contain other children (elements or attributes).

The configfile is processed in the following way:

1. Read the main configfile.
2. Recursively resolve all includes
3. Resolve all idrefs
4. Convert the XML hierachy into an internal one and do a first classification of the elements and attributes. In this stage the element and attribute names are converted to their canonical forms ([.-_] -> _)
5. Convert this to the final structure, identifying arrays, hashes etc and inheriting "sticky" elements.

File Interpretation Peculiarities

• Internally, all "-" and "." in the names of attributes and elements are translated to underscores ("_"), which means that a.b = a-b = a_b. Note: This is done after the idref resolving, so you should nevertheless always use the exact same name for elements that should be the same. Just be aware of potential conflicts with similar names.
• The configfile is so far not checked for completeness, validity or usable contents at startup. This means errors in it will usually semi-silently show up during runtime (check your "bug" logfile!).
• Internally, no distinction between attributes and elements is made. Only the "special" attributes sticky, id, idref and key have to be attributes
• Boolean values are a bit tricky to handle. In most cases the system simply interprets the presence of such a value as "true". Exceptions should be noted in the cfgfile comments.

Common Structures

System Commands

Definition of a command to be exec‘d. Maps to a Dsadmin::SystemCommand. Minimal Example:

  <rsync user='mirror'>
    <cmdline>/usr/bin/rsync</cmdline>
  </rsync>

Full Example:

  <rsync user='mirror' group='mirror'>
    <cmdline>/usr/bin/rsync -v -a -z</cmdline>
    <param>--exclude</param>
    <param>.teh suck.avi</param>
    <env key='RSYNC_PASSWORD' value='l33th05t'/>
    <dir>/srv/mirrors</dir>
  </rsync>

The tag name can be anything. user (required) and group (optional) specify as what user/group the command should be executed. cmdline specifies the actual command and optionally some of its parameters. This line is split up via the "Shellwords" library, so you can even use moderately complex strings in there. Even more complex parameters (or just additional ones that you want to pack in a more readable way) can be given with param elements. env elements specify environment variables to be set for the command‘s execution. dir allows to set the desired working directory.

System Paths

Definition of a filesystem path. Maps to a Dsadmin::SystemPath. Minimal Example:

  <templates>
    <path>share/dsadmin/templates</path>
  </templates>

Full Example:

  <web-statisticsfiles user='root' group='root' perm='0640'>
    <path>/srv/www/{PROJECTID}/statistics/{DATE}/{FILENAME}</path>
  </rsync>

The tag name can be anything. user and group (both optional) specify as what user/group the file should be accessed. perm (optional, default "0644") is the permissions to be used when creating the file. path specifies a path pattern optionally containing placeholders (matching /\{\w+\}/) substituted on each access.