/[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.10 - (hide annotations) (download) (as text)
Sat Oct 25 08:50:41 2003 UTC (15 years, 5 months ago) by swift
Branch: MAIN
Changes since 1.9: +3 -1 lines
File MIME type: application/xml
ZhEN asked to have his e-mail address removed from all docs

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

  ViewVC Help
Powered by ViewVC 1.1.20