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