/[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 - (show annotations) (download) (as text)
Tue Jul 23 14:10:11 2013 UTC (5 years 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 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.31 2011/09/04 17:53:40 swift Exp $ -->
3
4 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5
6 <guide disclaimer="obsolete" redirect="https://wiki.gentoo.org/wiki/User-mode_Linux/System_testing_with_UML">
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>1</version>
32 <!-- Last content edit: 2008-03-01 -->
33 <date>2013-07-23</date>
34
35 <chapter>
36 <title>Obtaining User-Mode Linux</title>
37 <section>
38 <body>
39
40 <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 <p>
49 As the user-mode Linux website
50 (<uri>http://user-mode-linux.sourceforge.net</uri>) states, user-modeL linux
51 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 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 unbootable; with user-mode Linux we can test these changes without having to
58 worry about breaking the live system.
59 </p>
60
61 <p>
62 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 </p>
68
69 <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 # <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
88 <warn>
89 The <e>ARCH=um</e> fragment is <e>extremely</e> important!
90 </warn>
91
92 <p>
93 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 </p>
97
98 <pre caption="Verifying $PATH">
99 $ <i>echo $PATH | grep /usr/local/bin</i>
100 </pre>
101
102 <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 <p>
111 For the user-mode Linux kernel to properly boot a Gentoo system the
112 kernel needs to be configured to <e>not</e> automatically mount
113 <path>/dev</path> (devfs) by default. Also, you will almost certainly
114 want to make sure that you have <e>tmpfs</e> (the "Virtual Memory
115 Filesystem") compiled in, since by default the Gentoo Linux bootscripts
116 store their information in a small tmpfs partition.
117 (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 </p>
121
122 <p>
123 I highly recommend reading the user-mode linux documentation, but the
124 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 directory.
128 </p>
129
130 <p>
131 It won't hurt to also install the user-mode Linux tools.
132 </p>
133
134 <pre caption="Installing UML tools">
135 # <i>emerge sys-apps/usermode-utilities</i>
136 </pre>
137
138 <p>
139 These tools facilitate networking (among other things) between the user-mode
140 Linux virtual system and the host Linux system.
141 </p>
142
143 </body>
144 </section>
145 </chapter>
146
147 <chapter>
148 <title>Creating root_fs</title>
149 <section>
150 <title>Making the Gentoo chroot</title>
151 <body>
152
153 <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
160 <p>
161 Generating the <path>root_fs</path> file itself will be
162 our last step. First we will generate a Gentoo filesystem in
163 an ordinary chroot. We need the stage tarball available, which
164 could be downloaded separately, extracted from an Installation CD, or
165 extracted from an Installation CD .iso.
166 </p>
167
168 <pre caption="Mounting an Installation CD .iso">
169 # <i>mkdir /mnt/loop</i>
170 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
171 </pre>
172
173 <p>
174 Setting up the chroot is essentially identical to an ordinary Gentoo
175 Linux build.
176 </p>
177
178 <pre caption="Creating the Gentoo chroot mount">
179 # <i>mkdir /mnt/gentoo</i>
180 # <i>cd /mnt/gentoo</i>
181 # <i>tar xvjpf /path/to/stage&lt;TAB&gt;.tar.bz2</i>
182 </pre>
183
184 <p>
185 Go ahead and unmount the .iso. You don't need it anymore.
186 </p>
187
188 <p>
189 Build the system in the usual fashion: chroot into <path>/mnt/gentoo</path> and
190 follow the Gentoo installation instructions.
191 </p>
192
193 <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 you will want <path>/dev/ROOT</path> to be <path>/dev/ubda</path>, with
197 a fs type of either ext2, ext3, or reiserfs. Set <path>/dev/SWAP</path>
198 to be <path>/dev/ubdb</path>, and comment out <path>/dev/BOOT</path>.
199 </p>
200
201 <p>
202 At this point, remember to set your root password.
203 </p>
204
205 <pre caption="Setting root password">
206 # <i>passwd</i>
207 </pre>
208
209 <p>
210 Now we need to make some changes to the boot scripts. Remove consolefont and
211 keymaps from the boot runlevel:
212 </p>
213
214 <pre caption="Removing unneeded initscripts">
215 # <i>rc-update del consolefont boot</i>
216 # <i>rc-update del keymaps boot</i>
217 </pre>
218
219 <p>
220 Exit the chroot, unmount all of the bind mounts,
221 tar up the new Gentoo distro, and clean up.
222 </p>
223
224 <pre caption="Finalising the installation">
225 # <i>cd /mnt/gentoo</i>
226 # <i>tar cvjpf ~/gentoo.tbz2 *</i>
227 # <i>cd</i>
228 # <i>rm -rf /mnt/gentoo</i>
229 </pre>
230
231 </body>
232 </section>
233 <section>
234 <title>Making root_fs</title>
235 <body>
236
237 <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
243 <pre caption="Creating UML files">
244 # <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
251 <p>
252 It would also be nice to have a 0.5 GB swap partition.
253 </p>
254
255 <pre caption="Create swap partition">
256 # <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
260 <p>
261 Now see if it works!
262 </p>
263
264 <pre caption="Start UML kernel thread">
265 # <i>linux ubd0=root_fs ubd1=swap_fs</i>
266 </pre>
267
268 <p>
269 User-mode Linux uses xterms for the virtual consoles that
270 are run at boot time, so you need to make sure that the
271 terminal from which you run user-mode Linux has $DISPLAY
272 properly set (along with proper xhost/xauth permissions).
273 </p>
274
275 <p>
276 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 of Gentoo from being fully functional is networking from the virtual
279 machine to the host.
280 </p>
281
282 <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 </body>
290 </section>
291 </chapter>
292
293 <chapter>
294 <title>Networking</title>
295 <section>
296 <title>Using an Existing Network</title>
297 <body>
298
299 <p>
300 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 </p>
317
318 <pre caption="Setup networking">
319 # <i>modprobe tun</i>
320 <comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment>
321 # <i>modprobe iptable_nat</i>
322 # <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i>
323 # <i>echo 1 &gt; /proc/sys/net/ipv4/ip_forward</i>
324 </pre>
325
326 <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
334 <p>
335 Now we bring up the user-mode system and see if networking
336 is functional.
337 </p>
338
339 <pre caption="Get UML up and running">
340 # <i>linux ubd0=root_fs ubd1=swap_fs eth0=tuntap,,,192.168.0.254</i>
341 <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 # <i>route add default gw 192.168.0.254</i>
352 # <i>netstat -rn</i>
353 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 # <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 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
368 <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
380 </body>
381 </section>
382 <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 </chapter>
428 <chapter>
429 <title>Testing the .iso</title>
430 <section>
431 <body>
432
433 <p>
434 Perhaps the true ideal of Gentoo Linux testing would be
435 to boot the .iso with user-mode Linux and do the complete
436 Gentoo install from within the user-mode Linux virtual system.
437 </p>
438
439 <p>
440 Booting the .iso, or actually the initrd from the .iso, is pretty
441 straightforward.
442 </p>
443
444 <pre caption="Booting the ISO">
445 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
446 # <i>cp /mnt/loop/isolinux/gentoo.igz .</i>
447 # <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 &gt; <i>ubd2=/dev/cdroms/cdrom0 eth0=tuntap,,,192.168.0.254</i>
450 </pre>
451
452 <p>
453 Now you can follow the Gentoo install doc essentially verbatim,
454 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 will be <path>/dev/ubd/2</path>.
458 </p>
459
460 </body>
461 </section>
462 </chapter>
463
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 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20