doc/config

   1 $Id: config,v 1.3 2006-01-18 10:29:08 mike Exp $
   2
   3 The Guerilla Guide to Configuring YP2
   4 =====================================
   5
   6 Introduction: invocation, schema and namespace
   7 ----------------------------------------------
   8
   9 YP2 configuration is by means of a single XML file, the name of which
  10 is supplied as the sole command-line argument to the "yp2" binary.
  11 This document briefly describes the format of that configuration file.
  12
  13 An XML schema, config.xsd, is provided for validating configuration
  14 files.  It can be used by (among other tools) the "xmllint" program
  15 supplied as part of the libxml2 distribution:
  16
  17         xmllint --noout --schema config.xsd config1.xml
  18
  19 (A recent version of libxml2 is required, as support for XML Schemas
  20 is a relatively recent addition.)
  21
  22 All elements and attributes are in the namespace
  23         http://indexdata.dk/yp2/config/1
  24 This is most easily achieved by setting the default namespace on the
  25 top-level element, as here:
  26
  27         <yp2 xmlns="http://indexdata.dk/yp2/config/1">
  28
  29
  30 Overview of XML structure
  31 -------------------------
  32
  33 The top-level element is <yp2>.  This contains a <start> element, a
  34 <filters> element and a <routes> element, in that order.  <filters> is
  35 optional; the other two are mandatory.  All three are non-repeatable.
  36
  37 <start> is empty, but carries a "route" attribute, whose value is the
  38 name of route at which to start running -- a bit like the name of the
  39 start production in a grammar.
  40
  41 If present, <filters> contains zero or more <filter> elements; filters
  42 carry a "type" attribute and contain various elements that provide
  43 suitable configuration for filters of that type.  The filter-specific
  44 elements are described below.  Filters defined in this part of the
  45 file must carry an "id" attribute so that they can be referenced from
  46 elsewhere.
  47
  48 <routes> contains zero or more <route> elements, each of which must
  49 carry an "id" element.  One of the routes must have the id that was
  50 specified for the start route in the <start> element's "route"
  51 attribute.  Each route contains zero or more <filter> elements.  These
  52 are of two types.  They may be empty, but carry a "refid" attribute
  53 whose value is the same as the "id" of a filter previously defined in
  54 the <filters> section.  Alternatively, a route within a filter may
  55 omit the "refid" attribute, but contain configuration elements similar
  56 to those used for filters defined in the <filters> section.
  57
  58
  59 Filter configuration
  60 --------------------
  61
  62 All <filter> elements have in common that they must carry a "type"
  63 attribute whose value is one of the supported ones, listed in the
  64 schema file and discussed below.  In additional, <filters>s occurring
  65 the <filters> section must have an "id" attribute, and those occurring
  66 within a route must have either a "refid" attribute referencing a
  67 previously defined filter or contain its own configuration
  68 information.
  69
  70 In general, each filter recognises different configuration elements
  71 within its element, as each filter has different functionality.  These
  72 are as follows:
  73
  74 <filter type="frontend_net">
  75   <threads>10</threads>
  76   <port>@:9000</port>
  77 </filter>
  78
  79 <filter type="z3950_client">
  80   <timeout>30</timeout>
  81 </filter>
  82
  83 <filter type="log">
  84   <message>B</message>
  85 </filter>
  86
  87 <filter type="virt_db">
  88   <virtual>
  89     <database>loc</database>
  90     <target>z3950.loc.gov:7090/voyager</target>
  91   </virtual>
  92   <virtual>
  93     <database>idgils</database>
  94     <target>indexdata.dk/gils</target>
  95   </virtual>
  96 </filter>
  97
  98 <filter type="auth_simple">
  99   <userRegister>../etc/example.simple-auth</userRegister>
 100 </filter>
 101
 102 <filter type="backend_test"/>
 103
 104 <filter type="multi">
 105   ### Not yet resolved
 106 </filter>
 107
 108 <filter type="session_shared">
 109   ### Not yet defined
 110 </filter>
 111
 112 <filter type="template"/>
 113