fixed detection of commented lines in config-files; formerly, only a
[util-vserver.git] / util-vserver / doc / configuration.xml
index 86d9241..6e51a73 100644 (file)
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- <!DOCTYPE database SYSTEM "configuration.dtd" []> -->
+<!DOCTYPE database SYSTEM "configuration.dtd" []>
 <!-- $Id$ -->
 
 <database xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     </link>
 
 
-    <boolean name="nonamespace">
+    <boolean id="global-nonamespace" name="nonamespace">
       <description>
-Disable namespace usage globally. It can be overridden for a single
-vserver by setting the 'namespace' flag there.
+Disable namespace usage globally. It can be overridden for a single vserver
+by setting the <optionref ref="global-namespace">namespace</optionref> flag
+there.
 
-In this mode the /vservers directory must have the 'barrier'
-attribute. Else, common chroot(2) exploits are possible.
+In this mode the <directory>/vservers</directory> directory must have
+the 'barrier' attribute. Else, common chroot(2) exploits are possible.
       </description>
     </boolean>
 
@@ -56,13 +57,13 @@ distribution specific configuration file.
       <collection name="debootstrap">
        <scalar name="mirror">
          <description>
-The Debian mirror to use with the 'debootstrap' program
+The Debian mirror to use with the <tool>debootstrap</tool> program
           </description>
        </scalar>
        <scalar name="uri">
          <description>
-When the 'debootstrap' package is not installed; fetch it from this
-uri and install it at a temporary place.
+When the <tool>debootstrap</tool> package is not installed; fetch it
+from this uri and install it at a temporary place.
           </description>
        </scalar>
       </collection>
@@ -70,8 +71,9 @@ uri and install it at a temporary place.
       <collection name="vshelper">
        <link name="logfile">
          <description>
-The file where output will be logged to when 'vshelper' is invoked
-from the kernel. This should point somewhere e.g. into /var/log.
+The file where output will be logged to when <tool>vshelper</tool>
+is invoked from the kernel. This should point somewhere e.g. into
+<directory>/var/log</directory>.
           </description>
        </link>
 
@@ -129,6 +131,42 @@ at startup via initscript.
        <list name="exclude">
          <description>Static list of excluded files.</description>
        </list>
+
+       <collection name="hash" since="0.30.205">
+         <description>
+A directory which will be used as the storage place for the
+<tool>vhashify</tool> command.
+          </description>
+         <link name="id" type="symbolic">
+           <description>
+Points to a directory within the filesystems which are used for the
+vservers. There must be not more than one of such a directory per
+filesystem.
+            </description>
+         </link>
+
+         <scalar name="method" since="0.30.299">
+           <default>SHA1</default>
+           <description>The used hash method.</description>
+         </scalar>
+       </collection>
+
+       <boolean name="pkgmgmt-ignore" default="off" since="0.30.205">
+         <description>
+When existing, information from packagemanagement will not be used to
+create dynamic exclude-lists.
+          </description>
+       </boolean>
+
+       <boolean name="pgkmgmt-force" default="off" since="0.30.205">
+         <description>
+When existing, information from packagemanagement will be used to
+create dynamic exclude-lists. This option requires that (a known)
+packagemanagement is configured for the vserver; else the requested
+operation will fail. Most tools assume 'on' as the default value.
+          </description>
+       </boolean>
+
       </collection>
     </collection>
   </collection>
@@ -140,13 +178,14 @@ at startup via initscript.
       </scalar>
       <collection name="yum">
        <description>
-The default, yum-related content of the /etc directory.
+The default, yum-related content of the <directory>/etc</directory>
+directory.
         </description>
        <scalar name="yum.conf">
          <description>
 The master yum configuration file. It supports the @YUMETCDIR@,
 @YUMCACHEDIR@ and @YUMLOGDIR@ placeholder which will be replaced at
-'vserver ... build' time.
+<command>vserver ... build</command> time.
           </description>
        </scalar>
       </collection>
@@ -196,7 +235,7 @@ The pathname of the vserver binary.
       
       <collection name="pkgs">
        <description>
-Contains files with packages.
+Contains files with packagenames.
         </description>
        <list name="list">
          <description>
@@ -215,19 +254,19 @@ distribution.
       
       <collection name="apt">
        <description>
-Default content of the /etc/apt/ directory.
+Default content of the <directory>/etc/apt/</directory> directory.
         </description>
       </collection>
       
       <collection name="rpm">
        <description>
-Default content of the /etc/rpm directory.
+Default content of the <directory>/etc/rpm</directory> directory.
         </description>
       </collection>
       
       <link name="rpmlib">
        <description>
-Directory which overrides /usr/lib/rpm.
+Directory which overrides <directory>/usr/lib/rpm</directory>.
         </description>
       </link>
       <link name="execdir">
