"Notes for distributors" + "Which version shall I use?" added
[util-vserver.git] / util-vserver / README
1 Some common notes/FAQs:
2 ======================
3
4 * when vserver startup/shutdown fails, or when you get
5
6   | Error: /proc must be mounted
7
8   errors, make sure, that 'vprocunhide' was executed. When installing
9   'util-vserver' with packagemanagement, an appropriate initscript
10   should be installed
11
12 * the name of old-style vservers is shown on 2.4 kernels only; the
13   needed functionality is not implemented for 2.6 kernels.
14
15
16
17 Some distribution specific notes:
18 =================================
19
20 Red Hat 7.3, Red Hat 9, Fedora Core 1&2
21 ---------------------------------------
22 * tested and running successfully as host and guest systems
23
24 * it is *strongly* suggested to use the rpm packages which can be
25   created from the tarball with
26
27   | $ rpmbuild -tb util-vserver-<version>.tar.bz2
28
29   For distributions below Fedora Core 2, additional
30
31   | --without dietlibc --without xalan
32
33   flags are required for the 'rpmbuild' command. Builds on Red Hat 7.3
34   will require a
35
36   | --nodeps
37
38   also, since 'vconfig' is not available there. Since it is required
39   for path-detection only and paths from RH systems will be assumed by
40   default, this should not be a big problem.
41
42 * guest systems can be created with the 'apt-rpm' build-method. This
43   requires the 'apt' package e.g. from http://fedora.us. Before first
44   invocation, a near mirror should be activated in
45
46   | /etc/vservers/.distributions/<id>/apt/sources.list
47
48   (To avoid slashdotting by the masses of util-vserver-users, there
49   does not exist a standard mirror)
50
51 * RH/FC uses the 'sysv' initstyle which is assumed by default
52
53 * when having existing vservers with RH 9 or Fedora Core 1, the startup
54   of the vserver will probably fail. You will have to add
55
56   | true
57
58   to etc/rc.d/rc (within the vserver root directory)
59
60 * when having RH/FC guestsystems, it is *strongly* recommended to use
61   a dietlibc linked version of 'rpm-fake-resolver'. Else, package
62   installation with 'vrpm' or 'vapt-get' can fail since users can not
63   be resolved.
64
65
66
67 Debian Woody & Sarge
68 --------------------
69 * tested and running successfully as guest systems on FC1/FC2 hosts
70
71 * guest systems can be created with the 'debootstrap' method. When
72   not already existing, the needed package will be downloaded
73   automatically.  Since it is updated very often, it can happen
74   that a '404 Not found' error occurs; in this case look either
75   for a newer util-vserver package, or configure the new URI e.g. with
76
77   | echo 'http://ftp.debian.org/debian/pool/main/d/debootstrap/debootstrap_<version>_i386.deb' \
78   |    >/etc/vservers/.defaults/apps/debootstrap/uri
79
80   You can download a local copy of this tarball also, and register it
81   with
82
83   | echo '/<path-to-the-tarball>' \
84   |    >/etc/vservers/.defaults/apps/debootstrap/uri
85
86 * it is known, that warning messages will be created at startup and
87   shutdown of guest servers. This is non fatal and can be ignored
88
89 * Debian guest systems are running fine with the 'sysv' initstyle;
90   success with 'plain' was reported also
91
92 * no packages for Debian hosts are known at time of writing (May 2004)
93
94
95
96 Gentoo
97 ------
98 * Gentoo guest systems are very complicated and are requiring lots of
99   modifications in the initscripts. Currently, no step-by-step guide
100   can be provided
101
102 * 'sysv' initstyle is probably not working for Gentoo guests (e.g. you
103   will see messages about missing 'utmp' files); 'gentoo' should be
104   used instead of:
105
106   | echo 'gentoo' >/etc/vservers/<id>/apps/init/style
107
108 * there does not exist a build-method for Gentoo guests; instead of,
109   create a skeleton with
110
111   | # vserver <id> build -m skeleton --initstyle gentoo <other-opts>*
112
113   and fill the vserver directory at /etc/vservers/<id>/vdir/ manually.
114
115
116
117 Notes for distributors:
118 =======================
119
120 To generate FHS compliant paths, call configure with
121
122 | ./configure --prefix=/usr --mandir=/usr/share/man \
123 |             --sysconfdir=/etc --localstatedir=/var \
124 |             --with-vrootdir=<an FHS compliant path for /vservers>
125
126 Except the '--with-vrootdir' option, rpm's '%configure' option will
127 expand to this.
128
129
130 There exists a 'make install-distribution' target which installs
131 files outside of the configured 'prefix'. In particular, these files are:
132
133 * the /sbin/vshelper symlink
134 * the /vservers and related directories (or whatever you configured
135   with '--with-vrootdir')
136
137 Without this rule, 'make distcheck' would fail.
138
139
140 It might be needed also, to call 'setattr --barrier /vservers' in an
141 after-installation script.
142
143
144
145 Which version shall I use?
146 ==========================
147
148 As you probably know, two branches of 'util-vserver' are existing: the
149 'stable' one, and the 'alpha' one. This terms are to be understood as
150 a level of the featureset stability but not of the software stability.
151
152 E.g. 'stable' is not really stable: it has huge security problems and
153 missing functionality. But you can expect that the current configuration
154 will work in future versions also.
155
156 In the opposite, the 'alpha' branch does not have known security issues
157 and works well on author's system. But it may happen that some behavior
158 or configuration options change. With 'alpha' you should be still able
159 to use vservers created with the 'stable' branch, but you may encounter
160 some oddities -- especially on kernel 2.6 systems (e.g. 'vserver-stat'
161 will show the names of old vservers).
162
163
164 So let me summarize:
165
166 * when you have productive vservers running for some years already, stay
167   at the 'stable' branch. A change to 'alpha' will need a completely
168   rewritten configuration which must be perhaps changed again.
169
170 * when you are new at vservers, use the 'alpha' branch. You will have
171   to learn the principles of vserver configuration for both branches
172   but 'alpha' makes some things easier.
173
174 * when you have existing vservers and want all the new kernel 2.6
175   functionality, use the 'alpha' branch.
176
177
178 A last note: the 'alpha' branch works both with the stable 2.4 and the
179 development 2.6 kernel patch.
180
181
182
183 ## $Id$