/[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.24 - (hide annotations) (download) (as text)
Thu Nov 17 17:19:55 2005 UTC (13 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.23: +70 -14 lines
File MIME type: application/xml
#103026 and #110695 - Fix ubd, place sources elsewhere, plus additional information on networking

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

  ViewVC Help
Powered by ViewVC 1.1.20