/[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 - (hide 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 zhen 1.3 <?xml version='1.0' encoding="UTF-8"?>
2 swift 1.14 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.13 2004/04/11 10:52:16 cam 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.12 <version>0.3</version>
28     <date>January 16, 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     <warn>
64     The <e>ARCH=um</e> fragment is <e>extremely</e> important!
65     </warn>
66    
67 drobbins 1.1 <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 swift 1.14 <path>/dev</path> (devfs) by default. Also, you will almost certainly
71 drobbins 1.1 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 swift 1.14 (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 drobbins 1.1 </impo>
78 swift 1.14
79     <p>
80     I highly recommend reading the user-mode linux documentation, but the
81 drobbins 1.1 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 swift 1.14 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 drobbins 1.1 # <i>emerge sys-apps/usermode-utilities</i>
93     </pre>
94 swift 1.14
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 drobbins 1.1 </body>
101     </section>
102     </chapter>
103    
104     <chapter>
105 cam 1.13 <title>Creating root_fs</title>
106 drobbins 1.1 <section>
107     <title>Making the Gentoo chroot</title>
108     <body>
109 swift 1.14
110 drobbins 1.1 <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 swift 1.14
117     <p>
118     Generating the <path>root_fs</path> file itself will be
119 drobbins 1.1 our last step. First we will generate a Gentoo filesystem in
120 zhen 1.4 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 drobbins 1.1 </p>
124 swift 1.14
125 zhen 1.4 <pre caption="Mounting a liveCD .iso">
126 drobbins 1.1 # <i>mkdir /mnt/loop</i>
127     # <i>mount -o loop /path/to/build-&lt;TAB&gt;.iso /mnt/loop</i>
128     </pre>
129 swift 1.14
130 drobbins 1.1 <p>
131     Setting up the chroot is essentially identical to an ordinary Gentoo
132     Linux build.
133     </p>
134 swift 1.14
135     <pre caption="Creating the Gentoo chroot mount">
136 drobbins 1.1 # <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 swift 1.14
141 drobbins 1.1 <p>
142     Go ahead and unmount the .iso. You don't need it anymore.
143     </p>
144 swift 1.14
145     <pre caption="Prepare to install Gentoo">
146 drobbins 1.1 # <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 zhen 1.5 <!--per bug 16134, added emerge sync to supress warning, etc-->
154     # <i>emerge sync</i>
155 drobbins 1.1 # <i>env-update</i>
156     # <i>source /etc/profile</i>
157     </pre>
158 swift 1.14
159 drobbins 1.1 <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 swift 1.14
165 drobbins 1.1 <p>
166     Bootstrap and build the system in the usual fashion:
167     </p>
168 swift 1.14
169     <pre caption="Start the Gentoo installation">
170 zhen 1.5 <!--removed the emerge sync below because it is done above-->
171 drobbins 1.1 # <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 swift 1.14
178 drobbins 1.1 <warn>
179 zhen 1.5 <!--Changed grub to virtual/bootloader-->
180 drobbins 1.1 The <path>/etc/make.profile/packages</path> file needs to be
181 swift 1.12 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 drobbins 1.1 </warn>
186 swift 1.14
187 drobbins 1.1 <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 swift 1.14
197 drobbins 1.1 <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 swift 1.7
205 swift 1.14 <p>
206     At this point, remember to set your root password.
207     </p>
208 swift 1.7
209     <pre caption="Setting root password">
210     # <i>passwd</i>
211     </pre>
212    
213 drobbins 1.1 <p>
214     Exit the chroot, unmount all of the bind mounts,
215     tar up the new Gentoo distro, and clean up:
216     </p>
217 swift 1.14
218     <pre caption="Finalising the installation">
219 drobbins 1.1 # <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 zhen 1.5 <!-- wtf is this? 261744 /mnt/gentoo-->
225     <!-- added dir change to be more explicit-->
226     # <i>cd /mnt/gentoo</i>
227 drobbins 1.1 # <i>tar cvjpf ~/gentoo.tbz2 *</i>
228     # <i>cd</i>
229     # <i>rm -rf /mnt/gentoo</i>
230 zhen 1.5 </pre>
231    
232 swift 1.14 <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 drobbins 1.1 </body>
238     </section>
239     <section>
240 cam 1.13 <title>Making root_fs</title>
241 drobbins 1.1 <body>
242 swift 1.14
243 drobbins 1.1 <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 swift 1.14
249     <pre caption="Creating UML files">
250 drobbins 1.1 # <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 swift 1.14
257 drobbins 1.1 <p>
258     It would also be nice to have a 0.5 GB swap partition.
259     </p>
260 swift 1.14
261     <pre caption="Create swap partition">
262 drobbins 1.1 # <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 swift 1.14
266 drobbins 1.1 <p>
267     Now see if it works!
268     </p>
269 swift 1.14
270     <pre caption="Start UML kernel thread">
271 drobbins 1.1 # <i>linux ubd0=root_fs ubd1=swap_fs</i>
272     </pre>
273 swift 1.14
274 drobbins 1.1 <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 swift 1.14
281 drobbins 1.1 <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 swift 1.6 machine to the host.
286 drobbins 1.1 </p>
287 swift 1.14
288 drobbins 1.1 </body>
289     </section>
290     </chapter>
291    
292     <chapter>
293     <title>Networking</title>
294     <section>
295     <body>
296 swift 1.14
297 drobbins 1.1 <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 swift 1.14
312     <pre caption="Setup networking">
313 drobbins 1.1 # <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 swift 1.14
319 drobbins 1.1 <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 swift 1.14
327 drobbins 1.1 <p>
328     Now we bring up the user-mode system and see if networking
329     is functional.
330     </p>
331 swift 1.14
332     <pre caption="Get UML up and running">
333 drobbins 1.1 # <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 bennyc 1.9 # <i>route add default gw 192.168.0.254</i>
345     # <i>netstat -rn</i>
346 drobbins 1.1 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 bennyc 1.9 # <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 drobbins 1.1 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 swift 1.14
361 drobbins 1.1 <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 swift 1.14
373 drobbins 1.1 </body>
374     </section>
375     </chapter>
376     <chapter>
377     <title>Testing the .iso</title>
378     <section>
379     <body>
380 swift 1.14
381 drobbins 1.1 <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 swift 1.14
387 drobbins 1.1 <p>
388     Booting the .iso, or actually the initrd from the .iso, is pretty
389     straightforward.
390     </p>
391 swift 1.14
392     <pre caption="Booting the ISO">
393 drobbins 1.1 # <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 swift 1.14
400     <p>
401     Now you can follow the Gentoo install doc essentially verbatim,
402 drobbins 1.1 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 swift 1.14 will be <path>/dev/ubd/2</path>.
406     </p>
407    
408 drobbins 1.1 </body>
409     </section>
410     </chapter>
411     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20