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

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.27 2006/11/17 21:07:40 nightmorph Exp $ -->
3
4 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5
6 <guide link="/doc/en/uml.xml">
7 <title>Gentoo Linux Developer's guide to system testing with User-Mode Linux</title>
8
9 <author title="Editor">
10 <mail link="g2boojum@gentoo.org">Grant Goodyear</mail>
11 </author>
12 <author title="Editor"><!-- zhen@gentoo.org -->
13 John Davis
14 </author>
15 <author title="Editor">
16 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
17 </author>
18 <author title="Editor">
19 <mail link="bennyc@gentoo.org">Benny Chuang</mail>
20 </author>
21
22 <abstract>
23 This guide shows Gentoo Linux developers how to set up and use
24 user-mode linux for testing potentially system-breaking changes.
25 </abstract>
26
27 <!-- The content of this document is licensed under the CC-BY-SA license -->
28 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
29 <license/>
30
31 <version>0.15</version>
32 <date>2006-11-17</date>
33
34 <chapter>
35 <title>Obtaining User-Mode Linux</title>
36 <section>
37 <body>
38
39 <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 <p>
48 As the user-mode Linux website
49 (<uri>http://user-mode-linux.sourceforge.net</uri>) states, user-modeL linux
50 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 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 unbootable; with user-mode Linux we can test these changes without having to
57 worry about breaking the live system.
58 </p>
59
60 <p>
61 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 </p>
67
68 <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 # <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
87 <warn>
88 The <e>ARCH=um</e> fragment is <e>extremely</e> important!
89 </warn>
90
91 <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 <p>
104 For the user-mode Linux kernel to properly boot a Gentoo system the
105 kernel needs to be configured to <e>not</e> automatically mount
106 <path>/dev</path> (devfs) by default. Also, you will almost certainly
107 want to make sure that you have <e>tmpfs</e> (the "Virtual Memory
108 Filesystem") compiled in, since by default the Gentoo Linux bootscripts
109 store their information in a small tmpfs partition.
110 (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 </p>
114
115 <p>
116 I highly recommend reading the user-mode linux documentation, but the
117 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 directory.
121 </p>
122
123 <p>
124 It won't hurt to also install the user-mode Linux tools.
125 </p>
126
127 <pre caption="Installing UML tools">
128 # <i>emerge sys-apps/usermode-utilities</i>
129 </pre>
130
131 <p>
132 These tools facilitate networking (among other things) between the user-mode
133 Linux virtual system and the host Linux system.
134 </p>
135
136 </body>
137 </section>
138 </chapter>
139
140 <chapter>
141 <title>Creating root_fs</title>
142 <section>
143 <title>Making the Gentoo chroot</title>
144 <body>
145
146 <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
153 <p>
154 Generating the <path>root_fs</path> file itself will be
155 our last step. First we will generate a Gentoo filesystem in
156 an ordinary chroot. We need the stage tarball available, which
157 could be downloaded separately, extracted from an Installation CD, or
158 extracted from an Installation CD .iso.
159 </p>
160
161 <pre caption="Mounting an Installation CD .iso">
162 # <i>mkdir /mnt/loop</i>
163 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
164 </pre>
165
166 <p>
167 Setting up the chroot is essentially identical to an ordinary Gentoo
168 Linux build.
169 </p>
170
171 <pre caption="Creating the Gentoo chroot mount">
172 # <i>mkdir /mnt/gentoo</i>
173 # <i>cd /mnt/gentoo</i>
174 # <i>tar xvjpf /path/to/stage&lt;TAB&gt;.tar.bz2</i>
175 </pre>
176
177 <p>
178 Go ahead and unmount the .iso. You don't need it anymore.
179 </p>
180
181 <p>
182 Build the system in the usual fashion: chroot into <path>/mnt/gentoo</path> and
183 follow the Gentoo installation instructions.
184 </p>
185
186 <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 you will want <path>/dev/ROOT</path> to be <path>/dev/ubda</path>, with
190 a fs type of either ext2, ext3, or reiserfs. Set <path>/dev/SWAP</path>
191 to be <path>/dev/ubdb</path>, and comment out <path>/dev/BOOT</path>.
192 </p>
193
194 <p>
195 At this point, remember to set your root password.
196 </p>
197
198 <pre caption="Setting root password">
199 # <i>passwd</i>
200 </pre>
201
202 <p>
203 Now we need to make some changes to the boot scripts. Remove consolefont and
204 keymaps from the boot runlevel:
205 </p>
206
207 <pre caption="Removing unneeded initscripts">
208 # <i>rc-update del consolefont boot</i>
209 # <i>rc-update del keymaps boot</i>
210 </pre>
211
212 <p>
213 Exit the chroot, unmount all of the bind mounts,
214 tar up the new Gentoo distro, and clean up.
215 </p>
216
217 <pre caption="Finalising the installation">
218 # <i>cd /mnt/gentoo</i>
219 # <i>tar cvjpf ~/gentoo.tbz2 *</i>
220 # <i>cd</i>
221 # <i>rm -rf /mnt/gentoo</i>
222 </pre>
223
224 </body>
225 </section>
226 <section>
227 <title>Making root_fs</title>
228 <body>
229
230 <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
236 <pre caption="Creating UML files">
237 # <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
244 <p>
245 It would also be nice to have a 0.5 GB swap partition.
246 </p>
247
248 <pre caption="Create swap partition">
249 # <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
253 <p>
254 Now see if it works!
255 </p>
256
257 <pre caption="Start UML kernel thread">
258 # <i>linux ubd0=root_fs ubd1=swap_fs</i>
259 </pre>
260
261 <p>
262 User-mode Linux uses xterms for the virtual consoles that
263 are run at boot time, so you need to make sure that the
264 terminal from which you run user-mode Linux has $DISPLAY
265 properly set (along with proper xhost/xauth permissions).
266 </p>
267
268 <p>
269 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 of Gentoo from being fully functional is networking from the virtual
272 machine to the host.
273 </p>
274
275 <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 </body>
283 </section>
284 </chapter>
285
286 <chapter>
287 <title>Networking</title>
288 <section>
289 <title>Using an Existing Network</title>
290 <body>
291
292 <p>
293 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 </p>
310
311 <pre caption="Setup networking">
312 # <i>modprobe tun</i>
313 <comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment>
314 # <i>modprobe iptable_nat</i>
315 # <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i>
316 # <i>echo 1 &gt; /proc/sys/net/ipv4/ip_forward</i>
317 </pre>
318
319 <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
327 <p>
328 Now we bring up the user-mode system and see if networking
329 is functional.
330 </p>
331
332 <pre caption="Get UML up and running">
333 # <i>linux ubd0=root_fs ubd1=swap_fs eth0=tuntap,,,192.168.0.254</i>
334 <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 # <i>route add default gw 192.168.0.254</i>
345 # <i>netstat -rn</i>
346 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 # <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 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
361 <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
373 </body>
374 </section>
375 <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 </chapter>
421 <chapter>
422 <title>Testing the .iso</title>
423 <section>
424 <body>
425
426 <p>
427 Perhaps the true ideal of Gentoo Linux testing would be
428 to boot the .iso with user-mode Linux and do the complete
429 Gentoo install from within the user-mode Linux virtual system.
430 </p>
431
432 <p>
433 Booting the .iso, or actually the initrd from the .iso, is pretty
434 straightforward.
435 </p>
436
437 <pre caption="Booting the ISO">
438 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
439 # <i>cp /mnt/loop/isolinux/gentoo.igz .</i>
440 # <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 &gt; <i>ubd2=/dev/cdroms/cdrom0 eth0=tuntap,,,192.168.0.254</i>
443 </pre>
444
445 <p>
446 Now you can follow the Gentoo install doc essentially verbatim,
447 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 will be <path>/dev/ubd/2</path>.
451 </p>
452
453 </body>
454 </section>
455 </chapter>
456
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 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20