/[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.25 - (show annotations) (download) (as text)
Fri Dec 16 15:54:54 2005 UTC (12 years, 1 month ago) by swift
Branch: MAIN
Changes since 1.24: +5 -5 lines
File MIME type: application/xml
Disambiguation of installation. A user reported that he went on by booting from the CD...

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.24 2005/11/17 17:19:55 swift 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.13</version>
32 <date>2005-12-16</date>
33
34 <chapter>
35 <title>Obtaining User-Mode Linux</title>
36 <section>
37 <body>
38
39 <p>
40 As the user-mode linux website
41 (<uri>http://user-mode-linux.sourceforge.net</uri>) states, user-mode linux
42 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 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 unbootable; with user-mode linux we can test these changes without having to
49 worry about breaking the live system.
50 </p>
51
52 <p>
53 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 </p>
59
60 <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 # <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
79 <warn>
80 The <e>ARCH=um</e> fragment is <e>extremely</e> important!
81 </warn>
82
83 <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 <p>
96 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 <path>/dev</path> (devfs) by default. Also, you will almost certainly
99 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 (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 </p>
106
107 <p>
108 I highly recommend reading the user-mode linux documentation, but the
109 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 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 # <i>emerge sys-apps/usermode-utilities</i>
121 </pre>
122
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 </body>
129 </section>
130 </chapter>
131
132 <chapter>
133 <title>Creating root_fs</title>
134 <section>
135 <title>Making the Gentoo chroot</title>
136 <body>
137
138 <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
145 <p>
146 Generating the <path>root_fs</path> file itself will be
147 our last step. First we will generate a Gentoo filesystem in
148 an ordinary chroot. We need the stage tarball available, which
149 could be downloaded separately, extracted from an Installation CD, or
150 extracted from an Installation CD .iso.
151 </p>
152
153 <pre caption="Mounting an Installation CD .iso">
154 # <i>mkdir /mnt/loop</i>
155 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
156 </pre>
157
158 <p>
159 Setting up the chroot is essentially identical to an ordinary Gentoo
160 Linux build.
161 </p>
162
163 <pre caption="Creating the Gentoo chroot mount">
164 # <i>mkdir /mnt/gentoo</i>
165 # <i>cd /mnt/gentoo</i>
166 # <i>tar xvjpf /path/to/stage&lt;TAB&gt;.tar.bz2</i>
167 </pre>
168
169 <p>
170 Go ahead and unmount the .iso. You don't need it anymore.
171 </p>
172
173 <p>
174 Build the system in the usual fashion: chroot into <path>/mnt/gentoo</path> and
175 follow the Gentoo installation instructions.
176 </p>
177
178 <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 you will want <path>/dev/ROOT</path> to be <path>/dev/ubda</path>, with
182 a fs type of either ext2, ext3, or reiserfs. Set <path>/dev/SWAP</path>
183 to be <path>/dev/ubdb</path>, and comment out <path>/dev/BOOT</path>.
184 </p>
185
186 <p>
187 At this point, remember to set your root password.
188 </p>
189
190 <pre caption="Setting root password">
191 # <i>passwd</i>
192 </pre>
193
194 <p>
195 Now we need to make some changes to the boot scripts. Remove consolefont and
196 keymaps from the boot runlevel:
197 </p>
198
199 <pre caption="Removing unneeded initscripts">
200 # <i>rc-update del consolefont boot</i>
201 # <i>rc-update del keymaps boot</i>
202 </pre>
203
204 <p>
205 Exit the chroot, unmount all of the bind mounts,
206 tar up the new Gentoo distro, and clean up.
207 </p>
208
209 <pre caption="Finalising the installation">
210 # <i>cd /mnt/gentoo</i>
211 # <i>tar cvjpf ~/gentoo.tbz2 *</i>
212 # <i>cd</i>
213 # <i>rm -rf /mnt/gentoo</i>
214 </pre>
215
216 </body>
217 </section>
218 <section>
219 <title>Making root_fs</title>
220 <body>
221
222 <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
228 <pre caption="Creating UML files">
229 # <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
236 <p>
237 It would also be nice to have a 0.5 GB swap partition.
238 </p>
239
240 <pre caption="Create swap partition">
241 # <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
245 <p>
246 Now see if it works!
247 </p>
248
249 <pre caption="Start UML kernel thread">
250 # <i>linux ubd0=root_fs ubd1=swap_fs</i>
251 </pre>
252
253 <p>
254 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 </p>
259
260 <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 machine to the host.
265 </p>
266
267 </body>
268 </section>
269 </chapter>
270
271 <chapter>
272 <title>Networking</title>
273 <section>
274 <title>Using an Existing Network</title>
275 <body>
276
277 <p>
278 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 </p>
295
296 <pre caption="Setup networking">
297 # <i>modprobe tun</i>
298 <comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment>
299 # <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
304 <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
312 <p>
313 Now we bring up the user-mode system and see if networking
314 is functional.
315 </p>
316
317 <pre caption="Get UML up and running">
318 # <i>linux ubd0=root_fs ubd1=swap_fs eth0=tuntap,,,192.168.0.254</i>
319 <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 # <i>route add default gw 192.168.0.254</i>
330 # <i>netstat -rn</i>
331 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 # <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 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
346 <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
358 </body>
359 </section>
360 <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 </chapter>
406 <chapter>
407 <title>Testing the .iso</title>
408 <section>
409 <body>
410
411 <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
417 <p>
418 Booting the .iso, or actually the initrd from the .iso, is pretty
419 straightforward.
420 </p>
421
422 <pre caption="Booting the ISO">
423 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
424 # <i>cp /mnt/loop/isolinux/gentoo.igz .</i>
425 # <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 &gt; <i>ubd2=/dev/cdroms/cdrom0 eth0=tuntap,,,192.168.0.254</i>
428 </pre>
429
430 <p>
431 Now you can follow the Gentoo install doc essentially verbatim,
432 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 will be <path>/dev/ubd/2</path>.
436 </p>
437
438 </body>
439 </section>
440 </chapter>
441
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 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20