/[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.14 - (show annotations) (download) (as text)
Sun Apr 25 18:09:45 2004 UTC (14 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.13: +97 -45 lines
File MIME type: application/xml
Apply Coding Style

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

  ViewVC Help
Powered by ViewVC 1.1.20