/[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.32 - (hide annotations) (download) (as text)
Tue Jul 23 14:10:11 2013 UTC (5 years, 8 months ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.31: +5 -4 lines
File MIME type: application/xml
UML guide is now moved to wiki at https://wiki.gentoo.org/wiki/User-mode_Linux/System_testing_with_UML

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

  ViewVC Help
Powered by ViewVC 1.1.20