/[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.22 - (show annotations) (download) (as text)
Sat Feb 5 16:52:57 2005 UTC (13 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.21: +11 -9 lines
File MIME type: application/xml
#78477 - UML is integrated in development-sources

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

  ViewVC Help
Powered by ViewVC 1.1.20