/[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.12 - (hide annotations) (download) (as text)
Fri Jan 16 08:21:57 2004 UTC (15 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.11: +7 -6 lines
File MIME type: application/xml
packages file doesnt necessarily contain the bootloader stuff, but some architectures still do

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

  ViewVC Help
Powered by ViewVC 1.1.20