/[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.15 - (show annotations) (download) (as text)
Sun Apr 25 18:15:08 2004 UTC (14 years, 6 months ago) by swift
Branch: MAIN
Changes since 1.14: +17 -14 lines
File MIME type: application/xml
#47602 - Fix some UML issues

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

  ViewVC Help
Powered by ViewVC 1.1.20