/[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.21 - (hide annotations) (download) (as text)
Fri Oct 22 09:34:38 2004 UTC (14 years, 6 months ago) by bennyc
Branch: MAIN
Changes since 1.20: +4 -4 lines
File MIME type: application/xml
fix typo, bug: 68513

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

  ViewVC Help
Powered by ViewVC 1.1.20