added/updated some descriptions
[util-vserver.git] / util-vserver / doc / configuration.xml
1 <?xml version="1.0"?>
2 <!DOCTYPE cfgdirdoc SYSTEM "configuration.dtd" [
3 <!ENTITY init-scriptlet-params
4           "<params>
5             <param id='vserver-dir'>
6               <description>The configuration directory of the current vserver</description>
7             </param>
8             <param id='vserver-name'>
9               <description>The name of the current vserver</description>
10             </param>
11             <param id='action'>
12               <description>The fixed value of the current action (e.g. 'prepre-start', 'post-stop', ...).</description>
13             </param>
14           </params>">
15 <!ENTITY init-script-text     "The scriptlet">
16 <!ENTITY init-dir-text        "A directory with scriptlets">
17 <!ENTITY init-dir-script-text "A scriptlet">
18
19 <!ENTITY init-prepre-start "which will be executed before the network-interfaces are enabled
20                             and the directories are mounted.">
21 <!ENTITY init-pre-start  "which will be executed after network-interfaces were enabled and
22                           the directories mounted, but before the vserver itself has been
23                           started.">
24 <!ENTITY init-post-start "which will be executed after the vserver has been started.">
25 <!ENTITY init-pre-stop   "which will be executed before the vserver will be stopped.">
26 <!ENTITY init-post-stop  "which will be executed after the vserver has been stopped, but
27                           before the directories will be umounted and the the interfaces
28                           disabled.">
29 <!ENTITY init-postpost-stop "which will be executed after the vserver has been stopped
30                              completely.">
31 ]>
32
33 <cfgdirdoc>
34   <topleveldir type="confdir">
35     <description>The base configuration directory.</description>
36
37     <dir name=".defaults" type="fixed" optional="yes">
38       <dir name="init" type="fixed">
39         <file name="mtab">
40           <description>Default mtab-file</description>
41         </file>
42       </dir>
43
44       <symlink name="vdirbase">
45         <description></description>
46         <default>/vservers</default>
47       </symlink>
48
49       <dir name="apps" type="fixed">
50         <dir name="pkgmgmt" type="fixed">
51           <symlink name="base">
52             <description></description>
53             <default>/vservers/.pkg</default>
54           </symlink>
55
56           <file name="apt.conf">
57             <description>The default apt.conf which is going to be used. It is overridden by
58             distribution specific configuration file.</description>
59           </file>
60         </dir>
61
62         <dir name="debootstrap" type="fixed">
63           <file name="mirror">
64             <description>The Debian mirror which is used for 'debootstrap'.</description>
65           </file>
66
67           <file name="uri">
68             <description>When the 'debootstrap' package is not installed; fetch it from this uri and
69             install it at a temporary place.</description>
70           </file>
71         </dir>
72
73         <dir name="vprocunhide" type="fixed">
74           <file name="files">
75             <description>A list of files which will be made visibly by vprocunhide. Wildcards are
76             allowed and anything ending in '/' will be processed recursively. When this file exists,
77             it overrides the defaults in SYSDEFAULTDIR/vprocunhide-files. The entries there must be
78             absolute filenames inclusive the leading '/proc'.</description>
79           </file>
80         </dir>
81
82         <dir name="init" type="fixed">
83           <symlink name="tty">
84             <description>A symlink to the TTY device where input/output will be redirected from/to
85             at startup via initscript.</description>
86           </symlink>
87         </dir>
88
89         <dir name="vunify" type="fixed">
90           <file name="exclude">
91             <description>Static list of excluded files.</description>
92           </file>
93         </dir>
94       </dir>
95     </dir>
96
97     <dir name=".distributions" type="fixed" optional="yes">
98       <dir name="dist" type="symbolic">
99         <file name="dev">
100           <description></description>
101         </file>
102
103         <file name="apt.conf">
104           <description>The default apt.conf which is going to be used. It overrides the apt.conf
105           from CONFDIR/.defaults/apps/pkgmgmt.</description>
106         </file>
107
108         <script name="initpre">
109           <description>Script which will be executed before packages will be installed.</description>
110           <params>
111             <param id="confdir">
112               <description>The configuration directory of the vserver which is going to be set
113               up.</description>
114             </param>
115
116             <param id="vserver">
117               <description>The pathname of the vserver binary.</description>
118             </param>
119           </params>
120         </script>
121
122         <script name="initpost">
123           <description>Script which will be executed after packages are installed.</description>
124           <params>
125             <param id="confdir">
126               <description>The configuration directory of the vserver which is going to be set
127               up.</description>
128             </param>
129
130             <param id="vserver">
131               <description>The pathname of the vserver binary.</description>
132             </param>
133           </params>
134         </script>
135
136         <dir name="pkgs" type="fixed">
137           <description>Contains files with packages.</description>
138           <file name="list" type="symbolic">
139             <description>File which contains the name of packages. On top of file the special
140             keywords '--reinstall' and '--can-fail' are possible.</description>
141           </file>
142         </dir>
143
144         <dir name="pubkeys" type="fixed">
145           <description>Directory with GPG pubkeys which are used to sign the packages of this
146           distribution.</description>
147         </dir>
148
149         <dir name="apt" type="fixed">
150           <description>Default content of the /etc/apt/ directory.</description>
151         </dir>
152
153         <dir name="rpm" type="fixed">
154           <description>Default content of the /etc/rpm directory.</description>
155         </dir>
156
157         <symlink name="rpmlib">
158           <description>Directory which overrides /usr/lib/rpm.</description>
159         </symlink>
160         
161         <symlink name="execdir">
162           <description>Directory with all executables and libraries which are required for this
163           distribution.</description>
164         </symlink>
165       </dir>
166     </dir> <!-- .distributions -->
167
168     <dir name="vserver-name" type="symbolic">
169       <description>The configuration directory for the vserver vserver-name.</description>
170
171       <file name="hostname">
172         <description>Contains the hostname of the vserver.</description>
173       </file>
174
175       <file name="name">
176         <description>Contains the name of the vserver. When not given, the basename of the directory
177         will be assumed as this name.</description>
178       </file>
179
180       <file name="domainname">
181         <description>The domainname of the vserver.</description>
182       </file>
183
184       <file name="nice">
185         <description>The nice-level on which the vserver will be started.</description>
186       </file>
187
188       <file name="capabilities">
189         <description>Contains per line a capability.</description>
190       </file>
191
192       <file name="shell">
193         <description>Contains the pathname of the shell which will be used by the "vserver ... enter"
194         command.</description>
195       </file>
196
197       <file name="flags">
198         <description>Contains per line a flag.</description>
199       </file>
200
201       <file name="context">
202         <description>Contains the context which shall be used for the vserver.</description>
203       </file>
204
205       <file name="fstab">
206         <description>The fstab file for the vserver.</description>
207       </file>
208       
209       <dir name="apps" type="fixed">
210         <dir name="init" type="fixed">
211           <file name="mtab">
212             <description>The initial-mtab which will be used for the vserver.</description>
213           </file>
214
215           <file name="style">
216             <description>Contains the init-style; possible values are 'sysv', 'plain' and
217             'minit'.</description>
218           </file>
219
220           <file name="runlevel">
221             <description>The start runlevel.</description>
222           </file>
223
224           <file name="runlevel.start">
225             <description>The start runlevel.</description>
226           </file>
227
228           <file name="runlevel.stop">
229             <description>The stop runlevel.</description>
230           </file>
231
232           <file name="killseq">
233             <description>Contains the 'signal [wait signal]*' sequence which is used to stop the
234             vserver.</description>
235           </file>
236
237           <file name="cmd.start">
238             <description>The command which is used to start the vserver. Each option must be on a
239             separate line.</description>
240           </file>
241
242           <file name="cmd.start-sync">
243             <description>The command which is used to wait on the vserver after it has been
244             started. Each option must be on a separate line. This file will be ignored when the
245             'sync' does not exist and the '--sync' option was not used.</description>
246           </file>
247           
248           <file name="cmd.stop">
249             <description>The command which is used to stop the vserver. Each option must be on a
250             separate line.</description>
251           </file>
252
253           <file name="cmd.stop-sync">
254             <description>The command which is used to wait on the vserver after it has been
255             stopped. Each option must be on a separate line. This file will be ignored when the
256             'sync' does not exist and the '--sync' option was not used.</description>
257           </file>
258
259           <file name="cmd.prepare">
260             <description>The command which is used to setup the init-system (e.g. to set the runlevel
261             in the utmp-file). Each option must be on a separate line.</description>
262           </file>
263
264           <file name="sync">
265             <description>Without this file, the 'cmd.*-sync' files will be ignored.</description>
266           </file>
267
268           <symlink name="tty">
269             <description>A symlink to the TTY device where input/output will be redirected from/to
270             at startup via initscript.</description>
271           </symlink>
272         </dir> <!-- ...apps/init -->
273
274         <dir name="vunify" type="fixed">
275           <description>This directory contains configuration data required for vserver
276           unification.</description>
277           
278           <file name="exclude">
279             <description>Static list of excluded files. This list supports an rsync syntax: when a
280             file is prefixed by '+', it is a candidate for unification; when there is no prefix or a
281             '-' it will be excluded. Shell-wildcards are allowed for the filenames.</description>
282           </file>
283
284           <symlink name="refserver.X">
285             <description>These are symlinks to the configuration directory
286             (e.g. CONFDIR/vservers/&lt;idgt;) of a refserver. There may be multiple such symlinks
287             but they must be prefixed by 'refserver.' and will be processed in alphanumerical
288             order.</description>
289           </symlink>
290         </dir>
291       </dir>
292
293       <dir name="scripts" type="fixed">
294         <script name="prepre-start">
295           <description>&init-script-text; &init-prepre-start;</description>
296           &init-scriptlet-params;
297         </script>
298         <dir name="prepre-start.d" type="fixed">
299           <description>&init-dir-text; &init-prepre-start;</description>
300
301           <script name="script">
302             <description>&init-dir-script-text; &init-prepre-start;</description>
303             &init-scriptlet-params;
304           </script>
305         </dir>
306
307         <script name="pre-start">
308           <description>&init-script-text; &init-pre-start;</description>
309           &init-scriptlet-params;
310         </script>
311
312         <dir name="pre-start.d">
313           <description>&init-dir-text; &init-pre-start;</description>
314           
315           <script name="script">
316             <description>&init-dir-script-text; &init-pre-start;</description>
317             &init-scriptlet-params;
318           </script>
319         </dir>
320
321         <script name="post-start">
322           <description>&init-script-text; &init-post-start;</description>
323           &init-scriptlet-params;
324         </script>
325
326         <dir name="post-start.d">
327           <description>&init-dir-text; &init-post-start;</description>
328           
329           <script name="script">
330             <description>&init-dir-script-text; &init-post-start;</description>
331             &init-scriptlet-params;
332           </script>
333         </dir>
334
335         <script name="pre-stop">
336           <description>&init-script-text; &init-pre-stop;</description>
337           &init-scriptlet-params;
338         </script>
339
340         <dir name="pre-stop.d" type="fixed">
341           <description>&init-dir-text; &init-pre-stop;</description>
342           <script name="script">
343             <description>&init-dir-script-text; &init-pre-stop;</description>
344             &init-scriptlet-params;
345           </script>
346         </dir>
347
348         <script name="post-stop">
349           <description>&init-script-text; &init-post-stop;</description>
350           &init-scriptlet-params;
351         </script>
352
353         <dir name="post-stop.d" type="fixed">
354           <description>&init-dir-text; &init-post-stop;</description>
355           <script name="script">
356             <description>&init-dir-script-text; &init-post-stop;</description>
357             &init-scriptlet-params;
358           </script>
359         </dir>
360
361         <script name="postpost-stop">
362           <description>&init-script-text; &init-postpost-stop;</description>
363           &init-scriptlet-params;
364         </script>
365
366         <dir name="postpost-stop.d" type="fixed">
367           <description>&init-dir-text; &init-postpost-stop;</description>
368           <script name="script">
369             <description>&init-dir-script-text; &init-postpost-stop;</description>
370             &init-scriptlet-params;
371           </script>
372         </dir>
373       </dir>
374
375
376       
377       <dir name="interfaces" type="fixed">
378         <file name="bcast">
379           <description>The deafult broadcast address.</description>
380         </file>
381         <file name="dev">
382           <description>The default network-device.</description>
383         </file>
384         <file name="prefix">
385           <description>The default network-prefix.</description>
386         </file>
387         <file name="mask">
388           <description>The default network-mask.</description>
389         </file>
390         <file name="scope">
391           <description>The default scope of the network interfaces.</description>
392         </file>
393
394         <dir name="iface" type="symbolic">
395           <description>'iface' is an arbitrary name for the interface; the value itself is not important
396           but may be interesting regarding interface-creation and usage with 'chbind'. Both happens in
397           alphabetical order and numbers like '00' are good names for these directories.</description>
398           
399           <file name="disabled">
400             <description>When this file exists, this interface will be ignored.</description>
401           </file>
402           
403           <file name="ip">
404             <description>The ip which will be assigned to this interface.</description>
405           </file>
406           <file name="bcast">
407             <description>The broadcast address.</description>
408           </file>
409           <file name="dev">
410             <description>The network-device.</description>
411           </file>
412           <file name="prefix">
413             <description>The network-prefix.</description>
414           </file>
415           <file name="mask">
416             <description>The network-mask.</description>
417           </file>
418           <file name="scope">
419             <description>The scope of the network interface.</description>
420           </file>
421           <file name="name">
422             <description>When this file exists, the interface will be named with the text in this file.</description>
423           </file>
424           <file name="nodev">
425             <description>When this file exists, the interface will be assumed to exist already. A
426             former name for this flag was 'only_ip' which is deprecated now.</description>
427           </file>
428         </dir>
429       </dir>
430
431       <dir name="ulimits" type="fixed">
432         <description>A directory with ulimits. Possible resources are cpu, data, fsize, locks,
433         memlock, nofile, nproc, rss and/or stack.</description>
434
435         <file name="resource" type="symbolic">
436           <description>A file which contains the hard- and soft-limit of the given resource in the
437           first line. The special keyword 'inf' is recognized.</description>
438         </file>
439
440         <file name="resource.hard" type="symbolic">
441           <description>A file which contains the hard- of the given resource in the first line. The
442           special keyword 'inf' is recognized.</description>
443         </file>
444
445         <file name="resource.soft" type="symbolic">
446           <description>A file which contains the soft- of the given resource in the first line. The
447           special keyword 'inf' is recognized.</description>
448         </file>
449       </dir>
450
451       <dir name="rlimits" type="fixed">
452         <description>see ulimits</description>
453       </dir>
454
455       <dir name="uts" type="fixed">
456         <file name="context">
457           <description>The context-name of the vserver</description>
458         </file>
459         <file name="sysname">
460           <description>The sysname of the vserver</description>
461         </file>
462         <file name="nodename">
463           <description>The node-/hostname of the vserver</description>
464         </file>
465         <file name="release">
466           <description>The OS-release of the vserver</description>
467         </file>
468         <file name="version">
469           <description>The OS-version of the vserver</description>
470         </file>
471         <file name="machine">
472           <description>The machine-type of the vserver</description>
473         </file>
474         <file name="domainname">
475           <description>The NIS domainname of the vserver</description>
476         </file>
477       </dir>
478     </dir>
479   </topleveldir>
480 </cfgdirdoc>
481
482
483 <!--
484 !! Local Variables:
485 !! fill-column: 100
486 !! End:
487 -->