/[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.22 Revision 1.27
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.22 2005/02/05 16:52:57 swift Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/uml.xml,v 1.27 2006/11/17 21:07:40 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
8<author title="Editor"> 9<author title="Editor">
9 <mail link="g2boojum@gentoo.org">Grant Goodyear</mail> 10 <mail link="g2boojum@gentoo.org">Grant Goodyear</mail>
10</author> 11</author>
11<author title="Editor"><!-- zhen@gentoo.org --> 12<author title="Editor"><!-- zhen@gentoo.org -->
12 John Davis 13 John Davis
21<abstract> 22<abstract>
22This guide shows Gentoo Linux developers how to set up and use 23This guide shows Gentoo Linux developers how to set up and use
23user-mode linux for testing potentially system-breaking changes. 24user-mode linux for testing potentially system-breaking changes.
24</abstract> 25</abstract>
25 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 -->
26<license/> 29<license/>
27 30
28<version>0.10</version> 31<version>0.15</version>
29<date>2005-02-05</date> 32<date>2006-11-17</date>
30 33
31<chapter> 34<chapter>
32<title>Obtaining User-Mode Linux</title> 35<title>Obtaining User-Mode Linux</title>
33<section> 36<section>
34<body> 37<body>
35 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
36<p> 47<p>
37As the user-mode linux website 48As the user-mode Linux website
38(<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
39allows a user to "run Linux inside itself". Specifically, 50allows a user to "run Linux inside itself". Specifically,
40user-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
41software, experiment with new Linux kernels or distributions, and poke around 52software, experiment with new Linux kernels or distributions, and poke around
42in the internals of Linux, all without risking your main Linux setup." 53in the internals of Linux, all without risking your main Linux setup."
43Experimental changes to Gentoo core packages such as <e>sys-apps/baselayout</e> 54Experimental changes to Gentoo core packages such as <e>sys-apps/baselayout</e>
44or <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
45unbootable; 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
46worry about breaking the live system. 57worry about breaking the live system.
47</p> 58</p>
48 59
49<p> 60<p>
50Installing user-mode linux is essentially identical to a normal kernel 61Most 2.6 kernels have UML support. Although you can use your current kernel
51install. First install the kernel sources (appropriately patched for 62sources, it might be wiser to keep the UML kernel tree(s) separate. After all,
52user-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
53usual fashion. Since kernel 2.6.9, UML has been integrated in the vanilla 64want to have heterogenous systems on your main Linux system (several different
54kernel. 65UML kernels).
66</p>
67
55</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>
56 73
57<pre caption="Installing UML kernel sources"> 74<p>
58<comment>(We'll install the vanilla 2.6 kernel, you can also use the usermode-sources)</comment> 75Next, configure this UML kernel as you would do for any other system, but append
59# <i>emerge sys-kernel/development-sources</i> 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">
60# <i>cd /usr/src/linux</i> 81# <i>cd /srv/aegis/src/uml-linux</i>
61# <i>make menuconfig <comment>ARCH=um</comment></i> 82# <i>make menuconfig <comment>ARCH=um</comment></i>
62# <i>make linux <comment>ARCH=um</comment></i> 83# <i>make linux <comment>ARCH=um</comment></i>
63# <i>cp linux /usr/local/bin/linux</i> 84# <i>cp linux /usr/local/bin/linux</i>
64</pre> 85</pre>
65 86
78# <i>env-update</i> 99# <i>env-update</i>
79# <i>source /etc/profile</i> 100# <i>source /etc/profile</i>
80</pre> 101</pre>
81 102
82<p> 103<p>
83For 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
84kernel needs to be configured to <e>not</e> automatically mount 105kernel needs to be configured to <e>not</e> automatically mount
85<path>/dev</path> (devfs) by default. Also, you will almost certainly 106<path>/dev</path> (devfs) by default. Also, you will almost certainly
86want 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
87Filesystem") compiled in, since by default the Gentoo linux bootscripts 108Filesystem") compiled in, since by default the Gentoo Linux bootscripts
88store their information in a small tmpfs partition. 109store their information in a small tmpfs partition.
89(The binary kernels available from the user-mode website do automatically 110(The binary kernels available from the user-mode website do automatically
90mount <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
91with them). 112with them).
92</p> 113</p>
98the 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
99directory. 120directory.
100</p> 121</p>
101 122
102<p> 123<p>
103It won't hurt to also install the user-mode linux tools. 124It won't hurt to also install the user-mode Linux tools.
104</p> 125</p>
105 126
106<pre caption="Installing UML tools"> 127<pre caption="Installing UML tools">
107# <i>emerge sys-apps/usermode-utilities</i> 128# <i>emerge sys-apps/usermode-utilities</i>
108</pre> 129</pre>
109 130
110<p> 131<p>
111These tools facilitate networking (among other things) between the user-mode 132These tools facilitate networking (among other things) between the user-mode
112linux virtual system and the host Linux system. 133Linux virtual system and the host Linux system.
113</p> 134</p>
114 135
115</body> 136</body>
116</section> 137</section>
117</chapter> 138</chapter>
131 152
132<p> 153<p>
133Generating the <path>root_fs</path> file itself will be 154Generating the <path>root_fs</path> file itself will be
134our last step. First we will generate a Gentoo filesystem in 155our last step. First we will generate a Gentoo filesystem in
135an ordinary chroot. We need the stage tarball available, which 156an ordinary chroot. We need the stage tarball available, which
136could be downloaded separately, extracted from a liveCD, or 157could be downloaded separately, extracted from an Installation CD, or
137extracted from a liveCD .iso. 158extracted from an Installation CD .iso.
138</p> 159</p>
139 160
140<pre caption="Mounting a liveCD .iso"> 161<pre caption="Mounting an Installation CD .iso">
141# <i>mkdir /mnt/loop</i> 162# <i>mkdir /mnt/loop</i>
142# <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>
143</pre> 164</pre>
144 165
145<p> 166<p>
156<p> 177<p>
157Go ahead and unmount the .iso. You don't need it anymore. 178Go ahead and unmount the .iso. You don't need it anymore.
158</p> 179</p>
159 180
160<p> 181<p>
161Bootstrap 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
162installation instructions :) 183follow the Gentoo installation instructions.
163</p> 184</p>
164 185
165<p> 186<p>
166Add any additional packages you desire. Feel free to give your virtual 187Add any additional packages you desire. Feel free to give your virtual
167Gentoo 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>
168you 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
169a 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>
170to 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>.
171</p> 192</p>
172 193
173<p> 194<p>
174At this point, remember to set your root password. 195At this point, remember to set your root password.
175</p> 196</p>
236<pre caption="Start UML kernel thread"> 257<pre caption="Start UML kernel thread">
237# <i>linux ubd0=root_fs ubd1=swap_fs</i> 258# <i>linux ubd0=root_fs ubd1=swap_fs</i>
238</pre> 259</pre>
239 260
240<p> 261<p>
241User-mode linux uses xterms for the virtual consoles that 262User-mode Linux uses xterms for the virtual consoles that
242are 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
243terminal from which you run user-mode linux has $DISPLAY 264terminal from which you run user-mode Linux has $DISPLAY
244properly set (along with proper xhost/xauth permissions). 265properly set (along with proper xhost/xauth permissions).
245</p> 266</p>
246 267
247<p> 268<p>
248With 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
249Gentoo system. The only thing keeping this user-mode linux version 270Gentoo system. The only thing keeping this user-mode Linux version
250of Gentoo from being fully functional is networking from the virtual 271of Gentoo from being fully functional is networking from the virtual
251machine to the host. 272machine to the host.
252</p> 273</p>
253 274
275<note>
276If you receive "No space left on device" errors, you may need to allocate more
277memory to your user mode system by appending <c>mem=xxxMB</c> to the end of the
278kernel thread line. For example: <c>linux ubd0=root_fs ubd1=swap_fs
279mem=128MB</c>.
280</note>
281
254</body> 282</body>
255</section> 283</section>
256</chapter> 284</chapter>
257 285
258<chapter> 286<chapter>
259<title>Networking</title> 287<title>Networking</title>
260<section> 288<section>
289<title>Using an Existing Network</title>
261<body> 290<body>
262 291
263<p> 292<p>
264Make sure that the host kernel has the following settings compiled as modules: 293Make sure that the host kernel has the following settings compiled as modules:
265</p> 294</p>
282<pre caption="Setup networking"> 311<pre caption="Setup networking">
283# <i>modprobe tun</i> 312# <i>modprobe tun</i>
284<comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment> 313<comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment>
285# <i>modprobe iptable_nat</i> 314# <i>modprobe iptable_nat</i>
286# <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i> 315# <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i>
287# <i>echo 1 > /proc/sys/net/ipv4/ip_forward</i> 316# <i>echo 1 &gt; /proc/sys/net/ipv4/ip_forward</i>
288</pre> 317</pre>
289 318
290<p> 319<p>
291The iptables line sets up IP Masquerading between the private 320The iptables line sets up IP Masquerading between the private
292network that our user-mode system will be on and the internet 321network that our user-mode system will be on and the internet
341<c>emerge</c> at will! 370<c>emerge</c> at will!
342</p> 371</p>
343 372
344</body> 373</body>
345</section> 374</section>
375<section>
376<title>Using a Virtual Network</title>
377<body>
378
379<p>
380Before you get all too excited, this is not a virtual private network. It is a
381network that is only accessible by the UML instances. The
382<c>usermode-utilities</c> package provides a tool called <c>uml_switch</c> which
383defines the end points of the switch.
384</p>
385
386<pre caption="Activating end points of a UML switch">
387<comment>(If the switch information should stay in the foreground:)</comment>
388$ <i>uml_switch -unix ~/tmp/switch.sock</i>
389
390<comment>(If it should be backgrounded:)</comment>
391$ <i>uml_switch -unix ~/tmp/switch.sock &amp;&gt; ~/tmp/switch.log &amp;</i>
392</pre>
393
394<p>
395To start the UML instances on the switch, run the next command. Your
396(virtual) network interface will be connected to the <c>uml_switch</c> process
397and will be using the given MAC address.
398</p>
399
400<pre caption="Running first UML instance">
401$ <i>linux ubd0=first_rootfs ubd1=first_swapfs eth0=daemon,10:00:01:02:00:00,,~/tmp/switch.sock</i>
402</pre>
403
404<p>
405You can still connect the system to the existing network, or have a second
406process attached to both the virtual one and the existing one:
407</p>
408
409<pre caption="Running second UML instance">
410$ <i>linux ubd0=second_rootfs ubd1=second_swapfs eth0=daemon,10:00:01:02:00:01,,~/tmp/switch.sock \
411 eth1=tuntap,,,192.168.1.43</i>
412</pre>
413
414<p>
415More information about the tuntap setting can be found in the previous section.
416</p>
417
418</body>
419</section>
346</chapter> 420</chapter>
347<chapter> 421<chapter>
348<title>Testing the .iso</title> 422<title>Testing the .iso</title>
349<section> 423<section>
350<body> 424<body>
351 425
352<p> 426<p>
353Perhaps the true ideal of Gentoo Linux testing would be 427Perhaps the true ideal of Gentoo Linux testing would be
354to boot the .iso with user-mode linux and do the complete 428to boot the .iso with user-mode Linux and do the complete
355Gentoo install from within the user-mode linux virtual system. 429Gentoo install from within the user-mode Linux virtual system.
356</p> 430</p>
357 431
358<p> 432<p>
359Booting the .iso, or actually the initrd from the .iso, is pretty 433Booting the .iso, or actually the initrd from the .iso, is pretty
360straightforward. 434straightforward.

Legend:
Removed from v.1.22  
changed lines
  Added in v.1.27

  ViewVC Help
Powered by ViewVC 1.1.20