@@ -258,7 +297,7 @@ the vserver is stopped, this can be a dangling symlink.
       </description>
     </link>
 
-    <list name="bcapabilities">
+    <list id="bcapabilities" name="bcapabilities">
       <description>
 [experimental; name is subject of possible change] Contains the system capabilities. See
 <ulink url="http://savannah.nongnu.org/cgi-bin/viewcvs/util-vserver/util-vserver/lib/bcaps-v13.c?rev=HEAD">lib/bcaps-v13.c</ulink>
@@ -274,10 +313,10 @@ for possible values.
       </description>
     </list>
 
-    <boolean name="namespace">
+    <boolean id="global-namespace" name="namespace">
       <description>
-Overrides the global 'nonamespace' flag and enables namespace usage
-for the current vserver.
+Overrides the global <optionref ref="global-nonamespace">nonamespace</optionref> flag and enables
+namespace usage for the current vserver.
       </description>
     </boolean>
 
@@ -285,8 +324,8 @@ for the current vserver.
       <description>
 Disables namespace usage for the current vserver.
 
-In this mode the /vservers directory must have the 'barrier'
-attribute. Else, common chroot(2) exploits are possible.
+In this mode the <directory>/vservers</directory> directory must have
+the 'barrier' attribute. Else, common chroot(2) exploits are possible.
       </description>
     </boolean>
 
@@ -305,15 +344,15 @@ hold queue. When the bucket has been refilled to at least M tokens,
 all on hold processes are rescheduled.
       </description>
       <keys>
-       <key name="fill-rate">
+       <key id="fill_rate" name="fill-rate">
          <description>
 Amount of tokens append to the bucket each interval.
             </description>
        </key>
        <key name="interval">
          <description>
-The intervall between refills of amount 'fill_rate'. This value is
-express in ticks.
+The intervall between refills of amount <optionref>fill_rate</optionref>. This
+value is express in ticks.
           </description>
        </key>
        <key name="tokens">
@@ -352,7 +391,7 @@ The nice-level on which the vserver will be started.
     <list name="capabilities">
       <description>
 Contains per line a capability. This file is used for the 2.4 kernel
-only; for 2.6 use 'bcapabilities'.
+only; for 2.6 use <optionref>bcapabilities</optionref>.
       </description>
     </list>
     <scalar name="shell">
@@ -361,6 +400,14 @@ Contains the pathname of the shell which will be used by the "vserver
 ... enter" command.
       </description>
     </scalar>
+    <list name="personality">
+      <description>
+Used to set the personality of the vserver. First line in the file
+is the personality-type followed by flags (one item per line). See
+<filename>/usr/include/linux/personality.h</filename> for possible
+values.
+      </description>
+    </list>
     <list name="flags">
       <description>
 Contains per line a flag. See <ulink
@@ -410,21 +457,21 @@ Apply the current ulimit to the whole context
 Contains the context which shall be used for the vserver.
         </description>
     </scalar>
-    <data name="fstab">
+    <data id="fstab" name="fstab">
       <description>
 The fstab file for the vserver. Entries in this file will be mounted
-within the network context of the vserver; this means that mount will
-be called as 'chbind &lt;options&gt; mount ...'. Use the 'fstab.local'
-file when you do not want this behavior, but in most cases the 'fstab'
-file should be used.
+within the network context of the host. Use the
+<optionref>fstab.remote</optionref> file when you want that the
+mounting happens in the network context of the vserver. In most cases
+the 'fstab' file should be used.
       </description>
     </data>
-    <data name="fstab.local">
+    <data id="fstab.remote" name="fstab.remote">
       <description>
-The fstab file for the vserver. In opposite to the normal 'fstab'
-file, the mounting happens in the local network context. Currently
-there is no way to mix entries of both files; 'fstab' will be always
-processed before 'fstab.local'.
+The fstab file for the vserver. Entries in this file will be mounted
+within the network context of the host; this means that mount will be
+called as <command>chbind &lt;options&gt; mount ...</command>. See
+<optionref>fstab</optionref> also.
       </description>
     </data>
     
@@ -478,8 +525,8 @@ a separate line.
          <description>
 The command which is used to wait on the vserver after it has been
 started. Each option must be on a separate line. This file will be
-ignored when the 'sync' does not exist and the '--sync' option was not
-used.
+ignored when the <optionref>sync</optionref> flag does not exist and the
+'--sync' option was not used.
          </description>
        </list>
        
@@ -494,8 +541,8 @@ a separate line.
          <description>
 The command which is used to wait on the vserver after it has been
 stopped. Each option must be on a separate line. This file will be
-ignored when the 'sync' does not exist and the '--sync' option was not
-used.
+ignored when the <optionref>sync</optionref> flag does not exist and the
+'--sync' option was not used.
           </description>
        </list>
        
