version 0.30.209
[util-vserver.git] / util-vserver / doc / configuration.xml
index 38e5741..f0563ba 100644 (file)
     </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>
 
@@ -132,8 +134,8 @@ at startup via initscript.
 
        <collection name="hash" since="0.30.205">
          <description>
-A directory which will be used as the storage place for the 'vhashify'
-command.
+A directory which will be used as the storage place for the
+<tool>vhashify</tool> command.
           </description>
          <link name="id" type="symbolic">
            <description>
@@ -176,13 +178,14 @@ operation will fail. Most tools assume 'on' as the default value.
       </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>
@@ -232,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>
@@ -251,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">
@@ -294,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>
@@ -310,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>
 
@@ -321,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>
 
@@ -339,17 +342,20 @@ a running process consumes one token from the bucket, unless the
 bucket is empty. If the bucket is empty the process is put in the
 hold queue. When the bucket has been refilled to at least M tokens,
 all on hold processes are rescheduled.
+
+See the <ulink url="http://linux-vserver.org/Scheduler+Parameters">Linux
+VServer Wiki</ulink> for more information about this file.
       </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">
@@ -388,7 +394,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">
@@ -397,12 +403,21 @@ 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
 url="http://savannah.nongnu.org/cgi-bin/viewcvs/util-vserver/util-vserver/lib/cflags-v13.c?rev=HEAD">lib/cflags-v13.c</ulink>
 for possible values.
       </description>
+      <!--
       <elements>
        <element name="fakeinit">
          <description>
@@ -440,27 +455,28 @@ Apply the current ulimit to the whole context
           </description>
        </element>
       </elements>
+      -->
     </list>
     <scalar name="context">
       <description>
 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>
     
@@ -514,8 +530,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>
        
@@ -530,8 +546,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>
        
@@ -542,7 +558,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>
@@ -585,18 +601,19 @@ assumed.
        <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>
        </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>
@@ -635,7 +652,7 @@ skipped.
        
       </collection>
       
-      <collection name="vshelper-methods">
+      <collection id="vshelper-methods" name="vshelper-methods">
        <program name="handler" type="symbolic">
          <description>
 See vshelper/action.
@@ -651,10 +668,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>
        
@@ -669,8 +689,8 @@ will be processed in alphanumerical order.
 
        <collection name="hash" since="0.30.205">
          <description>
-A directory which will be used as the storage place for the 'vhashify'
-command.
+A directory which will be used as the storage place for the
+<tool>vhashify</tool> command.
           </description>
          <link name="id" type="symbolic">
            <description>
@@ -717,7 +737,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">
@@ -739,7 +760,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>
@@ -767,7 +789,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">
@@ -789,7 +812,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>
@@ -814,7 +838,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">
@@ -831,7 +857,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>
@@ -853,7 +882,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">
@@ -871,7 +902,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>
@@ -895,7 +927,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">
@@ -912,7 +945,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>
@@ -934,7 +970,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">
@@ -951,7 +988,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>
@@ -992,8 +1032,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">
@@ -1020,10 +1060,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">