/[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.19 - (hide annotations) (download) (as text)
Tue Aug 31 07:38:46 2004 UTC (14 years, 6 months ago) by swift
Branch: MAIN
Changes since 1.18: +7 -7 lines
File MIME type: application/xml
#62217 - Move warning to correct location

1 zhen 1.3 <?xml version='1.0' encoding="UTF-8"?>
2 swift 1.19 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.18 2004/08/28 10:49:15 swift Exp $ -->
3 drobbins 1.1
4     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5    
6 zhen 1.2 <guide link="/doc/en/uml.xml">
7 drobbins 1.1 <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 swift 1.10 <author title="Editor"><!-- zhen@gentoo.org -->
10     John Davis
11     </author>
12 drobbins 1.1
13 swift 1.7 <author title="Editor">
14     <mail link="swift@gentoo.org">Sven Vermeulen</mail>
15     </author>
16 bennyc 1.9 <author title="Editor">
17     <mail link="bennyc@gentoo.org">Benny Chuang</mail>
18     </author>
19 swift 1.7
20 drobbins 1.1 <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 swift 1.8 <license/>
26    
27 swift 1.19 <version>0.8</version>
28     <date>August 31, 2004</date>
29 drobbins 1.1
30     <chapter>
31     <title>Obtaining User-Mode Linux</title>
32     <section>
33     <body>
34 swift 1.14
35     <p>
36     As the user-mode linux website
37     (<uri>http://user-mode-linux.sourceforge.net</uri>) states, user-mode linux
38 drobbins 1.1 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 swift 1.14 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 drobbins 1.1 </p>
47 swift 1.14
48 drobbins 1.1 <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 swift 1.14
55     <pre caption="Installing UML kernel sources">
56 drobbins 1.1 # <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 swift 1.14
63 swift 1.19 <warn>
64     The <e>ARCH=um</e> fragment is <e>extremely</e> important!
65     </warn>
66    
67 swift 1.15 <p>
68     Make sure that <path>/usr/local/bin</path> is in your path. Edit
69     <path>/etc/env.d/00basic</path> to that the PATH variable contains
70     <path>/usr/local/bin</path> and rerun <c>env-update</c>:
71     </p>
72    
73     <pre caption="Editing 00basic">
74     # <i>nano -w /etc/env.d/00basic</i>
75     # <i>env-update</i>
76     # <i>source /etc/profile</i>
77     </pre>
78    
79 drobbins 1.1 <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 swift 1.14 <path>/dev</path> (devfs) by default. Also, you will almost certainly
83 drobbins 1.1 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 swift 1.14 (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 drobbins 1.1 </impo>
90 swift 1.14
91     <p>
92     I highly recommend reading the user-mode linux documentation, but the
93 drobbins 1.1 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 swift 1.14 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 drobbins 1.1 # <i>emerge sys-apps/usermode-utilities</i>
105     </pre>
106 swift 1.14
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 drobbins 1.1 </body>
113     </section>
114     </chapter>
115    
116     <chapter>
117 cam 1.13 <title>Creating root_fs</title>
118 drobbins 1.1 <section>
119     <title>Making the Gentoo chroot</title>
120     <body>
121 swift 1.14
122 drobbins 1.1 <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 swift 1.14
129     <p>
130     Generating the <path>root_fs</path> file itself will be
131 drobbins 1.1 our last step. First we will generate a Gentoo filesystem in
132 zhen 1.4 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 drobbins 1.1 </p>
136 swift 1.14
137 zhen 1.4 <pre caption="Mounting a liveCD .iso">
138 drobbins 1.1 # <i>mkdir /mnt/loop</i>
139 swift 1.15 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
140 drobbins 1.1 </pre>
141 swift 1.14
142 drobbins 1.1 <p>
143     Setting up the chroot is essentially identical to an ordinary Gentoo
144     Linux build.
145     </p>
146 swift 1.14
147     <pre caption="Creating the Gentoo chroot mount">
148 drobbins 1.1 # <i>mkdir /mnt/gentoo</i>
149     # <i>cd /mnt/gentoo</i>
150 swift 1.15 # <i>tar xvjpf /path/to/stage&lt;TAB&gt;.tar.bz2</i>
151 drobbins 1.1 </pre>
152 swift 1.14
153 drobbins 1.1 <p>
154     Go ahead and unmount the .iso. You don't need it anymore.
155     </p>
156 swift 1.14
157 drobbins 1.1 <p>
158 swift 1.16 Bootstrap and build the system in the usual fashion. Just follow the
159     installation instructions :)
160 drobbins 1.1 </p>
161 swift 1.14
162 drobbins 1.1 <p>
163     Add any additional packages you desire. Feel free to give your virtual
164     Gentoo system a hostname, if you so desire. In <path>/etc/fstab</path>
165     you will want <path>/dev/ROOT</path> to be <path>/dev/ubd/0</path>, with
166     a fs type of either ext2, ext3, or reiserfs. Set <path>/dev/SWAP</path>
167     to be <path>/dev/ubd/1</path>, and comment out <path>/dev/BOOT</path>.
168     </p>
169 swift 1.7
170 swift 1.14 <p>
171     At this point, remember to set your root password.
172     </p>
173 swift 1.7
174     <pre caption="Setting root password">
175     # <i>passwd</i>
176     </pre>
177    
178 drobbins 1.1 <p>
179     Exit the chroot, unmount all of the bind mounts,
180 swift 1.16 tar up the new Gentoo distro, and clean up.
181 drobbins 1.1 </p>
182 swift 1.14
183     <pre caption="Finalising the installation">
184 zhen 1.5 # <i>cd /mnt/gentoo</i>
185 drobbins 1.1 # <i>tar cvjpf ~/gentoo.tbz2 *</i>
186     # <i>cd</i>
187     # <i>rm -rf /mnt/gentoo</i>
188 zhen 1.5 </pre>
189    
190 drobbins 1.1 </body>
191     </section>
192     <section>
193 cam 1.13 <title>Making root_fs</title>
194 drobbins 1.1 <body>
195 swift 1.14
196 drobbins 1.1 <p>
197     Our Gentoo chroot is nearly 300 MB in size, so
198     <path>root_fs</path> needs to be at least that size.
199     We'll choose 0.5 GB as a reasonable size.
200     </p>
201 swift 1.14
202     <pre caption="Creating UML files">
203 drobbins 1.1 # <i>dd if=/dev/zero of=root_fs seek=500 count=1 bs=1M</i>
204     # <i>mke2fs -F root_fs</i>
205     # <i>mount -o loop root_fs /mnt/loop</i>
206     # <i>tar xvjpf gentoo.tbz2 -C /mnt/loop</i>
207     # <i>umount /mnt/loop</i>
208     </pre>
209 swift 1.14
210 drobbins 1.1 <p>
211     It would also be nice to have a 0.5 GB swap partition.
212     </p>
213 swift 1.14
214     <pre caption="Create swap partition">
215 drobbins 1.1 # <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 swift 1.14
219 drobbins 1.1 <p>
220     Now see if it works!
221     </p>
222 swift 1.14
223     <pre caption="Start UML kernel thread">
224 drobbins 1.1 # <i>linux ubd0=root_fs ubd1=swap_fs</i>
225     </pre>
226 swift 1.14
227 drobbins 1.1 <note>
228     User-mode linux uses xterms for the virtual consoles that
229     are run at boot time, so you need to make sure that the
230     terminal from which you run user-mode linux has $DISPLAY
231     properly set (along with proper xhost/xauth permissions).
232     </note>
233 swift 1.14
234 drobbins 1.1 <p>
235     With any luck you should be able to log into your user-mode linux
236     Gentoo system. The only thing keeping this user-mode linux version
237     of Gentoo from being fully functional is networking from the virtual
238 swift 1.6 machine to the host.
239 drobbins 1.1 </p>
240 swift 1.14
241 drobbins 1.1 </body>
242     </section>
243     </chapter>
244    
245     <chapter>
246     <title>Networking</title>
247     <section>
248     <body>
249 swift 1.14
250 drobbins 1.1 <p>
251     Thanks to Martin Schlemmer (Azarah), I now know how
252     to get networking to function from within a user-mode
253     system. The idea is that we set up a private network
254     consisting of the user-mode system and the host system,
255     and then the user-mode system routes all of its packets
256     to the host, which then forwards packets to the net.
257     Make sure that the host kernel has
258     Networking --> IP: Netfilter Configuration --> IP tables support
259     --> Full NAT --> MASQUERADE target support and
260 swift 1.17 Network Device Support --> TUN/TAP Support
261 drobbins 1.1 compiled as modules; then do the following on the
262     <e>host</e> machine:
263     </p>
264 swift 1.14
265     <pre caption="Setup networking">
266 swift 1.17 # <i>modprobe tun</i>
267 drobbins 1.1 # <i>modprobe iptable_nat</i>
268     # <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i>
269     # <i>echo 1 > /proc/sys/net/ipv4/ip_forward</i>
270     </pre>
271 swift 1.14
272 drobbins 1.1 <p>
273     The iptables line sets up IP Masquerading between the private
274     network that our user-mode system will be on and the internet
275     (reachable via <c>eth0</c> in our case). The echo line then
276     turns on packet forwarding between the private network and the
277     interface that the default gateway is on (eth0 for us).
278     </p>
279 swift 1.14
280 drobbins 1.1 <p>
281     Now we bring up the user-mode system and see if networking
282     is functional.
283     </p>
284 swift 1.14
285     <pre caption="Get UML up and running">
286 swift 1.17 # <i>linux ubd0=root_fs ubd1=swap_fs eth0=tuntap,,,192.168.0.254</i>
287 drobbins 1.1 <comment>(login to user-mode system)</comment>
288     # <i>ifconfig eth0 192.168.0.1 up</i>
289     # <i>ping -c 2 192.168.0.254</i>
290     PING 192.168.0.254 (192.168.0.254): 56 octets data
291     64 octets from 192.168.0.254: icmp_seq=0 ttl=255 time=0.8 ms
292     64 octets from 192.168.0.254: icmp_seq=1 ttl=255 time=0.6 ms
293    
294     --- 192.168.0.254 ping statistics ---
295     2 packets transmitted, 2 packets received, 0% packet loss
296     round-trip min/avg/max = 0.6/0.7/0.8 ms
297 bennyc 1.9 # <i>route add default gw 192.168.0.254</i>
298     # <i>netstat -rn</i>
299 drobbins 1.1 Kernel IP routing table
300     Destination Gateway Genmask Flags MSS Window irtt Iface
301     192.168.0.0 0.0.0.0 255.255.255.0 U 40 0 0 eth0
302     0.0.0.0 192.168.0.254 0.0.0.0 UG 40 0 0 eth0
303 bennyc 1.9 # <i>scp user@192.168.0.254:/etc/resolv.conf /etc/resolv.conf</i> <comment>(if needed)</comment>
304     # <i>ping -c 2 www.gentoo.org</i>
305 drobbins 1.1 PING www.gentoo.org (207.170.82.202): 56 octets data
306     64 octets from 207.170.82.202: icmp_seq=0 ttl=240 time=119.6 ms
307     64 octets from 207.170.82.202: icmp_seq=1 ttl=240 time=92.0 ms
308    
309     --- www.gentoo.org ping statistics ---
310     2 packets transmitted, 2 packets received, 0% packet loss
311     round-trip min/avg/max = 92.0/105.8/119.6 ms
312     </pre>
313 swift 1.14
314 drobbins 1.1 <p>
315     On the user-mode system we assign the user-mode eth0 interface
316     the private IP address 192.168.0.1 and bring up the interface. The
317     host has private IP address 192.168.0.254, and we ping it to make sure
318     that our networking is, indeed, up. The route line adds a default
319     gateway, namely our host, we use scp to retrieve a working
320     <path>/etc/resolv.conf</path> (if necessary), and we ping www.gentoo.org
321     to make sure that name resolution (and general access to the internet)
322     is working from our user-mode system. Now the user-mode system can
323     <c>emerge</c> at will!
324     </p>
325 swift 1.14
326 drobbins 1.1 </body>
327     </section>
328     </chapter>
329     <chapter>
330     <title>Testing the .iso</title>
331     <section>
332     <body>
333 swift 1.14
334 drobbins 1.1 <p>
335     Perhaps the true ideal of Gentoo Linux testing would be
336     to boot the .iso with user-mode linux and do the complete
337     Gentoo install from within the user-mode linux virtual system.
338     </p>
339 swift 1.14
340 drobbins 1.1 <p>
341     Booting the .iso, or actually the initrd from the .iso, is pretty
342     straightforward.
343     </p>
344 swift 1.14
345     <pre caption="Booting the ISO">
346 swift 1.16 # <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
347     # <i>cp /mnt/loop/isolinux/gentoo.igz .</i>
348 drobbins 1.1 # <i>linux load_ramdisk=1 prompt_ramdisk=0 ramdisk_size=22000 \</i>
349     &gt; <i>initrd=rescue.gz root=/dev/ram0 ubd0=root_fs ubd1=swap_fs \</i>
350 swift 1.17 &gt; <i>ubd2=/dev/cdroms/cdrom0 eth0=tuntap,,,192.168.0.254</i>
351 drobbins 1.1 </pre>
352 swift 1.14
353     <p>
354     Now you can follow the Gentoo install doc essentially verbatim,
355 drobbins 1.1 although you'll need to know that the root filesystem will be
356     <path>/dev/ubd/0</path>, the swap "partition"
357     will be <path>/dev/ubd/1</path>, and the CD rom
358 swift 1.14 will be <path>/dev/ubd/2</path>.
359     </p>
360    
361 drobbins 1.1 </body>
362     </section>
363     </chapter>
364 swift 1.18
365     <chapter>
366     <title>Resources</title>
367     <section>
368     <body>
369    
370     <ul>
371     <li>
372     <uri link="http://edeca.net/articles/bridging/index.html">Bridging with
373     UML</uri>
374     </li>
375     <li>
376     <uri link="http://user-mode-linux.sourceforge.net/">UML Homepage</uri>
377     </li>
378     <li>
379     <uri link="http://www.theshore.net/~caker/uml/">Caker's UML Notes</uri>
380     </li>
381     <li>
382     <uri link="http://sourceforge.net/mailarchive/forum.php?forum_id=3647">UML
383     Mailinglist archives</uri>
384     </li>
385     </ul>
386    
387     </body>
388     </section>
389     </chapter>
390    
391 drobbins 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20