@@ -506,7 +553,7 @@ runlevel in the utmp-file). Each option must be on a separate line.
          </description>
        </list>
        
-       <boolean name="sync">
+       <boolean id="sync" name="sync">
          <description>
 If this file is not present, all 'cmd.*-sync files will be ignored.
            </description>
@@ -538,29 +585,30 @@ vserver ids (one name per line).
       
       <collection name="vshelper">
        <scalar name="sync-timeout">
+         <default>30</default>
          <description>
 The timeout in seconds which is used when synchronising vserver
 startup/shutdown with the vshelper. When no set, 30 seconds will be
 assumed.
          </description>
-         <default>30</default>
        </scalar>
        
        <scalar name="action">
+         <default>restart</default>
          <description>
-The action which is going to be executed when a vshelper event occurs. The
-default value is 'restart', but there can be defined own methods by placing
-scripts into the 'vshelper-methods' directories. These scripts are fed with
-the same arguments as the 'vshelper' script.
+The action which is going to be executed when a vshelper event
+occurs. The default value is 'restart', but there can be defined own
+methods by placing scripts into the
+<optionref>vshelper-methods</optionref> directories. These scripts are
+fed with the same arguments as the <tool>vshelper</tool> script.
           </description>
-         <default>restart</default>
        </scalar>
        
        <program name="event" type="symbolic">
          <description>
-When existing. these scripts will be executed *instead* of the default
-handler defined in 'action'. Their name must match the event which
-caused the execution of 'vshelper'; e.g. 'restart' or 'poweroff'. See
+When existing, these scripts will be executed *instead* of the default
+handler defined in 'action'. Their name must match the event which caused
+the execution of <tool>vshelper</tool>; e.g. 'restart' or 'poweroff'. See
 the vs_reboot() function in the kernel for more details.
           </description>
          <parameterList>
@@ -599,7 +647,7 @@ skipped.
        
       </collection>
       
-      <collection name="vshelper-methods">
+      <collection id="vshelper-methods" name="vshelper-methods">
        <program name="handler" type="symbolic">
          <description>
 See vshelper/action.
@@ -615,10 +663,13 @@ unification.
        
        <list name="exclude">
          <description>
-Static list of excluded files. This list supports an rsync syntax:
-when a file is prefixed by '+', it is a candidate for unification;
-when there is no prefix or a '-' it will be excluded. Shell-wildcards
-are allowed for the filenames.
+<p>Static list of files which are excluded for unification. This list
+supports an rsync-like syntax: when a file is prefixed by '+', it is a
+candidate for unification; when there is no prefix or a '-' or a '~' it
+will be excluded. Shell-wildcards are allowed for the filenames.</p>
+<p>When used with <tool>vcopy</tool>, the '~' prefix prevents copying
+of the file entirely (e.g. for keyfiles). With this tool, the file will
+be copied instead of hardlinked when the '-' prefix is used.</p>
           </description>
        </list>
        
@@ -630,6 +681,42 @@ multiple such symlinks but they must be prefixed by 'refserver.' and
 will be processed in alphanumerical order.
           </description>
        </link>
+
+       <collection name="hash" since="0.30.205">
+         <description>
+A directory which will be used as the storage place for the
+<tool>vhashify</tool> command.
+          </description>
+         <link name="id" type="symbolic">
+           <description>
+Points to a directory within the filesystems which are used for the
+vservers. There must be not more than one of such a directory per
+filesystem.
+            </description>
+         </link>
+
+         <scalar name="method"  since="0.30.299">
+           <default>SHA1</default>
+           <description>The used hash method.</description>
+         </scalar>
+       </collection>
+
+       <boolean name="pkgmgmt-ignore" default="off" since="0.30.205">
+         <description>
+When existing, information from packagemanagement will not be used to
+create dynamic exclude-lists.
+          </description>
+       </boolean>
+
+       <boolean name="pgkmgmt-force" default="off" since="0.30.205">
+         <description>
+When existing, information from packagemanagement will be used to
+create dynamic exclude-lists. This option requires that (a known)
+packagemanagement is configured for the vserver; else the requested
+operation will fail. Most tools assume 'on' as the default value.
+          </description>
+       </boolean>
+       
       </collection>
     </collection>
     
@@ -645,7 +732,8 @@ environment variable must be set by one of the in-shellcontext scripts
       <program name="prepre-start">
        <description>
 The scriptlet which will be executed before the network-interfaces are
-enabled and the directories are mounted."
+enabled and the directories are mounted. Before executing the script,
+the configuration directory will be made the working directory.
         </description>
        <parameterList>
          <parameter name="vserver-dir">
@@ -667,7 +755,8 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
       </program>
       <collection name="prepre-start.d">
        <description>
