PageRenderTime 66ms CodeModel.GetById 28ms RepoModel.GetById 0ms app.codeStats 1ms

/Documentation/uml/UserModeLinux-HOWTO.txt

https://bitbucket.org/abioy/linux
Plain Text | 4636 lines | 2289 code | 2347 blank | 0 comment | 0 complexity | eb1de3d2f6397647dd467d54a9b0b0a8 MD5 | raw file
Possible License(s): CC-BY-SA-3.0, GPL-2.0, LGPL-2.0, AGPL-1.0

Large files files are truncated, but you can click here to view the full file

  1. User Mode Linux HOWTO
  2. User Mode Linux Core Team
  3. Mon Nov 18 14:16:16 EST 2002
  4. This document describes the use and abuse of Jeff Dike's User Mode
  5. Linux: a port of the Linux kernel as a normal Intel Linux process.
  6. ______________________________________________________________________
  7. Table of Contents
  8. 1. Introduction
  9. 1.1 How is User Mode Linux Different?
  10. 1.2 Why Would I Want User Mode Linux?
  11. 2. Compiling the kernel and modules
  12. 2.1 Compiling the kernel
  13. 2.2 Compiling and installing kernel modules
  14. 2.3 Compiling and installing uml_utilities
  15. 3. Running UML and logging in
  16. 3.1 Running UML
  17. 3.2 Logging in
  18. 3.3 Examples
  19. 4. UML on 2G/2G hosts
  20. 4.1 Introduction
  21. 4.2 The problem
  22. 4.3 The solution
  23. 5. Setting up serial lines and consoles
  24. 5.1 Specifying the device
  25. 5.2 Specifying the channel
  26. 5.3 Examples
  27. 6. Setting up the network
  28. 6.1 General setup
  29. 6.2 Userspace daemons
  30. 6.3 Specifying ethernet addresses
  31. 6.4 UML interface setup
  32. 6.5 Multicast
  33. 6.6 TUN/TAP with the uml_net helper
  34. 6.7 TUN/TAP with a preconfigured tap device
  35. 6.8 Ethertap
  36. 6.9 The switch daemon
  37. 6.10 Slip
  38. 6.11 Slirp
  39. 6.12 pcap
  40. 6.13 Setting up the host yourself
  41. 7. Sharing Filesystems between Virtual Machines
  42. 7.1 A warning
  43. 7.2 Using layered block devices
  44. 7.3 Note!
  45. 7.4 Another warning
  46. 7.5 uml_moo : Merging a COW file with its backing file
  47. 8. Creating filesystems
  48. 8.1 Create the filesystem file
  49. 8.2 Assign the file to a UML device
  50. 8.3 Creating and mounting the filesystem
  51. 9. Host file access
  52. 9.1 Using hostfs
  53. 9.2 hostfs as the root filesystem
  54. 9.3 Building hostfs
  55. 10. The Management Console
  56. 10.1 version
  57. 10.2 halt and reboot
  58. 10.3 config
  59. 10.4 remove
  60. 10.5 sysrq
  61. 10.6 help
  62. 10.7 cad
  63. 10.8 stop
  64. 10.9 go
  65. 11. Kernel debugging
  66. 11.1 Starting the kernel under gdb
  67. 11.2 Examining sleeping processes
  68. 11.3 Running ddd on UML
  69. 11.4 Debugging modules
  70. 11.5 Attaching gdb to the kernel
  71. 11.6 Using alternate debuggers
  72. 12. Kernel debugging examples
  73. 12.1 The case of the hung fsck
  74. 12.2 Episode 2: The case of the hung fsck
  75. 13. What to do when UML doesn't work
  76. 13.1 Strange compilation errors when you build from source
  77. 13.2 (obsolete)
  78. 13.3 A variety of panics and hangs with /tmp on a reiserfs filesystem
  79. 13.4 The compile fails with errors about conflicting types for 'open', 'dup', and 'waitpid'
  80. 13.5 UML doesn't work when /tmp is an NFS filesystem
  81. 13.6 UML hangs on boot when compiled with gprof support
  82. 13.7 syslogd dies with a SIGTERM on startup
  83. 13.8 TUN/TAP networking doesn't work on a 2.4 host
  84. 13.9 You can network to the host but not to other machines on the net
  85. 13.10 I have no root and I want to scream
  86. 13.11 UML build conflict between ptrace.h and ucontext.h
  87. 13.12 The UML BogoMips is exactly half the host's BogoMips
  88. 13.13 When you run UML, it immediately segfaults
  89. 13.14 xterms appear, then immediately disappear
  90. 13.15 Any other panic, hang, or strange behavior
  91. 14. Diagnosing Problems
  92. 14.1 Case 1 : Normal kernel panics
  93. 14.2 Case 2 : Tracing thread panics
  94. 14.3 Case 3 : Tracing thread panics caused by other threads
  95. 14.4 Case 4 : Hangs
  96. 15. Thanks
  97. 15.1 Code and Documentation
  98. 15.2 Flushing out bugs
  99. 15.3 Buglets and clean-ups
  100. 15.4 Case Studies
  101. 15.5 Other contributions
  102. ______________________________________________________________________
  103. 11.. IInnttrroodduuccttiioonn
  104. Welcome to User Mode Linux. It's going to be fun.
  105. 11..11.. HHooww iiss UUsseerr MMooddee LLiinnuuxx DDiiffffeerreenntt??
  106. Normally, the Linux Kernel talks straight to your hardware (video
  107. card, keyboard, hard drives, etc), and any programs which run ask the
  108. kernel to operate the hardware, like so:
  109. +-----------+-----------+----+
  110. | Process 1 | Process 2 | ...|
  111. +-----------+-----------+----+
  112. | Linux Kernel |
  113. +----------------------------+
  114. | Hardware |
  115. +----------------------------+
  116. The User Mode Linux Kernel is different; instead of talking to the
  117. hardware, it talks to a `real' Linux kernel (called the `host kernel'
  118. from now on), like any other program. Programs can then run inside
  119. User-Mode Linux as if they were running under a normal kernel, like
  120. so:
  121. +----------------+
  122. | Process 2 | ...|
  123. +-----------+----------------+
  124. | Process 1 | User-Mode Linux|
  125. +----------------------------+
  126. | Linux Kernel |
  127. +----------------------------+
  128. | Hardware |
  129. +----------------------------+
  130. 11..22.. WWhhyy WWoouulldd II WWaanntt UUsseerr MMooddee LLiinnuuxx??
  131. 1. If User Mode Linux crashes, your host kernel is still fine.
  132. 2. You can run a usermode kernel as a non-root user.
  133. 3. You can debug the User Mode Linux like any normal process.
  134. 4. You can run gprof (profiling) and gcov (coverage testing).
  135. 5. You can play with your kernel without breaking things.
  136. 6. You can use it as a sandbox for testing new apps.
  137. 7. You can try new development kernels safely.
  138. 8. You can run different distributions simultaneously.
  139. 9. It's extremely fun.
  140. 22.. CCoommppiilliinngg tthhee kkeerrnneell aanndd mmoodduulleess
  141. 22..11.. CCoommppiilliinngg tthhee kkeerrnneell
  142. Compiling the user mode kernel is just like compiling any other
  143. kernel. Let's go through the steps, using 2.4.0-prerelease (current
  144. as of this writing) as an example:
  145. 1. Download the latest UML patch from
  146. the download page <http://user-mode-linux.sourceforge.net/dl-
  147. sf.html>
  148. In this example, the file is uml-patch-2.4.0-prerelease.bz2.
  149. 2. Download the matching kernel from your favourite kernel mirror,
  150. such as:
  151. ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
  152. <ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2>
  153. .
  154. 3. Make a directory and unpack the kernel into it.
  155. host%
  156. mkdir ~/uml
  157. host%
  158. cd ~/uml
  159. host%
  160. tar -xzvf linux-2.4.0-prerelease.tar.bz2
  161. 4. Apply the patch using
  162. host%
  163. cd ~/uml/linux
  164. host%
  165. bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
  166. 5. Run your favorite config; `make xconfig ARCH=um' is the most
  167. convenient. `make config ARCH=um' and 'make menuconfig ARCH=um'
  168. will work as well. The defaults will give you a useful kernel. If
  169. you want to change something, go ahead, it probably won't hurt
  170. anything.
  171. Note: If the host is configured with a 2G/2G address space split
  172. rather than the usual 3G/1G split, then the packaged UML binaries
  173. will not run. They will immediately segfault. See ``UML on 2G/2G
  174. hosts'' for the scoop on running UML on your system.
  175. 6. Finish with `make linux ARCH=um': the result is a file called
  176. `linux' in the top directory of your source tree.
  177. Make sure that you don't build this kernel in /usr/src/linux. On some
  178. distributions, /usr/include/asm is a link into this pool. The user-
  179. mode build changes the other end of that link, and things that include
  180. <asm/anything.h> stop compiling.
  181. The sources are also available from cvs at the project's cvs page,
  182. which has directions on getting the sources. You can also browse the
  183. CVS pool from there.
  184. If you get the CVS sources, you will have to check them out into an
  185. empty directory. You will then have to copy each file into the
  186. corresponding directory in the appropriate kernel pool.
  187. If you don't have the latest kernel pool, you can get the
  188. corresponding user-mode sources with
  189. host% cvs co -r v_2_3_x linux
  190. where 'x' is the version in your pool. Note that you will not get the
  191. bug fixes and enhancements that have gone into subsequent releases.
  192. 22..22.. CCoommppiilliinngg aanndd iinnssttaalllliinngg kkeerrnneell mmoodduulleess
  193. UML modules are built in the same way as the native kernel (with the
  194. exception of the 'ARCH=um' that you always need for UML):
  195. host% make modules ARCH=um
  196. Any modules that you want to load into this kernel need to be built in
  197. the user-mode pool. Modules from the native kernel won't work.
  198. You can install them by using ftp or something to copy them into the
  199. virtual machine and dropping them into /lib/modules/`uname -r`.
  200. You can also get the kernel build process to install them as follows:
  201. 1. with the kernel not booted, mount the root filesystem in the top
  202. level of the kernel pool:
  203. host% mount root_fs mnt -o loop
  204. 2. run
  205. host%
  206. make modules_install INSTALL_MOD_PATH=`pwd`/mnt ARCH=um
  207. 3. unmount the filesystem
  208. host% umount mnt
  209. 4. boot the kernel on it
  210. When the system is booted, you can use insmod as usual to get the
  211. modules into the kernel. A number of things have been loaded into UML
  212. as modules, especially filesystems and network protocols and filters,
  213. so most symbols which need to be exported probably already are.
  214. However, if you do find symbols that need exporting, let us
  215. <http://user-mode-linux.sourceforge.net/contacts.html> know, and
  216. they'll be "taken care of".
  217. 22..33.. CCoommppiilliinngg aanndd iinnssttaalllliinngg uummll__uuttiilliittiieess
  218. Many features of the UML kernel require a user-space helper program,
  219. so a uml_utilities package is distributed separately from the kernel
  220. patch which provides these helpers. Included within this is:
  221. +o port-helper - Used by consoles which connect to xterms or ports
  222. +o tunctl - Configuration tool to create and delete tap devices
  223. +o uml_net - Setuid binary for automatic tap device configuration
  224. +o uml_switch - User-space virtual switch required for daemon
  225. transport
  226. The uml_utilities tree is compiled with:
  227. host#
  228. make && make install
  229. Note that UML kernel patches may require a specific version of the
  230. uml_utilities distribution. If you don't keep up with the mailing
  231. lists, ensure that you have the latest release of uml_utilities if you
  232. are experiencing problems with your UML kernel, particularly when
  233. dealing with consoles or command-line switches to the helper programs
  234. 33.. RRuunnnniinngg UUMMLL aanndd llooggggiinngg iinn
  235. 33..11.. RRuunnnniinngg UUMMLL
  236. It runs on 2.2.15 or later, and all 2.4 kernels.
  237. Booting UML is straightforward. Simply run 'linux': it will try to
  238. mount the file `root_fs' in the current directory. You do not need to
  239. run it as root. If your root filesystem is not named `root_fs', then
  240. you need to put a `ubd0=root_fs_whatever' switch on the linux command
  241. line.
  242. You will need a filesystem to boot UML from. There are a number
  243. available for download from here <http://user-mode-
  244. linux.sourceforge.net/dl-sf.html> . There are also several tools
  245. <http://user-mode-linux.sourceforge.net/fs_making.html> which can be
  246. used to generate UML-compatible filesystem images from media.
  247. The kernel will boot up and present you with a login prompt.
  248. Note: If the host is configured with a 2G/2G address space split
  249. rather than the usual 3G/1G split, then the packaged UML binaries will
  250. not run. They will immediately segfault. See ``UML on 2G/2G hosts''
  251. for the scoop on running UML on your system.
  252. 33..22.. LLooggggiinngg iinn
  253. The prepackaged filesystems have a root account with password 'root'
  254. and a user account with password 'user'. The login banner will
  255. generally tell you how to log in. So, you log in and you will find
  256. yourself inside a little virtual machine. Our filesystems have a
  257. variety of commands and utilities installed (and it is fairly easy to
  258. add more), so you will have a lot of tools with which to poke around
  259. the system.
  260. There are a couple of other ways to log in:
  261. +o On a virtual console
  262. Each virtual console that is configured (i.e. the device exists in
  263. /dev and /etc/inittab runs a getty on it) will come up in its own
  264. xterm. If you get tired of the xterms, read ``Setting up serial
  265. lines and consoles'' to see how to attach the consoles to
  266. something else, like host ptys.
  267. +o Over the serial line
  268. In the boot output, find a line that looks like:
  269. serial line 0 assigned pty /dev/ptyp1
  270. Attach your favorite terminal program to the corresponding tty. I.e.
  271. for minicom, the command would be
  272. host% minicom -o -p /dev/ttyp1
  273. +o Over the net
  274. If the network is running, then you can telnet to the virtual
  275. machine and log in to it. See ``Setting up the network'' to learn
  276. about setting up a virtual network.
  277. When you're done using it, run halt, and the kernel will bring itself
  278. down and the process will exit.
  279. 33..33.. EExxaammpplleess
  280. Here are some examples of UML in action:
  281. +o A login session <http://user-mode-linux.sourceforge.net/login.html>
  282. +o A virtual network <http://user-mode-linux.sourceforge.net/net.html>
  283. 44.. UUMMLL oonn 22GG//22GG hhoossttss
  284. 44..11.. IInnttrroodduuccttiioonn
  285. Most Linux machines are configured so that the kernel occupies the
  286. upper 1G (0xc0000000 - 0xffffffff) of the 4G address space and
  287. processes use the lower 3G (0x00000000 - 0xbfffffff). However, some
  288. machine are configured with a 2G/2G split, with the kernel occupying
  289. the upper 2G (0x80000000 - 0xffffffff) and processes using the lower
  290. 2G (0x00000000 - 0x7fffffff).
  291. 44..22.. TThhee pprroobblleemm
  292. The prebuilt UML binaries on this site will not run on 2G/2G hosts
  293. because UML occupies the upper .5G of the 3G process address space
  294. (0xa0000000 - 0xbfffffff). Obviously, on 2G/2G hosts, this is right
  295. in the middle of the kernel address space, so UML won't even load - it
  296. will immediately segfault.
  297. 44..33.. TThhee ssoolluuttiioonn
  298. The fix for this is to rebuild UML from source after enabling
  299. CONFIG_HOST_2G_2G (under 'General Setup'). This will cause UML to
  300. load itself in the top .5G of that smaller process address space,
  301. where it will run fine. See ``Compiling the kernel and modules'' if
  302. you need help building UML from source.
  303. 55.. SSeettttiinngg uupp sseerriiaall lliinneess aanndd ccoonnssoolleess
  304. It is possible to attach UML serial lines and consoles to many types
  305. of host I/O channels by specifying them on the command line.
  306. You can attach them to host ptys, ttys, file descriptors, and ports.
  307. This allows you to do things like
  308. +o have a UML console appear on an unused host console,
  309. +o hook two virtual machines together by having one attach to a pty
  310. and having the other attach to the corresponding tty
  311. +o make a virtual machine accessible from the net by attaching a
  312. console to a port on the host.
  313. The general format of the command line option is device=channel.
  314. 55..11.. SSppeecciiffyyiinngg tthhee ddeevviiccee
  315. Devices are specified with "con" or "ssl" (console or serial line,
  316. respectively), optionally with a device number if you are talking
  317. about a specific device.
  318. Using just "con" or "ssl" describes all of the consoles or serial
  319. lines. If you want to talk about console #3 or serial line #10, they
  320. would be "con3" and "ssl10", respectively.
  321. A specific device name will override a less general "con=" or "ssl=".
  322. So, for example, you can assign a pty to each of the serial lines
  323. except for the first two like this:
  324. ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1
  325. The specificity of the device name is all that matters; order on the
  326. command line is irrelevant.
  327. 55..22.. SSppeecciiffyyiinngg tthhee cchhaannnneell
  328. There are a number of different types of channels to attach a UML
  329. device to, each with a different way of specifying exactly what to
  330. attach to.
  331. +o pseudo-terminals - device=pty pts terminals - device=pts
  332. This will cause UML to allocate a free host pseudo-terminal for the
  333. device. The terminal that it got will be announced in the boot
  334. log. You access it by attaching a terminal program to the
  335. corresponding tty:
  336. +o screen /dev/pts/n
  337. +o screen /dev/ttyxx
  338. +o minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
  339. devices
  340. +o kermit - start it up, 'open' the device, then 'connect'
  341. +o terminals - device=tty:tty device file
  342. This will make UML attach the device to the specified tty (i.e
  343. con1=tty:/dev/tty3
  344. will attach UML's console 1 to the host's /dev/tty3). If the tty that
  345. you specify is the slave end of a tty/pty pair, something else must
  346. have already opened the corresponding pty in order for this to work.
  347. +o xterms - device=xterm
  348. UML will run an xterm and the device will be attached to it.
  349. +o Port - device=port:port number
  350. This will attach the UML devices to the specified host port.
  351. Attaching console 1 to the host's port 9000 would be done like
  352. this:
  353. con1=port:9000
  354. Attaching all the serial lines to that port would be done similarly:
  355. ssl=port:9000
  356. You access these devices by telnetting to that port. Each active tel-
  357. net session gets a different device. If there are more telnets to a
  358. port than UML devices attached to it, then the extra telnet sessions
  359. will block until an existing telnet detaches, or until another device
  360. becomes active (i.e. by being activated in /etc/inittab).
  361. This channel has the advantage that you can both attach multiple UML
  362. devices to it and know how to access them without reading the UML boot
  363. log. It is also unique in allowing access to a UML from remote
  364. machines without requiring that the UML be networked. This could be
  365. useful in allowing public access to UMLs because they would be
  366. accessible from the net, but wouldn't need any kind of network
  367. filtering or access control because they would have no network access.
  368. If you attach the main console to a portal, then the UML boot will
  369. appear to hang. In reality, it's waiting for a telnet to connect, at
  370. which point the boot will proceed.
  371. +o already-existing file descriptors - device=file descriptor
  372. If you set up a file descriptor on the UML command line, you can
  373. attach a UML device to it. This is most commonly used to put the
  374. main console back on stdin and stdout after assigning all the other
  375. consoles to something else:
  376. con0=fd:0,fd:1 con=pts
  377. +o Nothing - device=null
  378. This allows the device to be opened, in contrast to 'none', but
  379. reads will block, and writes will succeed and the data will be
  380. thrown out.
  381. +o None - device=none
  382. This causes the device to disappear.
  383. You can also specify different input and output channels for a device
  384. by putting a comma between them:
  385. ssl3=tty:/dev/tty2,xterm
  386. will cause serial line 3 to accept input on the host's /dev/tty3 and
  387. display output on an xterm. That's a silly example - the most common
  388. use of this syntax is to reattach the main console to stdin and stdout
  389. as shown above.
  390. If you decide to move the main console away from stdin/stdout, the
  391. initial boot output will appear in the terminal that you're running
  392. UML in. However, once the console driver has been officially
  393. initialized, then the boot output will start appearing wherever you
  394. specified that console 0 should be. That device will receive all
  395. subsequent output.
  396. 55..33.. EExxaammpplleess
  397. There are a number of interesting things you can do with this
  398. capability.
  399. First, this is how you get rid of those bleeding console xterms by
  400. attaching them to host ptys:
  401. con=pty con0=fd:0,fd:1
  402. This will make a UML console take over an unused host virtual console,
  403. so that when you switch to it, you will see the UML login prompt
  404. rather than the host login prompt:
  405. con1=tty:/dev/tty6
  406. You can attach two virtual machines together with what amounts to a
  407. serial line as follows:
  408. Run one UML with a serial line attached to a pty -
  409. ssl1=pty
  410. Look at the boot log to see what pty it got (this example will assume
  411. that it got /dev/ptyp1).
  412. Boot the other UML with a serial line attached to the corresponding
  413. tty -
  414. ssl1=tty:/dev/ttyp1
  415. Log in, make sure that it has no getty on that serial line, attach a
  416. terminal program like minicom to it, and you should see the login
  417. prompt of the other virtual machine.
  418. 66.. SSeettttiinngg uupp tthhee nneettwwoorrkk
  419. This page describes how to set up the various transports and to
  420. provide a UML instance with network access to the host, other machines
  421. on the local net, and the rest of the net.
  422. As of 2.4.5, UML networking has been completely redone to make it much
  423. easier to set up, fix bugs, and add new features.
  424. There is a new helper, uml_net, which does the host setup that
  425. requires root privileges.
  426. There are currently five transport types available for a UML virtual
  427. machine to exchange packets with other hosts:
  428. +o ethertap
  429. +o TUN/TAP
  430. +o Multicast
  431. +o a switch daemon
  432. +o slip
  433. +o slirp
  434. +o pcap
  435. The TUN/TAP, ethertap, slip, and slirp transports allow a UML
  436. instance to exchange packets with the host. They may be directed
  437. to the host or the host may just act as a router to provide access
  438. to other physical or virtual machines.
  439. The pcap transport is a synthetic read-only interface, using the
  440. libpcap binary to collect packets from interfaces on the host and
  441. filter them. This is useful for building preconfigured traffic
  442. monitors or sniffers.
  443. The daemon and multicast transports provide a completely virtual
  444. network to other virtual machines. This network is completely
  445. disconnected from the physical network unless one of the virtual
  446. machines on it is acting as a gateway.
  447. With so many host transports, which one should you use? Here's when
  448. you should use each one:
  449. +o ethertap - if you want access to the host networking and it is
  450. running 2.2
  451. +o TUN/TAP - if you want access to the host networking and it is
  452. running 2.4. Also, the TUN/TAP transport is able to use a
  453. preconfigured device, allowing it to avoid using the setuid uml_net
  454. helper, which is a security advantage.
  455. +o Multicast - if you want a purely virtual network and you don't want
  456. to set up anything but the UML
  457. +o a switch daemon - if you want a purely virtual network and you
  458. don't mind running the daemon in order to get somewhat better
  459. performance
  460. +o slip - there is no particular reason to run the slip backend unless
  461. ethertap and TUN/TAP are just not available for some reason
  462. +o slirp - if you don't have root access on the host to setup
  463. networking, or if you don't want to allocate an IP to your UML
  464. +o pcap - not much use for actual network connectivity, but great for
  465. monitoring traffic on the host
  466. Ethertap is available on 2.4 and works fine. TUN/TAP is preferred
  467. to it because it has better performance and ethertap is officially
  468. considered obsolete in 2.4. Also, the root helper only needs to
  469. run occasionally for TUN/TAP, rather than handling every packet, as
  470. it does with ethertap. This is a slight security advantage since
  471. it provides fewer opportunities for a nasty UML user to somehow
  472. exploit the helper's root privileges.
  473. 66..11.. GGeenneerraall sseettuupp
  474. First, you must have the virtual network enabled in your UML. If are
  475. running a prebuilt kernel from this site, everything is already
  476. enabled. If you build the kernel yourself, under the "Network device
  477. support" menu, enable "Network device support", and then the three
  478. transports.
  479. The next step is to provide a network device to the virtual machine.
  480. This is done by describing it on the kernel command line.
  481. The general format is
  482. eth <n> = <transport> , <transport args>
  483. For example, a virtual ethernet device may be attached to a host
  484. ethertap device as follows:
  485. eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
  486. This sets up eth0 inside the virtual machine to attach itself to the
  487. host /dev/tap0, assigns it an ethernet address, and assigns the host
  488. tap0 interface an IP address.
  489. Note that the IP address you assign to the host end of the tap device
  490. must be different than the IP you assign to the eth device inside UML.
  491. If you are short on IPs and don't want to consume two per UML, then
  492. you can reuse the host's eth IP address for the host ends of the tap
  493. devices. Internally, the UMLs must still get unique IPs for their eth
  494. devices. You can also give the UMLs non-routable IPs (192.168.x.x or
  495. 10.x.x.x) and have the host masquerade them. This will let outgoing
  496. connections work, but incoming connections won't without more work,
  497. such as port forwarding from the host.
  498. Also note that when you configure the host side of an interface, it is
  499. only acting as a gateway. It will respond to pings sent to it
  500. locally, but is not useful to do that since it's a host interface.
  501. You are not talking to the UML when you ping that interface and get a
  502. response.
  503. You can also add devices to a UML and remove them at runtime. See the
  504. ``The Management Console'' page for details.
  505. The sections below describe this in more detail.
  506. Once you've decided how you're going to set up the devices, you boot
  507. UML, log in, configure the UML side of the devices, and set up routes
  508. to the outside world. At that point, you will be able to talk to any
  509. other machines, physical or virtual, on the net.
  510. If ifconfig inside UML fails and the network refuses to come up, run
  511. tell you what went wrong.
  512. 66..22.. UUsseerrssppaaccee ddaaeemmoonnss
  513. You will likely need the setuid helper, or the switch daemon, or both.
  514. They are both installed with the RPM and deb, so if you've installed
  515. either, you can skip the rest of this section.
  516. If not, then you need to check them out of CVS, build them, and
  517. install them. The helper is uml_net, in CVS /tools/uml_net, and the
  518. daemon is uml_switch, in CVS /tools/uml_router. They are both built
  519. with a plain 'make'. Both need to be installed in a directory that's
  520. in your path - /usr/bin is recommend. On top of that, uml_net needs
  521. to be setuid root.
  522. 66..33.. SSppeecciiffyyiinngg eetthheerrnneett aaddddrreesssseess
  523. Below, you will see that the TUN/TAP, ethertap, and daemon interfaces
  524. allow you to specify hardware addresses for the virtual ethernet
  525. devices. This is generally not necessary. If you don't have a
  526. specific reason to do it, you probably shouldn't. If one is not
  527. specified on the command line, the driver will assign one based on the
  528. device IP address. It will provide the address fe:fd:nn:nn:nn:nn
  529. where nn.nn.nn.nn is the device IP address. This is nearly always
  530. sufficient to guarantee a unique hardware address for the device. A
  531. couple of exceptions are:
  532. +o Another set of virtual ethernet devices are on the same network and
  533. they are assigned hardware addresses using a different scheme which
  534. may conflict with the UML IP address-based scheme
  535. +o You aren't going to use the device for IP networking, so you don't
  536. assign the device an IP address
  537. If you let the driver provide the hardware address, you should make
  538. sure that the device IP address is known before the interface is
  539. brought up. So, inside UML, this will guarantee that:
  540. UML#
  541. ifconfig eth0 192.168.0.250 up
  542. If you decide to assign the hardware address yourself, make sure that
  543. the first byte of the address is even. Addresses with an odd first
  544. byte are broadcast addresses, which you don't want assigned to a
  545. device.
  546. 66..44.. UUMMLL iinntteerrffaaccee sseettuupp
  547. Once the network devices have been described on the command line, you
  548. should boot UML and log in.
  549. The first thing to do is bring the interface up:
  550. UML# ifconfig ethn ip-address up
  551. You should be able to ping the host at this point.
  552. To reach the rest of the world, you should set a default route to the
  553. host:
  554. UML# route add default gw host ip
  555. Again, with host ip of 192.168.0.4:
  556. UML# route add default gw 192.168.0.4
  557. This page used to recommend setting a network route to your local net.
  558. This is wrong, because it will cause UML to try to figure out hardware
  559. addresses of the local machines by arping on the interface to the
  560. host. Since that interface is basically a single strand of ethernet
  561. with two nodes on it (UML and the host) and arp requests don't cross
  562. networks, they will fail to elicit any responses. So, what you want
  563. is for UML to just blindly throw all packets at the host and let it
  564. figure out what to do with them, which is what leaving out the network
  565. route and adding the default route does.
  566. Note: If you can't communicate with other hosts on your physical
  567. ethernet, it's probably because of a network route that's
  568. automatically set up. If you run 'route -n' and see a route that
  569. looks like this:
  570. Destination Gateway Genmask Flags Metric Ref Use Iface
  571. 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
  572. with a mask that's not 255.255.255.255, then replace it with a route
  573. to your host:
  574. UML#
  575. route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0
  576. UML#
  577. route add -host 192.168.0.4 dev eth0
  578. This, plus the default route to the host, will allow UML to exchange
  579. packets with any machine on your ethernet.
  580. 66..55.. MMuullttiiccaasstt
  581. The simplest way to set up a virtual network between multiple UMLs is
  582. to use the mcast transport. This was written by Harald Welte and is
  583. present in UML version 2.4.5-5um and later. Your system must have
  584. multicast enabled in the kernel and there must be a multicast-capable
  585. network device on the host. Normally, this is eth0, but if there is
  586. no ethernet card on the host, then you will likely get strange error
  587. messages when you bring the device up inside UML.
  588. To use it, run two UMLs with
  589. eth0=mcast
  590. on their command lines. Log in, configure the ethernet device in each
  591. machine with different IP addresses:
  592. UML1# ifconfig eth0 192.168.0.254
  593. UML2# ifconfig eth0 192.168.0.253
  594. and they should be able to talk to each other.
  595. The full set of command line options for this transport are
  596. ethn=mcast,ethernet address,multicast
  597. address,multicast port,ttl
  598. Harald's original README is here <http://user-mode-linux.source-
  599. forge.net/text/mcast.txt> and explains these in detail, as well as
  600. some other issues.
  601. 66..66.. TTUUNN//TTAAPP wwiitthh tthhee uummll__nneett hheellppeerr
  602. TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the
  603. host. The TUN/TAP backend has been in UML since 2.4.9-3um.
  604. The easiest way to get up and running is to let the setuid uml_net
  605. helper do the host setup for you. This involves insmod-ing the tun.o
  606. module if necessary, configuring the device, and setting up IP
  607. forwarding, routing, and proxy arp. If you are new to UML networking,
  608. do this first. If you're concerned about the security implications of
  609. the setuid helper, use it to get up and running, then read the next
  610. section to see how to have UML use a preconfigured tap device, which
  611. avoids the use of uml_net.
  612. If you specify an IP address for the host side of the device, the
  613. uml_net helper will do all necessary setup on the host - the only
  614. requirement is that TUN/TAP be available, either built in to the host
  615. kernel or as the tun.o module.
  616. The format of the command line switch to attach a device to a TUN/TAP
  617. device is
  618. eth <n> =tuntap,,, <IP address>
  619. For example, this argument will attach the UML's eth0 to the next
  620. available tap device and assign an ethernet address to it based on its
  621. IP address
  622. eth0=tuntap,,,192.168.0.254
  623. Note that the IP address that must be used for the eth device inside
  624. UML is fixed by the routing and proxy arp that is set up on the
  625. TUN/TAP device on the host. You can use a different one, but it won't
  626. work because reply packets won't reach the UML. This is a feature.
  627. It prevents a nasty UML user from doing things like setting the UML IP
  628. to the same as the network's nameserver or mail server.
  629. There are a couple potential problems with running the TUN/TAP
  630. transport on a 2.4 host kernel
  631. +o TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
  632. kernel or use the ethertap transport.
  633. +o With an upgraded kernel, TUN/TAP may fail with
  634. File descriptor in bad state
  635. This is due to a header mismatch between the upgraded kernel and the
  636. kernel that was originally installed on the machine. The fix is to
  637. make sure that /usr/src/linux points to the headers for the running
  638. kernel.
  639. These were pointed out by Tim Robinson <timro at trkr dot net> in
  640. <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="this uml-
  641. user post"> .
  642. 66..77.. TTUUNN//TTAAPP wwiitthh aa pprreeccoonnffiigguurreedd ttaapp ddeevviiccee
  643. If you prefer not to have UML use uml_net (which is somewhat
  644. insecure), with UML 2.4.17-11, you can set up a TUN/TAP device
  645. beforehand. The setup needs to be done as root, but once that's done,
  646. there is no need for root assistance. Setting up the device is done
  647. as follows:
  648. +o Create the device with tunctl (available from the UML utilities
  649. tarball)
  650. host# tunctl -u uid
  651. where uid is the user id or username that UML will be run as. This
  652. will tell you what device was created.
  653. +o Configure the device IP (change IP addresses and device name to
  654. suit)
  655. host# ifconfig tap0 192.168.0.254 up
  656. +o Set up routing and arping if desired - this is my recipe, there are
  657. other ways of doing the same thing
  658. host#
  659. bash -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'
  660. host#
  661. route add -host 192.168.0.253 dev tap0
  662. host#
  663. bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
  664. host#
  665. arp -Ds 192.168.0.253 eth0 pub
  666. Note that this must be done every time the host boots - this configu-
  667. ration is not stored across host reboots. So, it's probably a good
  668. idea to stick it in an rc file. An even better idea would be a little
  669. utility which reads the information from a config file and sets up
  670. devices at boot time.
  671. +o Rather than using up two IPs and ARPing for one of them, you can
  672. also provide direct access to your LAN by the UML by using a
  673. bridge.
  674. host#
  675. brctl addbr br0
  676. host#
  677. ifconfig eth0 0.0.0.0 promisc up
  678. host#
  679. ifconfig tap0 0.0.0.0 promisc up
  680. host#
  681. ifconfig br0 192.168.0.1 netmask 255.255.255.0 up
  682. host#
  683. brctl stp br0 off
  684. host#
  685. brctl setfd br0 1
  686. host#
  687. brctl sethello br0 1
  688. host#
  689. brctl addif br0 eth0
  690. host#
  691. brctl addif br0 tap0
  692. Note that 'br0' should be setup using ifconfig with the existing IP
  693. address of eth0, as eth0 no longer has its own IP.
  694. +o
  695. Also, the /dev/net/tun device must be writable by the user running
  696. UML in order for the UML to use the device that's been configured
  697. for it. The simplest thing to do is
  698. host# chmod 666 /dev/net/tun
  699. Making it world-writable looks bad, but it seems not to be
  700. exploitable as a security hole. However, it does allow anyone to cre-
  701. ate useless tap devices (useless because they can't configure them),
  702. which is a DOS attack. A somewhat more secure alternative would to be
  703. to create a group containing all the users who have preconfigured tap
  704. devices and chgrp /dev/net/tun to that group with mode 664 or 660.
  705. +o Once the device is set up, run UML with 'eth0=tuntap,device name'
  706. (i.e. 'eth0=tuntap,tap0') on the command line (or do it with the
  707. mconsole config command).
  708. +o Bring the eth device up in UML and you're in business.
  709. If you don't want that tap device any more, you can make it non-
  710. persistent with
  711. host# tunctl -d tap device
  712. Finally, tunctl has a -b (for brief mode) switch which causes it to
  713. output only the name of the tap device it created. This makes it
  714. suitable for capture by a script:
  715. host# TAP=`tunctl -u 1000 -b`
  716. 66..88.. EEtthheerrttaapp
  717. Ethertap is the general mechanism on 2.2 for userspace processes to
  718. exchange packets with the kernel.
  719. To use this transport, you need to describe the virtual network device
  720. on the UML command line. The general format for this is
  721. eth <n> =ethertap, <device> , <ethernet address> , <tap IP address>
  722. So, the previous example
  723. eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
  724. attaches the UML eth0 device to the host /dev/tap0, assigns it the
  725. ethernet address fe:fd:0:0:0:1, and assigns the IP address
  726. 192.168.0.254 to the tap device.
  727. The tap device is mandatory, but the others are optional. If the
  728. ethernet address is omitted, one will be assigned to it.
  729. The presence of the tap IP address will cause the helper to run and do
  730. whatever host setup is needed to allow the virtual machine to
  731. communicate with the outside world. If you're not sure you know what
  732. you're doing, this is the way to go.
  733. If it is absent, then you must configure the tap device and whatever
  734. arping and routing you will need on the host. However, even in this
  735. case, the uml_net helper still needs to be in your path and it must be
  736. setuid root if you're not running UML as root. This is because the
  737. tap device doesn't support SIGIO, which UML needs in order to use
  738. something as a source of input. So, the helper is used as a
  739. convenient asynchronous IO thread.
  740. If you're using the uml_net helper, you can ignore the following host
  741. setup - uml_net will do it for you. You just need to make sure you
  742. have ethertap available, either built in to the host kernel or
  743. available as a module.
  744. If you want to set things up yourself, you need to make sure that the
  745. appropriate /dev entry exists. If it doesn't, become root and create
  746. it as follows:
  747. mknod /dev/tap <minor> c 36 <minor> + 16
  748. For example, this is how to create /dev/tap0:
  749. mknod /dev/tap0 c 36 0 + 16
  750. You also need to make sure that the host kernel has ethertap support.
  751. If ethertap is enabled as a module, you apparently need to insmod
  752. ethertap once for each ethertap device you want to enable. So,
  753. host#
  754. insmod ethertap
  755. will give you the tap0 interface. To get the tap1 interface, you need
  756. to run
  757. host#
  758. insmod ethertap unit=1 -o ethertap1
  759. 66..99.. TThhee sswwiittcchh ddaaeemmoonn
  760. NNoottee: This is the daemon formerly known as uml_router, but which was
  761. renamed so the network weenies of the world would stop growling at me.
  762. The switch daemon, uml_switch, provides a mechanism for creating a
  763. totally virtual network. By default, it provides no connection to the
  764. host network (but see -tap, below).
  765. The first thing you need to do is run the daemon. Running it with no
  766. arguments will make it listen on a default pair of unix domain
  767. sockets.
  768. If you want it to listen on a different pair of sockets, use
  769. -unix control socket data socket
  770. If you want it to act as a hub rather than a switch, use
  771. -hub
  772. If you want the switch to be connected to host networking (allowing
  773. the umls to get access to the outside world through the host), use
  774. -tap tap0
  775. Note that the tap device must be preconfigured (see "TUN/TAP with a
  776. preconfigured tap device", above). If you're using a different tap
  777. device than tap0, specify that instead of tap0.
  778. uml_switch can be backgrounded as follows
  779. host%
  780. uml_switch [ options ] < /dev/null > /dev/null
  781. The reason it doesn't background by default is that it listens to
  782. stdin for EOF. When it sees that, it exits.
  783. The general format of the kernel command line switch is
  784. ethn=daemon,ethernet address,socket
  785. type,control socket,data socket
  786. You can leave off everything except the 'daemon'. You only need to
  787. specify the ethernet address if the one that will be assigned to it
  788. isn't acceptable for some reason. The rest of the arguments describe
  789. how to communicate with the daemon. You should only specify them if
  790. you told the daemon to use different sockets than the default. So, if
  791. you ran the daemon with no arguments, running the UML on the same
  792. machine with
  793. eth0=daemon
  794. will cause the eth0 driver to attach itself to the daemon correctly.
  795. 66..1100.. SSlliipp
  796. Slip is another, less general, mechanism for a process to communicate
  797. with the host networking. In contrast to the ethertap interface,
  798. which exchanges ethernet frames with the host and can be used to
  799. transport any higher-level protocol, it can only be used to transport
  800. IP.
  801. The general format of the command line switch is
  802. ethn=slip,slip IP
  803. The slip IP argument is the IP address that will be assigned to the
  804. host end of the slip device. If it is specified, the helper will run
  805. and will set up the host so that the virtual machine can reach it and
  806. the rest of the network.
  807. There are some oddities with this interface that you should be aware
  808. of. You should only specify one slip device on a given virtual
  809. machine, and its name inside UML will be 'umn', not 'eth0' or whatever
  810. you specified on the command line. These problems will be fixed at
  811. some point.
  812. 66..1111.. SSlliirrpp
  813. slirp uses an external program, usually /usr/bin/slirp, to provide IP
  814. only networking connectivity through the host. This is similar to IP
  815. masquerading with a firewall, although the translation is performed in
  816. user-space, rather than by the kernel. As slirp does not set up any
  817. interfaces on the host, or changes routing, slirp does not require
  818. root access or setuid binaries on the host.
  819. The general format of the command line switch for slirp is:
  820. ethn=slirp,ethernet address,slirp path
  821. The ethernet address is optional, as UML will set up the interface
  822. with an ethernet address based upon the initial IP address of the
  823. interface. The slirp path is generally /usr/bin/slirp, although it
  824. will depend on distribution.
  825. The slirp program can have a number of options passed to the command
  826. line and we can't add them to the UML command line, as they will be
  827. parsed incorrectly. Instead, a wrapper shell script can be written or
  828. the options inserted into the /.slirprc file. More information on
  829. all of the slirp options can be found in its man pages.
  830. The eth0 interface on UML should be set up with the IP 10.2.0.15,
  831. although you can use anything as long as it is not used by a network
  832. you will be connecting to. The default route on UML should be set to
  833. use
  834. UML#
  835. route add default dev eth0
  836. slirp provides a number of useful IP addresses which can be used by
  837. UML, such as 10.0.2.3 which is an alias for the DNS server specified
  838. in /etc/resolv.conf on the host or the IP given in the 'dns' option
  839. for slirp.
  840. Even with a baudrate setting higher than 115200, the slirp connection
  841. is limited to 115200. If you need it to go faster, the slirp binary
  842. needs to be compiled with FULL_BOLT defined in config.h.
  843. 66..1122.. ppccaapp
  844. The pcap transport is attached to a UML ethernet device on the command
  845. line or with uml_mconsole with the following syntax:
  846. ethn=pcap,host interface,filter
  847. expression,option1,option2
  848. The expression and options are optional.
  849. The interface is whatever network device on the host you want to
  850. sniff. The expression is a pcap filter expression, which is also what
  851. tcpdump uses, so if you know how to specify tcpdump filters, you will
  852. use the same expressions here. The options are up to two of
  853. 'promisc', control whether pcap puts the host interface into
  854. promiscuous mode. 'optimize' and 'nooptimize' control whether the pcap
  855. expression optimizer is used.
  856. Example:
  857. eth0=pcap,eth0,tcp
  858. eth1=pcap,eth0,!tcp
  859. will cause the UML eth0 to emit all tcp packets on the host eth0 and
  860. the UML eth1 to emit all non-tcp packets on the host eth0.
  861. 66..1133.. SSeettttiinngg uupp tthhee hhoosstt yyoouurrsseellff
  862. If you don't specify an address for the host side of the ethertap or
  863. slip device, UML won't do any setup on the host. So this is what is
  864. needed to get things working (the examples use a host-side IP of
  865. 192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your
  866. own network):
  867. +o The device needs to be configured with its IP address. Tap devices
  868. are also configured with an mtu of 1484. Slip devices are
  869. configured with a point-to-point address pointing at the UML ip
  870. address.
  871. host# ifconfig tap0 arp mtu 1484 192.168.0.251 up
  872. host#
  873. ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up
  874. +o If a tap device is being set up, a route is set to the UML IP.
  875. UML# route add -host 192.168.0.250 gw 192.168.0.251
  876. +o To allow other hosts on your network to see the virtual machine,
  877. proxy arp is set up for it.
  878. host# arp -Ds 192.168.0.250 eth0 pub
  879. +o Finally, the host is set up to route packets.
  880. host# echo 1 > /proc/sys/net/ipv4/ip_forward
  881. 77.. SShhaarriinngg FFiilleessyysstteemmss bbeettwweeeenn VViirrttuuaall MMaacchhiinneess
  882. 77..11.. AA wwaarrnniinngg
  883. Don't attempt to share filesystems simply by booting two UMLs from the
  884. same file. That's the same thing as booting two physical machines
  885. from a shared disk. It will result in filesystem corruption.
  886. 77..22.. UUssiinngg llaayyeerreedd bblloocckk ddeevviicceess
  887. The way to share a filesystem between two virtual machines is to use
  888. the copy-on-write (COW) layering capability of the ubd block driver.
  889. As of 2.4.6-2um, the driver supports layering a read-write private
  890. device over a read-only shared device. A machine's writes are stored
  891. in the private device, while reads come from either device - the
  892. private one if the requested block is valid in it, the shared one if
  893. not. Using this scheme, the majority of data which is unchanged is
  894. shared between an arbitrary number of virtual machines, each of which
  895. has a much smaller file containing the changes that it has made. With
  896. a large number of UMLs booting from a large root filesystem, this
  897. leads to a huge disk space saving. It will also help performance,
  898. since the host will be able to cache the shared data using a much
  899. smaller amount of memory, so UML disk requests will be served from the
  900. host's memory rather than its disks.
  901. To add a copy-on-write layer to an existing block device file, simply
  902. add the name of the COW file to the appropriate ubd switch:
  903. ubd0=root_fs_cow,root_fs_debian_22
  904. where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is
  905. the existing shared filesystem. The COW file need not exist. If it
  906. doesn't, the driver will create and initialize it. Once the COW file
  907. has been initialized, it can be used on its own on the command line:
  908. ubd0=root_fs_cow
  909. The name of the backing file is stored in the COW file header, so it
  910. would be redundant to continue specifying it on the command line.
  911. 77..33.. NNoottee!!
  912. When checking the size of the COW file in order to see the gobs of
  913. space that you're saving, make sure you use 'ls -ls' to see the actual
  914. disk consumption rather than the length of the file. The COW file is
  915. sparse, so the length will be very different from the disk usage.
  916. Here is a 'ls -l' of a COW file and backing file from one boot and
  917. shutdown:
  918. host% ls -l cow.debian debian2.2
  919. -rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
  920. -rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
  921. Doesn't look like much saved space, does it? Well, here's 'ls -ls':
  922. host% ls -ls cow.debian debian2.2
  923. 880 -rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
  924. 525832 -rwxrw-rw- 1…

Large files files are truncated, but you can click here to view the full file