/[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.30 - (show annotations) (download) (as text)
Sat Mar 1 19:24:22 2008 UTC (11 years ago) by jkt
Branch: MAIN
Changes since 1.29: +16 -10 lines
File MIME type: application/xml
#211997, /etc/env.d/00basic belongs to baselayout and shouldn't be touched

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

  ViewVC Help
Powered by ViewVC 1.1.20