/[gentoo]/xml/htdocs/proj/en/vps/vserver-howto.xml
Gentoo

Contents of /xml/htdocs/proj/en/vps/vserver-howto.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.4 - (show annotations) (download) (as text)
Wed Jan 10 17:21:36 2007 UTC (7 years, 11 months ago) by phreak
Branch: MAIN
Changes since 1.3: +6 -1 lines
File MIME type: application/xml
Adding a note about vserver-new in >=util-vserver-0.30.212.

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/vps/vserver-howto.xml,v 1.3 2006/10/24 20:15:16 hollow Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="/proj/en/vps/vserver-howto.xml">
6 <title>Gentoo Linux-VServer Howto</title>
7
8 <author title="Author">
9 <mail link="hollow@gentoo.org">Benedikt Boehm</mail>
10 </author>
11 <author title="Editor">
12 <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
13 </author>
14
15 <abstract>
16 In this Howto you will learn to setup a basic virtual server using the
17 Linux-VServer Technology
18 </abstract>
19
20 <!-- The content of this document is licensed under the CC-BY-SA license -->
21 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
22 <license/>
23
24 <version>1.6</version>
25 <date>2006-06-19</date>
26
27 <chapter>
28 <title>Introduction</title>
29 <section>
30 <title>The Linux-VServer Concept</title>
31 <body>
32
33 <p>
34 The basic concept of the Linux-VServer solution is to separate the user-space
35 environment into distinct units (sometimes called Virtual Private Servers) in
36 such a way that each VPS looks and feels like a real server to the processes
37 contained within.
38 </p>
39
40 </body>
41 </section>
42 <section>
43 <title>Terms used in this Howto</title>
44 <body>
45
46 <table>
47 <tr>
48 <th>Term</th>
49 <th>Description</th>
50 </tr>
51 <tr>
52 <th>Linux-VServer, VServer</th>
53 <ti>
54 Linux-VServer is the official name of the project and used in this Howto
55 the same way
56 </ti>
57 </tr>
58 <tr>
59 <th>virtual server, vserver, guest system</th>
60 <ti>
61 All these are interchangable and refer to one instance of a server (i.e.
62 one virtual server)
63 </ti>
64 </tr>
65 <tr>
66 <th>host system, host</th>
67 <ti>
68 The physical machine running your Gentoo Linux will host all virtual
69 servers
70 </ti>
71 </tr>
72 <tr>
73 <th>util-vserver</th>
74 <ti>
75 The <c>util-vserver</c> package contains all programs necessary for
76 maintaining your virtual servers
77 </ti>
78 </tr>
79 </table>
80
81 </body>
82 </section>
83 </chapter>
84
85 <chapter>
86 <title>Host configuration</title>
87 <section>
88 <title>Install a VServer kernel</title>
89 <body>
90
91 <pre caption="Install vserver-sources">
92 # <i>emerge vserver-sources</i>
93 </pre>
94
95 <p>
96 After the vserver-sources are installed it's time to configure them using
97 <c>make menuconfig</c>.
98 </p>
99
100 <pre caption="Configure vserver-sources">
101 # <i>cd /usr/src/linux-&lt;KERNELVERSION&gt;-vserver-&lt;VSERVERVERSION&gt;</i>
102 # <i>make menuconfig</i>
103
104 Linux VServer ---&gt;
105 [ ] Enable Legacy Kernel API
106 [*] Disable Legacy Networking Kernel API
107 <comment>(Highly recommended)</comment>
108 [*] Enable Proc Security
109 [*] Enable Hard CPU Limits
110 Persistent Inode Context Tagging (UID24/GID24) ---&gt;
111 [ ] Tag NFSD User Auth and Files
112 [ ] Compile Debugging Code
113 </pre>
114
115 <note>
116 If you are using reiserfs as filesystem on the partition where guest images are
117 stored, you will need to enable extended attributes for reiserfs in your
118 kernel config and additionally add the <c>attrs</c> option in
119 <path>/etc/fstab</path>.
120 </note>
121
122 <pre caption="Configure reiserfs options">
123 File systems --->
124 &lt;*&gt; Reiserfs support
125 [*] ReiserFS extended attributes
126 </pre>
127
128 <pre caption="Example fstab with extended attributes">
129 /dev/hdb1 /vservers reiserfs noatime,attrs 0 0
130 </pre>
131
132 <p>
133 After you've built and installed the kernel, update your boot loader and
134 finally reboot to see if the kernel boots correctly.
135 </p>
136
137 <pre caption="Install the kernel">
138 <comment>(Building the kernel)</comment>
139 # <i>make</i>
140 <comment>(Installing)</comment>
141 # <i>make modules_install</i>
142 # <i>cp arch/&lt;arch&gt;/boot/bzImage /boot/kernel-&lt;KERNELVERSION&gt;-vserver-&lt;VSERVERVERSION&gt;</i>
143 <comment>(Edit bootloader config file as required and)</comment>
144 # <i>reboot</i>
145 </pre>
146
147 </body>
148 </section>
149 <section>
150 <title>Setup host environment</title>
151 <body>
152
153 <p>
154 To maintain your virtual servers you need the util-vserver package which
155 contains all necessary programs and many useful features. Be aware that there
156 is also a package called <c>vserver-utils</c>. It is a new incarnation of the
157 user-space implementation of the VServer kernel API, but not yet usable for
158 production use.
159 </p>
160
161 <note>
162 This version of the howto requires features only available in
163 <c>&gt;=sys-apps/util-vserver-0.30.210-r6</c>. You may have to keyword/upgrade
164 it first.
165 </note>
166
167 <pre caption="Install util-vserver">
168 # <i>emerge util-vserver</i>
169 </pre>
170
171 <p>
172 You have to run the <c>vprocunhide</c> command after every reboot in order to
173 setup <path>/proc</path> permissions correctly for vserver use. An init script
174 has been installed by util-vserver. To use it you should add it to a runlevel:
175 </p>
176
177 <pre caption="vserver init script">
178 # <i>rc-update add vservers default</i>
179 # <i>/etc/init.d/vservers start</i>
180 </pre>
181
182 <note>
183 This init script will also start your default vservers. Read below for more
184 information.
185 </note>
186
187 <p>
188 The vshelper script is used to restart virtual servers correctly. You
189 have to tell the kernel where the vshelper script is located:
190 </p>
191
192 <pre caption="vshelper setup">
193 # <i>echo 'kernel.vshelper = /usr/lib/util-vserver/vshelper' &gt;&gt; /etc/sysctl.conf</i>
194 # <i>sysctl -p</i>
195 </pre>
196
197 </body>
198 </section>
199 </chapter>
200
201 <chapter>
202 <title>Creating a guest template</title>
203 <section>
204 <title>Install a vserver stage3</title>
205 <body>
206
207 <p>
208 You have to download a vserver prepared stage3 from one of
209 <uri link="/main/en/mirrors.xml">our mirrors</uri>. Those stages are located
210 under the <path>experimental/&lt;arch&gt;/vserver/</path> directory.
211 Then use the <c>vserver-new</c> script to create the initial guest.
212 </p>
213
214 <note>Please note that starting with util-vserver-0.30.212 the vserver-new script
215 stopped existing, as the functionality got merged into UPSTREAM's release and is
216 now integrated into util-vserver's swiss army knive <c>vserver</c>. It's now called
217 via <c>vserver &lt;name&gt; build</c>.</note>
218
219 <p>
220 You have to choose a context ID for your vserver (dynamic context IDs are
221 discouraged) as well as the necessary network device information (In this
222 example eth0 is configured with 192.168.1.253/24 and the context ID is
223 equivalent to the last two parts of the virtual servers IP).
224 </p>
225
226 <note>
227 The context ID should be 1 &lt; ID &lt; 49152.
228 </note>
229
230 <pre caption="Start stage3 installation">
231 # <i>vserver-new gentoo-template \</i>
232 <i>--hostname gentoo \</i>
233 <i>--context 1253 \</i>
234 <i>--interface eth0:192.168.1.253/24 \</i>
235 <i>stage3 /path/to/stage3-&lt;arch&gt;-&lt;date&gt;.tar.bz2 &lt;arch&gt;</i>
236 </pre>
237
238 <note>
239 To reflect your network settings you should change
240 <path>/etc/conf.d/hostname</path>, <path>/etc/conf.d/domainname</path> and
241 <path>/etc/hosts</path> inside the guest to your needs. See <uri
242 link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=8#doc_chap2_sect1">chapter
243 8.b.1</uri> and <uri
244 link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=8#doc_chap2_sect4">chapter
245 8.b.4</uri>. The rest of your virtual servers network setup will be
246 done on the host.
247 </note>
248
249 </body>
250 </section>
251 <section>
252 <title>Create the template tarball</title>
253 <body>
254
255 <p>
256 You don't have to build a stage3 tarball for every guest. The <c>vserver-new</c>
257 script supports templates. In order to use them you have to create a tarball of
258 your vserver installation:
259 </p>
260
261 <pre caption="Create template tarball">
262 # <i>cd /vservers/gentoo-template</i>
263 # <i>tar cjvpf ../gentoo-template-&lt;arch&gt;-&lt;date&gt;.tar.bz2 ./</i>
264 </pre>
265
266 <p>
267 To create a new guest using this tarball just use <c>vserver-new</c>:
268 </p>
269
270 <pre caption="Use template tarball">
271 # <i>cd /vservers</i>
272 # <i>vserver-new myguest \</i>
273 <i>--hostname myguest \</i>
274 <i>--context 1252 \</i>
275 <i>--interface eth0:192.168.1.252/24 \</i>
276 <i>template ./gentoo-template-&lt;arch&gt;-&lt;date&gt;.tar.bz2 &lt;arch&gt;</i>
277 </pre>
278
279 <note>
280 You should use a shared portage tree to keep guests small in size. Edit
281 <path>/etc/vservers/myguest/fstab</path> and uncomment the entries
282 for <path>/usr/portage</path> and <path>/usr/portage/distfiles</path>. Guests
283 will have read-only access to <path>/usr/portage</path> and read-write access
284 to <path>/usr/portage/distfiles</path>.
285 </note>
286
287 </body>
288 </section>
289 <section>
290 <title>Test the virtual server</title>
291 <body>
292
293 <p>
294 You should be able to start and enter the vserver by using the commands below.
295 If you miss commands like <c>mount</c> or <c>dmesg</c> you should <c>emerge
296 util-linux</c> inside your virtual server as the vserver profile doesn't ship
297 this package by default.
298 </p>
299
300 <pre caption="Test the virtual server">
301 # <i>vserver myguest start</i>
302 # <i>vserver-stat</i>
303 CTX PROC VSZ RSS userTIME sysTIME UPTIME NAME
304 0 90 1.4G 153.4K 14m00s11 6m45s17 2h59m59 root server
305 1252 2 3M 286 0m00s45 0m00s42 0m02s91 myguest
306 # <i>vserver myguest enter</i>
307 # <i>ps ax</i>
308 PID TTY STAT TIME COMMAND
309 1 ? S 0:00 init [3]
310 22887 ? Ss 0:00 /usr/sbin/syslog-ng
311 20496 pts/0 S 0:00 /bin/bash -login
312 20508 pts/0 R+ 0:00 ps ax
313 # <i>logout</i>
314 </pre>
315
316 </body>
317 </section>
318 </chapter>
319
320 <chapter>
321 <title>Maintenance made easy</title>
322 <section>
323 <title>Start guests on boot</title>
324 <body>
325
326 <p>
327 You can start certain guests during boot. Each guest can be assigned a MARK.
328 Now everything you have to do is configure these MARKs in the guests
329 configuration and tell the init script to run all MARKed guests.
330 </p>
331
332 <pre caption="Configure MARKs for each guest">
333 <comment>(Do this for every guest you want to start)</comment>
334 # <i>mkdir -p /etc/vservers/myguest/apps/init</i>
335 # <i>echo "default" > /etc/vservers/myguest/apps/init/mark</i>
336 </pre>
337
338 <note>
339 Since all guests marked with "default" are started by default, nothing more has
340 to be done. If you have different marks you should also update
341 <path>/etc/conf.d/vservers</path>.
342 </note>
343
344 </body>
345 </section>
346 <section>
347 <title>Gentoo goodies</title>
348 <body>
349
350 <p>
351 The util-vserver ebuild has installed some goodies for Gentoo guests. You know
352 <c>vserver-new</c> from the previous chapter. In this chapter, you will learn
353 how to use <c>vesync</c> and <c>vemerge</c> to keep portage in sync as well as
354 <c>vupdateworld</c> and <c>vdispatch-conf</c> to update guests.
355 </p>
356
357 </body>
358 </section>
359 <section>
360 <title>Keep portage in sync</title>
361 <body>
362
363 <p>
364 The script <c>vesync</c> will help you to keep the metadata cache and overlays
365 in sync. <c>vemerge</c> is a simple wrapper for <c>emerge</c> in guests.
366 </p>
367
368 <pre caption="Examples">
369 <comment>(Sync metadata for 'myguest')</comment>
370 # <i>vesync myguest</i>
371 <comment>(Sync metadata for all guests)</comment>
372 # <i>vesync -a</i>
373 <comment>(Sync metadata for all guests except 'myguest')</comment>
374 # <i>vesync -a -e myguest</i>
375 <comment>(Sync 'myoverlay' for all guests)</comment>
376 # <i>vesync -a \</i>
377 <i>--overlay /usr/local/overlays/myoverlay \</i>
378 <i>--overlay-host rsync://rsync.myhost.com/myoverlay \</i>
379 <i>--overlay-only</i>
380 <comment>(emerge app-editors/vim in 'myguest')</comment>
381 # <i>vemerge myguest app-editors/vim -va</i>
382 </pre>
383
384 <note>
385 This script requires you to have a shared portage tree.
386 </note>
387
388 </body>
389 </section>
390 <section>
391 <title>Update guests</title>
392 <body>
393
394 <p>
395 Gentoo guests can share packages to save compilation time. In order to use
396 shared packages, you have to create a central directory for packages on the
397 host. We will use <path>/var/cache/vpackages</path> on the host and mount it
398 to <path>/usr/portage/packages</path> in every guest.
399 </p>
400
401 <pre caption="Add bind mount to guest configuration">
402 # <i>mkdir -p /var/cache/vpackages</i>
403 # <i>$EDITOR /etc/vservers/myguest/fstab</i>
404 <comment>(Add this line at the end)</comment>
405 /var/cache/vpackages /usr/portage/packages none bind,rw 0 0
406 </pre>
407
408 <p>
409 Now you can use <c>vupdateworld</c> to update every guest. The command is
410 equivalent to something like <c>emerge --deep --update --newuse world</c>
411 depending on command line options.
412 </p>
413
414 <pre caption="vupdateworld examples">
415 <comment>(Pretend update for 'myguest')</comment>
416 # <i>vupdateworld -p myguest</i>
417 <comment>(Update 'myguest' using binary packages)</comment>
418 # <i>vupdateworld -k myguest</i>
419 <comment>(Update all guests using binary packages)</comment>
420 # <i>vupdateworld -ka</i>
421 </pre>
422
423 <note>
424 In order to get binary packages you can either use PORTAGE_BINHOST (see <c>man
425 make.conf</c>) or set FEATURES="buildpkg" in one or more guests.
426 </note>
427
428 <p>
429 After a successful update you can easily update all configuration files with
430 <c>vdispatch-conf</c>. It is a simple wrapper for <c>dispatch-conf</c> and
431 behaves exactly the same.
432 </p>
433
434 <pre caption="vdispatch-conf examples">
435 <comment>(Update configuration files for 'myguest')</comment>
436 # <i>vdispatch-conf myguest</i>
437 <comment>(Update configuration files for all guests)</comment>
438 # <i>vdispatch-conf -a</i>
439 </pre>
440
441 </body>
442 </section>
443
444 <section>
445 <title>Contact</title>
446 <body>
447
448 <p>
449 Please feel free to contact the <mail link="hollow@gentoo.org">author</mail> or
450 file a bug on <uri link="http://bugs.gentoo.org">Bugzilla</uri> in case of any
451 problems.
452 </p>
453
454 </body>
455 </section>
456 </chapter>
457 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20