/[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.7 - (show annotations) (download) (as text)
Sun Sep 7 10:32:23 2003 UTC (15 years, 6 months ago) by swift
Branch: MAIN
Changes since 1.6: +13 -9 lines
File MIME type: application/xml
Fix #28012

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

  ViewVC Help
Powered by ViewVC 1.1.20