blob: 628013f944c4e0c090b2e70b4d625e6942948e27 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001 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
Adrian Bunkbf6ee0a2006-10-03 22:17:48 +0200160 13.2 (obsolete)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700161 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
Linus Torvalds1da177e2005-04-16 15:20:36 -0700382 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
Adrian Bunkbf6ee0a2006-10-03 22:17:48 +0200817 This causes the device to disappear.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700818
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.
Matt LaPlante6c28f2c2006-10-03 22:46:31 +02001023 If you are short on IPs and don't want to consume two per UML, then
Linus Torvalds1da177e2005-04-16 15:20:36 -07001024 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
Matt LaPlante4ae0edc2006-11-30 04:58:40 +01001480 Making it world-writable looks bad, but it seems not to be
Linus Torvalds1da177e2005-04-16 15:20:36 -07001481 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 jdike jdike 537919488 Aug 6 20:42 debian2.2
1967
1968
1969
1970
1971 Now, you can see that the COW file has less than a meg of disk, rather
1972 than 492 meg.
1973
1974
1975
1976 77..44.. AAnnootthheerr wwaarrnniinngg
1977
1978 Once a filesystem is being used as a readonly backing file for a COW
1979 file, do not boot directly from it or modify it in any way. Doing so
1980 will invalidate any COW files that are using it. The mtime and size
1981 of the backing file are stored in the COW file header at its creation,
1982 and they must continue to match. If they don't, the driver will
1983 refuse to use the COW file.
1984
1985
1986
1987
1988 If you attempt to evade this restriction by changing either the
1989 backing file or the COW header by hand, you will get a corrupted
1990 filesystem.
1991
1992
1993
1994
1995 Among other things, this means that upgrading the distribution in a
1996 backing file and expecting that all of the COW files using it will see
1997 the upgrade will not work.
1998
1999
2000
2001
2002 77..55.. uummll__mmoooo :: MMeerrggiinngg aa CCOOWW ffiillee wwiitthh iittss bbaacckkiinngg ffiillee
2003
2004 Depending on how you use UML and COW devices, it may be advisable to
2005 merge the changes in the COW file into the backing file every once in
2006 a while.
2007
2008
2009
2010
2011 The utility that does this is uml_moo. Its usage is
2012
2013
2014 host% uml_moo COW file new backing file
2015
2016
2017
2018
2019 There's no need to specify the backing file since that information is
2020 already in the COW file header. If you're paranoid, boot the new
2021 merged file, and if you're happy with it, move it over the old backing
2022 file.
2023
2024
2025
2026
2027 uml_moo creates a new backing file by default as a safety measure. It
2028 also has a destructive merge option which will merge the COW file
2029 directly into its current backing file. This is really only usable
2030 when the backing file only has one COW file associated with it. If
2031 there are multiple COWs associated with a backing file, a -d merge of
2032 one of them will invalidate all of the others. However, it is
2033 convenient if you're short of disk space, and it should also be
Matt LaPlante992caac2006-10-03 22:52:05 +02002034 noticeably faster than a non-destructive merge.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002035
2036
2037
2038
2039 uml_moo is installed with the UML deb and RPM. If you didn't install
2040 UML from one of those packages, you can also get it from the UML
2041 utilities <http://user-mode-linux.sourceforge.net/dl-sf.html#UML
2042 utilities> tar file in tools/moo.
2043
2044
2045
2046
2047
2048
2049
2050
2051 88.. CCrreeaattiinngg ffiilleessyysstteemmss
2052
2053
2054 You may want to create and mount new UML filesystems, either because
2055 your root filesystem isn't large enough or because you want to use a
2056 filesystem other than ext2.
2057
2058
2059 This was written on the occasion of reiserfs being included in the
2060 2.4.1 kernel pool, and therefore the 2.4.1 UML, so the examples will
2061 talk about reiserfs. This information is generic, and the examples
2062 should be easy to translate to the filesystem of your choice.
2063
2064
2065 88..11.. CCrreeaattee tthhee ffiilleessyysstteemm ffiillee
2066
2067 dd is your friend. All you need to do is tell dd to create an empty
2068 file of the appropriate size. I usually make it sparse to save time
2069 and to avoid allocating disk space until it's actually used. For
2070 example, the following command will create a sparse 100 meg file full
2071 of zeroes.
2072
2073
2074 host%
2075 dd if=/dev/zero of=new_filesystem seek=100 count=1 bs=1M
2076
2077
2078
2079
2080
2081
2082 88..22.. AAssssiiggnn tthhee ffiillee ttoo aa UUMMLL ddeevviiccee
2083
2084 Add an argument like the following to the UML command line:
2085
2086 ubd4=new_filesystem
2087
2088
2089
2090
2091 making sure that you use an unassigned ubd device number.
2092
2093
2094
2095 88..33.. CCrreeaattiinngg aanndd mmoouunnttiinngg tthhee ffiilleessyysstteemm
2096
2097 Make sure that the filesystem is available, either by being built into
2098 the kernel, or available as a module, then boot up UML and log in. If
2099 the root filesystem doesn't have the filesystem utilities (mkfs, fsck,
2100 etc), then get them into UML by way of the net or hostfs.
2101
2102
2103 Make the new filesystem on the device assigned to the new file:
2104
2105
2106 host# mkreiserfs /dev/ubd/4
2107
2108
2109 <----------- MKREISERFSv2 ----------->
2110
2111 ReiserFS version 3.6.25
2112 Block size 4096 bytes
2113 Block count 25856
2114 Used blocks 8212
2115 Journal - 8192 blocks (18-8209), journal header is in block 8210
2116 Bitmaps: 17
2117 Root block 8211
2118 Hash function "r5"
2119 ATTENTION: ALL DATA WILL BE LOST ON '/dev/ubd/4'! (y/n)y
2120 journal size 8192 (from 18)
2121 Initializing journal - 0%....20%....40%....60%....80%....100%
2122 Syncing..done.
2123
2124
2125
2126
2127 Now, mount it:
2128
2129
2130 UML#
2131 mount /dev/ubd/4 /mnt
2132
2133
2134
2135
2136 and you're in business.
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146 99.. HHoosstt ffiillee aacccceessss
2147
2148
2149 If you want to access files on the host machine from inside UML, you
2150 can treat it as a separate machine and either nfs mount directories
2151 from the host or copy files into the virtual machine with scp or rcp.
Tobias Klauserd533f672005-09-10 00:26:46 -07002152 However, since UML is running on the host, it can access those
Linus Torvalds1da177e2005-04-16 15:20:36 -07002153 files just like any other process and make them available inside the
2154 virtual machine without needing to use the network.
2155
2156
2157 This is now possible with the hostfs virtual filesystem. With it, you
2158 can mount a host directory into the UML filesystem and access the
2159 files contained in it just as you would on the host.
2160
2161
2162 99..11.. UUssiinngg hhoossttffss
2163
2164 To begin with, make sure that hostfs is available inside the virtual
2165 machine with
2166
2167
2168 UML# cat /proc/filesystems
2169
2170
2171
2172 . hostfs should be listed. If it's not, either rebuild the kernel
2173 with hostfs configured into it or make sure that hostfs is built as a
2174 module and available inside the virtual machine, and insmod it.
2175
2176
2177 Now all you need to do is run mount:
2178
2179
2180 UML# mount none /mnt/host -t hostfs
2181
2182
2183
2184
2185 will mount the host's / on the virtual machine's /mnt/host.
2186
2187
2188 If you don't want to mount the host root directory, then you can
2189 specify a subdirectory to mount with the -o switch to mount:
2190
2191
2192 UML# mount none /mnt/home -t hostfs -o /home
2193
2194
2195
2196
2197 will mount the hosts's /home on the virtual machine's /mnt/home.
2198
2199
2200
2201 99..22.. hhoossttffss aass tthhee rroooott ffiilleessyysstteemm
2202
2203 It's possible to boot from a directory hierarchy on the host using
2204 hostfs rather than using the standard filesystem in a file.
2205
2206 To start, you need that hierarchy. The easiest way is to loop mount
2207 an existing root_fs file:
2208
2209
2210 host# mount root_fs uml_root_dir -o loop
2211
2212
2213
2214
2215 You need to change the filesystem type of / in etc/fstab to be
2216 'hostfs', so that line looks like this:
2217
2218 /dev/ubd/0 / hostfs defaults 1 1
2219
2220
2221
2222
2223 Then you need to chown to yourself all the files in that directory
2224 that are owned by root. This worked for me:
2225
2226
2227 host# find . -uid 0 -exec chown jdike {} \;
2228
2229
2230
2231
2232 Next, make sure that your UML kernel has hostfs compiled in, not as a
2233 module. Then run UML with the boot device pointing at that directory:
2234
2235
2236 ubd0=/path/to/uml/root/directory
2237
2238
2239
2240
2241 UML should then boot as it does normally.
2242
2243
2244 99..33.. BBuuiillddiinngg hhoossttffss
2245
2246 If you need to build hostfs because it's not in your kernel, you have
2247 two choices:
2248
2249
2250
2251 +o Compiling hostfs into the kernel:
2252
2253
2254 Reconfigure the kernel and set the 'Host filesystem' option under
2255
2256
2257 +o Compiling hostfs as a module:
2258
2259
2260 Reconfigure the kernel and set the 'Host filesystem' option under
2261 be in arch/um/fs/hostfs/hostfs.o. Install that in
2262 /lib/modules/`uname -r`/fs in the virtual machine, boot it up, and
2263
2264
2265 UML# insmod hostfs
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278 1100.. TThhee MMaannaaggeemmeenntt CCoonnssoollee
2279
2280
2281
2282 The UML management console is a low-level interface to the kernel,
2283 somewhat like the i386 SysRq interface. Since there is a full-blown
2284 operating system under UML, there is much greater flexibility possible
2285 than with the SysRq mechanism.
2286
2287
2288 There are a number of things you can do with the mconsole interface:
2289
2290 +o get the kernel version
2291
2292 +o add and remove devices
2293
2294 +o halt or reboot the machine
2295
2296 +o Send SysRq commands
2297
2298 +o Pause and resume the UML
2299
2300
2301 You need the mconsole client (uml_mconsole) which is present in CVS
2302 (/tools/mconsole) in 2.4.5-9um and later, and will be in the RPM in
2303 2.4.6.
2304
2305
2306 You also need CONFIG_MCONSOLE (under 'General Setup') enabled in UML.
2307 When you boot UML, you'll see a line like:
2308
2309
2310 mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole
2311
2312
2313
2314
2315 If you specify a unique machine id one the UML command line, i.e.
2316
2317
2318 umid=debian
2319
2320
2321
2322
2323 you'll see this
2324
2325
2326 mconsole initialized on /home/jdike/.uml/debian/mconsole
2327
2328
2329
2330
2331 That file is the socket that uml_mconsole will use to communicate with
2332 UML. Run it with either the umid or the full path as its argument:
2333
2334
2335 host% uml_mconsole debian
2336
2337
2338
2339
2340 or
2341
2342
2343 host% uml_mconsole /home/jdike/.uml/debian/mconsole
2344
2345
2346
2347
2348 You'll get a prompt, at which you can run one of these commands:
2349
2350 +o version
2351
2352 +o halt
2353
2354 +o reboot
2355
2356 +o config
2357
2358 +o remove
2359
2360 +o sysrq
2361
2362 +o help
2363
2364 +o cad
2365
2366 +o stop
2367
2368 +o go
2369
2370
2371 1100..11.. vveerrssiioonn
2372
2373 This takes no arguments. It prints the UML version.
2374
2375
2376 (mconsole) version
2377 OK Linux usermode 2.4.5-9um #1 Wed Jun 20 22:47:08 EDT 2001 i686
2378
2379
2380
2381
2382 There are a couple actual uses for this. It's a simple no-op which
2383 can be used to check that a UML is running. It's also a way of
2384 sending an interrupt to the UML. This is sometimes useful on SMP
2385 hosts, where there's a bug which causes signals to UML to be lost,
2386 often causing it to appear to hang. Sending such a UML the mconsole
2387 version command is a good way to 'wake it up' before networking has
2388 been enabled, as it does not do anything to the function of the UML.
2389
2390
2391
2392 1100..22.. hhaalltt aanndd rreebboooott
2393
2394 These take no arguments. They shut the machine down immediately, with
2395 no syncing of disks and no clean shutdown of userspace. So, they are
2396 pretty close to crashing the machine.
2397
2398
2399 (mconsole) halt
2400 OK
2401
2402
2403
2404
2405
2406
2407 1100..33.. ccoonnffiigg
2408
2409 "config" adds a new device to the virtual machine. Currently the ubd
2410 and network drivers support this. It takes one argument, which is the
2411 device to add, with the same syntax as the kernel command line.
2412
2413
2414
2415
2416 (mconsole)
2417 config ubd3=/home/jdike/incoming/roots/root_fs_debian22
2418
2419 OK
2420 (mconsole) config eth1=mcast
2421 OK
2422
2423
2424
2425
2426
2427
2428 1100..44.. rreemmoovvee
2429
2430 "remove" deletes a device from the system. Its argument is just the
2431 name of the device to be removed. The device must be idle in whatever
2432 sense the driver considers necessary. In the case of the ubd driver,
2433 the removed block device must not be mounted, swapped on, or otherwise
2434 open, and in the case of the network driver, the device must be down.
2435
2436
2437 (mconsole) remove ubd3
2438 OK
2439 (mconsole) remove eth1
2440 OK
2441
2442
2443
2444
2445
2446
2447 1100..55.. ssyyssrrqq
2448
2449 This takes one argument, which is a single letter. It calls the
2450 generic kernel's SysRq driver, which does whatever is called for by
2451 that argument. See the SysRq documentation in Documentation/sysrq.txt
2452 in your favorite kernel tree to see what letters are valid and what
2453 they do.
2454
2455
2456
2457 1100..66.. hheellpp
2458
2459 "help" returns a string listing the valid commands and what each one
2460 does.
2461
2462
2463
2464 1100..77.. ccaadd
2465
2466 This invokes the Ctl-Alt-Del action on init. What exactly this ends
2467 up doing is up to /etc/inittab. Normally, it reboots the machine.
2468 With UML, this is usually not desired, so if a halt would be better,
2469 then find the section of inittab that looks like this
2470
2471
2472 # What to do when CTRL-ALT-DEL is pressed.
2473 ca:12345:ctrlaltdel:/sbin/shutdown -t1 -a -r now
2474
2475
2476
2477
2478 and change the command to halt.
2479
2480
2481
2482 1100..88.. ssttoopp
2483
2484 This puts the UML in a loop reading mconsole requests until a 'go'
2485 mconsole command is received. This is very useful for making backups
2486 of UML filesystems, as the UML can be stopped, then synced via 'sysrq
2487 s', so that everything is written to the filesystem. You can then copy
2488 the filesystem and then send the UML 'go' via mconsole.
2489
2490
2491 Note that a UML running with more than one CPU will have problems
2492 after you send the 'stop' command, as only one CPU will be held in a
2493 mconsole loop and all others will continue as normal. This is a bug,
2494 and will be fixed.
2495
2496
2497
2498 1100..99.. ggoo
2499
2500 This resumes a UML after being paused by a 'stop' command. Note that
2501 when the UML has resumed, TCP connections may have timed out and if
2502 the UML is paused for a long period of time, crond might go a little
2503 crazy, running all the jobs it didn't do earlier.
2504
2505
2506
2507
2508
2509
2510
2511
2512 1111.. KKeerrnneell ddeebbuuggggiinngg
2513
2514
2515 NNoottee:: The interface that makes debugging, as described here, possible
2516 is present in 2.4.0-test6 kernels and later.
2517
2518
2519 Since the user-mode kernel runs as a normal Linux process, it is
2520 possible to debug it with gdb almost like any other process. It is
2521 slightly different because the kernel's threads are already being
2522 ptraced for system call interception, so gdb can't ptrace them.
2523 However, a mechanism has been added to work around that problem.
2524
2525
2526 In order to debug the kernel, you need build it from source. See
2527 ``Compiling the kernel and modules'' for information on doing that.
2528 Make sure that you enable CONFIG_DEBUGSYM and CONFIG_PT_PROXY during
2529 the config. These will compile the kernel with -g, and enable the
2530 ptrace proxy so that gdb works with UML, respectively.
2531
2532
2533
2534
2535 1111..11.. SSttaarrttiinngg tthhee kkeerrnneell uunnddeerr ggddbb
2536
2537 You can have the kernel running under the control of gdb from the
2538 beginning by putting 'debug' on the command line. You will get an
2539 xterm with gdb running inside it. The kernel will send some commands
2540 to gdb which will leave it stopped at the beginning of start_kernel.
2541 At this point, you can get things going with 'next', 'step', or
2542 'cont'.
2543
2544
2545 There is a transcript of a debugging session here <debug-
2546 session.html> , with breakpoints being set in the scheduler and in an
2547 interrupt handler.
2548 1111..22.. EExxaammiinniinngg sslleeeeppiinngg pprroocceesssseess
2549
2550 Not every bug is evident in the currently running process. Sometimes,
2551 processes hang in the kernel when they shouldn't because they've
2552 deadlocked on a semaphore or something similar. In this case, when
2553 you ^C gdb and get a backtrace, you will see the idle thread, which
2554 isn't very relevant.
2555
2556
2557 What you want is the stack of whatever process is sleeping when it
2558 shouldn't be. You need to figure out which process that is, which is
2559 generally fairly easy. Then you need to get its host process id,
2560 which you can do either by looking at ps on the host or at
2561 task.thread.extern_pid in gdb.
2562
2563
2564 Now what you do is this:
2565
2566 +o detach from the current thread
2567
2568
2569 (UML gdb) det
2570
2571
2572
2573
2574
2575 +o attach to the thread you are interested in
2576
2577
2578 (UML gdb) att <host pid>
2579
2580
2581
2582
2583
2584 +o look at its stack and anything else of interest
2585
2586
2587 (UML gdb) bt
2588
2589
2590
2591
2592 Note that you can't do anything at this point that requires that a
2593 process execute, e.g. calling a function
2594
2595 +o when you're done looking at that process, reattach to the current
2596 thread and continue it
2597
2598
2599 (UML gdb)
2600 att 1
2601
2602
2603
2604
2605
2606
2607 (UML gdb)
2608 c
2609
2610
2611
2612
2613 Here, specifying any pid which is not the process id of a UML thread
2614 will cause gdb to reattach to the current thread. I commonly use 1,
2615 but any other invalid pid would work.
2616
2617
2618
2619 1111..33.. RRuunnnniinngg dddddd oonn UUMMLL
2620
2621 ddd works on UML, but requires a special kludge. The process goes
2622 like this:
2623
2624 +o Start ddd
2625
2626
2627 host% ddd linux
2628
2629
2630
2631
2632
2633 +o With ps, get the pid of the gdb that ddd started. You can ask the
2634 gdb to tell you, but for some reason that confuses things and
2635 causes a hang.
2636
2637 +o run UML with 'debug=parent gdb-pid=<pid>' added to the command line
2638 - it will just sit there after you hit return
2639
2640 +o type 'att 1' to the ddd gdb and you will see something like
2641
2642
2643 0xa013dc51 in __kill ()
2644
2645
2646 (gdb)
2647
2648
2649
2650
2651
2652 +o At this point, type 'c', UML will boot up, and you can use ddd just
2653 as you do on any other process.
2654
2655
2656
2657 1111..44.. DDeebbuuggggiinngg mmoodduulleess
2658
2659 gdb has support for debugging code which is dynamically loaded into
2660 the process. This support is what is needed to debug kernel modules
2661 under UML.
2662
2663
2664 Using that support is somewhat complicated. You have to tell gdb what
2665 object file you just loaded into UML and where in memory it is. Then,
2666 it can read the symbol table, and figure out where all the symbols are
2667 from the load address that you provided. It gets more interesting
2668 when you load the module again (i.e. after an rmmod). You have to
2669 tell gdb to forget about all its symbols, including the main UML ones
2670 for some reason, then load then all back in again.
2671
2672
2673 There's an easy way and a hard way to do this. The easy way is to use
2674 the umlgdb expect script written by Chandan Kudige. It basically
2675 automates the process for you.
2676
2677
2678 First, you must tell it where your modules are. There is a list in
2679 the script that looks like this:
2680 set MODULE_PATHS {
2681 "fat" "/usr/src/uml/linux-2.4.18/fs/fat/fat.o"
2682 "isofs" "/usr/src/uml/linux-2.4.18/fs/isofs/isofs.o"
2683 "minix" "/usr/src/uml/linux-2.4.18/fs/minix/minix.o"
2684 }
2685
2686
2687
2688
2689 You change that to list the names and paths of the modules that you
2690 are going to debug. Then you run it from the toplevel directory of
2691 your UML pool and it basically tells you what to do:
2692
2693
2694
2695
2696 ******** GDB pid is 21903 ********
2697 Start UML as: ./linux <kernel switches> debug gdb-pid=21903
2698
2699
2700
2701 GNU gdb 5.0rh-5 Red Hat Linux 7.1
2702 Copyright 2001 Free Software Foundation, Inc.
2703 GDB is free software, covered by the GNU General Public License, and you are
2704 welcome to change it and/or distribute copies of it under certain conditions.
2705 Type "show copying" to see the conditions.
2706 There is absolutely no warranty for GDB. Type "show warranty" for details.
2707 This GDB was configured as "i386-redhat-linux"...
2708 (gdb) b sys_init_module
2709 Breakpoint 1 at 0xa0011923: file module.c, line 349.
2710 (gdb) att 1
2711
2712
2713
2714
2715 After you run UML and it sits there doing nothing, you hit return at
2716 the 'att 1' and continue it:
2717
2718
2719 Attaching to program: /home/jdike/linux/2.4/um/./linux, process 1
2720 0xa00f4221 in __kill ()
2721 (UML gdb) c
2722 Continuing.
2723
2724
2725
2726
2727 At this point, you debug normally. When you insmod something, the
2728 expect magic will kick in and you'll see something like:
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746 *** Module hostfs loaded ***
2747 Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
2748 mod_user=0x8070e00) at module.c:349
2749 349 char *name, *n_name, *name_tmp = NULL;
2750 (UML gdb) finish
2751 Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
2752 mod_user=0x8070e00) at module.c:349
2753 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
2754 411 else res = EXECUTE_SYSCALL(syscall, regs);
2755 Value returned is $1 = 0
2756 (UML gdb)
2757 p/x (int)module_list + module_list->size_of_struct
2758
2759 $2 = 0xa9021054
2760 (UML gdb) symbol-file ./linux
2761 Load new symbol table from "./linux"? (y or n) y
2762 Reading symbols from ./linux...
2763 done.
2764 (UML gdb)
2765 add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
2766
2767 add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
2768 .text_addr = 0xa9021054
2769 (y or n) y
2770
2771 Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
2772 done.
2773 (UML gdb) p *module_list
2774 $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
2775 size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
2776 nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
2777 init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
2778 ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
2779 persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
2780 kallsyms_end = 0x0,
2781 archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
2782 archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
2783 kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
2784 >> Finished loading symbols for hostfs ...
2785
2786
2787
2788
2789 That's the easy way. It's highly recommended. The hard way is
2790 described below in case you're interested in what's going on.
2791
2792
2793 Boot the kernel under the debugger and load the module with insmod or
2794 modprobe. With gdb, do:
2795
2796
2797 (UML gdb) p module_list
2798
2799
2800
2801
2802 This is a list of modules that have been loaded into the kernel, with
2803 the most recently loaded module first. Normally, the module you want
2804 is at module_list. If it's not, walk down the next links, looking at
2805 the name fields until find the module you want to debug. Take the
2806 address of that structure, and add module.size_of_struct (which in
2807 2.4.10 kernels is 96 (0x60)) to it. Gdb can make this hard addition
2808 for you :-):
2809
2810
2811
2812 (UML gdb)
2813 printf "%#x\n", (int)module_list module_list->size_of_struct
2814
2815
2816
2817
2818 The offset from the module start occasionally changes (before 2.4.0,
2819 it was module.size_of_struct + 4), so it's a good idea to check the
2820 init and cleanup addresses once in a while, as describe below. Now
2821 do:
2822
2823
2824 (UML gdb)
2825 add-symbol-file /path/to/module/on/host that_address
2826
2827
2828
2829
2830 Tell gdb you really want to do it, and you're in business.
2831
2832
2833 If there's any doubt that you got the offset right, like breakpoints
2834 appear not to work, or they're appearing in the wrong place, you can
2835 check it by looking at the module structure. The init and cleanup
2836 fields should look like:
2837
2838
2839 init = 0x588066b0 <init_hostfs>, cleanup = 0x588066c0 <exit_hostfs>
2840
2841
2842
2843
2844 with no offsets on the symbol names. If the names are right, but they
2845 are offset, then the offset tells you how much you need to add to the
2846 address you gave to add-symbol-file.
2847
2848
2849 When you want to load in a new version of the module, you need to get
2850 gdb to forget about the old one. The only way I've found to do that
2851 is to tell gdb to forget about all symbols that it knows about:
2852
2853
2854 (UML gdb) symbol-file
2855
2856
2857
2858
2859 Then reload the symbols from the kernel binary:
2860
2861
2862 (UML gdb) symbol-file /path/to/kernel
2863
2864
2865
2866
2867 and repeat the process above. You'll also need to re-enable break-
2868 points. They were disabled when you dumped all the symbols because
2869 gdb couldn't figure out where they should go.
2870
2871
2872
2873 1111..55.. AAttttaacchhiinngg ggddbb ttoo tthhee kkeerrnneell
2874
2875 If you don't have the kernel running under gdb, you can attach gdb to
2876 it later by sending the tracing thread a SIGUSR1. The first line of
2877 the console output identifies its pid:
2878 tracing thread pid = 20093
2879
2880
2881
2882
2883 When you send it the signal:
2884
2885
2886 host% kill -USR1 20093
2887
2888
2889
2890
2891 you will get an xterm with gdb running in it.
2892
2893
2894 If you have the mconsole compiled into UML, then the mconsole client
2895 can be used to start gdb:
2896
2897
2898 (mconsole) (mconsole) config gdb=xterm
2899
2900
2901
2902
2903 will fire up an xterm with gdb running in it.
2904
2905
2906
2907 1111..66.. UUssiinngg aalltteerrnnaattee ddeebbuuggggeerrss
2908
2909 UML has support for attaching to an already running debugger rather
2910 than starting gdb itself. This is present in CVS as of 17 Apr 2001.
2911 I sent it to Alan for inclusion in the ac tree, and it will be in my
2912 2.4.4 release.
2913
2914
2915 This is useful when gdb is a subprocess of some UI, such as emacs or
2916 ddd. It can also be used to run debuggers other than gdb on UML.
2917 Below is an example of using strace as an alternate debugger.
2918
2919
2920 To do this, you need to get the pid of the debugger and pass it in
2921 with the
2922
2923
2924 If you are using gdb under some UI, then tell it to 'att 1', and
2925 you'll find yourself attached to UML.
2926
2927
2928 If you are using something other than gdb as your debugger, then
2929 you'll need to get it to do the equivalent of 'att 1' if it doesn't do
2930 it automatically.
2931
2932
2933 An example of an alternate debugger is strace. You can strace the
2934 actual kernel as follows:
2935
2936 +o Run the following in a shell
2937
2938
2939 host%
2940 sh -c 'echo pid=$$; echo -n hit return; read x; exec strace -p 1 -o strace.out'
2941
2942
2943
2944 +o Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
2945 by the previous command
2946
2947 +o Hit return in the shell, and UML will start running, and strace
2948 output will start accumulating in the output file.
2949
2950 Note that this is different from running
2951
2952
2953 host% strace ./linux
2954
2955
2956
2957
2958 That will strace only the main UML thread, the tracing thread, which
2959 doesn't do any of the actual kernel work. It just oversees the vir-
2960 tual machine. In contrast, using strace as described above will show
2961 you the low-level activity of the virtual machine.
2962
2963
2964
2965
2966
2967 1122.. KKeerrnneell ddeebbuuggggiinngg eexxaammpplleess
2968
2969 1122..11.. TThhee ccaassee ooff tthhee hhuunngg ffsscckk
2970
2971 When booting up the kernel, fsck failed, and dropped me into a shell
2972 to fix things up. I ran fsck -y, which hung:
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010 Setting hostname uml [ OK ]
3011 Checking root filesystem
3012 /dev/fhd0 was not cleanly unmounted, check forced.
3013 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
3014
3015 /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
3016 (i.e., without -a or -p options)
3017 [ FAILED ]
3018
3019 *** An error occurred during the file system check.
3020 *** Dropping you to a shell; the system will reboot
3021 *** when you leave the shell.
3022 Give root password for maintenance
3023 (or type Control-D for normal startup):
3024
3025 [root@uml /root]# fsck -y /dev/fhd0
3026 fsck -y /dev/fhd0
3027 Parallelizing fsck version 1.14 (9-Jan-1999)
3028 e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
3029 /dev/fhd0 contains a file system with errors, check forced.
3030 Pass 1: Checking inodes, blocks, and sizes
3031 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
3032
3033 Inode 19780, i_blocks is 1548, should be 540. Fix? yes
3034
3035 Pass 2: Checking directory structure
3036 Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
3037
3038 Directory inode 11858, block 0, offset 0: directory corrupted
3039 Salvage? yes
3040
3041 Missing '.' in directory inode 11858.
3042 Fix? yes
3043
3044 Missing '..' in directory inode 11858.
3045 Fix? yes
3046
3047
3048
3049
3050
3051 The standard drill in this sort of situation is to fire up gdb on the
3052 signal thread, which, in this case, was pid 1935. In another window,
3053 I run gdb and attach pid 1935.
3054
3055
3056
3057
3058 ~/linux/2.3.26/um 1016: gdb linux
3059 GNU gdb 4.17.0.11 with Linux support
3060 Copyright 1998 Free Software Foundation, Inc.
3061 GDB is free software, covered by the GNU General Public License, and you are
3062 welcome to change it and/or distribute copies of it under certain conditions.
3063 Type "show copying" to see the conditions.
3064 There is absolutely no warranty for GDB. Type "show warranty" for details.
3065 This GDB was configured as "i386-redhat-linux"...
3066
3067 (gdb) att 1935
3068 Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 1935
3069 0x100756d9 in __wait4 ()
3070
3071
3072
3073
3074
3075
3076 Let's see what's currently running:
3077
3078
3079
3080 (gdb) p current_task.pid
3081 $1 = 0
3082
3083
3084
3085
3086
3087 It's the idle thread, which means that fsck went to sleep for some
3088 reason and never woke up.
3089
3090
3091 Let's guess that the last process in the process list is fsck:
3092
3093
3094
3095 (gdb) p current_task.prev_task.comm
3096 $13 = "fsck.ext2\000\000\000\000\000\000"
3097
3098
3099
3100
3101
3102 It is, so let's see what it thinks it's up to:
3103
3104
3105
3106 (gdb) p current_task.prev_task.thread
3107 $14 = {extern_pid = 1980, tracing = 0, want_tracing = 0, forking = 0,
3108 kernel_stack_page = 0, signal_stack = 1342627840, syscall = {id = 4, args = {
3109 3, 134973440, 1024, 0, 1024}, have_result = 0, result = 50590720},
3110 request = {op = 2, u = {exec = {ip = 1350467584, sp = 2952789424}, fork = {
3111 regs = {1350467584, 2952789424, 0 <repeats 15 times>}, sigstack = 0,
3112 pid = 0}, switch_to = 0x507e8000, thread = {proc = 0x507e8000,
3113 arg = 0xaffffdb0, flags = 0, new_pid = 0}, input_request = {
3114 op = 1350467584, fd = -1342177872, proc = 0, pid = 0}}}}
3115
3116
3117
3118
3119
3120 The interesting things here are the fact that its .thread.syscall.id
3121 is __NR_write (see the big switch in arch/um/kernel/syscall_kern.c or
3122 the defines in include/asm-um/arch/unistd.h), and that it never
3123 returned. Also, its .request.op is OP_SWITCH (see
3124 arch/um/include/user_util.h). These mean that it went into a write,
3125 and, for some reason, called schedule().
3126
3127
3128 The fact that it never returned from write means that its stack should
3129 be fairly interesting. Its pid is 1980 (.thread.extern_pid). That
3130 process is being ptraced by the signal thread, so it must be detached
3131 before gdb can attach it:
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142 (gdb) call detach(1980)
3143
3144 Program received signal SIGSEGV, Segmentation fault.
3145 <function called from gdb>
3146 The program being debugged stopped while in a function called from GDB.
3147 When the function (detach) is done executing, GDB will silently
3148 stop (instead of continuing to evaluate the expression containing
3149 the function call).
3150 (gdb) call detach(1980)
3151 $15 = 0
3152
3153
3154
3155
3156
3157 The first detach segfaults for some reason, and the second one
3158 succeeds.
3159
3160
3161 Now I detach from the signal thread, attach to the fsck thread, and
3162 look at its stack:
3163
3164
3165 (gdb) det
3166 Detaching from program: /home/dike/linux/2.3.26/um/linux Pid 1935
3167 (gdb) att 1980
3168 Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 1980
3169 0x10070451 in __kill ()
3170 (gdb) bt
3171 #0 0x10070451 in __kill ()
3172 #1 0x10068ccd in usr1_pid (pid=1980) at process.c:30
3173 #2 0x1006a03f in _switch_to (prev=0x50072000, next=0x507e8000)
3174 at process_kern.c:156
3175 #3 0x1006a052 in switch_to (prev=0x50072000, next=0x507e8000, last=0x50072000)
3176 at process_kern.c:161
3177 #4 0x10001d12 in schedule () at sched.c:777
3178 #5 0x1006a744 in __down (sem=0x507d241c) at semaphore.c:71
3179 #6 0x1006aa10 in __down_failed () at semaphore.c:157
3180 #7 0x1006c5d8 in segv_handler (sc=0x5006e940) at trap_user.c:174
3181 #8 0x1006c5ec in kern_segv_handler (sig=11) at trap_user.c:182
3182 #9 <signal handler called>
3183 #10 0x10155404 in errno ()
3184 #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
3185 #12 0x1006c5d8 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
3186 #13 0x1006c5ec in kern_segv_handler (sig=11) at trap_user.c:182
3187 #14 <signal handler called>
3188 #15 0xc0fd in ?? ()
3189 #16 0x10016647 in sys_write (fd=3,
3190 buf=0x80b8800 <Address 0x80b8800 out of bounds>, count=1024)
3191 at read_write.c:159
3192 #17 0x1006d5b3 in execute_syscall (syscall=4, args=0x5006ef08)
3193 at syscall_kern.c:254
3194 #18 0x1006af87 in really_do_syscall (sig=12) at syscall_user.c:35
3195 #19 <signal handler called>
3196 #20 0x400dc8b0 in ?? ()
3197
3198
3199
3200
3201
3202 The interesting things here are :
3203
3204 +o There are two segfaults on this stack (frames 9 and 14)
3205
3206 +o The first faulting address (frame 11) is 0x50000800
3207
3208 (gdb) p (void *)1342179328
3209 $16 = (void *) 0x50000800
3210
3211
3212
3213
3214
3215 The initial faulting address is interesting because it is on the idle
3216 thread's stack. I had been seeing the idle thread segfault for no
3217 apparent reason, and the cause looked like stack corruption. In hopes
3218 of catching the culprit in the act, I had turned off all protections
3219 to that stack while the idle thread wasn't running. This apparently
3220 tripped that trap.
3221
3222
3223 However, the more immediate problem is that second segfault and I'm
3224 going to concentrate on that. First, I want to see where the fault
3225 happened, so I have to go look at the sigcontent struct in frame 8:
3226
3227
3228
3229 (gdb) up
3230 #1 0x10068ccd in usr1_pid (pid=1980) at process.c:30
3231 30 kill(pid, SIGUSR1);
3232 (gdb)
3233 #2 0x1006a03f in _switch_to (prev=0x50072000, next=0x507e8000)
3234 at process_kern.c:156
3235 156 usr1_pid(getpid());
3236 (gdb)
3237 #3 0x1006a052 in switch_to (prev=0x50072000, next=0x507e8000, last=0x50072000)
3238 at process_kern.c:161
3239 161 _switch_to(prev, next);
3240 (gdb)
3241 #4 0x10001d12 in schedule () at sched.c:777
3242 777 switch_to(prev, next, prev);
3243 (gdb)
3244 #5 0x1006a744 in __down (sem=0x507d241c) at semaphore.c:71
3245 71 schedule();
3246 (gdb)
3247 #6 0x1006aa10 in __down_failed () at semaphore.c:157
3248 157 }
3249 (gdb)
3250 #7 0x1006c5d8 in segv_handler (sc=0x5006e940) at trap_user.c:174
3251 174 segv(sc->cr2, sc->err & 2);
3252 (gdb)
3253 #8 0x1006c5ec in kern_segv_handler (sig=11) at trap_user.c:182
3254 182 segv_handler(sc);
3255 (gdb) p *sc
3256 Cannot access memory at address 0x0.
3257
3258
3259
3260
3261 That's not very useful, so I'll try a more manual method:
3262
3263
3264 (gdb) p *((struct sigcontext *) (&sig + 1))
3265 $19 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
3266 __dsh = 0, edi = 1342179328, esi = 1350378548, ebp = 1342630440,
3267 esp = 1342630420, ebx = 1348150624, edx = 1280, ecx = 0, eax = 0,
3268 trapno = 14, err = 4, eip = 268480945, cs = 35, __csh = 0, eflags = 66118,
3269 esp_at_signal = 1342630420, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
3270 cr2 = 1280}
3271
3272
3273
3274 The ip is in handle_mm_fault:
3275
3276
3277 (gdb) p (void *)268480945
3278 $20 = (void *) 0x1000b1b1
3279 (gdb) i sym $20
3280 handle_mm_fault + 57 in section .text
3281
3282
3283
3284
3285
3286 Specifically, it's in pte_alloc:
3287
3288
3289 (gdb) i line *$20
3290 Line 124 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3291 starts at address 0x1000b1b1 <handle_mm_fault+57>
3292 and ends at 0x1000b1b7 <handle_mm_fault+63>.
3293
3294
3295
3296
3297
3298 To find where in handle_mm_fault this is, I'll jump forward in the
3299 code until I see an address in that procedure:
3300
3301
3302
3303 (gdb) i line *0x1000b1c0
3304 Line 126 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3305 starts at address 0x1000b1b7 <handle_mm_fault+63>
3306 and ends at 0x1000b1c3 <handle_mm_fault+75>.
3307 (gdb) i line *0x1000b1d0
3308 Line 131 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3309 starts at address 0x1000b1d0 <handle_mm_fault+88>
3310 and ends at 0x1000b1da <handle_mm_fault+98>.
3311 (gdb) i line *0x1000b1e0
3312 Line 61 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3313 starts at address 0x1000b1da <handle_mm_fault+98>
3314 and ends at 0x1000b1e1 <handle_mm_fault+105>.
3315 (gdb) i line *0x1000b1f0
3316 Line 134 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3317 starts at address 0x1000b1f0 <handle_mm_fault+120>
3318 and ends at 0x1000b200 <handle_mm_fault+136>.
3319 (gdb) i line *0x1000b200
3320 Line 135 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3321 starts at address 0x1000b200 <handle_mm_fault+136>
3322 and ends at 0x1000b208 <handle_mm_fault+144>.
3323 (gdb) i line *0x1000b210
3324 Line 139 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3325 starts at address 0x1000b210 <handle_mm_fault+152>
3326 and ends at 0x1000b219 <handle_mm_fault+161>.
3327 (gdb) i line *0x1000b220
3328 Line 1168 of "memory.c" starts at address 0x1000b21e <handle_mm_fault+166>
3329 and ends at 0x1000b222 <handle_mm_fault+170>.
3330
3331
3332
3333
3334
3335 Something is apparently wrong with the page tables or vma_structs, so
3336 lets go back to frame 11 and have a look at them:
3337
3338
3339
3340 #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
3341 50 handle_mm_fault(current, vma, address, is_write);
3342 (gdb) call pgd_offset_proc(vma->vm_mm, address)
3343 $22 = (pgd_t *) 0x80a548c
3344
3345
3346
3347
3348
3349 That's pretty bogus. Page tables aren't supposed to be in process
3350 text or data areas. Let's see what's in the vma:
3351
3352
3353 (gdb) p *vma
3354 $23 = {vm_mm = 0x507d2434, vm_start = 0, vm_end = 134512640,
3355 vm_next = 0x80a4f8c, vm_page_prot = {pgprot = 0}, vm_flags = 31200,
3356 vm_avl_height = 2058, vm_avl_left = 0x80a8c94, vm_avl_right = 0x80d1000,
3357 vm_next_share = 0xaffffdb0, vm_pprev_share = 0xaffffe63,
3358 vm_ops = 0xaffffe7a, vm_pgoff = 2952789626, vm_file = 0xafffffec,
3359 vm_private_data = 0x62}
3360 (gdb) p *vma.vm_mm
3361 $24 = {mmap = 0x507d2434, mmap_avl = 0x0, mmap_cache = 0x8048000,
3362 pgd = 0x80a4f8c, mm_users = {counter = 0}, mm_count = {counter = 134904288},
3363 map_count = 134909076, mmap_sem = {count = {counter = 135073792},
3364 sleepers = -1342177872, wait = {lock = <optimized out or zero length>,
3365 task_list = {next = 0xaffffe63, prev = 0xaffffe7a},
3366 __magic = -1342177670, __creator = -1342177300}, __magic = 98},
3367 page_table_lock = {}, context = 138, start_code = 0, end_code = 0,
3368 start_data = 0, end_data = 0, start_brk = 0, brk = 0, start_stack = 0,
3369 arg_start = 0, arg_end = 0, env_start = 0, env_end = 0, rss = 1350381536,
3370 total_vm = 0, locked_vm = 0, def_flags = 0, cpu_vm_mask = 0, swap_cnt = 0,
3371 swap_address = 0, segments = 0x0}
3372
3373
3374
3375
3376
3377 This also pretty bogus. With all of the 0x80xxxxx and 0xaffffxxx
3378 addresses, this is looking like a stack was plonked down on top of
3379 these structures. Maybe it's a stack overflow from the next page:
3380
3381
3382
3383 (gdb) p vma
3384 $25 = (struct vm_area_struct *) 0x507d2434
3385
3386
3387
3388
3389
3390 That's towards the lower quarter of the page, so that would have to
3391 have been pretty heavy stack overflow:
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406 (gdb) x/100x $25
3407 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
3408 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
3409 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
3410 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
3411 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
3412 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
3413 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
3414 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
3415 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
3416 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
3417 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
3418 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
3419 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
3420 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
3421 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
3422 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
3423 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
3424 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
3425 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
3426 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
3427 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
3428 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
3429 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
3430 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
3431 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
3432
3433
3434
3435
3436
3437 It's not stack overflow. The only "stack-like" piece of this data is
3438 the vma_struct itself.
3439
3440
3441 At this point, I don't see any avenues to pursue, so I just have to
3442 admit that I have no idea what's going on. What I will do, though, is
3443 stick a trap on the segfault handler which will stop if it sees any
3444 writes to the idle thread's stack. That was the thing that happened
3445 first, and it may be that if I can catch it immediately, what's going
3446 on will be somewhat clearer.
3447
3448
3449 1122..22.. EEppiissooddee 22:: TThhee ccaassee ooff tthhee hhuunngg ffsscckk
3450
3451 After setting a trap in the SEGV handler for accesses to the signal
3452 thread's stack, I reran the kernel.
3453
3454
3455 fsck hung again, this time by hitting the trap:
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472 Setting hostname uml [ OK ]
3473 Checking root filesystem
3474 /dev/fhd0 contains a file system with errors, check forced.
3475 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
3476
3477 /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
3478 (i.e., without -a or -p options)
3479 [ FAILED ]
3480
3481 *** An error occurred during the file system check.
3482 *** Dropping you to a shell; the system will reboot
3483 *** when you leave the shell.
3484 Give root password for maintenance
3485 (or type Control-D for normal startup):
3486
3487 [root@uml /root]# fsck -y /dev/fhd0
3488 fsck -y /dev/fhd0
3489 Parallelizing fsck version 1.14 (9-Jan-1999)
3490 e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
3491 /dev/fhd0 contains a file system with errors, check forced.
3492 Pass 1: Checking inodes, blocks, and sizes
3493 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
3494
3495 Pass 2: Checking directory structure
3496 Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
3497
3498 Directory inode 11858, block 0, offset 0: directory corrupted
3499 Salvage? yes
3500
3501 Missing '.' in directory inode 11858.
3502 Fix? yes
3503
3504 Missing '..' in directory inode 11858.
3505 Fix? yes
3506
3507 Untested (4127) [100fe44c]: trap_kern.c line 31
3508
3509
3510
3511
3512
3513 I need to get the signal thread to detach from pid 4127 so that I can
3514 attach to it with gdb. This is done by sending it a SIGUSR1, which is
3515 caught by the signal thread, which detaches the process:
3516
3517
3518 kill -USR1 4127
3519
3520
3521
3522
3523
3524 Now I can run gdb on it:
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538 ~/linux/2.3.26/um 1034: gdb linux
3539 GNU gdb 4.17.0.11 with Linux support
3540 Copyright 1998 Free Software Foundation, Inc.
3541 GDB is free software, covered by the GNU General Public License, and you are
3542 welcome to change it and/or distribute copies of it under certain conditions.
3543 Type "show copying" to see the conditions.
3544 There is absolutely no warranty for GDB. Type "show warranty" for details.
3545 This GDB was configured as "i386-redhat-linux"...
3546 (gdb) att 4127
3547 Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
3548 0x10075891 in __libc_nanosleep ()
3549
3550
3551
3552
3553
3554 The backtrace shows that it was in a write and that the fault address
3555 (address in frame 3) is 0x50000800, which is right in the middle of
3556 the signal thread's stack page:
3557
3558
3559 (gdb) bt
3560 #0 0x10075891 in __libc_nanosleep ()
3561 #1 0x1007584d in __sleep (seconds=1000000)
3562 at ../sysdeps/unix/sysv/linux/sleep.c:78
3563 #2 0x1006ce9a in stop () at user_util.c:191
3564 #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
3565 #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
3566 #5 0x1006c63c in kern_segv_handler (sig=11) at trap_user.c:182
3567 #6 <signal handler called>
3568 #7 0xc0fd in ?? ()
3569 #8 0x10016647 in sys_write (fd=3, buf=0x80b8800 "R.", count=1024)
3570 at read_write.c:159
3571 #9 0x1006d603 in execute_syscall (syscall=4, args=0x5006ef08)
3572 at syscall_kern.c:254
3573 #10 0x1006af87 in really_do_syscall (sig=12) at syscall_user.c:35
3574 #11 <signal handler called>
3575 #12 0x400dc8b0 in ?? ()
3576 #13 <signal handler called>
3577 #14 0x400dc8b0 in ?? ()
3578 #15 0x80545fd in ?? ()
3579 #16 0x804daae in ?? ()
3580 #17 0x8054334 in ?? ()
3581 #18 0x804d23e in ?? ()
3582 #19 0x8049632 in ?? ()
3583 #20 0x80491d2 in ?? ()
3584 #21 0x80596b5 in ?? ()
3585 (gdb) p (void *)1342179328
3586 $3 = (void *) 0x50000800
3587
3588
3589
3590
3591
3592 Going up the stack to the segv_handler frame and looking at where in
3593 the code the access happened shows that it happened near line 110 of
3594 block_dev.c:
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604 (gdb) up
3605 #1 0x1007584d in __sleep (seconds=1000000)
3606 at ../sysdeps/unix/sysv/linux/sleep.c:78
3607 ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
3608 (gdb)
3609 #2 0x1006ce9a in stop () at user_util.c:191
3610 191 while(1) sleep(1000000);
3611 (gdb)
3612 #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
3613 31 KERN_UNTESTED();
3614 (gdb)
3615 #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
3616 174 segv(sc->cr2, sc->err & 2);
3617 (gdb) p *sc
3618 $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
3619 __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
3620 esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
3621 err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
3622 esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
3623 cr2 = 1342179328}
3624 (gdb) p (void *)268550834
3625 $2 = (void *) 0x1001c2b2
3626 (gdb) i sym $2
3627 block_write + 1090 in section .text
3628 (gdb) i line *$2
3629 Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
3630 starts at address 0x1001c2a1 <block_write+1073>
3631 and ends at 0x1001c2bf <block_write+1103>.
3632 (gdb) i line *0x1001c2c0
3633 Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
3634 and ends at 0x1001c2e3 <block_write+1139>.
3635
3636
3637
3638
3639
3640 Looking at the source shows that the fault happened during a call to
3641 copy_to_user to copy the data into the kernel:
3642
3643
3644 107 count -= chars;
3645 108 copy_from_user(p,buf,chars);
3646 109 p += chars;
3647 110 buf += chars;
3648
3649
3650
3651
3652
3653 p is the pointer which must contain 0x50000800, since buf contains
3654 0x80b8800 (frame 8 above). It is defined as:
3655
3656
3657 p = offset + bh->b_data;
3658
3659
3660
3661
3662
3663 I need to figure out what bh is, and it just so happens that bh is
3664 passed as an argument to mark_buffer_uptodate and mark_buffer_dirty a
3665 few lines later, so I do a little disassembly:
3666
3667
3668
3669
3670 (gdb) disas 0x1001c2bf 0x1001c2e0
3671 Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
3672 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
3673 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
3674 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
3675 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
3676 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
3677 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
3678 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
3679 0x1001c2d8 <block_write+1128>: pushl $0x0
3680 0x1001c2da <block_write+1130>: pushl %edx
3681 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
3682 End of assembler dump.
3683
3684
3685
3686
3687
3688 At that point, bh is in %edx (address 0x1001c2da), which is calculated
3689 at 0x1001c2c2 as %ebp + 0xfffffdd4, so I figure exactly what that is,
3690 taking %ebp from the sigcontext_struct above:
3691
3692
3693 (gdb) p (void *)1342631484
3694 $5 = (void *) 0x5006ee3c
3695 (gdb) p 0x5006ee3c+0xfffffdd4
3696 $6 = 1342630928
3697 (gdb) p (void *)$6
3698 $7 = (void *) 0x5006ec10
3699 (gdb) p *((void **)$7)
3700 $8 = (void *) 0x50100200
3701
3702
3703
3704
3705
3706 Now, I look at the structure to see what's in it, and particularly,
3707 what its b_data field contains:
3708
3709
3710 (gdb) p *((struct buffer_head *)0x50100200)
3711 $13 = {b_next = 0x50289380, b_blocknr = 49405, b_size = 1024, b_list = 0,
3712 b_dev = 15872, b_count = {counter = 1}, b_rdev = 15872, b_state = 24,
3713 b_flushtime = 0, b_next_free = 0x501001a0, b_prev_free = 0x50100260,
3714 b_this_page = 0x501001a0, b_reqnext = 0x0, b_pprev = 0x507fcf58,
3715 b_data = 0x50000800 "", b_page = 0x50004000,
3716 b_end_io = 0x10017f60 <end_buffer_io_sync>, b_dev_id = 0x0,
3717 b_rsector = 98810, b_wait = {lock = <optimized out or zero length>,
3718 task_list = {next = 0x50100248, prev = 0x50100248}, __magic = 1343226448,
3719 __creator = 0}, b_kiobuf = 0x0}
3720
3721
3722
3723
3724
3725 The b_data field is indeed 0x50000800, so the question becomes how
3726 that happened. The rest of the structure looks fine, so this probably
3727 is not a case of data corruption. It happened on purpose somehow.
3728
3729
3730 The b_page field is a pointer to the page_struct representing the
3731 0x50000000 page. Looking at it shows the kernel's idea of the state
3732 of that page:
3733
3734
3735
3736 (gdb) p *$13.b_page
3737 $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
3738 index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
3739 next = 0x50008460, prev = 0x50019350}, wait = {
3740 lock = <optimized out or zero length>, task_list = {next = 0x50004024,
3741 prev = 0x50004024}, __magic = 1342193708, __creator = 0},
3742 pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
3743 zone = 0x100c5160}
3744
3745
3746
3747
3748
3749 Some sanity-checking: the virtual field shows the "virtual" address of
3750 this page, which in this kernel is the same as its "physical" address,
3751 and the page_struct itself should be mem_map[0], since it represents
3752 the first page of memory:
3753
3754
3755
3756 (gdb) p (void *)1342177280
3757 $18 = (void *) 0x50000000
3758 (gdb) p mem_map
3759 $19 = (mem_map_t *) 0x50004000
3760
3761
3762
3763
3764
3765 These check out fine.
3766
3767
3768 Now to check out the page_struct itself. In particular, the flags
3769 field shows whether the page is considered free or not:
3770
3771
3772 (gdb) p (void *)132
3773 $21 = (void *) 0x84
3774
3775
3776
3777
3778
3779 The "reserved" bit is the high bit, which is definitely not set, so
3780 the kernel considers the signal stack page to be free and available to
3781 be used.
3782
3783
3784 At this point, I jump to conclusions and start looking at my early
3785 boot code, because that's where that page is supposed to be reserved.
3786
3787
3788 In my setup_arch procedure, I have the following code which looks just
3789 fine:
3790
3791
3792
3793 bootmap_size = init_bootmem(start_pfn, end_pfn - start_pfn);
3794 free_bootmem(__pa(low_physmem) + bootmap_size, high_physmem - low_physmem);
3795
3796
3797
3798
3799
3800 Two stack pages have already been allocated, and low_physmem points to
3801 the third page, which is the beginning of free memory.
3802 The init_bootmem call declares the entire memory to the boot memory
3803 manager, which marks it all reserved. The free_bootmem call frees up
3804 all of it, except for the first two pages. This looks correct to me.
3805
3806
3807 So, I decide to see init_bootmem run and make sure that it is marking
3808 those first two pages as reserved. I never get that far.
3809
3810
3811 Stepping into init_bootmem, and looking at bootmem_map before looking
3812 at what it contains shows the following:
3813
3814
3815
3816 (gdb) p bootmem_map
3817 $3 = (void *) 0x50000000
3818
3819
3820
3821
3822
3823 Aha! The light dawns. That first page is doing double duty as a
3824 stack and as the boot memory map. The last thing that the boot memory
3825 manager does is to free the pages used by its memory map, so this page
3826 is getting freed even its marked as reserved.
3827
3828
3829 The fix was to initialize the boot memory manager before allocating
3830 those two stack pages, and then allocate them through the boot memory
3831 manager. After doing this, and fixing a couple of subsequent buglets,
3832 the stack corruption problem disappeared.
3833
3834
3835
3836
3837
3838 1133.. WWhhaatt ttoo ddoo wwhheenn UUMMLL ddooeessnn''tt wwoorrkk
3839
3840
3841
3842
3843 1133..11.. SSttrraannggee ccoommppiillaattiioonn eerrrroorrss wwhheenn yyoouu bbuuiilldd ffrroomm ssoouurrccee
3844
3845 As of test11, it is necessary to have "ARCH=um" in the environment or
3846 on the make command line for all steps in building UML, including
3847 clean, distclean, or mrproper, config, menuconfig, or xconfig, dep,
3848 and linux. If you forget for any of them, the i386 build seems to
3849 contaminate the UML build. If this happens, start from scratch with
3850
3851
3852 host%
3853 make mrproper ARCH=um
3854
3855
3856
3857
3858 and repeat the build process with ARCH=um on all the steps.
3859
3860
3861 See ``Compiling the kernel and modules'' for more details.
3862
3863
3864 Another cause of strange compilation errors is building UML in
3865 /usr/src/linux. If you do this, the first thing you need to do is
3866 clean up the mess you made. The /usr/src/linux/asm link will now
3867 point to /usr/src/linux/asm-um. Make it point back to
3868 /usr/src/linux/asm-i386. Then, move your UML pool someplace else and
3869 build it there. Also see below, where a more specific set of symptoms
3870 is described.
3871
3872
3873
Linus Torvalds1da177e2005-04-16 15:20:36 -07003874 1133..33.. AA vvaarriieettyy ooff ppaanniiccss aanndd hhaannggss wwiitthh //ttmmpp oonn aa rreeiisseerrffss ffiilleessyyss--
3875 tteemm
3876
3877 I saw this on reiserfs 3.5.21 and it seems to be fixed in 3.5.27.
3878 Panics preceded by
3879
3880
3881 Detaching pid nnnn
3882
3883
3884
3885 are diagnostic of this problem. This is a reiserfs bug which causes a
3886 thread to occasionally read stale data from a mmapped page shared with
3887 another thread. The fix is to upgrade the filesystem or to have /tmp
3888 be an ext2 filesystem.
3889
3890
3891
3892 1133..44.. TThhee ccoommppiillee ffaaiillss wwiitthh eerrrroorrss aabboouutt ccoonnfflliiccttiinngg ttyyppeess ffoorr
3893 ''ooppeenn'',, ''dduupp'',, aanndd ''wwaaiittppiidd''
3894
3895 This happens when you build in /usr/src/linux. The UML build makes
3896 the include/asm link point to include/asm-um. /usr/include/asm points
3897 to /usr/src/linux/include/asm, so when that link gets moved, files
3898 which need to include the asm-i386 versions of headers get the
3899 incompatible asm-um versions. The fix is to move the include/asm link
3900 back to include/asm-i386 and to do UML builds someplace else.
3901
3902
3903
3904 1133..55.. UUMMLL ddooeessnn''tt wwoorrkk wwhheenn //ttmmpp iiss aann NNFFSS ffiilleessyysstteemm
3905
Matt LaPlanted6bc8ac2006-10-03 22:54:15 +02003906 This seems to be a similar situation with the ReiserFS problem above.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003907 Some versions of NFS seems not to handle mmap correctly, which UML
Matt LaPlanted6bc8ac2006-10-03 22:54:15 +02003908 depends on. The workaround is have /tmp be a non-NFS directory.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003909
3910
3911 1133..66.. UUMMLL hhaannggss oonn bboooott wwhheenn ccoommppiilleedd wwiitthh ggpprrooff ssuuppppoorrtt
3912
3913 If you build UML with gprof support and, early in the boot, it does
3914 this
3915
3916
3917 kernel BUG at page_alloc.c:100!
3918
3919
3920
3921
3922 you have a buggy gcc. You can work around the problem by removing
3923 UM_FASTCALL from CFLAGS in arch/um/Makefile-i386. This will open up
3924 another bug, but that one is fairly hard to reproduce.
3925
3926
3927
3928 1133..77.. ssyyssllooggdd ddiieess wwiitthh aa SSIIGGTTEERRMM oonn ssttaarrttuupp
3929
3930 The exact boot error depends on the distribution that you're booting,
3931 but Debian produces this:
3932
3933
3934 /etc/rc2.d/S10sysklogd: line 49: 93 Terminated
3935 start-stop-daemon --start --quiet --exec /sbin/syslogd -- $SYSLOGD
3936
3937
3938
3939
3940 This is a syslogd bug. There's a race between a parent process
3941 installing a signal handler and its child sending the signal. See
3942 this uml-devel post <http://www.geocrawler.com/lists/3/Source-
3943 Forge/709/0/6612801> for the details.
3944
3945
3946
3947 1133..88.. TTUUNN//TTAAPP nneettwwoorrkkiinngg ddooeessnn''tt wwoorrkk oonn aa 22..44 hhoosstt
3948
3949 There are a couple of problems which were
3950 <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
3951 out"> by Tim Robinson <timro at trkr dot net>
3952
3953 +o It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
3954 The fix is to upgrade to something more recent and then read the
3955 next item.
3956
3957 +o If you see
3958
3959
3960 File descriptor in bad state
3961
3962
3963
3964 when you bring up the device inside UML, you have a header mismatch
3965 between the original kernel and the upgraded one. Make /usr/src/linux
3966 point at the new headers. This will only be a problem if you build
3967 uml_net yourself.
3968
3969
3970
3971 1133..99.. YYoouu ccaann nneettwwoorrkk ttoo tthhee hhoosstt bbuutt nnoott ttoo ootthheerr mmaacchhiinneess oonn tthhee
3972 nneett
3973
3974 If you can connect to the host, and the host can connect to UML, but
Matt LaPlante84eb8d02006-10-03 22:53:09 +02003975 you cannot connect to any other machines, then you may need to enable
Linus Torvalds1da177e2005-04-16 15:20:36 -07003976 IP Masquerading on the host. Usually this is only experienced when
3977 using private IP addresses (192.168.x.x or 10.x.x.x) for host/UML
3978 networking, rather than the public address space that your host is
3979 connected to. UML does not enable IP Masquerading, so you will need
3980 to create a static rule to enable it:
3981
3982
3983 host%
3984 iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
3985
3986
3987
3988
3989 Replace eth0 with the interface that you use to talk to the rest of
3990 the world.
3991
3992
3993 Documentation on IP Masquerading, and SNAT, can be found at
3994 www.netfilter.org <http://www.netfilter.org> .
3995
3996
3997 If you can reach the local net, but not the outside Internet, then
3998 that is usually a routing problem. The UML needs a default route:
3999
4000
4001 UML#
4002 route add default gw gateway IP
4003
4004
4005
4006
4007 The gateway IP can be any machine on the local net that knows how to
4008 reach the outside world. Usually, this is the host or the local net-
4009 work's gateway.
4010
4011
4012 Occasionally, we hear from someone who can reach some machines, but
4013 not others on the same net, or who can reach some ports on other
4014 machines, but not others. These are usually caused by strange
4015 firewalling somewhere between the UML and the other box. You track
4016 this down by running tcpdump on every interface the packets travel
4017 over and see where they disappear. When you find a machine that takes
4018 the packets in, but does not send them onward, that's the culprit.
4019
4020
4021
4022 1133..1100.. II hhaavvee nnoo rroooott aanndd II wwaanntt ttoo ssccrreeaamm
4023
4024 Thanks to Birgit Wahlich for telling me about this strange one. It
4025 turns out that there's a limit of six environment variables on the
4026 kernel command line. When that limit is reached or exceeded, argument
4027 processing stops, which means that the 'root=' argument that UML
4028 usually adds is not seen. So, the filesystem has no idea what the
4029 root device is, so it panics.
4030
4031
4032 The fix is to put less stuff on the command line. Glomming all your
4033 setup variables into one is probably the best way to go.
4034
4035
4036
4037 1133..1111.. UUMMLL bbuuiilldd ccoonnfflliicctt bbeettwweeeenn ppttrraaccee..hh aanndd uuccoonntteexxtt..hh
4038
4039 On some older systems, /usr/include/asm/ptrace.h and
4040 /usr/include/sys/ucontext.h define the same names. So, when they're
4041 included together, the defines from one completely mess up the parsing
4042 of the other, producing errors like:
4043 /usr/include/sys/ucontext.h:47: parse error before
4044 `10'
4045
4046
4047
4048
4049 plus a pile of warnings.
4050
4051
4052 This is a libc botch, which has since been fixed, and I don't see any
4053 way around it besides upgrading.
4054
4055
4056
4057 1133..1122.. TThhee UUMMLL BBooggooMMiippss iiss eexxaaccttllyy hhaallff tthhee hhoosstt''ss BBooggooMMiippss
4058
4059 On i386 kernels, there are two ways of running the loop that is used
4060 to calculate the BogoMips rating, using the TSC if it's there or using
4061 a one-instruction loop. The TSC produces twice the BogoMips as the
4062 loop. UML uses the loop, since it has nothing resembling a TSC, and
4063 will get almost exactly the same BogoMips as a host using the loop.
4064 However, on a host with a TSC, its BogoMips will be double the loop
4065 BogoMips, and therefore double the UML BogoMips.
4066
4067
4068
4069 1133..1133.. WWhheenn yyoouu rruunn UUMMLL,, iitt iimmmmeeddiiaatteellyy sseeggffaauullttss
4070
4071 If the host is configured with the 2G/2G address space split, that's
4072 why. See ``UML on 2G/2G hosts'' for the details on getting UML to
4073 run on your host.
4074
4075
4076
4077 1133..1144.. xxtteerrmmss aappppeeaarr,, tthheenn iimmmmeeddiiaatteellyy ddiissaappppeeaarr
4078
4079 If you're running an up to date kernel with an old release of
4080 uml_utilities, the port-helper program will not work properly, so
4081 xterms will exit straight after they appear. The solution is to
4082 upgrade to the latest release of uml_utilities. Usually this problem
4083 occurs when you have installed a packaged release of UML then compiled
4084 your own development kernel without upgrading the uml_utilities from
4085 the source distribution.
4086
4087
4088
4089 1133..1155.. AAnnyy ootthheerr ppaanniicc,, hhaanngg,, oorr ssttrraannggee bbeehhaavviioorr
4090
4091 If you're seeing truly strange behavior, such as hangs or panics that
4092 happen in random places, or you try running the debugger to see what's
4093 happening and it acts strangely, then it could be a problem in the
4094 host kernel. If you're not running a stock Linus or -ac kernel, then
4095 try that. An early version of the preemption patch and a 2.4.10 SuSE
4096 kernel have caused very strange problems in UML.
4097
4098
4099 Otherwise, let me know about it. Send a message to one of the UML
4100 mailing lists - either the developer list - user-mode-linux-devel at
4101 lists dot sourceforge dot net (subscription info) or the user list -
4102 user-mode-linux-user at lists dot sourceforge do net (subscription
4103 info), whichever you prefer. Don't assume that everyone knows about
4104 it and that a fix is imminent.
4105
4106
4107 If you want to be super-helpful, read ``Diagnosing Problems'' and
4108 follow the instructions contained therein.
4109 1144.. DDiiaaggnnoossiinngg PPrroobblleemmss
4110
4111
4112 If you get UML to crash, hang, or otherwise misbehave, you should
4113 report this on one of the project mailing lists, either the developer
4114 list - user-mode-linux-devel at lists dot sourceforge dot net
4115 (subscription info) or the user list - user-mode-linux-user at lists
4116 dot sourceforge dot net (subscription info). When you do, it is
4117 likely that I will want more information. So, it would be helpful to
4118 read the stuff below, do whatever is applicable in your case, and
4119 report the results to the list.
4120
4121
4122 For any diagnosis, you're going to need to build a debugging kernel.
4123 The binaries from this site aren't debuggable. If you haven't done
4124 this before, read about ``Compiling the kernel and modules'' and
4125 ``Kernel debugging'' UML first.
4126
4127
4128 1144..11.. CCaassee 11 :: NNoorrmmaall kkeerrnneell ppaanniiccss
4129
4130 The most common case is for a normal thread to panic. To debug this,
4131 you will need to run it under the debugger (add 'debug' to the command
4132 line). An xterm will start up with gdb running inside it. Continue
4133 it when it stops in start_kernel and make it crash. Now ^C gdb and
4134
4135
4136 If the panic was a "Kernel mode fault", then there will be a segv
4137 frame on the stack and I'm going to want some more information. The
4138 stack might look something like this:
4139
4140
4141 (UML gdb) backtrace
4142 #0 0x1009bf76 in __sigprocmask (how=1, set=0x5f347940, oset=0x0)
4143 at ../sysdeps/unix/sysv/linux/sigprocmask.c:49
4144 #1 0x10091411 in change_sig (signal=10, on=1) at process.c:218
4145 #2 0x10094785 in timer_handler (sig=26) at time_kern.c:32
4146 #3 0x1009bf38 in __restore ()
4147 at ../sysdeps/unix/sysv/linux/i386/sigaction.c:125
4148 #4 0x1009534c in segv (address=8, ip=268849158, is_write=2, is_user=0)
4149 at trap_kern.c:66
4150 #5 0x10095c04 in segv_handler (sig=11) at trap_user.c:285
4151 #6 0x1009bf38 in __restore ()
4152
4153
4154
4155
4156 I'm going to want to see the symbol and line information for the value
4157 of ip in the segv frame. In this case, you would do the following:
4158
4159
4160 (UML gdb) i sym 268849158
4161
4162
4163
4164
4165 and
4166
4167
4168 (UML gdb) i line *268849158
4169
4170
4171
4172
4173 The reason for this is the __restore frame right above the segv_han-
4174 dler frame is hiding the frame that actually segfaulted. So, I have
4175 to get that information from the faulting ip.
4176
4177
4178 1144..22.. CCaassee 22 :: TTrraacciinngg tthhrreeaadd ppaanniiccss
4179
4180 The less common and more painful case is when the tracing thread
4181 panics. In this case, the kernel debugger will be useless because it
4182 needs a healthy tracing thread in order to work. The first thing to
4183 do is get a backtrace from the tracing thread. This is done by
4184 figuring out what its pid is, firing up gdb, and attaching it to that
4185 pid. You can figure out the tracing thread pid by looking at the
4186 first line of the console output, which will look like this:
4187
4188
4189 tracing thread pid = 15851
4190
4191
4192
4193
4194 or by running ps on the host and finding the line that looks like
4195 this:
4196
4197
4198 jdike 15851 4.5 0.4 132568 1104 pts/0 S 21:34 0:05 ./linux [(tracing thread)]
4199
4200
4201
4202
4203 If the panic was 'segfault in signals', then follow the instructions
4204 above for collecting information about the location of the seg fault.
4205
4206
4207 If the tracing thread flaked out all by itself, then send that
4208 backtrace in and wait for our crack debugging team to fix the problem.
4209
4210
4211 1144..33.. CCaassee 33 :: TTrraacciinngg tthhrreeaadd ppaanniiccss ccaauusseedd bbyy ootthheerr tthhrreeaaddss
4212
4213 However, there are cases where the misbehavior of another thread
4214 caused the problem. The most common panic of this type is:
4215
4216
4217 wait_for_stop failed to wait for <pid> to stop with <signal number>
4218
4219
4220
4221
4222 In this case, you'll need to get a backtrace from the process men-
4223 tioned in the panic, which is complicated by the fact that the kernel
4224 debugger is defunct and without some fancy footwork, another gdb can't
4225 attach to it. So, this is how the fancy footwork goes:
4226
4227 In a shell:
4228
4229
4230 host% kill -STOP pid
4231
4232
4233
4234
4235 Run gdb on the tracing thread as described in case 2 and do:
4236
4237
4238 (host gdb) call detach(pid)
4239
4240
4241 If you get a segfault, do it again. It always works the second time.
4242
4243 Detach from the tracing thread and attach to that other thread:
4244
4245
4246 (host gdb) detach
4247
4248
4249
4250
4251
4252
4253 (host gdb) attach pid
4254
4255
4256
4257
4258 If gdb hangs when attaching to that process, go back to a shell and
4259 do:
4260
4261
4262 host%
4263 kill -CONT pid
4264
4265
4266
4267
4268 And then get the backtrace:
4269
4270
4271 (host gdb) backtrace
4272
4273
4274
4275
4276
4277 1144..44.. CCaassee 44 :: HHaannggss
4278
4279 Hangs seem to be fairly rare, but they sometimes happen. When a hang
4280 happens, we need a backtrace from the offending process. Run the
4281 kernel debugger as described in case 1 and get a backtrace. If the
4282 current process is not the idle thread, then send in the backtrace.
4283 You can tell that it's the idle thread if the stack looks like this:
4284
4285
4286 #0 0x100b1401 in __libc_nanosleep ()
4287 #1 0x100a2885 in idle_sleep (secs=10) at time.c:122
4288 #2 0x100a546f in do_idle () at process_kern.c:445
4289 #3 0x100a5508 in cpu_idle () at process_kern.c:471
4290 #4 0x100ec18f in start_kernel () at init/main.c:592
4291 #5 0x100a3e10 in start_kernel_proc (unused=0x0) at um_arch.c:71
4292 #6 0x100a383f in signal_tramp (arg=0x100a3dd8) at trap_user.c:50
4293
4294
4295
4296
4297 If this is the case, then some other process is at fault, and went to
4298 sleep when it shouldn't have. Run ps on the host and figure out which
4299 process should not have gone to sleep and stayed asleep. Then attach
4300 to it with gdb and get a backtrace as described in case 3.
4301
4302
4303
4304
4305
4306
4307 1155.. TThhaannkkss
4308
4309
4310 A number of people have helped this project in various ways, and this
4311 page gives recognition where recognition is due.
4312
4313
4314 If you're listed here and you would prefer a real link on your name,
4315 or no link at all, instead of the despammed email address pseudo-link,
4316 let me know.
4317
4318
4319 If you're not listed here and you think maybe you should be, please
4320 let me know that as well. I try to get everyone, but sometimes my
4321 bookkeeping lapses and I forget about contributions.
4322
4323
4324 1155..11.. CCooddee aanndd DDooccuummeennttaattiioonn
4325
4326 Rusty Russell <rusty at linuxcare.com.au> -
4327
4328 +o wrote the HOWTO <http://user-mode-
4329 linux.sourceforge.net/UserModeLinux-HOWTO.html>
4330
4331 +o prodded me into making this project official and putting it on
4332 SourceForge
4333
4334 +o came up with the way cool UML logo <http://user-mode-
4335 linux.sourceforge.net/uml-small.png>
4336
4337 +o redid the config process
4338
4339
4340 Peter Moulder <reiter at netspace.net.au> - Fixed my config and build
4341 processes, and added some useful code to the block driver
4342
4343
4344 Bill Stearns <wstearns at pobox.com> -
4345
4346 +o HOWTO updates
4347
4348 +o lots of bug reports
4349
4350 +o lots of testing
4351
4352 +o dedicated a box (uml.ists.dartmouth.edu) to support UML development
4353
4354 +o wrote the mkrootfs script, which allows bootable filesystems of
4355 RPM-based distributions to be cranked out
4356
4357 +o cranked out a large number of filesystems with said script
4358
4359
4360 Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
4361 and associated usermode tools
4362
4363 Lars Brinkhoff <http://lars.nocrew.org/> - Contributed the ptrace
4364 proxy from his own project <http://a386.nocrew.org/> to allow easier
4365 kernel debugging
4366
4367
4368 Andrea Arcangeli <andrea at suse.de> - Redid some of the early boot
4369 code so that it would work on machines with Large File Support
4370
4371
4372 Chris Emerson <http://www.chiark.greenend.org.uk/~cemerson/> - Did
4373 the first UML port to Linux/ppc
4374
4375
4376 Harald Welte <laforge at gnumonks.org> - Wrote the multicast
4377 transport for the network driver
4378
4379
4380 Jorgen Cederlof - Added special file support to hostfs
4381
4382
4383 Greg Lonnon <glonnon at ridgerun dot com> - Changed the ubd driver
4384 to allow it to layer a COW file on a shared read-only filesystem and
4385 wrote the iomem emulation support
4386
4387
4388 Henrik Nordstrom <http://hem.passagen.se/hno/> - Provided a variety
4389 of patches, fixes, and clues
4390
4391
4392 Lennert Buytenhek - Contributed various patches, a rewrite of the
4393 network driver, the first implementation of the mconsole driver, and
4394 did the bulk of the work needed to get SMP working again.
4395
4396
4397 Yon Uriarte - Fixed the TUN/TAP network backend while I slept.
4398
4399
4400 Adam Heath - Made a bunch of nice cleanups to the initialization code,
4401 plus various other small patches.
4402
4403
4404 Matt Zimmerman - Matt volunteered to be the UML Debian maintainer and
4405 is doing a real nice job of it. He also noticed and fixed a number of
4406 actually and potentially exploitable security holes in uml_net. Plus
4407 the occasional patch. I like patches.
4408
4409
4410 James McMechan - James seems to have taken over maintenance of the ubd
4411 driver and is doing a nice job of it.
4412
4413
4414 Chandan Kudige - wrote the umlgdb script which automates the reloading
4415 of module symbols.
4416
4417
4418 Steve Schmidtke - wrote the UML slirp transport and hostaudio drivers,
4419 enabling UML processes to access audio devices on the host. He also
4420 submitted patches for the slip transport and lots of other things.
4421
4422
4423 David Coulson <http://davidcoulson.net> -
4424
4425 +o Set up the usermodelinux.org <http://usermodelinux.org> site,
4426 which is a great way of keeping the UML user community on top of
4427 UML goings-on.
4428
4429 +o Site documentation and updates
4430
4431 +o Nifty little UML management daemon UMLd
4432 <http://uml.openconsultancy.com/umld/>
4433
4434 +o Lots of testing and bug reports
4435
4436
4437
4438
4439 1155..22.. FFlluusshhiinngg oouutt bbuuggss
4440
4441
4442
4443 +o Yuri Pudgorodsky
4444
4445 +o Gerald Britton
4446
4447 +o Ian Wehrman
4448
4449 +o Gord Lamb
4450
4451 +o Eugene Koontz
4452
4453 +o John H. Hartman
4454
4455 +o Anders Karlsson
4456
4457 +o Daniel Phillips
4458
4459 +o John Fremlin
4460
4461 +o Rainer Burgstaller
4462
4463 +o James Stevenson
4464
4465 +o Matt Clay
4466
4467 +o Cliff Jefferies
4468
4469 +o Geoff Hoff
4470
4471 +o Lennert Buytenhek
4472
4473 +o Al Viro
4474
4475 +o Frank Klingenhoefer
4476
4477 +o Livio Baldini Soares
4478
4479 +o Jon Burgess
4480
4481 +o Petru Paler
4482
4483 +o Paul
4484
4485 +o Chris Reahard
4486
4487 +o Sverker Nilsson
4488
4489 +o Gong Su
4490
4491 +o johan verrept
4492
4493 +o Bjorn Eriksson
4494
4495 +o Lorenzo Allegrucci
4496
4497 +o Muli Ben-Yehuda
4498
4499 +o David Mansfield
4500
4501 +o Howard Goff
4502
4503 +o Mike Anderson
4504
4505 +o John Byrne
4506
4507 +o Sapan J. Batia
4508
4509 +o Iris Huang
4510
4511 +o Jan Hudec
4512
4513 +o Voluspa
4514
4515
4516
4517
4518 1155..33.. BBuugglleettss aanndd cclleeaann--uuppss
4519
4520
4521
4522 +o Dave Zarzycki
4523
4524 +o Adam Lazur
4525
4526 +o Boria Feigin
4527
4528 +o Brian J. Murrell
4529
4530 +o JS
4531
4532 +o Roman Zippel
4533
4534 +o Wil Cooley
4535
4536 +o Ayelet Shemesh
4537
4538 +o Will Dyson
4539
4540 +o Sverker Nilsson
4541
4542 +o dvorak
4543
4544 +o v.naga srinivas
4545
4546 +o Shlomi Fish
4547
4548 +o Roger Binns
4549
4550 +o johan verrept
4551
4552 +o MrChuoi
4553
4554 +o Peter Cleve
4555
4556 +o Vincent Guffens
4557
4558 +o Nathan Scott
4559
4560 +o Patrick Caulfield
4561
4562 +o jbearce
4563
4564 +o Catalin Marinas
4565
4566 +o Shane Spencer
4567
4568 +o Zou Min
4569
4570
4571 +o Ryan Boder
4572
4573 +o Lorenzo Colitti
4574
4575 +o Gwendal Grignou
4576
4577 +o Andre' Breiler
4578
4579 +o Tsutomu Yasuda
4580
4581
4582
4583 1155..44.. CCaassee SSttuuddiieess
4584
4585
4586 +o Jon Wright
4587
4588 +o William McEwan
4589
4590 +o Michael Richardson
4591
4592
4593
4594 1155..55.. OOtthheerr ccoonnttrriibbuuttiioonnss
4595
4596
4597 Bill Carr <Bill.Carr at compaq.com> made the Red Hat mkrootfs script
4598 work with RH 6.2.
4599
4600 Michael Jennings <mikejen at hevanet.com> sent in some material which
4601 is now gracing the top of the index page <http://user-mode-
4602 linux.sourceforge.net/index.html> of this site.
4603
4604 SGI <http://www.sgi.com> (and more specifically Ralf Baechle <ralf at
4605 uni-koblenz.de> ) gave me an account on oss.sgi.com
4606 <http://www.oss.sgi.com> . The bandwidth there made it possible to
4607 produce most of the filesystems available on the project download
4608 page.
4609
4610 Laurent Bonnaud <Laurent.Bonnaud at inpg.fr> took the old grotty
4611 Debian filesystem that I've been distributing and updated it to 2.2.
4612 It is now available by itself here.
4613
4614 Rik van Riel gave me some ftp space on ftp.nl.linux.org so I can make
4615 releases even when Sourceforge is broken.
4616
4617 Rodrigo de Castro looked at my broken pte code and told me what was
4618 wrong with it, letting me fix a long-standing (several weeks) and
4619 serious set of bugs.
4620
4621 Chris Reahard built a specialized root filesystem for running a DNS
4622 server jailed inside UML. It's available from the download
4623 <http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
Matt LaPlantea2ffd272006-10-03 22:49:15 +02004624 Filesystems section.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636