/[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.9 - (hide annotations) (download) (as text)
Fri Oct 24 10:03:25 2003 UTC (14 years, 11 months ago) by bennyc
Branch: MAIN
Changes since 1.8: +8 -5 lines
File MIME type: application/xml
Bug: 31811

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

  ViewVC Help
Powered by ViewVC 1.1.20