/[gentoo]/xml/htdocs/doc/en/uml.xml
Gentoo

Diff of /xml/htdocs/doc/en/uml.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.19 Revision 1.26
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.19 2004/08/31 07:38:46 swift Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.26 2006/06/26 16:16:58 nightmorph Exp $ -->
3 3
4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 5
6<guide link="/doc/en/uml.xml"> 6<guide link="/doc/en/uml.xml">
7<title>Gentoo Linux Developer's guide to system testing with User-Mode Linux</title> 7<title>Gentoo Linux Developer's guide to system testing with User-Mode Linux</title>
8
9<author title="Editor">
8<author title="Editor"><mail link="g2boojum@gentoo.org">Grant Goodyear</mail></author> 10 <mail link="g2boojum@gentoo.org">Grant Goodyear</mail>
11</author>
9<author title="Editor"><!-- zhen@gentoo.org --> 12<author title="Editor"><!-- zhen@gentoo.org -->
10 John Davis 13 John Davis
11</author> 14</author>
12
13<author title="Editor"> 15<author title="Editor">
14 <mail link="swift@gentoo.org">Sven Vermeulen</mail> 16 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
15</author> 17</author>
16<author title="Editor"> 18<author title="Editor">
17 <mail link="bennyc@gentoo.org">Benny Chuang</mail> 19 <mail link="bennyc@gentoo.org">Benny Chuang</mail>
18</author> 20</author>
19 21
20<abstract> 22<abstract>
21 This guide shows Gentoo Linux developers how to set up and use 23This guide shows Gentoo Linux developers how to set up and use
22 user-mode linux for testing potentially system-breaking changes. 24user-mode linux for testing potentially system-breaking changes.
23</abstract> 25</abstract>
24 26
27<!-- The content of this document is licensed under the CC-BY-SA license -->
28<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
25<license/> 29<license/>
26 30
27<version>0.8</version> 31<version>0.14</version>
28<date>August 31, 2004</date> 32<date>2006-06-26</date>
29 33
30<chapter> 34<chapter>
31<title>Obtaining User-Mode Linux</title> 35<title>Obtaining User-Mode Linux</title>
32<section> 36<section>
33<body> 37<body>
34 38
39<impo>
40Before you can use user-mode Linux, you <e>must</e> be using a non-NPTL
41profile, and you must be using &lt;<c>glibc</c>-2.4. Follow the instructions
42for <uri link="/doc/en/gentoo-upgrading.xml#instructions">changing
43profiles</uri>. You will need to run <c>emerge -e world</c> after switching to
44a non-NPTL profile.
45</impo>
46
35<p> 47<p>
36As the user-mode linux website 48As the user-mode Linux website
37(<uri>http://user-mode-linux.sourceforge.net</uri>) states, user-mode linux 49(<uri>http://user-mode-linux.sourceforge.net</uri>) states, user-modeL linux
38allows a user to "run Linux inside itself". Specifically, 50allows a user to "run Linux inside itself". Specifically,
39user-mode linux provides a virtual machine on which a user can "[r]un buggy 51user-mode linux provides a virtual machine on which a user can "[r]un buggy
40software, experiment with new Linux kernels or distributions, and poke around 52software, experiment with new Linux kernels or distributions, and poke around
41in the internals of Linux, all without risking your main Linux setup." Changes 53in the internals of Linux, all without risking your main Linux setup."
42to Gentoo core packages such as <e>sys-apps/baselayout</e> or 54Experimental changes to Gentoo core packages such as <e>sys-apps/baselayout</e>
43<e>sys-libs/glibc</e> have the potential to break the system and render it 55or <e>sys-libs/glibc</e> have the potential to break the system and render it
44unbootable; with user-mode linux we can test these changes without having to 56unbootable; with user-mode Linux we can test these changes without having to
45worry about breaking the live system. 57worry about breaking the live system.
46</p> 58</p>
47 59
48<p> 60<p>
49Installing user-mode linux is essentially identical to a normal kernel 61Most 2.6 kernels have UML support. Although you can use your current kernel
50install. First install the kernel sources (appropriately patched for 62sources, it might be wiser to keep the UML kernel tree(s) separate. After all,
51user-mode linux), and then configure the user-mode linux kernel in the 63you'll be building a new kernel with a different configuration and you might
52usual fashion: 64want to have heterogenous systems on your main Linux system (several different
65UML kernels).
66</p>
67
53</p> 68<p>
69So download a nice kernel tree (like the vanilla one from <uri
70link="http://www.kernel.org">kernel.org</uri>) and extract it to some local
71development location.
72</p>
54 73
55<pre caption="Installing UML kernel sources"> 74<p>
56# <i>emerge sys-kernel/usermode-sources</i> 75Next, configure this UML kernel as you would do for any other system, but append
76<e>ARCH=um</e> so that the kernel build software knows that the kernel
77is meant to run as a guest process on the main system.
78</p>
79
80<pre caption="Building the UML kernel">
57# <i>cd /usr/src/uml/linux</i> 81# <i>cd /srv/aegis/src/uml-linux</i>
58# <i>make menuconfig <comment>ARCH=um</comment></i> 82# <i>make menuconfig <comment>ARCH=um</comment></i>
59# <i>make linux <comment>ARCH=um</comment></i> 83# <i>make linux <comment>ARCH=um</comment></i>
60# <i>cp linux /usr/local/bin/linux</i> 84# <i>cp linux /usr/local/bin/linux</i>
61</pre> 85</pre>
62 86
74# <i>nano -w /etc/env.d/00basic</i> 98# <i>nano -w /etc/env.d/00basic</i>
75# <i>env-update</i> 99# <i>env-update</i>
76# <i>source /etc/profile</i> 100# <i>source /etc/profile</i>
77</pre> 101</pre>
78 102
79<impo> 103<p>
80For the user-mode linux kernel to properly boot a Gentoo system the 104For the user-mode Linux kernel to properly boot a Gentoo system the
81kernel needs to be configured to <e>not</e> automatically mount 105kernel needs to be configured to <e>not</e> automatically mount
82<path>/dev</path> (devfs) by default. Also, you will almost certainly 106<path>/dev</path> (devfs) by default. Also, you will almost certainly
83want to make sure that you have <e>tmpfs</e> (the "Virtual Memory 107want to make sure that you have <e>tmpfs</e> (the "Virtual Memory
84Filesystem") compiled in, since by default the Gentoo linux bootscripts 108Filesystem") compiled in, since by default the Gentoo Linux bootscripts
85store their information in a small tmpfs partition. 109store their information in a small tmpfs partition.
86(The binary kernels available from the user-mode website do automatically 110(The binary kernels available from the user-mode website do automatically
87mount <path>/dev</path>, and they don't have tmpfs compiled in; don't bother 111mount <path>/dev</path>, and they don't have tmpfs compiled in; don't bother
88with them). 112with them).
89</impo> 113</p>
90 114
91<p> 115<p>
92I highly recommend reading the user-mode linux documentation, but the 116I highly recommend reading the user-mode linux documentation, but the
93basic idea is that running the <path>/usr/local/bin/linux</path> program 117basic idea is that running the <path>/usr/local/bin/linux</path> program
94boots the user-mode kernel and tries to bring up the system stored in 118boots the user-mode kernel and tries to bring up the system stored in
95the file <path>root_fs</path> that should be located in the current working 119the file <path>root_fs</path> that should be located in the current working
96directory. 120directory.
97</p> 121</p>
98 122
99<p> 123<p>
100It won't hurt to also install the user-mode linux tools. 124It won't hurt to also install the user-mode Linux tools.
101</p> 125</p>
102 126
103<pre caption="Installing UML tools"> 127<pre caption="Installing UML tools">
104# <i>emerge sys-apps/usermode-utilities</i> 128# <i>emerge sys-apps/usermode-utilities</i>
105</pre> 129</pre>
106 130
107<p> 131<p>
108These tools facilitate networking (among other things) between the user-mode 132These tools facilitate networking (among other things) between the user-mode
109linux virtual system and the host Linux system. 133Linux virtual system and the host Linux system.
110</p> 134</p>
111 135
112</body> 136</body>
113</section> 137</section>
114</chapter> 138</chapter>
128 152
129<p> 153<p>
130Generating the <path>root_fs</path> file itself will be 154Generating the <path>root_fs</path> file itself will be
131our last step. First we will generate a Gentoo filesystem in 155our last step. First we will generate a Gentoo filesystem in
132an ordinary chroot. We need the stage tarball available, which 156an ordinary chroot. We need the stage tarball available, which
133could be downloaded separately, extracted from a liveCD, or 157could be downloaded separately, extracted from an Installation CD, or
134extracted from a liveCD .iso. 158extracted from an Installation CD .iso.
135</p> 159</p>
136 160
137<pre caption="Mounting a liveCD .iso"> 161<pre caption="Mounting an Installation CD .iso">
138# <i>mkdir /mnt/loop</i> 162# <i>mkdir /mnt/loop</i>
139# <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i> 163# <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
140</pre> 164</pre>
141 165
142<p> 166<p>
153<p> 177<p>
154Go ahead and unmount the .iso. You don't need it anymore. 178Go ahead and unmount the .iso. You don't need it anymore.
155</p> 179</p>
156 180
157<p> 181<p>
158Bootstrap and build the system in the usual fashion. Just follow the 182Build the system in the usual fashion: chroot into <path>/mnt/gentoo</path> and
159installation instructions :) 183follow the Gentoo installation instructions.
160</p> 184</p>
161 185
162<p> 186<p>
163Add any additional packages you desire. Feel free to give your virtual 187Add any additional packages you desire. Feel free to give your virtual
164Gentoo system a hostname, if you so desire. In <path>/etc/fstab</path> 188Gentoo system a hostname, if you so desire. In <path>/etc/fstab</path>
165you will want <path>/dev/ROOT</path> to be <path>/dev/ubd/0</path>, with 189you will want <path>/dev/ROOT</path> to be <path>/dev/ubda</path>, with
166a fs type of either ext2, ext3, or reiserfs. Set <path>/dev/SWAP</path> 190a fs type of either ext2, ext3, or reiserfs. Set <path>/dev/SWAP</path>
167to be <path>/dev/ubd/1</path>, and comment out <path>/dev/BOOT</path>. 191to be <path>/dev/ubdb</path>, and comment out <path>/dev/BOOT</path>.
168</p> 192</p>
169 193
170<p> 194<p>
171At this point, remember to set your root password. 195At this point, remember to set your root password.
172</p> 196</p>
173 197
174<pre caption="Setting root password"> 198<pre caption="Setting root password">
175# <i>passwd</i> 199# <i>passwd</i>
200</pre>
201
202<p>
203Now we need to make some changes to the boot scripts. Remove consolefont and
204keymaps from the boot runlevel:
205</p>
206
207<pre caption="Removing unneeded initscripts">
208# <i>rc-update del consolefont boot</i>
209# <i>rc-update del keymaps boot</i>
176</pre> 210</pre>
177 211
178<p> 212<p>
179Exit the chroot, unmount all of the bind mounts, 213Exit the chroot, unmount all of the bind mounts,
180tar up the new Gentoo distro, and clean up. 214tar up the new Gentoo distro, and clean up.
222 256
223<pre caption="Start UML kernel thread"> 257<pre caption="Start UML kernel thread">
224# <i>linux ubd0=root_fs ubd1=swap_fs</i> 258# <i>linux ubd0=root_fs ubd1=swap_fs</i>
225</pre> 259</pre>
226 260
227<note> 261<p>
228User-mode linux uses xterms for the virtual consoles that 262User-mode Linux uses xterms for the virtual consoles that
229are run at boot time, so you need to make sure that the 263are run at boot time, so you need to make sure that the
230terminal from which you run user-mode linux has $DISPLAY 264terminal from which you run user-mode Linux has $DISPLAY
231properly set (along with proper xhost/xauth permissions). 265properly set (along with proper xhost/xauth permissions).
232</note>
233
234<p> 266</p>
267
268<p>
235With any luck you should be able to log into your user-mode linux 269With any luck you should be able to log into your user-mode Linux
236Gentoo system. The only thing keeping this user-mode linux version 270Gentoo system. The only thing keeping this user-mode Linux version
237of Gentoo from being fully functional is networking from the virtual 271of Gentoo from being fully functional is networking from the virtual
238machine to the host. 272machine to the host.
239</p> 273</p>
240 274
241</body> 275</body>
243</chapter> 277</chapter>
244 278
245<chapter> 279<chapter>
246<title>Networking</title> 280<title>Networking</title>
247<section> 281<section>
282<title>Using an Existing Network</title>
248<body> 283<body>
249 284
285<p>
286Make sure that the host kernel has the following settings compiled as modules:
250<p> 287</p>
251Thanks to Martin Schlemmer (Azarah), I now know how 288
252to get networking to function from within a user-mode 289<pre caption="Host kernel configuration">
253system. The idea is that we set up a private network 290Networking --&gt;
254consisting of the user-mode system and the host system, 291 IP: Netfilter Configuration --&gt;
255and then the user-mode system routes all of its packets 292 IP tables support --&gt;
256to the host, which then forwards packets to the net. 293 Full NAT --&gt;
257Make sure that the host kernel has 294 &lt;M&gt; MASQUERADE target support
258Networking --> IP: Netfilter Configuration --> IP tables support 295
259--> Full NAT --> MASQUERADE target support and 296 Network Device Support --&gt;
260Network Device Support --> TUN/TAP Support 297 &lt;M&gt; TUN/TAP Support
261compiled as modules; then do the following on the 298</pre>
262<e>host</e> machine: 299
300<p>
301Run the following commands on the <e>host</e> machine:
263</p> 302</p>
264 303
265<pre caption="Setup networking"> 304<pre caption="Setup networking">
266# <i>modprobe tun</i> 305# <i>modprobe tun</i>
306<comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment>
267# <i>modprobe iptable_nat</i> 307# <i>modprobe iptable_nat</i>
268# <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i> 308# <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i>
269# <i>echo 1 > /proc/sys/net/ipv4/ip_forward</i> 309# <i>echo 1 &gt; /proc/sys/net/ipv4/ip_forward</i>
270</pre> 310</pre>
271 311
272<p> 312<p>
273The iptables line sets up IP Masquerading between the private 313The iptables line sets up IP Masquerading between the private
274network that our user-mode system will be on and the internet 314network that our user-mode system will be on and the internet
323<c>emerge</c> at will! 363<c>emerge</c> at will!
324</p> 364</p>
325 365
326</body> 366</body>
327</section> 367</section>
368<section>
369<title>Using a Virtual Network</title>
370<body>
371
372<p>
373Before you get all too excited, this is not a virtual private network. It is a
374network that is only accessible by the UML instances. The
375<c>usermode-utilities</c> package provides a tool called <c>uml_switch</c> which
376defines the end points of the switch.
377</p>
378
379<pre caption="Activating end points of a UML switch">
380<comment>(If the switch information should stay in the foreground:)</comment>
381$ <i>uml_switch -unix ~/tmp/switch.sock</i>
382
383<comment>(If it should be backgrounded:)</comment>
384$ <i>uml_switch -unix ~/tmp/switch.sock &amp;&gt; ~/tmp/switch.log &amp;</i>
385</pre>
386
387<p>
388To start the UML instances on the switch, run the next command. Your
389(virtual) network interface will be connected to the <c>uml_switch</c> process
390and will be using the given MAC address.
391</p>
392
393<pre caption="Running first UML instance">
394$ <i>linux ubd0=first_rootfs ubd1=first_swapfs eth0=daemon,10:00:01:02:00:00,,~/tmp/switch.sock</i>
395</pre>
396
397<p>
398You can still connect the system to the existing network, or have a second
399process attached to both the virtual one and the existing one:
400</p>
401
402<pre caption="Running second UML instance">
403$ <i>linux ubd0=second_rootfs ubd1=second_swapfs eth0=daemon,10:00:01:02:00:01,,~/tmp/switch.sock \
404 eth1=tuntap,,,192.168.1.43</i>
405</pre>
406
407<p>
408More information about the tuntap setting can be found in the previous section.
409</p>
410
411</body>
412</section>
328</chapter> 413</chapter>
329<chapter> 414<chapter>
330<title>Testing the .iso</title> 415<title>Testing the .iso</title>
331<section> 416<section>
332<body> 417<body>
333 418
334<p> 419<p>
335Perhaps the true ideal of Gentoo Linux testing would be 420Perhaps the true ideal of Gentoo Linux testing would be
336to boot the .iso with user-mode linux and do the complete 421to boot the .iso with user-mode Linux and do the complete
337Gentoo install from within the user-mode linux virtual system. 422Gentoo install from within the user-mode Linux virtual system.
338</p> 423</p>
339 424
340<p> 425<p>
341Booting the .iso, or actually the initrd from the .iso, is pretty 426Booting the .iso, or actually the initrd from the .iso, is pretty
342straightforward. 427straightforward.

Legend:
Removed from v.1.19  
changed lines
  Added in v.1.26

  ViewVC Help
Powered by ViewVC 1.1.20