/[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.8 - (hide annotations) (download) (as text)
Tue Sep 30 08:48:56 2003 UTC (14 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.7: +4 -2 lines
File MIME type: application/xml
Add license information

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

  ViewVC Help
Powered by ViewVC 1.1.20