/[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.31
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.31 2011/09/04 17:53:40 swift 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>
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.16</version>
29<date>2005-02-05</date> 32<date>2008-03-01</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
66<warn> 87<warn>
67The <e>ARCH=um</e> fragment is <e>extremely</e> important! 88The <e>ARCH=um</e> fragment is <e>extremely</e> important!
68</warn> 89</warn>
69 90
70<p> 91<p>
71Make sure that <path>/usr/local/bin</path> is in your path. Edit 92On a default Gentoo system, <path>/usr/local/bin</path> is in your <c>$PATH</c>.
72<path>/etc/env.d/00basic</path> to that the PATH variable contains 93If it isn't, you should find a definition of <c>PATH</c> in the
73<path>/usr/local/bin</path> and rerun <c>env-update</c>: 94<path>/etc/profile</path> and fix it:
74</p>
75
76<pre caption="Editing 00basic">
77# <i>nano -w /etc/env.d/00basic</i>
78# <i>env-update</i>
79# <i>source /etc/profile</i>
80</pre>
81
82<p> 95</p>
96
97<pre caption="Verifying $PATH">
98$ <i>echo $PATH | grep /usr/local/bin</i>
99</pre>
100
101<pre caption="Sample definition of $PATH in /etc/profile">
102PATH="/usr/local/bin:/usr/bin:/bin:${PATH}"
103</pre>
104
105<p>
106Don't forget to run <c>source /etc/profile</c> for the change to take effect.
107</p>
108
109<p>
83For the user-mode linux kernel to properly boot a Gentoo system the 110For the user-mode Linux kernel to properly boot a Gentoo system the
84kernel needs to be configured to <e>not</e> automatically mount 111kernel needs to be configured to <e>not</e> automatically mount
85<path>/dev</path> (devfs) by default. Also, you will almost certainly 112<path>/dev</path> (devfs) by default. Also, you will almost certainly
86want to make sure that you have <e>tmpfs</e> (the "Virtual Memory 113want to make sure that you have <e>tmpfs</e> (the "Virtual Memory
87Filesystem") compiled in, since by default the Gentoo linux bootscripts 114Filesystem") compiled in, since by default the Gentoo Linux bootscripts
88store their information in a small tmpfs partition. 115store their information in a small tmpfs partition.
89(The binary kernels available from the user-mode website do automatically 116(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 117mount <path>/dev</path>, and they don't have tmpfs compiled in; don't bother
91with them). 118with them).
92</p> 119</p>
98the file <path>root_fs</path> that should be located in the current working 125the file <path>root_fs</path> that should be located in the current working
99directory. 126directory.
100</p> 127</p>
101 128
102<p> 129<p>
103It won't hurt to also install the user-mode linux tools. 130It won't hurt to also install the user-mode Linux tools.
104</p> 131</p>
105 132
106<pre caption="Installing UML tools"> 133<pre caption="Installing UML tools">
107# <i>emerge sys-apps/usermode-utilities</i> 134# <i>emerge sys-apps/usermode-utilities</i>
108</pre> 135</pre>
109 136
110<p> 137<p>
111These tools facilitate networking (among other things) between the user-mode 138These tools facilitate networking (among other things) between the user-mode
112linux virtual system and the host Linux system. 139Linux virtual system and the host Linux system.
113</p> 140</p>
114 141
115</body> 142</body>
116</section> 143</section>
117</chapter> 144</chapter>
131 158
132<p> 159<p>
133Generating the <path>root_fs</path> file itself will be 160Generating the <path>root_fs</path> file itself will be
134our last step. First we will generate a Gentoo filesystem in 161our last step. First we will generate a Gentoo filesystem in
135an ordinary chroot. We need the stage tarball available, which 162an ordinary chroot. We need the stage tarball available, which
136could be downloaded separately, extracted from a liveCD, or 163could be downloaded separately, extracted from an Installation CD, or
137extracted from a liveCD .iso. 164extracted from an Installation CD .iso.
138</p> 165</p>
139 166
140<pre caption="Mounting a liveCD .iso"> 167<pre caption="Mounting an Installation CD .iso">
141# <i>mkdir /mnt/loop</i> 168# <i>mkdir /mnt/loop</i>
142# <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i> 169# <i>mount -o loop /path/to/install-&lt;TAB&gt;.iso /mnt/loop</i>
143</pre> 170</pre>
144 171
145<p> 172<p>
156<p> 183<p>
157Go ahead and unmount the .iso. You don't need it anymore. 184Go ahead and unmount the .iso. You don't need it anymore.
158</p> 185</p>
159 186
160<p> 187<p>
161Bootstrap and build the system in the usual fashion. Just follow the 188Build the system in the usual fashion: chroot into <path>/mnt/gentoo</path> and
162installation instructions :) 189follow the Gentoo installation instructions.
163</p> 190</p>
164 191
165<p> 192<p>
166Add any additional packages you desire. Feel free to give your virtual 193Add any additional packages you desire. Feel free to give your virtual
167Gentoo system a hostname, if you so desire. In <path>/etc/fstab</path> 194Gentoo 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 195you 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> 196a 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>. 197to be <path>/dev/ubdb</path>, and comment out <path>/dev/BOOT</path>.
171</p> 198</p>
172 199
173<p> 200<p>
174At this point, remember to set your root password. 201At this point, remember to set your root password.
175</p> 202</p>
236<pre caption="Start UML kernel thread"> 263<pre caption="Start UML kernel thread">
237# <i>linux ubd0=root_fs ubd1=swap_fs</i> 264# <i>linux ubd0=root_fs ubd1=swap_fs</i>
238</pre> 265</pre>
239 266
240<p> 267<p>
241User-mode linux uses xterms for the virtual consoles that 268User-mode Linux uses xterms for the virtual consoles that
242are run at boot time, so you need to make sure that the 269are run at boot time, so you need to make sure that the
243terminal from which you run user-mode linux has $DISPLAY 270terminal from which you run user-mode Linux has $DISPLAY
244properly set (along with proper xhost/xauth permissions). 271properly set (along with proper xhost/xauth permissions).
245</p> 272</p>
246 273
247<p> 274<p>
248With any luck you should be able to log into your user-mode linux 275With any luck you should be able to log into your user-mode Linux
249Gentoo system. The only thing keeping this user-mode linux version 276Gentoo system. The only thing keeping this user-mode Linux version
250of Gentoo from being fully functional is networking from the virtual 277of Gentoo from being fully functional is networking from the virtual
251machine to the host. 278machine to the host.
252</p> 279</p>
253 280
281<note>
282If you receive "No space left on device" errors, you may need to allocate more
283memory to your user mode system by appending <c>mem=xxxMB</c> to the end of the
284kernel thread line. For example: <c>linux ubd0=root_fs ubd1=swap_fs
285mem=128MB</c>.
286</note>
287
254</body> 288</body>
255</section> 289</section>
256</chapter> 290</chapter>
257 291
258<chapter> 292<chapter>
259<title>Networking</title> 293<title>Networking</title>
260<section> 294<section>
295<title>Using an Existing Network</title>
261<body> 296<body>
262 297
263<p> 298<p>
264Make sure that the host kernel has the following settings compiled as modules: 299Make sure that the host kernel has the following settings compiled as modules:
265</p> 300</p>
282<pre caption="Setup networking"> 317<pre caption="Setup networking">
283# <i>modprobe tun</i> 318# <i>modprobe tun</i>
284<comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment> 319<comment>(If you receive a FATAL error here, try deleting /dev/net/tun and retry)</comment>
285# <i>modprobe iptable_nat</i> 320# <i>modprobe iptable_nat</i>
286# <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i> 321# <i>iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE</i>
287# <i>echo 1 > /proc/sys/net/ipv4/ip_forward</i> 322# <i>echo 1 &gt; /proc/sys/net/ipv4/ip_forward</i>
288</pre> 323</pre>
289 324
290<p> 325<p>
291The iptables line sets up IP Masquerading between the private 326The iptables line sets up IP Masquerading between the private
292network that our user-mode system will be on and the internet 327network that our user-mode system will be on and the internet
341<c>emerge</c> at will! 376<c>emerge</c> at will!
342</p> 377</p>
343 378
344</body> 379</body>
345</section> 380</section>
381<section>
382<title>Using a Virtual Network</title>
383<body>
384
385<p>
386Before you get all too excited, this is not a virtual private network. It is a
387network that is only accessible by the UML instances. The
388<c>usermode-utilities</c> package provides a tool called <c>uml_switch</c> which
389defines the end points of the switch.
390</p>
391
392<pre caption="Activating end points of a UML switch">
393<comment>(If the switch information should stay in the foreground:)</comment>
394$ <i>uml_switch -unix ~/tmp/switch.sock</i>
395
396<comment>(If it should be backgrounded:)</comment>
397$ <i>uml_switch -unix ~/tmp/switch.sock &amp;&gt; ~/tmp/switch.log &amp;</i>
398</pre>
399
400<p>
401To start the UML instances on the switch, run the next command. Your
402(virtual) network interface will be connected to the <c>uml_switch</c> process
403and will be using the given MAC address.
404</p>
405
406<pre caption="Running first UML instance">
407$ <i>linux ubd0=first_rootfs ubd1=first_swapfs eth0=daemon,10:00:01:02:00:00,,~/tmp/switch.sock</i>
408</pre>
409
410<p>
411You can still connect the system to the existing network, or have a second
412process attached to both the virtual one and the existing one:
413</p>
414
415<pre caption="Running second UML instance">
416$ <i>linux ubd0=second_rootfs ubd1=second_swapfs eth0=daemon,10:00:01:02:00:01,,~/tmp/switch.sock \
417 eth1=tuntap,,,192.168.1.43</i>
418</pre>
419
420<p>
421More information about the tuntap setting can be found in the previous section.
422</p>
423
424</body>
425</section>
346</chapter> 426</chapter>
347<chapter> 427<chapter>
348<title>Testing the .iso</title> 428<title>Testing the .iso</title>
349<section> 429<section>
350<body> 430<body>
351 431
352<p> 432<p>
353Perhaps the true ideal of Gentoo Linux testing would be 433Perhaps the true ideal of Gentoo Linux testing would be
354to boot the .iso with user-mode linux and do the complete 434to boot the .iso with user-mode Linux and do the complete
355Gentoo install from within the user-mode linux virtual system. 435Gentoo install from within the user-mode Linux virtual system.
356</p> 436</p>
357 437
358<p> 438<p>
359Booting the .iso, or actually the initrd from the .iso, is pretty 439Booting the .iso, or actually the initrd from the .iso, is pretty
360straightforward. 440straightforward.

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

  ViewVC Help
Powered by ViewVC 1.1.20