/[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.29 - (hide annotations) (download) (as text)
Wed Nov 29 15:48:57 2006 UTC (12 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.28: +3 -3 lines
File MIME type: application/xml
revert previous change

1 zhen 1.3 <?xml version='1.0' encoding="UTF-8"?>
2 nightmorph 1.28 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.27 2006/11/17 21:07:40 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 nightmorph 1.29 <version>0.15</version>
32     <date>2006-11-17</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 nightmorph 1.27 <note>
276     If you receive "No space left on device" errors, you may need to allocate more
277     memory to your user mode system by appending <c>mem=xxxMB</c> to the end of the
278     kernel thread line. For example: <c>linux ubd0=root_fs ubd1=swap_fs
279     mem=128MB</c>.
280     </note>
281    
282 drobbins 1.1 </body>
283     </section>
284     </chapter>
285    
286     <chapter>
287     <title>Networking</title>
288     <section>
289 swift 1.24 <title>Using an Existing Network</title>
290 drobbins 1.1 <body>
291 swift 1.14
292 drobbins 1.1 <p>
293 swift 1.20 Make sure that the host kernel has the following settings compiled as modules:
294     </p>
295    
296     <pre caption="Host kernel configuration">
297     Networking --&gt;
298     IP: Netfilter Configuration --&gt;
299     IP tables support --&gt;
300     Full NAT --&gt;
301     &lt;M&gt; MASQUERADE target support
302    
303     Network Device Support --&gt;
304     &lt;M&gt; TUN/TAP Support
305     </pre>
306    
307     <p>
308     Run the following commands on the <e>host</e> machine:
309 drobbins 1.1 </p>
310 swift 1.14
311     <pre caption="Setup networking">
312 swift 1.17 # <i>modprobe tun</i>
313 swift 1.20 <comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment>
314 drobbins 1.1 # <i>modprobe iptable_nat</i>
315     # <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i>
316 nightmorph 1.26 # <i>echo 1 &gt; /proc/sys/net/ipv4/ip_forward</i>
317 drobbins 1.1 </pre>
318 swift 1.14
319 drobbins 1.1 <p>
320     The iptables line sets up IP Masquerading between the private
321     network that our user-mode system will be on and the internet
322     (reachable via <c>eth0</c> in our case). The echo line then
323     turns on packet forwarding between the private network and the
324     interface that the default gateway is on (eth0 for us).
325     </p>
326 swift 1.14
327 drobbins 1.1 <p>
328     Now we bring up the user-mode system and see if networking
329     is functional.
330     </p>
331 swift 1.14
332     <pre caption="Get UML up and running">
333 swift 1.17 # <i>linux ubd0=root_fs ubd1=swap_fs eth0=tuntap,,,192.168.0.254</i>
334 drobbins 1.1 <comment>(login to user-mode system)</comment>
335     # <i>ifconfig eth0 192.168.0.1 up</i>
336     # <i>ping -c 2 192.168.0.254</i>
337     PING 192.168.0.254 (192.168.0.254): 56 octets data
338     64 octets from 192.168.0.254: icmp_seq=0 ttl=255 time=0.8 ms
339     64 octets from 192.168.0.254: icmp_seq=1 ttl=255 time=0.6 ms
340    
341     --- 192.168.0.254 ping statistics ---
342     2 packets transmitted, 2 packets received, 0% packet loss
343     round-trip min/avg/max = 0.6/0.7/0.8 ms
344 bennyc 1.9 # <i>route add default gw 192.168.0.254</i>
345     # <i>netstat -rn</i>
346 drobbins 1.1 Kernel IP routing table
347     Destination Gateway Genmask Flags MSS Window irtt Iface
348     192.168.0.0 0.0.0.0 255.255.255.0 U 40 0 0 eth0
349     0.0.0.0 192.168.0.254 0.0.0.0 UG 40 0 0 eth0
350 bennyc 1.9 # <i>scp user@192.168.0.254:/etc/resolv.conf /etc/resolv.conf</i> <comment>(if needed)</comment>
351     # <i>ping -c 2 www.gentoo.org</i>
352 drobbins 1.1 PING www.gentoo.org (207.170.82.202): 56 octets data
353     64 octets from 207.170.82.202: icmp_seq=0 ttl=240 time=119.6 ms
354     64 octets from 207.170.82.202: icmp_seq=1 ttl=240 time=92.0 ms
355    
356     --- www.gentoo.org ping statistics ---
357     2 packets transmitted, 2 packets received, 0% packet loss
358     round-trip min/avg/max = 92.0/105.8/119.6 ms
359     </pre>
360 swift 1.14
361 drobbins 1.1 <p>
362     On the user-mode system we assign the user-mode eth0 interface
363     the private IP address 192.168.0.1 and bring up the interface. The
364     host has private IP address 192.168.0.254, and we ping it to make sure
365     that our networking is, indeed, up. The route line adds a default
366     gateway, namely our host, we use scp to retrieve a working
367     <path>/etc/resolv.conf</path> (if necessary), and we ping www.gentoo.org
368     to make sure that name resolution (and general access to the internet)
369     is working from our user-mode system. Now the user-mode system can
370     <c>emerge</c> at will!
371     </p>
372 swift 1.14
373 drobbins 1.1 </body>
374     </section>
375 swift 1.24 <section>
376     <title>Using a Virtual Network</title>
377     <body>
378    
379     <p>
380     Before you get all too excited, this is not a virtual private network. It is a
381     network that is only accessible by the UML instances. The
382     <c>usermode-utilities</c> package provides a tool called <c>uml_switch</c> which
383     defines the end points of the switch.
384     </p>
385    
386     <pre caption="Activating end points of a UML switch">
387     <comment>(If the switch information should stay in the foreground:)</comment>
388     $ <i>uml_switch -unix ~/tmp/switch.sock</i>
389    
390     <comment>(If it should be backgrounded:)</comment>
391     $ <i>uml_switch -unix ~/tmp/switch.sock &amp;&gt; ~/tmp/switch.log &amp;</i>
392     </pre>
393    
394     <p>
395     To start the UML instances on the switch, run the next command. Your
396     (virtual) network interface will be connected to the <c>uml_switch</c> process
397     and will be using the given MAC address.
398     </p>
399    
400     <pre caption="Running first UML instance">
401     $ <i>linux ubd0=first_rootfs ubd1=first_swapfs eth0=daemon,10:00:01:02:00:00,,~/tmp/switch.sock</i>
402     </pre>
403    
404     <p>
405     You can still connect the system to the existing network, or have a second
406     process attached to both the virtual one and the existing one:
407     </p>
408    
409     <pre caption="Running second UML instance">
410     $ <i>linux ubd0=second_rootfs ubd1=second_swapfs eth0=daemon,10:00:01:02:00:01,,~/tmp/switch.sock \
411     eth1=tuntap,,,192.168.1.43</i>
412     </pre>
413    
414     <p>
415     More information about the tuntap setting can be found in the previous section.
416     </p>
417    
418     </body>
419     </section>
420 drobbins 1.1 </chapter>
421     <chapter>
422     <title>Testing the .iso</title>
423     <section>
424     <body>
425 swift 1.14
426 drobbins 1.1 <p>
427     Perhaps the true ideal of Gentoo Linux testing would be
428 nightmorph 1.26 to boot the .iso with user-mode Linux and do the complete
429     Gentoo install from within the user-mode Linux virtual system.
430 drobbins 1.1 </p>
431 swift 1.14
432 drobbins 1.1 <p>
433     Booting the .iso, or actually the initrd from the .iso, is pretty
434     straightforward.
435     </p>
436 swift 1.14
437     <pre caption="Booting the ISO">
438 swift 1.16 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
439     # <i>cp /mnt/loop/isolinux/gentoo.igz .</i>
440 drobbins 1.1 # <i>linux load_ramdisk=1 prompt_ramdisk=0 ramdisk_size=22000 \</i>
441     &gt; <i>initrd=rescue.gz root=/dev/ram0 ubd0=root_fs ubd1=swap_fs \</i>
442 swift 1.17 &gt; <i>ubd2=/dev/cdroms/cdrom0 eth0=tuntap,,,192.168.0.254</i>
443 drobbins 1.1 </pre>
444 swift 1.14
445     <p>
446     Now you can follow the Gentoo install doc essentially verbatim,
447 drobbins 1.1 although you'll need to know that the root filesystem will be
448     <path>/dev/ubd/0</path>, the swap "partition"
449     will be <path>/dev/ubd/1</path>, and the CD rom
450 swift 1.14 will be <path>/dev/ubd/2</path>.
451     </p>
452    
453 drobbins 1.1 </body>
454     </section>
455     </chapter>
456 swift 1.18
457     <chapter>
458     <title>Resources</title>
459     <section>
460     <body>
461    
462     <ul>
463     <li>
464     <uri link="http://edeca.net/articles/bridging/index.html">Bridging with
465     UML</uri>
466     </li>
467     <li>
468     <uri link="http://user-mode-linux.sourceforge.net/">UML Homepage</uri>
469     </li>
470     <li>
471     <uri link="http://www.theshore.net/~caker/uml/">Caker's UML Notes</uri>
472     </li>
473     <li>
474     <uri link="http://sourceforge.net/mailarchive/forum.php?forum_id=3647">UML
475     Mailinglist archives</uri>
476     </li>
477     </ul>
478    
479     </body>
480     </section>
481     </chapter>
482    
483 drobbins 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20