/[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.21 - (show annotations) (download) (as text)
Fri Oct 22 09:34:38 2004 UTC (13 years, 3 months ago) by bennyc
Branch: MAIN
Changes since 1.20: +4 -4 lines
File MIME type: application/xml
fix typo, bug: 68513

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

  ViewVC Help
Powered by ViewVC 1.1.20