-Repository of prepre-start like scripts
+Repository of prepre-start like scripts.  Before executing the script,
+the configuration directory will be made the working directory.
         </description>                                                                                                                 
        <program name="script" type="symbolic">
          <description>See prepre-start.</description>
@@ -695,7 +784,8 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
        <description>
 The scriptlet which will be executed after network-interfaces were
 enabled and the directories mounted, but before the vserver itself has
-been started.
+been started.  Before executing the script, the vserver root directory
+will be made the working directory.
         </description>
        <parameterList>
          <parameter name="vserver-dir">
@@ -717,7 +807,8 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
       </program>
       <collection name="pre-start.d">
        <description>
-Repository of pre-start like scripts
+Repository of pre-start like scripts. Before executing these scripts,
+the vserver root directory will be made the working directory.
         </description>                                                                                                                 
        <program name="script" type="symbolic">
          <description>See pre-start.</description>
@@ -742,7 +833,9 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
 
       <program name="post-start">
        <description>
-The scriptlet which will be executed after the vserver has been started.
+The scriptlet which will be executed after the vserver has been
+started. Before executing the script, the vserver root directory
+will be made the working directory.
         </description>
        <parameterList>
          <parameter name="vserver-dir">
@@ -759,7 +852,10 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
        </parameterList>
       </program>
       <collection name="post-start.d">
-       <description>Repository of post-start like scripts</description>
+       <description>
+Repository of post-start like scripts. Before executing these scripts,
+the vserver root directory will be made the working directory.
+        </description>
        <program name="script" type="symbolic">
          <description>See post-start.</description>
          <parameterList>
@@ -781,7 +877,9 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
 
       <program name="pre-stop">
        <description>
-The scriptlet which will be executed before the vserver will be stopped.
+The scriptlet which will be executed before the vserver will be
+stopped. Before executing the script, the vserver root directory
+will be made the working directory.
         </description>
        <parameterList>
          <parameter name="vserver-dir">
@@ -799,7 +897,8 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
       </program>
       <collection name="pre-stop.d">
        <description>
-Repository of pre-stop like scripts
+Repository of pre-stop like scripts. Before executing the script, the
+vserver root directory will be made the working directory.
         </description>                                                                                                                 
        <program name="script" type="symbolic">
          <description>See pre-stop.</description>
@@ -823,7 +922,8 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
        <description>
 The scriptlet which will be executed after the vserver has been
 stopped, but before the directories will be umounted and the the
-interfaces disabled.
+interfaces disabled. Before executing the script, the vserver root
+directory will be made the working directory.
         </description>
        <parameterList>
          <parameter name="vserver-dir">
@@ -840,7 +940,10 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
        </parameterList>
       </program>
       <collection name="post-stop.d">
-       <description>Repository of post-stop like scripts</description>
+       <description>
+Repository of post-stop like scripts. Before executing the script, the
+vserver root directory will be made the working directory.
+        </description>
        <program name="script" type="symbolic">
          <description>See post-stop.</description>
          <parameterList>
@@ -862,7 +965,8 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
       <program name="postpost-stop">
        <description>
 The scriptlet which will be executed after the vserver has been stopped
-completely.
+completely. Before executing the script, the vserver root directory
+will be made the working directory.
         </description>
        <parameterList>
          <parameter name="vserver-dir">
@@ -879,7 +983,10 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
        </parameterList>
       </program>
       <collection name="postpost-stop.d">
-       <description>Repository of postpost-stop like scripts</description>
+       <description>
+Repository of postpost-stop like scripts. Before executing the script,
+the vserver root directory will be made the working directory.
+        </description>
        <program name="script" type="symbolic">
          <description>See postpost-stop.</description>
          <parameterList>
@@ -920,8 +1027,8 @@ The fixed value of the current action (e.g. 'prepre-start', 'post-stop'...).
        <description>
 'iface' is an arbitrary name for the interface; the value itself is
 not important but may be interesting regarding interface-creation and
-usage with 'chbind'. Both happens in alphabetical order and numbers
-like '00' are good names for these directories.
+usage with <tool>chbind</tool>. Both happens in alphabetical order and
+numbers like '00' are good names for these directories.
         </description>
        
        <boolean name="disabled">
@@ -948,10 +1055,10 @@ like '00' are good names for these directories.
        </scalar>
        <scalar name="name">
          <description>
-When this file exists, the interface will be named with the text in this
-file. Without such an entry, the IP will not be shown by 'ifconfig' but
-by 'ip addr ls' only.  Such a labeled interface is known as an "alias"
-also (e.g. 'eth0:foo').
+When this file exists, the interface will be named with the text in
+this file. Without such an entry, the IP will not be shown by
+<tool>ifconfig</tool> but by <command>ip addr ls</command> only.  Such
+a labeled interface is known as an "alias" also (e.g. 'eth0:foo').
           </description>
        </scalar>
        <boolean name="nodev">