/[gentoo]/xml/htdocs/doc/en/uml.xml
Gentoo

Contents of /xml/htdocs/doc/en/uml.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.30 - (hide annotations) (download) (as text)
Sat Mar 1 19:24:22 2008 UTC (11 years ago) by jkt
Branch: MAIN
Changes since 1.29: +16 -10 lines
File MIME type: application/xml
#211997, /etc/env.d/00basic belongs to baselayout and shouldn't be touched

1 zhen 1.3 <?xml version='1.0' encoding="UTF-8"?>
2 jkt 1.30 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.29 2006/11/29 15:48:57 nightmorph Exp $ -->
3 drobbins 1.1
4     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5    
6 zhen 1.2 <guide link="/doc/en/uml.xml">
7 drobbins 1.1 <title>Gentoo Linux Developer's guide to system testing with User-Mode Linux</title>
8 rane 1.23
9 swift 1.20 <author title="Editor">
10     <mail link="g2boojum@gentoo.org">Grant Goodyear</mail>
11     </author>
12 swift 1.10 <author title="Editor"><!-- zhen@gentoo.org -->
13     John Davis
14     </author>
15 swift 1.7 <author title="Editor">
16 nightmorph 1.29 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
17 swift 1.7 </author>
18 bennyc 1.9 <author title="Editor">
19     <mail link="bennyc@gentoo.org">Benny Chuang</mail>
20     </author>
21 swift 1.7
22 drobbins 1.1 <abstract>
23 swift 1.20 This guide shows Gentoo Linux developers how to set up and use
24     user-mode linux for testing potentially system-breaking changes.
25 drobbins 1.1 </abstract>
26    
27 rane 1.23 <!-- The content of this document is licensed under the CC-BY-SA license -->
28     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
29 swift 1.8 <license/>
30    
31 jkt 1.30 <version>0.16</version>
32     <date>2008-03-01</date>
33 drobbins 1.1
34     <chapter>
35     <title>Obtaining User-Mode Linux</title>
36     <section>
37     <body>
38 swift 1.14
39 nightmorph 1.26 <impo>
40     Before you can use user-mode Linux, you <e>must</e> be using a non-NPTL
41     profile, and you must be using &lt;<c>glibc</c>-2.4. Follow the instructions
42     for <uri link="/doc/en/gentoo-upgrading.xml#instructions">changing
43     profiles</uri>. You will need to run <c>emerge -e world</c> after switching to
44     a non-NPTL profile.
45     </impo>
46    
47 swift 1.14 <p>
48 nightmorph 1.26 As the user-mode Linux website
49     (<uri>http://user-mode-linux.sourceforge.net</uri>) states, user-modeL linux
50 drobbins 1.1 allows a user to "run Linux inside itself". Specifically,
51     user-mode linux provides a virtual machine on which a user can "[r]un buggy
52     software, experiment with new Linux kernels or distributions, and poke around
53 swift 1.22 in the internals of Linux, all without risking your main Linux setup."
54     Experimental changes to Gentoo core packages such as <e>sys-apps/baselayout</e>
55     or <e>sys-libs/glibc</e> have the potential to break the system and render it
56 nightmorph 1.26 unbootable; with user-mode Linux we can test these changes without having to
57 swift 1.14 worry about breaking the live system.
58 drobbins 1.1 </p>
59 swift 1.14
60 drobbins 1.1 <p>
61 swift 1.24 Most 2.6 kernels have UML support. Although you can use your current kernel
62     sources, it might be wiser to keep the UML kernel tree(s) separate. After all,
63     you'll be building a new kernel with a different configuration and you might
64     want to have heterogenous systems on your main Linux system (several different
65     UML kernels).
66 drobbins 1.1 </p>
67 swift 1.14
68 swift 1.24 <p>
69     So download a nice kernel tree (like the vanilla one from <uri
70     link="http://www.kernel.org">kernel.org</uri>) and extract it to some local
71     development location.
72     </p>
73    
74     <p>
75     Next, configure this UML kernel as you would do for any other system, but append
76     <e>ARCH=um</e> so that the kernel build software knows that the kernel
77     is meant to run as a guest process on the main system.
78     </p>
79    
80     <pre caption="Building the UML kernel">
81     # <i>cd /srv/aegis/src/uml-linux</i>
82 drobbins 1.1 # <i>make menuconfig <comment>ARCH=um</comment></i>
83     # <i>make linux <comment>ARCH=um</comment></i>
84     # <i>cp linux /usr/local/bin/linux</i>
85     </pre>
86 swift 1.14
87 swift 1.19 <warn>
88     The <e>ARCH=um</e> fragment is <e>extremely</e> important!
89     </warn>
90    
91 swift 1.15 <p>
92 jkt 1.30 On a default Gentoo system, <path>/usr/local/bin</path> is in your <c>$PATH</c>.
93     If it isn't, you should find a definition of <c>PATH</c> in the
94     <path>/etc/profile</path> and fix it:
95 swift 1.15 </p>
96    
97 jkt 1.30 <pre caption="Verifying $PATH">
98     $ <i>echo $PATH | grep /usr/local/bin</i>
99 swift 1.15 </pre>
100    
101 jkt 1.30 <pre caption="Sample definition of $PATH in /etc/profile">
102     PATH="/usr/local/bin:/usr/bin:/bin:${PATH}"
103     </pre>
104    
105     <p>
106     Don't forget to run <c>source /etc/profile</c> for the change to take effect.
107     </p>
108    
109 swift 1.20 <p>
110 nightmorph 1.26 For the user-mode Linux kernel to properly boot a Gentoo system the
111 drobbins 1.1 kernel needs to be configured to <e>not</e> automatically mount
112 swift 1.14 <path>/dev</path> (devfs) by default. Also, you will almost certainly
113 drobbins 1.1 want to make sure that you have <e>tmpfs</e> (the "Virtual Memory
114 nightmorph 1.26 Filesystem") compiled in, since by default the Gentoo Linux bootscripts
115 drobbins 1.1 store their information in a small tmpfs partition.
116 swift 1.14 (The binary kernels available from the user-mode website do automatically
117     mount <path>/dev</path>, and they don't have tmpfs compiled in; don't bother
118     with them).
119 swift 1.20 </p>
120 swift 1.14
121     <p>
122     I highly recommend reading the user-mode linux documentation, but the
123 drobbins 1.1 basic idea is that running the <path>/usr/local/bin/linux</path> program
124     boots the user-mode kernel and tries to bring up the system stored in
125     the file <path>root_fs</path> that should be located in the current working
126 swift 1.14 directory.
127     </p>
128    
129     <p>
130 nightmorph 1.26 It won't hurt to also install the user-mode Linux tools.
131 swift 1.14 </p>
132    
133     <pre caption="Installing UML tools">
134 drobbins 1.1 # <i>emerge sys-apps/usermode-utilities</i>
135     </pre>
136 swift 1.14
137     <p>
138     These tools facilitate networking (among other things) between the user-mode
139 nightmorph 1.26 Linux virtual system and the host Linux system.
140 swift 1.14 </p>
141    
142 drobbins 1.1 </body>
143     </section>
144     </chapter>
145    
146     <chapter>
147 cam 1.13 <title>Creating root_fs</title>
148 drobbins 1.1 <section>
149     <title>Making the Gentoo chroot</title>
150     <body>
151 swift 1.14
152 drobbins 1.1 <p>
153     The <path>root_fs</path> file needed for user-mode linux is
154     a single file that contains an entire Gentoo Linux filesystem.
155     To generate this file you will need to have Loopback device
156     support enabled in the host (non-user-mode) kernel.
157     </p>
158 swift 1.14
159     <p>
160     Generating the <path>root_fs</path> file itself will be
161 drobbins 1.1 our last step. First we will generate a Gentoo filesystem in
162 zhen 1.4 an ordinary chroot. We need the stage tarball available, which
163 rane 1.23 could be downloaded separately, extracted from an Installation CD, or
164     extracted from an Installation CD .iso.
165 drobbins 1.1 </p>
166 swift 1.14
167 rane 1.23 <pre caption="Mounting an Installation CD .iso">
168 drobbins 1.1 # <i>mkdir /mnt/loop</i>
169 swift 1.15 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
170 drobbins 1.1 </pre>
171 swift 1.14
172 drobbins 1.1 <p>
173     Setting up the chroot is essentially identical to an ordinary Gentoo
174     Linux build.
175     </p>
176 swift 1.14
177     <pre caption="Creating the Gentoo chroot mount">
178 drobbins 1.1 # <i>mkdir /mnt/gentoo</i>
179     # <i>cd /mnt/gentoo</i>
180 swift 1.15 # <i>tar xvjpf /path/to/stage&lt;TAB&gt;.tar.bz2</i>
181 drobbins 1.1 </pre>
182 swift 1.14
183 drobbins 1.1 <p>
184     Go ahead and unmount the .iso. You don't need it anymore.
185     </p>
186 swift 1.14
187 drobbins 1.1 <p>
188 swift 1.25 Build the system in the usual fashion: chroot into <path>/mnt/gentoo</path> and
189     follow the Gentoo installation instructions.
190 drobbins 1.1 </p>
191 swift 1.14
192 drobbins 1.1 <p>
193     Add any additional packages you desire. Feel free to give your virtual
194     Gentoo system a hostname, if you so desire. In <path>/etc/fstab</path>
195 swift 1.24 you will want <path>/dev/ROOT</path> to be <path>/dev/ubda</path>, with
196 drobbins 1.1 a fs type of either ext2, ext3, or reiserfs. Set <path>/dev/SWAP</path>
197 swift 1.24 to be <path>/dev/ubdb</path>, and comment out <path>/dev/BOOT</path>.
198 drobbins 1.1 </p>
199 swift 1.7
200 swift 1.14 <p>
201     At this point, remember to set your root password.
202     </p>
203 swift 1.7
204     <pre caption="Setting root password">
205     # <i>passwd</i>
206     </pre>
207    
208 drobbins 1.1 <p>
209 bennyc 1.21 Now we need to make some changes to the boot scripts. Remove consolefont and
210 swift 1.20 keymaps from the boot runlevel:
211     </p>
212    
213     <pre caption="Removing unneeded initscripts">
214 bennyc 1.21 # <i>rc-update del consolefont boot</i>
215 swift 1.20 # <i>rc-update del keymaps boot</i>
216     </pre>
217    
218     <p>
219 drobbins 1.1 Exit the chroot, unmount all of the bind mounts,
220 swift 1.16 tar up the new Gentoo distro, and clean up.
221 drobbins 1.1 </p>
222 swift 1.14
223     <pre caption="Finalising the installation">
224 zhen 1.5 # <i>cd /mnt/gentoo</i>
225 drobbins 1.1 # <i>tar cvjpf ~/gentoo.tbz2 *</i>
226     # <i>cd</i>
227     # <i>rm -rf /mnt/gentoo</i>
228 zhen 1.5 </pre>
229    
230 drobbins 1.1 </body>
231     </section>
232     <section>
233 cam 1.13 <title>Making root_fs</title>
234 drobbins 1.1 <body>
235 swift 1.14
236 drobbins 1.1 <p>
237     Our Gentoo chroot is nearly 300 MB in size, so
238     <path>root_fs</path> needs to be at least that size.
239     We'll choose 0.5 GB as a reasonable size.
240     </p>
241 swift 1.14
242     <pre caption="Creating UML files">
243 drobbins 1.1 # <i>dd if=/dev/zero of=root_fs seek=500 count=1 bs=1M</i>
244     # <i>mke2fs -F root_fs</i>
245     # <i>mount -o loop root_fs /mnt/loop</i>
246     # <i>tar xvjpf gentoo.tbz2 -C /mnt/loop</i>
247     # <i>umount /mnt/loop</i>
248     </pre>
249 swift 1.14
250 drobbins 1.1 <p>
251     It would also be nice to have a 0.5 GB swap partition.
252     </p>
253 swift 1.14
254     <pre caption="Create swap partition">
255 drobbins 1.1 # <i>dd if=/dev/zero of=swap_fs seek=500 count=1 bs=1M</i>
256     # <i>mkswap -f swap_fs</i>
257     </pre>
258 swift 1.14
259 drobbins 1.1 <p>
260     Now see if it works!
261     </p>
262 swift 1.14
263     <pre caption="Start UML kernel thread">
264 drobbins 1.1 # <i>linux ubd0=root_fs ubd1=swap_fs</i>
265     </pre>
266 swift 1.14
267 swift 1.20 <p>
268 nightmorph 1.26 User-mode Linux uses xterms for the virtual consoles that
269 drobbins 1.1 are run at boot time, so you need to make sure that the
270 nightmorph 1.26 terminal from which you run user-mode Linux has $DISPLAY
271 drobbins 1.1 properly set (along with proper xhost/xauth permissions).
272 swift 1.20 </p>
273 swift 1.14
274 drobbins 1.1 <p>
275 nightmorph 1.26 With any luck you should be able to log into your user-mode Linux
276     Gentoo system. The only thing keeping this user-mode Linux version
277 drobbins 1.1 of Gentoo from being fully functional is networking from the virtual
278 swift 1.6 machine to the host.
279 drobbins 1.1 </p>
280 swift 1.14
281 nightmorph 1.27 <note>
282     If you receive "No space left on device" errors, you may need to allocate more
283     memory to your user mode system by appending <c>mem=xxxMB</c> to the end of the
284     kernel thread line. For example: <c>linux ubd0=root_fs ubd1=swap_fs
285     mem=128MB</c>.
286     </note>
287    
288 drobbins 1.1 </body>
289     </section>
290     </chapter>
291    
292     <chapter>
293     <title>Networking</title>
294     <section>
295 swift 1.24 <title>Using an Existing Network</title>
296 drobbins 1.1 <body>
297 swift 1.14
298 drobbins 1.1 <p>
299 swift 1.20 Make sure that the host kernel has the following settings compiled as modules:
300     </p>
301    
302     <pre caption="Host kernel configuration">
303     Networking --&gt;
304     IP: Netfilter Configuration --&gt;
305     IP tables support --&gt;
306     Full NAT --&gt;
307     &lt;M&gt; MASQUERADE target support
308    
309     Network Device Support --&gt;
310     &lt;M&gt; TUN/TAP Support
311     </pre>
312    
313     <p>
314     Run the following commands on the <e>host</e> machine:
315 drobbins 1.1 </p>
316 swift 1.14
317     <pre caption="Setup networking">
318 swift 1.17 # <i>modprobe tun</i>
319 swift 1.20 <comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment>
320 drobbins 1.1 # <i>modprobe iptable_nat</i>
321     # <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i>
322 nightmorph 1.26 # <i>echo 1 &gt; /proc/sys/net/ipv4/ip_forward</i>
323 drobbins 1.1 </pre>
324 swift 1.14
325 drobbins 1.1 <p>
326     The iptables line sets up IP Masquerading between the private
327     network that our user-mode system will be on and the internet
328     (reachable via <c>eth0</c> in our case). The echo line then
329     turns on packet forwarding between the private network and the
330     interface that the default gateway is on (eth0 for us).
331     </p>
332 swift 1.14
333 drobbins 1.1 <p>
334     Now we bring up the user-mode system and see if networking
335     is functional.
336     </p>
337 swift 1.14
338     <pre caption="Get UML up and running">
339 swift 1.17 # <i>linux ubd0=root_fs ubd1=swap_fs eth0=tuntap,,,192.168.0.254</i>
340 drobbins 1.1 <comment>(login to user-mode system)</comment>
341     # <i>ifconfig eth0 192.168.0.1 up</i>
342     # <i>ping -c 2 192.168.0.254</i>
343     PING 192.168.0.254 (192.168.0.254): 56 octets data
344     64 octets from 192.168.0.254: icmp_seq=0 ttl=255 time=0.8 ms
345     64 octets from 192.168.0.254: icmp_seq=1 ttl=255 time=0.6 ms
346    
347     --- 192.168.0.254 ping statistics ---
348     2 packets transmitted, 2 packets received, 0% packet loss
349     round-trip min/avg/max = 0.6/0.7/0.8 ms
350 bennyc 1.9 # <i>route add default gw 192.168.0.254</i>
351     # <i>netstat -rn</i>
352 drobbins 1.1 Kernel IP routing table
353     Destination Gateway Genmask Flags MSS Window irtt Iface
354     192.168.0.0 0.0.0.0 255.255.255.0 U 40 0 0 eth0
355     0.0.0.0 192.168.0.254 0.0.0.0 UG 40 0 0 eth0
356 bennyc 1.9 # <i>scp user@192.168.0.254:/etc/resolv.conf /etc/resolv.conf</i> <comment>(if needed)</comment>
357     # <i>ping -c 2 www.gentoo.org</i>
358 drobbins 1.1 PING www.gentoo.org (207.170.82.202): 56 octets data
359     64 octets from 207.170.82.202: icmp_seq=0 ttl=240 time=119.6 ms
360     64 octets from 207.170.82.202: icmp_seq=1 ttl=240 time=92.0 ms
361    
362     --- www.gentoo.org ping statistics ---
363     2 packets transmitted, 2 packets received, 0% packet loss
364     round-trip min/avg/max = 92.0/105.8/119.6 ms
365     </pre>
366 swift 1.14
367 drobbins 1.1 <p>
368     On the user-mode system we assign the user-mode eth0 interface
369     the private IP address 192.168.0.1 and bring up the interface. The
370     host has private IP address 192.168.0.254, and we ping it to make sure
371     that our networking is, indeed, up. The route line adds a default
372     gateway, namely our host, we use scp to retrieve a working
373     <path>/etc/resolv.conf</path> (if necessary), and we ping www.gentoo.org
374     to make sure that name resolution (and general access to the internet)
375     is working from our user-mode system. Now the user-mode system can
376     <c>emerge</c> at will!
377     </p>
378 swift 1.14
379 drobbins 1.1 </body>
380     </section>
381 swift 1.24 <section>
382     <title>Using a Virtual Network</title>
383     <body>
384    
385     <p>
386     Before you get all too excited, this is not a virtual private network. It is a
387     network that is only accessible by the UML instances. The
388     <c>usermode-utilities</c> package provides a tool called <c>uml_switch</c> which
389     defines the end points of the switch.
390     </p>
391    
392     <pre caption="Activating end points of a UML switch">
393     <comment>(If the switch information should stay in the foreground:)</comment>
394     $ <i>uml_switch -unix ~/tmp/switch.sock</i>
395    
396     <comment>(If it should be backgrounded:)</comment>
397     $ <i>uml_switch -unix ~/tmp/switch.sock &amp;&gt; ~/tmp/switch.log &amp;</i>
398     </pre>
399    
400     <p>
401     To start the UML instances on the switch, run the next command. Your
402     (virtual) network interface will be connected to the <c>uml_switch</c> process
403     and will be using the given MAC address.
404     </p>
405    
406     <pre caption="Running first UML instance">
407     $ <i>linux ubd0=first_rootfs ubd1=first_swapfs eth0=daemon,10:00:01:02:00:00,,~/tmp/switch.sock</i>
408     </pre>
409    
410     <p>
411     You can still connect the system to the existing network, or have a second
412     process attached to both the virtual one and the existing one:
413     </p>
414    
415     <pre caption="Running second UML instance">
416     $ <i>linux ubd0=second_rootfs ubd1=second_swapfs eth0=daemon,10:00:01:02:00:01,,~/tmp/switch.sock \
417     eth1=tuntap,,,192.168.1.43</i>
418     </pre>
419    
420     <p>
421     More information about the tuntap setting can be found in the previous section.
422     </p>
423    
424     </body>
425     </section>
426 drobbins 1.1 </chapter>
427     <chapter>
428     <title>Testing the .iso</title>
429     <section>
430     <body>
431 swift 1.14
432 drobbins 1.1 <p>
433     Perhaps the true ideal of Gentoo Linux testing would be
434 nightmorph 1.26 to boot the .iso with user-mode Linux and do the complete
435     Gentoo install from within the user-mode Linux virtual system.
436 drobbins 1.1 </p>
437 swift 1.14
438 drobbins 1.1 <p>
439     Booting the .iso, or actually the initrd from the .iso, is pretty
440     straightforward.
441     </p>
442 swift 1.14
443     <pre caption="Booting the ISO">
444 swift 1.16 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
445     # <i>cp /mnt/loop/isolinux/gentoo.igz .</i>
446 drobbins 1.1 # <i>linux load_ramdisk=1 prompt_ramdisk=0 ramdisk_size=22000 \</i>
447     &gt; <i>initrd=rescue.gz root=/dev/ram0 ubd0=root_fs ubd1=swap_fs \</i>
448 swift 1.17 &gt; <i>ubd2=/dev/cdroms/cdrom0 eth0=tuntap,,,192.168.0.254</i>
449 drobbins 1.1 </pre>
450 swift 1.14
451     <p>
452     Now you can follow the Gentoo install doc essentially verbatim,
453 drobbins 1.1 although you'll need to know that the root filesystem will be
454     <path>/dev/ubd/0</path>, the swap "partition"
455     will be <path>/dev/ubd/1</path>, and the CD rom
456 swift 1.14 will be <path>/dev/ubd/2</path>.
457     </p>
458    
459 drobbins 1.1 </body>
460     </section>
461     </chapter>
462 swift 1.18
463     <chapter>
464     <title>Resources</title>
465     <section>
466     <body>
467    
468     <ul>
469     <li>
470     <uri link="http://edeca.net/articles/bridging/index.html">Bridging with
471     UML</uri>
472     </li>
473     <li>
474     <uri link="http://user-mode-linux.sourceforge.net/">UML Homepage</uri>
475     </li>
476     <li>
477     <uri link="http://www.theshore.net/~caker/uml/">Caker's UML Notes</uri>
478     </li>
479     <li>
480     <uri link="http://sourceforge.net/mailarchive/forum.php?forum_id=3647">UML
481     Mailinglist archives</uri>
482     </li>
483     </ul>
484    
485     </body>
486     </section>
487     </chapter>
488    
489 drobbins 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20