/Documentation/uml/UserModeLinux-HOWTO.txt
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
5 This document describes the use and abuse of Jeff Dike's User Mode
6 Linux: a port of the Linux kernel as a normal Intel Linux process.
7 ______________________________________________________________________
8
9 Table of Contents
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67 1. Introduction
68
69 1.1 How is User Mode Linux Different?
70 1.2 Why Would I Want User Mode Linux?
71
72 2. Compiling the kernel and modules
73
74 2.1 Compiling the kernel
75 2.2 Compiling and installing kernel modules
76 2.3 Compiling and installing uml_utilities
77
78 3. Running UML and logging in
79
80 3.1 Running UML
81 3.2 Logging in
82 3.3 Examples
83
84 4. UML on 2G/2G hosts
85
86 4.1 Introduction
87 4.2 The problem
88 4.3 The solution
89
90 5. Setting up serial lines and consoles
91
92 5.1 Specifying the device
93 5.2 Specifying the channel
94 5.3 Examples
95
96 6. Setting up the network
97
98 6.1 General setup
99 6.2 Userspace daemons
100 6.3 Specifying ethernet addresses
101 6.4 UML interface setup
102 6.5 Multicast
103 6.6 TUN/TAP with the uml_net helper
104 6.7 TUN/TAP with a preconfigured tap device
105 6.8 Ethertap
106 6.9 The switch daemon
107 6.10 Slip
108 6.11 Slirp
109 6.12 pcap
110 6.13 Setting up the host yourself
111
112 7. Sharing Filesystems between Virtual Machines
113
114 7.1 A warning
115 7.2 Using layered block devices
116 7.3 Note!
117 7.4 Another warning
118 7.5 uml_moo : Merging a COW file with its backing file
119
120 8. Creating filesystems
121
122 8.1 Create the filesystem file
123 8.2 Assign the file to a UML device
124 8.3 Creating and mounting the filesystem
125
126 9. Host file access
127
128 9.1 Using hostfs
129 9.2 hostfs as the root filesystem
130 9.3 Building hostfs
131
132 10. The Management Console
133 10.1 version
134 10.2 halt and reboot
135 10.3 config
136 10.4 remove
137 10.5 sysrq
138 10.6 help
139 10.7 cad
140 10.8 stop
141 10.9 go
142
143 11. Kernel debugging
144
145 11.1 Starting the kernel under gdb
146 11.2 Examining sleeping processes
147 11.3 Running ddd on UML
148 11.4 Debugging modules
149 11.5 Attaching gdb to the kernel
150 11.6 Using alternate debuggers
151
152 12. Kernel debugging examples
153
154 12.1 The case of the hung fsck
155 12.2 Episode 2: The case of the hung fsck
156
157 13. What to do when UML doesn't work
158
159 13.1 Strange compilation errors when you build from source
160 13.2 (obsolete)
161 13.3 A variety of panics and hangs with /tmp on a reiserfs filesystem
162 13.4 The compile fails with errors about conflicting types for 'open', 'dup', and 'waitpid'
163 13.5 UML doesn't work when /tmp is an NFS filesystem
164 13.6 UML hangs on boot when compiled with gprof support
165 13.7 syslogd dies with a SIGTERM on startup
166 13.8 TUN/TAP networking doesn't work on a 2.4 host
167 13.9 You can network to the host but not to other machines on the net
168 13.10 I have no root and I want to scream
169 13.11 UML build conflict between ptrace.h and ucontext.h
170 13.12 The UML BogoMips is exactly half the host's BogoMips
171 13.13 When you run UML, it immediately segfaults
172 13.14 xterms appear, then immediately disappear
173 13.15 Any other panic, hang, or strange behavior
174
175 14. Diagnosing Problems
176
177 14.1 Case 1 : Normal kernel panics
178 14.2 Case 2 : Tracing thread panics
179 14.3 Case 3 : Tracing thread panics caused by other threads
180 14.4 Case 4 : Hangs
181
182 15. Thanks
183
184 15.1 Code and Documentation
185 15.2 Flushing out bugs
186 15.3 Buglets and clean-ups
187 15.4 Case Studies
188 15.5 Other contributions
189
190
191 ______________________________________________________________________
192
193 11.. IInnttrroodduuccttiioonn
194
195 Welcome to User Mode Linux. It's going to be fun.
196
197
198
199 11..11.. HHooww iiss UUsseerr MMooddee LLiinnuuxx DDiiffffeerreenntt??
200
201 Normally, the Linux Kernel talks straight to your hardware (video
202 card, keyboard, hard drives, etc), and any programs which run ask the
203 kernel to operate the hardware, like so:
204
205
206
207 +-----------+-----------+----+
208 | Process 1 | Process 2 | ...|
209 +-----------+-----------+----+
210 | Linux Kernel |
211 +----------------------------+
212 | Hardware |
213 +----------------------------+
214
215
216
217
218 The User Mode Linux Kernel is different; instead of talking to the
219 hardware, it talks to a `real' Linux kernel (called the `host kernel'
220 from now on), like any other program. Programs can then run inside
221 User-Mode Linux as if they were running under a normal kernel, like
222 so:
223
224
225
226 +----------------+
227 | Process 2 | ...|
228 +-----------+----------------+
229 | Process 1 | User-Mode Linux|
230 +----------------------------+
231 | Linux Kernel |
232 +----------------------------+
233 | Hardware |
234 +----------------------------+
235
236
237
238
239
240 11..22.. WWhhyy WWoouulldd II WWaanntt UUsseerr MMooddee LLiinnuuxx??
241
242
243 1. If User Mode Linux crashes, your host kernel is still fine.
244
245 2. You can run a usermode kernel as a non-root user.
246
247 3. You can debug the User Mode Linux like any normal process.
248
249 4. You can run gprof (profiling) and gcov (coverage testing).
250
251 5. You can play with your kernel without breaking things.
252
253 6. You can use it as a sandbox for testing new apps.
254
255 7. You can try new development kernels safely.
256
257 8. You can run different distributions simultaneously.
258
259 9. It's extremely fun.
260
261
262
263
264
265 22.. CCoommppiilliinngg tthhee kkeerrnneell aanndd mmoodduulleess
266
267
268
269
270 22..11.. CCoommppiilliinngg tthhee kkeerrnneell
271
272
273 Compiling the user mode kernel is just like compiling any other
274 kernel. Let's go through the steps, using 2.4.0-prerelease (current
275 as of this writing) as an example:
276
277
278 1. Download the latest UML patch from
279
280 the download page <http://user-mode-linux.sourceforge.net/dl-
281 sf.html>
282
283 In this example, the file is uml-patch-2.4.0-prerelease.bz2.
284
285
286 2. Download the matching kernel from your favourite kernel mirror,
287 such as:
288
289 ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
290 <ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2>
291 .
292
293
294 3. Make a directory and unpack the kernel into it.
295
296
297
298 host%
299 mkdir ~/uml
300
301
302
303
304
305
306 host%
307 cd ~/uml
308
309
310
311
312
313
314 host%
315 tar -xzvf linux-2.4.0-prerelease.tar.bz2
316
317
318
319
320
321
322 4. Apply the patch using
323
324
325
326 host%
327 cd ~/uml/linux
328
329
330
331 host%
332 bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
333
334
335
336
337
338
339 5. Run your favorite config; `make xconfig ARCH=um' is the most
340 convenient. `make config ARCH=um' and 'make menuconfig ARCH=um'
341 will work as well. The defaults will give you a useful kernel. If
342 you want to change something, go ahead, it probably won't hurt
343 anything.
344
345
346 Note: If the host is configured with a 2G/2G address space split
347 rather than the usual 3G/1G split, then the packaged UML binaries
348 will not run. They will immediately segfault. See ``UML on 2G/2G
349 hosts'' for the scoop on running UML on your system.
350
351
352
353 6. Finish with `make linux ARCH=um': the result is a file called
354 `linux' in the top directory of your source tree.
355
356 Make sure that you don't build this kernel in /usr/src/linux. On some
357 distributions, /usr/include/asm is a link into this pool. The user-
358 mode build changes the other end of that link, and things that include
359 <asm/anything.h> stop compiling.
360
361 The sources are also available from cvs at the project's cvs page,
362 which has directions on getting the sources. You can also browse the
363 CVS pool from there.
364
365 If you get the CVS sources, you will have to check them out into an
366 empty directory. You will then have to copy each file into the
367 corresponding directory in the appropriate kernel pool.
368
369 If you don't have the latest kernel pool, you can get the
370 corresponding user-mode sources with
371
372
373 host% cvs co -r v_2_3_x linux
374
375
376
377
378 where 'x' is the version in your pool. Note that you will not get the
379 bug fixes and enhancements that have gone into subsequent releases.
380
381
382 22..22.. CCoommppiilliinngg aanndd iinnssttaalllliinngg kkeerrnneell mmoodduulleess
383
384 UML modules are built in the same way as the native kernel (with the
385 exception of the 'ARCH=um' that you always need for UML):
386
387
388 host% make modules ARCH=um
389
390
391
392
393 Any modules that you want to load into this kernel need to be built in
394 the user-mode pool. Modules from the native kernel won't work.
395
396 You can install them by using ftp or something to copy them into the
397 virtual machine and dropping them into /lib/modules/`uname -r`.
398
399 You can also get the kernel build process to install them as follows:
400
401 1. with the kernel not booted, mount the root filesystem in the top
402 level of the kernel pool:
403
404
405 host% mount root_fs mnt -o loop
406
407
408
409
410
411
412 2. run
413
414
415 host%
416 make modules_install INSTALL_MOD_PATH=`pwd`/mnt ARCH=um
417
418
419
420
421
422
423 3. unmount the filesystem
424
425
426 host% umount mnt
427
428
429
430
431
432
433 4. boot the kernel on it
434
435
436 When the system is booted, you can use insmod as usual to get the
437 modules into the kernel. A number of things have been loaded into UML
438 as modules, especially filesystems and network protocols and filters,
439 so most symbols which need to be exported probably already are.
440 However, if you do find symbols that need exporting, let us
441 <http://user-mode-linux.sourceforge.net/contacts.html> know, and
442 they'll be "taken care of".
443
444
445
446 22..33.. CCoommppiilliinngg aanndd iinnssttaalllliinngg uummll__uuttiilliittiieess
447
448 Many features of the UML kernel require a user-space helper program,
449 so a uml_utilities package is distributed separately from the kernel
450 patch which provides these helpers. Included within this is:
451
452 +o port-helper - Used by consoles which connect to xterms or ports
453
454 +o tunctl - Configuration tool to create and delete tap devices
455
456 +o uml_net - Setuid binary for automatic tap device configuration
457
458 +o uml_switch - User-space virtual switch required for daemon
459 transport
460
461 The uml_utilities tree is compiled with:
462
463
464 host#
465 make && make install
466
467
468
469
470 Note that UML kernel patches may require a specific version of the
471 uml_utilities distribution. If you don't keep up with the mailing
472 lists, ensure that you have the latest release of uml_utilities if you
473 are experiencing problems with your UML kernel, particularly when
474 dealing with consoles or command-line switches to the helper programs
475
476
477
478
479
480
481
482
483 33.. RRuunnnniinngg UUMMLL aanndd llooggggiinngg iinn
484
485
486
487 33..11.. RRuunnnniinngg UUMMLL
488
489 It runs on 2.2.15 or later, and all 2.4 kernels.
490
491
492 Booting UML is straightforward. Simply run 'linux': it will try to
493 mount the file `root_fs' in the current directory. You do not need to
494 run it as root. If your root filesystem is not named `root_fs', then
495 you need to put a `ubd0=root_fs_whatever' switch on the linux command
496 line.
497
498
499 You will need a filesystem to boot UML from. There are a number
500 available for download from here <http://user-mode-
501 linux.sourceforge.net/dl-sf.html> . There are also several tools
502 <http://user-mode-linux.sourceforge.net/fs_making.html> which can be
503 used to generate UML-compatible filesystem images from media.
504 The kernel will boot up and present you with a login prompt.
505
506
507 Note: If the host is configured with a 2G/2G address space split
508 rather than the usual 3G/1G split, then the packaged UML binaries will
509 not run. They will immediately segfault. See ``UML on 2G/2G hosts''
510 for the scoop on running UML on your system.
511
512
513
514 33..22.. LLooggggiinngg iinn
515
516
517
518 The prepackaged filesystems have a root account with password 'root'
519 and a user account with password 'user'. The login banner will
520 generally tell you how to log in. So, you log in and you will find
521 yourself inside a little virtual machine. Our filesystems have a
522 variety of commands and utilities installed (and it is fairly easy to
523 add more), so you will have a lot of tools with which to poke around
524 the system.
525
526 There are a couple of other ways to log in:
527
528 +o On a virtual console
529
530
531
532 Each virtual console that is configured (i.e. the device exists in
533 /dev and /etc/inittab runs a getty on it) will come up in its own
534 xterm. If you get tired of the xterms, read ``Setting up serial
535 lines and consoles'' to see how to attach the consoles to
536 something else, like host ptys.
537
538
539
540 +o Over the serial line
541
542
543 In the boot output, find a line that looks like:
544
545
546
547 serial line 0 assigned pty /dev/ptyp1
548
549
550
551
552 Attach your favorite terminal program to the corresponding tty. I.e.
553 for minicom, the command would be
554
555
556 host% minicom -o -p /dev/ttyp1
557
558
559
560
561
562
563 +o Over the net
564
565
566 If the network is running, then you can telnet to the virtual
567 machine and log in to it. See ``Setting up the network'' to learn
568 about setting up a virtual network.
569
570 When you're done using it, run halt, and the kernel will bring itself
571 down and the process will exit.
572
573
574 33..33.. EExxaammpplleess
575
576 Here are some examples of UML in action:
577
578 +o A login session <http://user-mode-linux.sourceforge.net/login.html>
579
580 +o A virtual network <http://user-mode-linux.sourceforge.net/net.html>
581
582
583
584
585
586
587
588 44.. UUMMLL oonn 22GG//22GG hhoossttss
589
590
591
592
593 44..11.. IInnttrroodduuccttiioonn
594
595
596 Most Linux machines are configured so that the kernel occupies the
597 upper 1G (0xc0000000 - 0xffffffff) of the 4G address space and
598 processes use the lower 3G (0x00000000 - 0xbfffffff). However, some
599 machine are configured with a 2G/2G split, with the kernel occupying
600 the upper 2G (0x80000000 - 0xffffffff) and processes using the lower
601 2G (0x00000000 - 0x7fffffff).
602
603
604
605
606 44..22.. TThhee pprroobblleemm
607
608
609 The prebuilt UML binaries on this site will not run on 2G/2G hosts
610 because UML occupies the upper .5G of the 3G process address space
611 (0xa0000000 - 0xbfffffff). Obviously, on 2G/2G hosts, this is right
612 in the middle of the kernel address space, so UML won't even load - it
613 will immediately segfault.
614
615
616
617
618 44..33.. TThhee ssoolluuttiioonn
619
620
621 The fix for this is to rebuild UML from source after enabling
622 CONFIG_HOST_2G_2G (under 'General Setup'). This will cause UML to
623 load itself in the top .5G of that smaller process address space,
624 where it will run fine. See ``Compiling the kernel and modules'' if
625 you need help building UML from source.
626
627
628
629
630
631
632
633
634
635
636 55.. SSeettttiinngg uupp sseerriiaall lliinneess aanndd ccoonnssoolleess
637
638
639 It is possible to attach UML serial lines and consoles to many types
640 of host I/O channels by specifying them on the command line.
641
642
643 You can attach them to host ptys, ttys, file descriptors, and ports.
644 This allows you to do things like
645
646 +o have a UML console appear on an unused host console,
647
648 +o hook two virtual machines together by having one attach to a pty
649 and having the other attach to the corresponding tty
650
651 +o make a virtual machine accessible from the net by attaching a
652 console to a port on the host.
653
654
655 The general format of the command line option is device=channel.
656
657
658
659 55..11.. SSppeecciiffyyiinngg tthhee ddeevviiccee
660
661 Devices are specified with "con" or "ssl" (console or serial line,
662 respectively), optionally with a device number if you are talking
663 about a specific device.
664
665
666 Using just "con" or "ssl" describes all of the consoles or serial
667 lines. If you want to talk about console #3 or serial line #10, they
668 would be "con3" and "ssl10", respectively.
669
670
671 A specific device name will override a less general "con=" or "ssl=".
672 So, for example, you can assign a pty to each of the serial lines
673 except for the first two like this:
674
675
676 ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1
677
678
679
680
681 The specificity of the device name is all that matters; order on the
682 command line is irrelevant.
683
684
685
686 55..22.. SSppeecciiffyyiinngg tthhee cchhaannnneell
687
688 There are a number of different types of channels to attach a UML
689 device to, each with a different way of specifying exactly what to
690 attach to.
691
692 +o pseudo-terminals - device=pty pts terminals - device=pts
693
694
695 This will cause UML to allocate a free host pseudo-terminal for the
696 device. The terminal that it got will be announced in the boot
697 log. You access it by attaching a terminal program to the
698 corresponding tty:
699
700 +o screen /dev/pts/n
701
702 +o screen /dev/ttyxx
703
704 +o minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
705 devices
706
707 +o kermit - start it up, 'open' the device, then 'connect'
708
709
710
711
712
713 +o terminals - device=tty:tty device file
714
715
716 This will make UML attach the device to the specified tty (i.e
717
718
719 con1=tty:/dev/tty3
720
721
722
723
724 will attach UML's console 1 to the host's /dev/tty3). If the tty that
725 you specify is the slave end of a tty/pty pair, something else must
726 have already opened the corresponding pty in order for this to work.
727
728
729
730
731
732 +o xterms - device=xterm
733
734
735 UML will run an xterm and the device will be attached to it.
736
737
738
739
740
741 +o Port - device=port:port number
742
743
744 This will attach the UML devices to the specified host port.
745 Attaching console 1 to the host's port 9000 would be done like
746 this:
747
748
749 con1=port:9000
750
751
752
753
754 Attaching all the serial lines to that port would be done similarly:
755
756
757 ssl=port:9000
758
759
760
761
762 You access these devices by telnetting to that port. Each active tel-
763 net session gets a different device. If there are more telnets to a
764 port than UML devices attached to it, then the extra telnet sessions
765 will block until an existing telnet detaches, or until another device
766 becomes active (i.e. by being activated in /etc/inittab).
767
768 This channel has the advantage that you can both attach multiple UML
769 devices to it and know how to access them without reading the UML boot
770 log. It is also unique in allowing access to a UML from remote
771 machines without requiring that the UML be networked. This could be
772 useful in allowing public access to UMLs because they would be
773 accessible from the net, but wouldn't need any kind of network
774 filtering or access control because they would have no network access.
775
776
777 If you attach the main console to a portal, then the UML boot will
778 appear to hang. In reality, it's waiting for a telnet to connect, at
779 which point the boot will proceed.
780
781
782
783
784
785 +o already-existing file descriptors - device=file descriptor
786
787
788 If you set up a file descriptor on the UML command line, you can
789 attach a UML device to it. This is most commonly used to put the
790 main console back on stdin and stdout after assigning all the other
791 consoles to something else:
792
793
794 con0=fd:0,fd:1 con=pts
795
796
797
798
799
800
801
802
803 +o Nothing - device=null
804
805
806 This allows the device to be opened, in contrast to 'none', but
807 reads will block, and writes will succeed and the data will be
808 thrown out.
809
810
811
812
813
814 +o None - device=none
815
816
817 This causes the device to disappear.
818
819
820
821 You can also specify different input and output channels for a device
822 by putting a comma between them:
823
824
825 ssl3=tty:/dev/tty2,xterm
826
827
828
829
830 will cause serial line 3 to accept input on the host's /dev/tty3 and
831 display output on an xterm. That's a silly example - the most common
832 use of this syntax is to reattach the main console to stdin and stdout
833 as shown above.
834
835
836 If you decide to move the main console away from stdin/stdout, the
837 initial boot output will appear in the terminal that you're running
838 UML in. However, once the console driver has been officially
839 initialized, then the boot output will start appearing wherever you
840 specified that console 0 should be. That device will receive all
841 subsequent output.
842
843
844
845 55..33.. EExxaammpplleess
846
847 There are a number of interesting things you can do with this
848 capability.
849
850
851 First, this is how you get rid of those bleeding console xterms by
852 attaching them to host ptys:
853
854
855 con=pty con0=fd:0,fd:1
856
857
858
859
860 This will make a UML console take over an unused host virtual console,
861 so that when you switch to it, you will see the UML login prompt
862 rather than the host login prompt:
863
864
865 con1=tty:/dev/tty6
866
867
868
869
870 You can attach two virtual machines together with what amounts to a
871 serial line as follows:
872
873 Run one UML with a serial line attached to a pty -
874
875
876 ssl1=pty
877
878
879
880
881 Look at the boot log to see what pty it got (this example will assume
882 that it got /dev/ptyp1).
883
884 Boot the other UML with a serial line attached to the corresponding
885 tty -
886
887
888 ssl1=tty:/dev/ttyp1
889
890
891
892
893 Log in, make sure that it has no getty on that serial line, attach a
894 terminal program like minicom to it, and you should see the login
895 prompt of the other virtual machine.
896
897
898 66.. SSeettttiinngg uupp tthhee nneettwwoorrkk
899
900
901
902 This page describes how to set up the various transports and to
903 provide a UML instance with network access to the host, other machines
904 on the local net, and the rest of the net.
905
906
907 As of 2.4.5, UML networking has been completely redone to make it much
908 easier to set up, fix bugs, and add new features.
909
910
911 There is a new helper, uml_net, which does the host setup that
912 requires root privileges.
913
914
915 There are currently five transport types available for a UML virtual
916 machine to exchange packets with other hosts:
917
918 +o ethertap
919
920 +o TUN/TAP
921
922 +o Multicast
923
924 +o a switch daemon
925
926 +o slip
927
928 +o slirp
929
930 +o pcap
931
932 The TUN/TAP, ethertap, slip, and slirp transports allow a UML
933 instance to exchange packets with the host. They may be directed
934 to the host or the host may just act as a router to provide access
935 to other physical or virtual machines.
936
937
938 The pcap transport is a synthetic read-only interface, using the
939 libpcap binary to collect packets from interfaces on the host and
940 filter them. This is useful for building preconfigured traffic
941 monitors or sniffers.
942
943
944 The daemon and multicast transports provide a completely virtual
945 network to other virtual machines. This network is completely
946 disconnected from the physical network unless one of the virtual
947 machines on it is acting as a gateway.
948
949
950 With so many host transports, which one should you use? Here's when
951 you should use each one:
952
953 +o ethertap - if you want access to the host networking and it is
954 running 2.2
955
956 +o TUN/TAP - if you want access to the host networking and it is
957 running 2.4. Also, the TUN/TAP transport is able to use a
958 preconfigured device, allowing it to avoid using the setuid uml_net
959 helper, which is a security advantage.
960
961 +o Multicast - if you want a purely virtual network and you don't want
962 to set up anything but the UML
963
964 +o a switch daemon - if you want a purely virtual network and you
965 don't mind running the daemon in order to get somewhat better
966 performance
967
968 +o slip - there is no particular reason to run the slip backend unless
969 ethertap and TUN/TAP are just not available for some reason
970
971 +o slirp - if you don't have root access on the host to setup
972 networking, or if you don't want to allocate an IP to your UML
973
974 +o pcap - not much use for actual network connectivity, but great for
975 monitoring traffic on the host
976
977 Ethertap is available on 2.4 and works fine. TUN/TAP is preferred
978 to it because it has better performance and ethertap is officially
979 considered obsolete in 2.4. Also, the root helper only needs to
980 run occasionally for TUN/TAP, rather than handling every packet, as
981 it does with ethertap. This is a slight security advantage since
982 it provides fewer opportunities for a nasty UML user to somehow
983 exploit the helper's root privileges.
984
985
986 66..11.. GGeenneerraall sseettuupp
987
988 First, you must have the virtual network enabled in your UML. If are
989 running a prebuilt kernel from this site, everything is already
990 enabled. If you build the kernel yourself, under the "Network device
991 support" menu, enable "Network device support", and then the three
992 transports.
993
994
995 The next step is to provide a network device to the virtual machine.
996 This is done by describing it on the kernel command line.
997
998 The general format is
999
1000
1001 eth <n> = <transport> , <transport args>
1002
1003
1004
1005
1006 For example, a virtual ethernet device may be attached to a host
1007 ethertap device as follows:
1008
1009
1010 eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
1011
1012
1013
1014
1015 This sets up eth0 inside the virtual machine to attach itself to the
1016 host /dev/tap0, assigns it an ethernet address, and assigns the host
1017 tap0 interface an IP address.
1018
1019
1020
1021 Note that the IP address you assign to the host end of the tap device
1022 must be different than the IP you assign to the eth device inside UML.
1023 If you are short on IPs and don't want to consume two per UML, then
1024 you can reuse the host's eth IP address for the host ends of the tap
1025 devices. Internally, the UMLs must still get unique IPs for their eth
1026 devices. You can also give the UMLs non-routable IPs (192.168.x.x or
1027 10.x.x.x) and have the host masquerade them. This will let outgoing
1028 connections work, but incoming connections won't without more work,
1029 such as port forwarding from the host.
1030 Also note that when you configure the host side of an interface, it is
1031 only acting as a gateway. It will respond to pings sent to it
1032 locally, but is not useful to do that since it's a host interface.
1033 You are not talking to the UML when you ping that interface and get a
1034 response.
1035
1036
1037 You can also add devices to a UML and remove them at runtime. See the
1038 ``The Management Console'' page for details.
1039
1040
1041 The sections below describe this in more detail.
1042
1043
1044 Once you've decided how you're going to set up the devices, you boot
1045 UML, log in, configure the UML side of the devices, and set up routes
1046 to the outside world. At that point, you will be able to talk to any
1047 other machines, physical or virtual, on the net.
1048
1049
1050 If ifconfig inside UML fails and the network refuses to come up, run
1051 tell you what went wrong.
1052
1053
1054
1055 66..22.. UUsseerrssppaaccee ddaaeemmoonnss
1056
1057 You will likely need the setuid helper, or the switch daemon, or both.
1058 They are both installed with the RPM and deb, so if you've installed
1059 either, you can skip the rest of this section.
1060
1061
1062 If not, then you need to check them out of CVS, build them, and
1063 install them. The helper is uml_net, in CVS /tools/uml_net, and the
1064 daemon is uml_switch, in CVS /tools/uml_router. They are both built
1065 with a plain 'make'. Both need to be installed in a directory that's
1066 in your path - /usr/bin is recommend. On top of that, uml_net needs
1067 to be setuid root.
1068
1069
1070
1071 66..33.. SSppeecciiffyyiinngg eetthheerrnneett aaddddrreesssseess
1072
1073 Below, you will see that the TUN/TAP, ethertap, and daemon interfaces
1074 allow you to specify hardware addresses for the virtual ethernet
1075 devices. This is generally not necessary. If you don't have a
1076 specific reason to do it, you probably shouldn't. If one is not
1077 specified on the command line, the driver will assign one based on the
1078 device IP address. It will provide the address fe:fd:nn:nn:nn:nn
1079 where nn.nn.nn.nn is the device IP address. This is nearly always
1080 sufficient to guarantee a unique hardware address for the device. A
1081 couple of exceptions are:
1082
1083 +o Another set of virtual ethernet devices are on the same network and
1084 they are assigned hardware addresses using a different scheme which
1085 may conflict with the UML IP address-based scheme
1086
1087 +o You aren't going to use the device for IP networking, so you don't
1088 assign the device an IP address
1089
1090 If you let the driver provide the hardware address, you should make
1091 sure that the device IP address is known before the interface is
1092 brought up. So, inside UML, this will guarantee that:
1093
1094
1095
1096 UML#
1097 ifconfig eth0 192.168.0.250 up
1098
1099
1100
1101
1102 If you decide to assign the hardware address yourself, make sure that
1103 the first byte of the address is even. Addresses with an odd first
1104 byte are broadcast addresses, which you don't want assigned to a
1105 device.
1106
1107
1108
1109 66..44.. UUMMLL iinntteerrffaaccee sseettuupp
1110
1111 Once the network devices have been described on the command line, you
1112 should boot UML and log in.
1113
1114
1115 The first thing to do is bring the interface up:
1116
1117
1118 UML# ifconfig ethn ip-address up
1119
1120
1121
1122
1123 You should be able to ping the host at this point.
1124
1125
1126 To reach the rest of the world, you should set a default route to the
1127 host:
1128
1129
1130 UML# route add default gw host ip
1131
1132
1133
1134
1135 Again, with host ip of 192.168.0.4:
1136
1137
1138 UML# route add default gw 192.168.0.4
1139
1140
1141
1142
1143 This page used to recommend setting a network route to your local net.
1144 This is wrong, because it will cause UML to try to figure out hardware
1145 addresses of the local machines by arping on the interface to the
1146 host. Since that interface is basically a single strand of ethernet
1147 with two nodes on it (UML and the host) and arp requests don't cross
1148 networks, they will fail to elicit any responses. So, what you want
1149 is for UML to just blindly throw all packets at the host and let it
1150 figure out what to do with them, which is what leaving out the network
1151 route and adding the default route does.
1152
1153
1154 Note: If you can't communicate with other hosts on your physical
1155 ethernet, it's probably because of a network route that's
1156 automatically set up. If you run 'route -n' and see a route that
1157 looks like this:
1158
1159
1160
1161
1162 Destination Gateway Genmask Flags Metric Ref Use Iface
1163 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
1164
1165
1166
1167
1168 with a mask that's not 255.255.255.255, then replace it with a route
1169 to your host:
1170
1171
1172 UML#
1173 route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0
1174
1175
1176
1177
1178
1179
1180 UML#
1181 route add -host 192.168.0.4 dev eth0
1182
1183
1184
1185
1186 This, plus the default route to the host, will allow UML to exchange
1187 packets with any machine on your ethernet.
1188
1189
1190
1191 66..55.. MMuullttiiccaasstt
1192
1193 The simplest way to set up a virtual network between multiple UMLs is
1194 to use the mcast transport. This was written by Harald Welte and is
1195 present in UML version 2.4.5-5um and later. Your system must have
1196 multicast enabled in the kernel and there must be a multicast-capable
1197 network device on the host. Normally, this is eth0, but if there is
1198 no ethernet card on the host, then you will likely get strange error
1199 messages when you bring the device up inside UML.
1200
1201
1202 To use it, run two UMLs with
1203
1204
1205 eth0=mcast
1206
1207
1208
1209
1210 on their command lines. Log in, configure the ethernet device in each
1211 machine with different IP addresses:
1212
1213
1214 UML1# ifconfig eth0 192.168.0.254
1215
1216
1217
1218
1219
1220
1221 UML2# ifconfig eth0 192.168.0.253
1222
1223
1224
1225
1226 and they should be able to talk to each other.
1227
1228 The full set of command line options for this transport are
1229
1230
1231
1232 ethn=mcast,ethernet address,multicast
1233 address,multicast port,ttl
1234
1235
1236
1237
1238 Harald's original README is here <http://user-mode-linux.source-
1239 forge.net/text/mcast.txt> and explains these in detail, as well as
1240 some other issues.
1241
1242
1243
1244 66..66.. TTUUNN//TTAAPP wwiitthh tthhee uummll__nneett hheellppeerr
1245
1246 TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the
1247 host. The TUN/TAP backend has been in UML since 2.4.9-3um.
1248
1249
1250 The easiest way to get up and running is to let the setuid uml_net
1251 helper do the host setup for you. This involves insmod-ing the tun.o
1252 module if necessary, configuring the device, and setting up IP
1253 forwarding, routing, and proxy arp. If you are new to UML networking,
1254 do this first. If you're concerned about the security implications of
1255 the setuid helper, use it to get up and running, then read the next
1256 section to see how to have UML use a preconfigured tap device, which
1257 avoids the use of uml_net.
1258
1259
1260 If you specify an IP address for the host side of the device, the
1261 uml_net helper will do all necessary setup on the host - the only
1262 requirement is that TUN/TAP be available, either built in to the host
1263 kernel or as the tun.o module.
1264
1265 The format of the command line switch to attach a device to a TUN/TAP
1266 device is
1267
1268
1269 eth <n> =tuntap,,, <IP address>
1270
1271
1272
1273
1274 For example, this argument will attach the UML's eth0 to the next
1275 available tap device and assign an ethernet address to it based on its
1276 IP address
1277
1278
1279 eth0=tuntap,,,192.168.0.254
1280
1281
1282
1283
1284
1285
1286 Note that the IP address that must be used for the eth device inside
1287 UML is fixed by the routing and proxy arp that is set up on the
1288 TUN/TAP device on the host. You can use a different one, but it won't
1289 work because reply packets won't reach the UML. This is a feature.
1290 It prevents a nasty UML user from doing things like setting the UML IP
1291 to the same as the network's nameserver or mail server.
1292
1293
1294 There are a couple potential problems with running the TUN/TAP
1295 transport on a 2.4 host kernel
1296
1297 +o TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
1298 kernel or use the ethertap transport.
1299
1300 +o With an upgraded kernel, TUN/TAP may fail with
1301
1302
1303 File descriptor in bad state
1304
1305
1306
1307
1308 This is due to a header mismatch between the upgraded kernel and the
1309 kernel that was originally installed on the machine. The fix is to
1310 make sure that /usr/src/linux points to the headers for the running
1311 kernel.
1312
1313 These were pointed out by Tim Robinson <timro at trkr dot net> in
1314 <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="this uml-
1315 user post"> .
1316
1317
1318
1319 66..77.. TTUUNN//TTAAPP wwiitthh aa pprreeccoonnffiigguurreedd ttaapp ddeevviiccee
1320
1321 If you prefer not to have UML use uml_net (which is somewhat
1322 insecure), with UML 2.4.17-11, you can set up a TUN/TAP device
1323 beforehand. The setup needs to be done as root, but once that's done,
1324 there is no need for root assistance. Setting up the device is done
1325 as follows:
1326
1327 +o Create the device with tunctl (available from the UML utilities
1328 tarball)
1329
1330
1331
1332
1333 host# tunctl -u uid
1334
1335
1336
1337
1338 where uid is the user id or username that UML will be run as. This
1339 will tell you what device was created.
1340
1341 +o Configure the device IP (change IP addresses and device name to
1342 suit)
1343
1344
1345
1346
1347 host# ifconfig tap0 192.168.0.254 up
1348
1349
1350
1351
1352
1353 +o Set up routing and arping if desired - this is my recipe, there are
1354 other ways of doing the same thing
1355
1356
1357 host#
1358 bash -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'
1359
1360 host#
1361 route add -host 192.168.0.253 dev tap0
1362
1363
1364
1365
1366
1367
1368 host#
1369 bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
1370
1371
1372
1373
1374
1375
1376 host#
1377 arp -Ds 192.168.0.253 eth0 pub
1378
1379
1380
1381
1382 Note that this must be done every time the host boots - this configu-
1383 ration is not stored across host reboots. So, it's probably a good
1384 idea to stick it in an rc file. An even better idea would be a little
1385 utility which reads the information from a config file and sets up
1386 devices at boot time.
1387
1388 +o Rather than using up two IPs and ARPing for one of them, you can
1389 also provide direct access to your LAN by the UML by using a
1390 bridge.
1391
1392
1393 host#
1394 brctl addbr br0
1395
1396
1397
1398
1399
1400
1401 host#
1402 ifconfig eth0 0.0.0.0 promisc up
1403
1404
1405
1406
1407
1408
1409 host#
1410 ifconfig tap0 0.0.0.0 promisc up
1411
1412
1413
1414
1415
1416
1417 host#
1418 ifconfig br0 192.168.0.1 netmask 255.255.255.0 up
1419
1420
1421
1422
1423
1424
1425
1426 host#
1427 brctl stp br0 off
1428
1429
1430
1431
1432
1433
1434 host#
1435 brctl setfd br0 1
1436
1437
1438
1439
1440
1441
1442 host#
1443 brctl sethello br0 1
1444
1445
1446
1447
1448
1449
1450 host#
1451 brctl addif br0 eth0
1452
1453
1454
1455
1456
1457
1458 host#
1459 brctl addif br0 tap0
1460
1461
1462
1463
1464 Note that 'br0' should be setup using ifconfig with the existing IP
1465 address of eth0, as eth0 no longer has its own IP.
1466
1467 +o
1468
1469
1470 Also, the /dev/net/tun device must be writable by the user running
1471 UML in order for the UML to use the device that's been configured
1472 for it. The simplest thing to do is
1473
1474
1475 host# chmod 666 /dev/net/tun
1476
1477
1478
1479
1480 Making it world-writable looks bad, but it seems not to be
1481 exploitable as a security hole. However, it does allow anyone to cre-
1482 ate useless tap devices (useless because they can't configure them),
1483 which is a DOS attack. A somewhat more secure alternative would to be
1484 to create a group containing all the users who have preconfigured tap
1485 devices and chgrp /dev/net/tun to that group with mode 664 or 660.
1486
1487
1488 +o Once the device is set up, run UML with 'eth0=tuntap,device name'
1489 (i.e. 'eth0=tuntap,tap0') on the command line (or do it with the
1490 mconsole config command).
1491
1492 +o Bring the eth device up in UML and you're in business.
1493
1494 If you don't want that tap device any more, you can make it non-
1495 persistent with
1496
1497
1498 host# tunctl -d tap device
1499
1500
1501
1502
1503 Finally, tunctl has a -b (for brief mode) switch which causes it to
1504 output only the name of the tap device it created. This makes it
1505 suitable for capture by a script:
1506
1507
1508 host# TAP=`tunctl -u 1000 -b`
1509
1510
1511
1512
1513
1514
1515 66..88.. EEtthheerrttaapp
1516
1517 Ethertap is the general mechanism on 2.2 for userspace processes to
1518 exchange packets with the kernel.
1519
1520
1521
1522 To use this transport, you need to describe the virtual network device
1523 on the UML command line. The general format for this is
1524
1525
1526 eth <n> =ethertap, <device> , <ethernet address> , <tap IP address>
1527
1528
1529
1530
1531 So, the previous example
1532
1533
1534 eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
1535
1536
1537
1538
1539 attaches the UML eth0 device to the host /dev/tap0, assigns it the
1540 ethernet address fe:fd:0:0:0:1, and assigns the IP address
1541 192.168.0.254 to the tap device.
1542
1543
1544
1545 The tap device is mandatory, but the others are optional. If the
1546 ethernet address is omitted, one will be assigned to it.
1547
1548
1549 The presence of the tap IP address will cause the helper to run and do
1550 whatever host setup is needed to allow the virtual machine to
1551 communicate with the outside world. If you're not sure you know what
1552 you're doing, this is the way to go.
1553
1554
1555 If it is absent, then you must configure the tap device and whatever
1556 arping and routing you will need on the host. However, even in this
1557 case, the uml_net helper still needs to be in your path and it must be
1558 setuid root if you're not running UML as root. This is because the
1559 tap device doesn't support SIGIO, which UML needs in order to use
1560 something as a source of input. So, the helper is used as a
1561 convenient asynchronous IO thread.
1562
1563 If you're using the uml_net helper, you can ignore the following host
1564 setup - uml_net will do it for you. You just need to make sure you
1565 have ethertap available, either built in to the host kernel or
1566 available as a module.
1567
1568
1569 If you want to set things up yourself, you need to make sure that the
1570 appropriate /dev entry exists. If it doesn't, become root and create
1571 it as follows:
1572
1573
1574 mknod /dev/tap <minor> c 36 <minor> + 16
1575
1576
1577
1578
1579 For example, this is how to create /dev/tap0:
1580
1581
1582 mknod /dev/tap0 c 36 0 + 16
1583
1584
1585
1586
1587 You also need to make sure that the host kernel has ethertap support.
1588 If ethertap is enabled as a module, you apparently need to insmod
1589 ethertap once for each ethertap device you want to enable. So,
1590
1591
1592 host#
1593 insmod ethertap
1594
1595
1596
1597
1598 will give you the tap0 interface. To get the tap1 interface, you need
1599 to run
1600
1601
1602 host#
1603 insmod ethertap unit=1 -o ethertap1
1604
1605
1606
1607
1608
1609
1610
1611 66..99.. TThhee sswwiittcchh ddaaeemmoonn
1612
1613 NNoottee: This is the daemon formerly known as uml_router, but which was
1614 renamed so the network weenies of the world would stop growling at me.
1615
1616
1617 The switch daemon, uml_switch, provides a mechanism for creating a
1618 totally virtual network. By default, it provides no connection to the
1619 host network (but see -tap, below).
1620
1621
1622 The first thing you need to do is run the daemon. Running it with no
1623 arguments will make it listen on a default pair of unix domain
1624 sockets.
1625
1626
1627 If you want it to listen on a different pair of sockets, use
1628
1629
1630 -unix control socket data socket
1631
1632
1633
1634
1635
1636 If you want it to act as a hub rather than a switch, use
1637
1638
1639 -hub
1640
1641
1642
1643
1644
1645 If you want the switch to be connected to host networking (allowing
1646 the umls to get access to the outside world through the host), use
1647
1648
1649 -tap tap0
1650
1651
1652
1653
1654
1655 Note that the tap device must be preconfigured (see "TUN/TAP with a
1656 preconfigured tap device", above). If you're using a different tap
1657 device than tap0, specify that instead of tap0.
1658
1659
1660 uml_switch can be backgrounded as follows
1661
1662
1663 host%
1664 uml_switch [ options ] < /dev/null > /dev/null
1665
1666
1667
1668
1669 The reason it doesn't background by default is that it listens to
1670 stdin for EOF. When it sees that, it exits.
1671
1672
1673 The general format of the kernel command line switch is
1674
1675
1676
1677 ethn=daemon,ethernet address,socket
1678 type,control socket,data socket
1679
1680
1681
1682
1683 You can leave off everything except the 'daemon'. You only need to
1684 specify the ethernet address if the one that will be assigned to it
1685 isn't acceptable for some reason. The rest of the arguments describe
1686 how to communicate with the daemon. You should only specify them if
1687 you told the daemon to use different sockets than the default. So, if
1688 you ran the daemon with no arguments, running the UML on the same
1689 machine with
1690 eth0=daemon
1691
1692
1693
1694
1695 will cause the eth0 driver to attach itself to the daemon correctly.
1696
1697
1698
1699 66..1100.. SSlliipp
1700
1701 Slip is another, less general, mechanism for a process to communicate
1702 with the host networking. In contrast to the ethertap interface,
1703 which exchanges ethernet frames with the host and can be used to
1704 transport any higher-level protocol, it can only be used to transport
1705 IP.
1706
1707
1708 The general format of the command line switch is
1709
1710
1711
1712 ethn=slip,slip IP
1713
1714
1715
1716
1717 The slip IP argument is the IP address that will be assigned to the
1718 host end of the slip device. If it is specified, the helper will run
1719 and will set up the host so that the virtual machine can reach it and
1720 the rest of the network.
1721
1722
1723 There are some oddities with this interface that you should be aware
1724 of. You should only specify one slip device on a given virtual
1725 machine, and its name inside UML will be 'umn', not 'eth0' or whatever
1726 you specified on the command line. These problems will be fixed at
1727 some point.
1728
1729
1730
1731 66..1111.. SSlliirrpp
1732
1733 slirp uses an external program, usually /usr/bin/slirp, to provide IP
1734 only networking connectivity through the host. This is similar to IP
1735 masquerading with a firewall, although the translation is performed in
1736 user-space, rather than by the kernel. As slirp does not set up any
1737 interfaces on the host, or changes routing, slirp does not require
1738 root access or setuid binaries on the host.
1739
1740
1741 The general format of the command line switch for slirp is:
1742
1743
1744
1745 ethn=slirp,ethernet address,slirp path
1746
1747
1748
1749
1750 The ethernet address is optional, as UML will set up the interface
1751 with an ethernet address based upon the initial IP address of the
1752 interface. The slirp path is generally /usr/bin/slirp, although it
1753 will depend on distribution.
1754
1755
1756 The slirp program can have a number of options passed to the command
1757 line and we can't add them to the UML command line, as they will be
1758 parsed incorrectly. Instead, a wrapper shell script can be written or
1759 the options inserted into the /.slirprc file. More information on
1760 all of the slirp options can be found in its man pages.
1761
1762
1763 The eth0 interface on UML should be set up with the IP 10.2.0.15,
1764 although you can use anything as long as it is not used by a network
1765 you will be connecting to. The default route on UML should be set to
1766 use
1767
1768
1769 UML#
1770 route add default dev eth0
1771
1772
1773
1774
1775 slirp provides a number of useful IP addresses which can be used by
1776 UML, such as 10.0.2.3 which is an alias for the DNS server specified
1777 in /etc/resolv.conf on the host or the IP given in the 'dns' option
1778 for slirp.
1779
1780
1781 Even with a baudrate setting higher than 115200, the slirp connection
1782 is limited to 115200. If you need it to go faster, the slirp binary
1783 needs to be compiled with FULL_BOLT defined in config.h.
1784
1785
1786
1787 66..1122.. ppccaapp
1788
1789 The pcap transport is attached to a UML ethernet device on the command
1790 line or with uml_mconsole with the following syntax:
1791
1792
1793
1794 ethn=pcap,host interface,filter
1795 expression,option1,option2
1796
1797
1798
1799
1800 The expression and options are optional.
1801
1802
1803 The interface is whatever network device on the host you want to
1804 sniff. The expression is a pcap filter expression, which is also what
1805 tcpdump uses, so if you know how to specify tcpdump filters, you will
1806 use the same expressions here. The options are up to two of
1807 'promisc', control whether pcap puts the host interface into
1808 promiscuous mode. 'optimize' and 'nooptimize' control whether the pcap
1809 expression optimizer is used.
1810
1811
1812 Example:
1813
1814
1815
1816 eth0=pcap,eth0,tcp
1817
1818 eth1=pcap,eth0,!tcp
1819
1820
1821
1822 will cause the UML eth0 to emit all tcp packets on the host eth0 and
1823 the UML eth1 to emit all non-tcp packets on the host eth0.
1824
1825
1826
1827 66..1133.. SSeettttiinngg uupp tthhee hhoosstt yyoouurrsseellff
1828
1829 If you don't specify an address for the host side of the ethertap or
1830 slip device, UML won't do any setup on the host. So this is what is
1831 needed to get things working (the examples use a host-side IP of
1832 192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your
1833 own network):
1834
1835 +o The device needs to be configured with its IP address. Tap devices
1836 are also configured with an mtu of 1484. Slip devices are
1837 configured with a point-to-point address pointing at the UML ip
1838 address.
1839
1840
1841 host# ifconfig tap0 arp mtu 1484 192.168.0.251 up
1842
1843
1844
1845
1846
1847
1848 host#
1849 ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up
1850
1851
1852
1853
1854
1855 +o If a tap device is being set up, a route is set to the UML IP.
1856
1857
1858 UML# route add -host 192.168.0.250 gw 192.168.0.251
1859
1860
1861
1862
1863
1864 +o To allow other hosts on your network to see the virtual machine,
1865 proxy arp is set up for it.
1866
1867
1868 host# arp -Ds 192.168.0.250 eth0 pub
1869
1870
1871
1872
1873
1874 +o Finally, the host is set up to route packets.
1875
1876
1877 host# echo 1 > /proc/sys/net/ipv4/ip_forward
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888 77.. SShhaarriinngg FFiilleessyysstteemmss bbeettwweeeenn VViirrttuuaall MMaacchhiinneess
1889
1890
1891
1892
1893 77..11.. AA wwaarrnniinngg
1894
1895 Don't attempt to share filesystems simply by booting two UMLs from the
1896 same file. That's the same thing as booting two physical machines
1897 from a shared disk. It will result in filesystem corruption.
1898
1899
1900
1901 77..22.. UUssiinngg llaayyeerreedd bblloocckk ddeevviicceess
1902
1903 The way to share a filesystem between two virtual machines is to use
1904 the copy-on-write (COW) layering capability of the ubd block driver.
1905 As of 2.4.6-2um, the driver supports layering a read-write private
1906 device over a read-only shared device. A machine's writes are stored
1907 in the private device, while reads come from either device - the
1908 private one if the requested block is valid in it, the shared one if
1909 not. Using this scheme, the majority of data which is unchanged is
1910 shared between an arbitrary number of virtual machines, each of which
1911 has a much smaller file containing the changes that it has made. With
1912 a large number of UMLs booting from a large root filesystem, this
1913 leads to a huge disk space saving. It will also help performance,
1914 since the host will be able to cache the shared data using a much
1915 smaller amount of memory, so UML disk requests will be served from the
1916 host's memory rather than its disks.
1917
1918
1919
1920
1921 To add a copy-on-write layer to an existing block device file, simply
1922 add the name of the COW file to the appropriate ubd switch:
1923
1924
1925 ubd0=root_fs_cow,root_fs_debian_22
1926
1927
1928
1929
1930 where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is
1931 the existing shared filesystem. The COW file need not exist. If it
1932 doesn't, the driver will create and initialize it. Once the COW file
1933 has been initialized, it can be used on its own on the command line:
1934
1935
1936 ubd0=root_fs_cow
1937
1938
1939
1940
1941 The name of the backing file is stored in the COW file header, so it
1942 would be redundant to continue specifying it on the command line.
1943
1944
1945
1946 77..33.. NNoottee!!
1947
1948 When checking the size of the COW file in order to see the gobs of
1949 space that you're saving, make sure you use 'ls -ls' to see the actual
1950 disk consumption rather than the length of the file. The COW file is
1951 sparse, so the length will be very different from the disk usage.
1952 Here is a 'ls -l' of a COW file and backing file from one boot and
1953 shutdown:
1954 host% ls -l cow.debian debian2.2
1955 -rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
1956 -rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
1957
1958
1959
1960
1961 Doesn't look like much saved space, does it? Well, here's 'ls -ls':
1962
1963
1964 host% ls -ls cow.debian debian2.2
1965 880 -rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
1966 525832 -rwxrw-rw- 1…Large files files are truncated, but you can click here to view the full file