/[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.26 - (hide annotations) (download) (as text)
Mon Jun 26 16:16:58 2006 UTC (12 years, 9 months ago) by nightmorph
Branch: MAIN
Changes since 1.25: +25 -17 lines
File MIME type: application/xml
Updated UML guide for bug 137908

1 zhen 1.3 <?xml version='1.0' encoding="UTF-8"?>
2 nightmorph 1.26 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.25 2005/12/16 15:54:54 swift 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     <mail link="swift@gentoo.org">Sven Vermeulen</mail>
17     </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 nightmorph 1.26 <version>0.14</version>
32     <date>2006-06-26</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     Make sure that <path>/usr/local/bin</path> is in your path. Edit
93     <path>/etc/env.d/00basic</path> to that the PATH variable contains
94     <path>/usr/local/bin</path> and rerun <c>env-update</c>:
95     </p>
96    
97     <pre caption="Editing 00basic">
98     # <i>nano -w /etc/env.d/00basic</i>
99     # <i>env-update</i>
100     # <i>source /etc/profile</i>
101     </pre>
102    
103 swift 1.20 <p>
104 nightmorph 1.26 For the user-mode Linux kernel to properly boot a Gentoo system the
105 drobbins 1.1 kernel needs to be configured to <e>not</e> automatically mount
106 swift 1.14 <path>/dev</path> (devfs) by default. Also, you will almost certainly
107 drobbins 1.1 want to make sure that you have <e>tmpfs</e> (the "Virtual Memory
108 nightmorph 1.26 Filesystem") compiled in, since by default the Gentoo Linux bootscripts
109 drobbins 1.1 store their information in a small tmpfs partition.
110 swift 1.14 (The binary kernels available from the user-mode website do automatically
111     mount <path>/dev</path>, and they don't have tmpfs compiled in; don't bother
112     with them).
113 swift 1.20 </p>
114 swift 1.14
115     <p>
116     I highly recommend reading the user-mode linux documentation, but the
117 drobbins 1.1 basic idea is that running the <path>/usr/local/bin/linux</path> program
118     boots the user-mode kernel and tries to bring up the system stored in
119     the file <path>root_fs</path> that should be located in the current working
120 swift 1.14 directory.
121     </p>
122    
123     <p>
124 nightmorph 1.26 It won't hurt to also install the user-mode Linux tools.
125 swift 1.14 </p>
126    
127     <pre caption="Installing UML tools">
128 drobbins 1.1 # <i>emerge sys-apps/usermode-utilities</i>
129     </pre>
130 swift 1.14
131     <p>
132     These tools facilitate networking (among other things) between the user-mode
133 nightmorph 1.26 Linux virtual system and the host Linux system.
134 swift 1.14 </p>
135    
136 drobbins 1.1 </body>
137     </section>
138     </chapter>
139    
140     <chapter>
141 cam 1.13 <title>Creating root_fs</title>
142 drobbins 1.1 <section>
143     <title>Making the Gentoo chroot</title>
144     <body>
145 swift 1.14
146 drobbins 1.1 <p>
147     The <path>root_fs</path> file needed for user-mode linux is
148     a single file that contains an entire Gentoo Linux filesystem.
149     To generate this file you will need to have Loopback device
150     support enabled in the host (non-user-mode) kernel.
151     </p>
152 swift 1.14
153     <p>
154     Generating the <path>root_fs</path> file itself will be
155 drobbins 1.1 our last step. First we will generate a Gentoo filesystem in
156 zhen 1.4 an ordinary chroot. We need the stage tarball available, which
157 rane 1.23 could be downloaded separately, extracted from an Installation CD, or
158     extracted from an Installation CD .iso.
159 drobbins 1.1 </p>
160 swift 1.14
161 rane 1.23 <pre caption="Mounting an Installation CD .iso">
162 drobbins 1.1 # <i>mkdir /mnt/loop</i>
163 swift 1.15 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
164 drobbins 1.1 </pre>
165 swift 1.14
166 drobbins 1.1 <p>
167     Setting up the chroot is essentially identical to an ordinary Gentoo
168     Linux build.
169     </p>
170 swift 1.14
171     <pre caption="Creating the Gentoo chroot mount">
172 drobbins 1.1 # <i>mkdir /mnt/gentoo</i>
173     # <i>cd /mnt/gentoo</i>
174 swift 1.15 # <i>tar xvjpf /path/to/stage&lt;TAB&gt;.tar.bz2</i>
175 drobbins 1.1 </pre>
176 swift 1.14
177 drobbins 1.1 <p>
178     Go ahead and unmount the .iso. You don't need it anymore.
179     </p>
180 swift 1.14
181 drobbins 1.1 <p>
182 swift 1.25 Build the system in the usual fashion: chroot into <path>/mnt/gentoo</path> and
183     follow the Gentoo installation instructions.
184 drobbins 1.1 </p>
185 swift 1.14
186 drobbins 1.1 <p>
187     Add any additional packages you desire. Feel free to give your virtual
188     Gentoo system a hostname, if you so desire. In <path>/etc/fstab</path>
189 swift 1.24 you will want <path>/dev/ROOT</path> to be <path>/dev/ubda</path>, with
190 drobbins 1.1 a fs type of either ext2, ext3, or reiserfs. Set <path>/dev/SWAP</path>
191 swift 1.24 to be <path>/dev/ubdb</path>, and comment out <path>/dev/BOOT</path>.
192 drobbins 1.1 </p>
193 swift 1.7
194 swift 1.14 <p>
195     At this point, remember to set your root password.
196     </p>
197 swift 1.7
198     <pre caption="Setting root password">
199     # <i>passwd</i>
200     </pre>
201    
202 drobbins 1.1 <p>
203 bennyc 1.21 Now we need to make some changes to the boot scripts. Remove consolefont and
204 swift 1.20 keymaps from the boot runlevel:
205     </p>
206    
207     <pre caption="Removing unneeded initscripts">
208 bennyc 1.21 # <i>rc-update del consolefont boot</i>
209 swift 1.20 # <i>rc-update del keymaps boot</i>
210     </pre>
211    
212     <p>
213 drobbins 1.1 Exit the chroot, unmount all of the bind mounts,
214 swift 1.16 tar up the new Gentoo distro, and clean up.
215 drobbins 1.1 </p>
216 swift 1.14
217     <pre caption="Finalising the installation">
218 zhen 1.5 # <i>cd /mnt/gentoo</i>
219 drobbins 1.1 # <i>tar cvjpf ~/gentoo.tbz2 *</i>
220     # <i>cd</i>
221     # <i>rm -rf /mnt/gentoo</i>
222 zhen 1.5 </pre>
223    
224 drobbins 1.1 </body>
225     </section>
226     <section>
227 cam 1.13 <title>Making root_fs</title>
228 drobbins 1.1 <body>
229 swift 1.14
230 drobbins 1.1 <p>
231     Our Gentoo chroot is nearly 300 MB in size, so
232     <path>root_fs</path> needs to be at least that size.
233     We'll choose 0.5 GB as a reasonable size.
234     </p>
235 swift 1.14
236     <pre caption="Creating UML files">
237 drobbins 1.1 # <i>dd if=/dev/zero of=root_fs seek=500 count=1 bs=1M</i>
238     # <i>mke2fs -F root_fs</i>
239     # <i>mount -o loop root_fs /mnt/loop</i>
240     # <i>tar xvjpf gentoo.tbz2 -C /mnt/loop</i>
241     # <i>umount /mnt/loop</i>
242     </pre>
243 swift 1.14
244 drobbins 1.1 <p>
245     It would also be nice to have a 0.5 GB swap partition.
246     </p>
247 swift 1.14
248     <pre caption="Create swap partition">
249 drobbins 1.1 # <i>dd if=/dev/zero of=swap_fs seek=500 count=1 bs=1M</i>
250     # <i>mkswap -f swap_fs</i>
251     </pre>
252 swift 1.14
253 drobbins 1.1 <p>
254     Now see if it works!
255     </p>
256 swift 1.14
257     <pre caption="Start UML kernel thread">
258 drobbins 1.1 # <i>linux ubd0=root_fs ubd1=swap_fs</i>
259     </pre>
260 swift 1.14
261 swift 1.20 <p>
262 nightmorph 1.26 User-mode Linux uses xterms for the virtual consoles that
263 drobbins 1.1 are run at boot time, so you need to make sure that the
264 nightmorph 1.26 terminal from which you run user-mode Linux has $DISPLAY
265 drobbins 1.1 properly set (along with proper xhost/xauth permissions).
266 swift 1.20 </p>
267 swift 1.14
268 drobbins 1.1 <p>
269 nightmorph 1.26 With any luck you should be able to log into your user-mode Linux
270     Gentoo system. The only thing keeping this user-mode Linux version
271 drobbins 1.1 of Gentoo from being fully functional is networking from the virtual
272 swift 1.6 machine to the host.
273 drobbins 1.1 </p>
274 swift 1.14
275 drobbins 1.1 </body>
276     </section>
277     </chapter>
278    
279     <chapter>
280     <title>Networking</title>
281     <section>
282 swift 1.24 <title>Using an Existing Network</title>
283 drobbins 1.1 <body>
284 swift 1.14
285 drobbins 1.1 <p>
286 swift 1.20 Make sure that the host kernel has the following settings compiled as modules:
287     </p>
288    
289     <pre caption="Host kernel configuration">
290     Networking --&gt;
291     IP: Netfilter Configuration --&gt;
292     IP tables support --&gt;
293     Full NAT --&gt;
294     &lt;M&gt; MASQUERADE target support
295    
296     Network Device Support --&gt;
297     &lt;M&gt; TUN/TAP Support
298     </pre>
299    
300     <p>
301     Run the following commands on the <e>host</e> machine:
302 drobbins 1.1 </p>
303 swift 1.14
304     <pre caption="Setup networking">
305 swift 1.17 # <i>modprobe tun</i>
306 swift 1.20 <comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment>
307 drobbins 1.1 # <i>modprobe iptable_nat</i>
308     # <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i>
309 nightmorph 1.26 # <i>echo 1 &gt; /proc/sys/net/ipv4/ip_forward</i>
310 drobbins 1.1 </pre>
311 swift 1.14
312 drobbins 1.1 <p>
313     The iptables line sets up IP Masquerading between the private
314     network that our user-mode system will be on and the internet
315     (reachable via <c>eth0</c> in our case). The echo line then
316     turns on packet forwarding between the private network and the
317     interface that the default gateway is on (eth0 for us).
318     </p>
319 swift 1.14
320 drobbins 1.1 <p>
321     Now we bring up the user-mode system and see if networking
322     is functional.
323     </p>
324 swift 1.14
325     <pre caption="Get UML up and running">
326 swift 1.17 # <i>linux ubd0=root_fs ubd1=swap_fs eth0=tuntap,,,192.168.0.254</i>
327 drobbins 1.1 <comment>(login to user-mode system)</comment>
328     # <i>ifconfig eth0 192.168.0.1 up</i>
329     # <i>ping -c 2 192.168.0.254</i>
330     PING 192.168.0.254 (192.168.0.254): 56 octets data
331     64 octets from 192.168.0.254: icmp_seq=0 ttl=255 time=0.8 ms
332     64 octets from 192.168.0.254: icmp_seq=1 ttl=255 time=0.6 ms
333    
334     --- 192.168.0.254 ping statistics ---
335     2 packets transmitted, 2 packets received, 0% packet loss
336     round-trip min/avg/max = 0.6/0.7/0.8 ms
337 bennyc 1.9 # <i>route add default gw 192.168.0.254</i>
338     # <i>netstat -rn</i>
339 drobbins 1.1 Kernel IP routing table
340     Destination Gateway Genmask Flags MSS Window irtt Iface
341     192.168.0.0 0.0.0.0 255.255.255.0 U 40 0 0 eth0
342     0.0.0.0 192.168.0.254 0.0.0.0 UG 40 0 0 eth0
343 bennyc 1.9 # <i>scp user@192.168.0.254:/etc/resolv.conf /etc/resolv.conf</i> <comment>(if needed)</comment>
344     # <i>ping -c 2 www.gentoo.org</i>
345 drobbins 1.1 PING www.gentoo.org (207.170.82.202): 56 octets data
346     64 octets from 207.170.82.202: icmp_seq=0 ttl=240 time=119.6 ms
347     64 octets from 207.170.82.202: icmp_seq=1 ttl=240 time=92.0 ms
348    
349     --- www.gentoo.org ping statistics ---
350     2 packets transmitted, 2 packets received, 0% packet loss
351     round-trip min/avg/max = 92.0/105.8/119.6 ms
352     </pre>
353 swift 1.14
354 drobbins 1.1 <p>
355     On the user-mode system we assign the user-mode eth0 interface
356     the private IP address 192.168.0.1 and bring up the interface. The
357     host has private IP address 192.168.0.254, and we ping it to make sure
358     that our networking is, indeed, up. The route line adds a default
359     gateway, namely our host, we use scp to retrieve a working
360     <path>/etc/resolv.conf</path> (if necessary), and we ping www.gentoo.org
361     to make sure that name resolution (and general access to the internet)
362     is working from our user-mode system. Now the user-mode system can
363     <c>emerge</c> at will!
364     </p>
365 swift 1.14
366 drobbins 1.1 </body>
367     </section>
368 swift 1.24 <section>
369     <title>Using a Virtual Network</title>
370     <body>
371    
372     <p>
373     Before you get all too excited, this is not a virtual private network. It is a
374     network that is only accessible by the UML instances. The
375     <c>usermode-utilities</c> package provides a tool called <c>uml_switch</c> which
376     defines the end points of the switch.
377     </p>
378    
379     <pre caption="Activating end points of a UML switch">
380     <comment>(If the switch information should stay in the foreground:)</comment>
381     $ <i>uml_switch -unix ~/tmp/switch.sock</i>
382    
383     <comment>(If it should be backgrounded:)</comment>
384     $ <i>uml_switch -unix ~/tmp/switch.sock &amp;&gt; ~/tmp/switch.log &amp;</i>
385     </pre>
386    
387     <p>
388     To start the UML instances on the switch, run the next command. Your
389     (virtual) network interface will be connected to the <c>uml_switch</c> process
390     and will be using the given MAC address.
391     </p>
392    
393     <pre caption="Running first UML instance">
394     $ <i>linux ubd0=first_rootfs ubd1=first_swapfs eth0=daemon,10:00:01:02:00:00,,~/tmp/switch.sock</i>
395     </pre>
396    
397     <p>
398     You can still connect the system to the existing network, or have a second
399     process attached to both the virtual one and the existing one:
400     </p>
401    
402     <pre caption="Running second UML instance">
403     $ <i>linux ubd0=second_rootfs ubd1=second_swapfs eth0=daemon,10:00:01:02:00:01,,~/tmp/switch.sock \
404     eth1=tuntap,,,192.168.1.43</i>
405     </pre>
406    
407     <p>
408     More information about the tuntap setting can be found in the previous section.
409     </p>
410    
411     </body>
412     </section>
413 drobbins 1.1 </chapter>
414     <chapter>
415     <title>Testing the .iso</title>
416     <section>
417     <body>
418 swift 1.14
419 drobbins 1.1 <p>
420     Perhaps the true ideal of Gentoo Linux testing would be
421 nightmorph 1.26 to boot the .iso with user-mode Linux and do the complete
422     Gentoo install from within the user-mode Linux virtual system.
423 drobbins 1.1 </p>
424 swift 1.14
425 drobbins 1.1 <p>
426     Booting the .iso, or actually the initrd from the .iso, is pretty
427     straightforward.
428     </p>
429 swift 1.14
430     <pre caption="Booting the ISO">
431 swift 1.16 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
432     # <i>cp /mnt/loop/isolinux/gentoo.igz .</i>
433 drobbins 1.1 # <i>linux load_ramdisk=1 prompt_ramdisk=0 ramdisk_size=22000 \</i>
434     &gt; <i>initrd=rescue.gz root=/dev/ram0 ubd0=root_fs ubd1=swap_fs \</i>
435 swift 1.17 &gt; <i>ubd2=/dev/cdroms/cdrom0 eth0=tuntap,,,192.168.0.254</i>
436 drobbins 1.1 </pre>
437 swift 1.14
438     <p>
439     Now you can follow the Gentoo install doc essentially verbatim,
440 drobbins 1.1 although you'll need to know that the root filesystem will be
441     <path>/dev/ubd/0</path>, the swap "partition"
442     will be <path>/dev/ubd/1</path>, and the CD rom
443 swift 1.14 will be <path>/dev/ubd/2</path>.
444     </p>
445    
446 drobbins 1.1 </body>
447     </section>
448     </chapter>
449 swift 1.18
450     <chapter>
451     <title>Resources</title>
452     <section>
453     <body>
454    
455     <ul>
456     <li>
457     <uri link="http://edeca.net/articles/bridging/index.html">Bridging with
458     UML</uri>
459     </li>
460     <li>
461     <uri link="http://user-mode-linux.sourceforge.net/">UML Homepage</uri>
462     </li>
463     <li>
464     <uri link="http://www.theshore.net/~caker/uml/">Caker's UML Notes</uri>
465     </li>
466     <li>
467     <uri link="http://sourceforge.net/mailarchive/forum.php?forum_id=3647">UML
468     Mailinglist archives</uri>
469     </li>
470     </ul>
471    
472     </body>
473     </section>
474     </chapter>
475    
476 drobbins 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20