/[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.11 - (show annotations) (download) (as text)
Sat Nov 15 00:35:19 2003 UTC (15 years, 4 months ago) by neysx
Branch: MAIN
Changes since 1.10: +1 -0 lines
File MIME type: application/xml
Added $Header$ cvs tag -- NO CONTENT CHANGE

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

  ViewVC Help
Powered by ViewVC 1.1.20