/[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.2 - (hide annotations) (download) (as text)
Sat Oct 21 02:46:38 2006 UTC (7 years, 11 months ago) by hollow
Branch: MAIN
Changes since 1.1: +2 -2 lines
File MIME type: application/xml
fix typo

1 hollow 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 hollow 1.2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/vps/vserver-howto.xml,v 1.1 2006/06/19 09:08:32 hollow Exp $ -->
3 hollow 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5     <guide link="/doc/en/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 hollow 1.2 /dev/hdb1 /vservers reiserfs noatime,attrs 0 0
130 hollow 1.1 </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     <p>
215     You have to choose a context ID for your vserver (dynamic context IDs are
216     discouraged) as well as the necessary network device information (In this
217     example eth0 is configured with 192.168.1.253/24 and the context ID is
218     equivalent to the last two parts of the virtual servers IP).
219     </p>
220    
221     <note>
222     The context ID should be 1 &lt; ID &lt; 49152.
223     </note>
224    
225     <pre caption="Start stage3 installation">
226     # <i>vserver-new gentoo-template \</i>
227     <i>--hostname gentoo \</i>
228     <i>--context 1253 \</i>
229     <i>--interface eth0:192.168.1.253/24 \</i>
230     <i>stage3 /path/to/stage3-&lt;arch&gt;-&lt;date&gt;.tar.bz2 &lt;arch&gt;</i>
231     </pre>
232    
233     <note>
234     To reflect your network settings you should change
235     <path>/etc/conf.d/hostname</path>, <path>/etc/conf.d/domainname</path> and
236     <path>/etc/hosts</path> inside the guest to your needs. See <uri
237     link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=8#doc_chap2_sect1">chapter
238     8.b.1</uri> and <uri
239     link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=8#doc_chap2_sect4">chapter
240     8.b.4</uri>. The rest of your virtual servers network setup will be
241     done on the host.
242     </note>
243    
244     </body>
245     </section>
246     <section>
247     <title>Create the template tarball</title>
248     <body>
249    
250     <p>
251     You don't have to build a stage3 tarball for every guest. The <c>vserver-new</c>
252     script supports templates. In order to use them you have to create a tarball of
253     your vserver installation:
254     </p>
255    
256     <pre caption="Create template tarball">
257     # <i>cd /vservers/gentoo-template</i>
258     # <i>tar cjvpf ../gentoo-template-&lt;arch&gt;-&lt;date&gt;.tar.bz2 ./</i>
259     </pre>
260    
261     <p>
262     To create a new guest using this tarball just use <c>vserver-new</c>:
263     </p>
264    
265     <pre caption="Use template tarball">
266     # <i>cd /vservers</i>
267     # <i>vserver-new myguest \</i>
268     <i>--hostname myguest \</i>
269     <i>--context 1252 \</i>
270     <i>--interface eth0:192.168.1.252/24 \</i>
271     <i>template ./gentoo-template-&lt;arch&gt;-&lt;date&gt;.tar.bz2 &lt;arch&gt;</i>
272     </pre>
273    
274     <note>
275     You should use a shared portage tree to keep guests small in size. Edit
276     <path>/etc/vservers/myguest/fstab</path> and uncomment the entries
277     for <path>/usr/portage</path> and <path>/usr/portage/distfiles</path>. Guests
278     will have read-only access to <path>/usr/portage</path> and read-write access
279     to <path>/usr/portage/distfiles</path>.
280     </note>
281    
282     </body>
283     </section>
284     <section>
285     <title>Test the virtual server</title>
286     <body>
287    
288     <p>
289     You should be able to start and enter the vserver by using the commands below.
290     If you miss commands like <c>mount</c> or <c>dmesg</c> you should <c>emerge
291     util-linux</c> inside your virtual server as the vserver profile doesn't ship
292     this package by default.
293     </p>
294    
295     <pre caption="Test the virtual server">
296     # <i>vserver myguest start</i>
297     # <i>vserver-stat</i>
298     CTX PROC VSZ RSS userTIME sysTIME UPTIME NAME
299     0 90 1.4G 153.4K 14m00s11 6m45s17 2h59m59 root server
300     1252 2 3M 286 0m00s45 0m00s42 0m02s91 myguest
301     # <i>vserver myguest enter</i>
302     # <i>ps ax</i>
303     PID TTY STAT TIME COMMAND
304     1 ? S 0:00 init [3]
305     22887 ? Ss 0:00 /usr/sbin/syslog-ng
306     20496 pts/0 S 0:00 /bin/bash -login
307     20508 pts/0 R+ 0:00 ps ax
308     # <i>logout</i>
309     </pre>
310    
311     </body>
312     </section>
313     </chapter>
314    
315     <chapter>
316     <title>Maintenance made easy</title>
317     <section>
318     <title>Start guests on boot</title>
319     <body>
320    
321     <p>
322     You can start certain guests during boot. Each guest can be assigned a MARK.
323     Now everything you have to do is configure these MARKs in the guests
324     configuration and tell the init script to run all MARKed guests.
325     </p>
326    
327     <pre caption="Configure MARKs for each guest">
328     <comment>(Do this for every guest you want to start)</comment>
329     # <i>mkdir -p /etc/vservers/myguest/apps/init</i>
330     # <i>echo "default" > /etc/vservers/myguest/apps/init/mark</i>
331     </pre>
332    
333     <note>
334     Since all guests marked with "default" are started by default, nothing more has
335     to be done. If you have different marks you should also update
336     <path>/etc/conf.d/vservers</path>.
337     </note>
338    
339     </body>
340     </section>
341     <section>
342     <title>Gentoo goodies</title>
343     <body>
344    
345     <p>
346     The util-vserver ebuild has installed some goodies for Gentoo guests. You know
347     <c>vserver-new</c> from the previous chapter. In this chapter, you will learn
348     how to use <c>vesync</c> and <c>vemerge</c> to keep portage in sync as well as
349     <c>vupdateworld</c> and <c>vdispatch-conf</c> to update guests.
350     </p>
351    
352     </body>
353     </section>
354     <section>
355     <title>Keep portage in sync</title>
356     <body>
357    
358     <p>
359     The script <c>vesync</c> will help you to keep the metadata cache and overlays
360     in sync. <c>vemerge</c> is a simple wrapper for <c>emerge</c> in guests.
361     </p>
362    
363     <pre caption="Examples">
364     <comment>(Sync metadata for 'myguest')</comment>
365     # <i>vesync myguest</i>
366     <comment>(Sync metadata for all guests)</comment>
367     # <i>vesync -a</i>
368     <comment>(Sync metadata for all guests except 'myguest')</comment>
369     # <i>vesync -a -e myguest</i>
370     <comment>(Sync 'myoverlay' for all guests)</comment>
371     # <i>vesync -a \</i>
372     <i>--overlay /usr/local/overlays/myoverlay \</i>
373     <i>--overlay-host rsync://rsync.myhost.com/myoverlay \</i>
374     <i>--overlay-only</i>
375     <comment>(emerge app-editors/vim in 'myguest')</comment>
376     # <i>vemerge myguest app-editors/vim -va</i>
377     </pre>
378    
379     <note>
380     This script requires you to have a shared portage tree.
381     </note>
382    
383     </body>
384     </section>
385     <section>
386     <title>Update guests</title>
387     <body>
388    
389     <p>
390     Gentoo guests can share packages to save compilation time. In order to use
391     shared packages, you have to create a central directory for packages on the
392     host. We will use <path>/var/cache/vpackages</path> on the host and mount it
393     to <path>/usr/portage/packages</path> in every guest.
394     </p>
395    
396     <pre caption="Add bind mount to guest configuration">
397     # <i>mkdir -p /var/cache/vpackages</i>
398     # <i>$EDITOR /etc/vservers/myguest/fstab</i>
399     <comment>(Add this line at the end)</comment>
400     /var/cache/vpackages /usr/portage/packages none bind,rw 0 0
401     </pre>
402    
403     <p>
404     Now you can use <c>vupdateworld</c> to update every guest. The command is
405     equivalent to something like <c>emerge --deep --update --newuse world</c>
406     depending on command line options.
407     </p>
408    
409     <pre caption="vupdateworld examples">
410     <comment>(Pretend update for 'myguest')</comment>
411     # <i>vupdateworld -p myguest</i>
412     <comment>(Update 'myguest' using binary packages)</comment>
413     # <i>vupdateworld -k myguest</i>
414     <comment>(Update all guests using binary packages)</comment>
415     # <i>vupdateworld -ka</i>
416     </pre>
417    
418     <note>
419     In order to get binary packages you can either use PORTAGE_BINHOST (see <c>man
420     make.conf</c>) or set FEATURES="buildpkg" in one or more guests.
421     </note>
422    
423     <p>
424     After a successful update you can easily update all configuration files with
425     <c>vdispatch-conf</c>. It is a simple wrapper for <c>dispatch-conf</c> and
426     behaves exactly the same.
427     </p>
428    
429     <pre caption="vdispatch-conf examples">
430     <comment>(Update configuration files for 'myguest')</comment>
431     # <i>vdispatch-conf myguest</i>
432     <comment>(Update configuration files for all guests)</comment>
433     # <i>vdispatch-conf -a</i>
434     </pre>
435    
436     </body>
437     </section>
438    
439     <section>
440     <title>Contact</title>
441     <body>
442    
443     <p>
444     Please feel free to contact the <mail link="hollow@gentoo.org">author</mail> or
445     file a bug on <uri link="http://bugs.gentoo.org">Bugzilla</uri> in case of any
446     problems.
447     </p>
448    
449     </body>
450     </section>
451     </chapter>
452     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20