aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/uml/UserModeLinux-HOWTO.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/uml/UserModeLinux-HOWTO.txt')
-rw-r--r--Documentation/uml/UserModeLinux-HOWTO.txt4686
1 files changed, 4686 insertions, 0 deletions
diff --git a/Documentation/uml/UserModeLinux-HOWTO.txt b/Documentation/uml/UserModeLinux-HOWTO.txt
new file mode 100644
index 000000000000..0c7b654fec99
--- /dev/null
+++ b/Documentation/uml/UserModeLinux-HOWTO.txt
@@ -0,0 +1,4686 @@
1 User Mode Linux HOWTO
2 User Mode Linux Core Team
3 Mon Nov 18 14:16:16 EST 2002
4
5 This document describes the use and abuse of Jeff Dike's User Mode
6 Linux: a port of the Linux kernel as a normal Intel Linux process.
7 ______________________________________________________________________
8
9 Table of Contents
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67 1. Introduction
68
69 1.1 How is User Mode Linux Different?
70 1.2 Why Would I Want User Mode Linux?
71
72 2. Compiling the kernel and modules
73
74 2.1 Compiling the kernel
75 2.2 Compiling and installing kernel modules
76 2.3 Compiling and installing uml_utilities
77
78 3. Running UML and logging in
79
80 3.1 Running UML
81 3.2 Logging in
82 3.3 Examples
83
84 4. UML on 2G/2G hosts
85
86 4.1 Introduction
87 4.2 The problem
88 4.3 The solution
89
90 5. Setting up serial lines and consoles
91
92 5.1 Specifying the device
93 5.2 Specifying the channel
94 5.3 Examples
95
96 6. Setting up the network
97
98 6.1 General setup
99 6.2 Userspace daemons
100 6.3 Specifying ethernet addresses
101 6.4 UML interface setup
102 6.5 Multicast
103 6.6 TUN/TAP with the uml_net helper
104 6.7 TUN/TAP with a preconfigured tap device
105 6.8 Ethertap
106 6.9 The switch daemon
107 6.10 Slip
108 6.11 Slirp
109 6.12 pcap
110 6.13 Setting up the host yourself
111
112 7. Sharing Filesystems between Virtual Machines
113
114 7.1 A warning
115 7.2 Using layered block devices
116 7.3 Note!
117 7.4 Another warning
118 7.5 uml_moo : Merging a COW file with its backing file
119
120 8. Creating filesystems
121
122 8.1 Create the filesystem file
123 8.2 Assign the file to a UML device
124 8.3 Creating and mounting the filesystem
125
126 9. Host file access
127
128 9.1 Using hostfs
129 9.2 hostfs as the root filesystem
130 9.3 Building hostfs
131
132 10. The Management Console
133 10.1 version
134 10.2 halt and reboot
135 10.3 config
136 10.4 remove
137 10.5 sysrq
138 10.6 help
139 10.7 cad
140 10.8 stop
141 10.9 go
142
143 11. Kernel debugging
144
145 11.1 Starting the kernel under gdb
146 11.2 Examining sleeping processes
147 11.3 Running ddd on UML
148 11.4 Debugging modules
149 11.5 Attaching gdb to the kernel
150 11.6 Using alternate debuggers
151
152 12. Kernel debugging examples
153
154 12.1 The case of the hung fsck
155 12.2 Episode 2: The case of the hung fsck
156
157 13. What to do when UML doesn't work
158
159 13.1 Strange compilation errors when you build from source
160 13.2 UML hangs on boot after mounting devfs
161 13.3 A variety of panics and hangs with /tmp on a reiserfs filesystem
162 13.4 The compile fails with errors about conflicting types for 'open', 'dup', and 'waitpid'
163 13.5 UML doesn't work when /tmp is an NFS filesystem
164 13.6 UML hangs on boot when compiled with gprof support
165 13.7 syslogd dies with a SIGTERM on startup
166 13.8 TUN/TAP networking doesn't work on a 2.4 host
167 13.9 You can network to the host but not to other machines on the net
168 13.10 I have no root and I want to scream
169 13.11 UML build conflict between ptrace.h and ucontext.h
170 13.12 The UML BogoMips is exactly half the host's BogoMips
171 13.13 When you run UML, it immediately segfaults
172 13.14 xterms appear, then immediately disappear
173 13.15 Any other panic, hang, or strange behavior
174
175 14. Diagnosing Problems
176
177 14.1 Case 1 : Normal kernel panics
178 14.2 Case 2 : Tracing thread panics
179 14.3 Case 3 : Tracing thread panics caused by other threads
180 14.4 Case 4 : Hangs
181
182 15. Thanks
183
184 15.1 Code and Documentation
185 15.2 Flushing out bugs
186 15.3 Buglets and clean-ups
187 15.4 Case Studies
188 15.5 Other contributions
189
190
191 ______________________________________________________________________
192
193 11.. IInnttrroodduuccttiioonn
194
195 Welcome to User Mode Linux. It's going to be fun.
196
197
198
199 11..11.. HHooww iiss UUsseerr MMooddee LLiinnuuxx DDiiffffeerreenntt??
200
201 Normally, the Linux Kernel talks straight to your hardware (video
202 card, keyboard, hard drives, etc), and any programs which run ask the
203 kernel to operate the hardware, like so:
204
205
206
207 +-----------+-----------+----+
208 | Process 1 | Process 2 | ...|
209 +-----------+-----------+----+
210 | Linux Kernel |
211 +----------------------------+
212 | Hardware |
213 +----------------------------+
214
215
216
217
218 The User Mode Linux Kernel is different; instead of talking to the
219 hardware, it talks to a `real' Linux kernel (called the `host kernel'
220 from now on), like any other program. Programs can then run inside
221 User-Mode Linux as if they were running under a normal kernel, like
222 so:
223
224
225
226 +----------------+
227 | Process 2 | ...|
228 +-----------+----------------+
229 | Process 1 | User-Mode Linux|
230 +----------------------------+
231 | Linux Kernel |
232 +----------------------------+
233 | Hardware |
234 +----------------------------+
235
236
237
238
239
240 11..22.. WWhhyy WWoouulldd II WWaanntt UUsseerr MMooddee LLiinnuuxx??
241
242
243 1. If User Mode Linux crashes, your host kernel is still fine.
244
245 2. You can run a usermode kernel as a non-root user.
246
247 3. You can debug the User Mode Linux like any normal process.
248
249 4. You can run gprof (profiling) and gcov (coverage testing).
250
251 5. You can play with your kernel without breaking things.
252
253 6. You can use it as a sandbox for testing new apps.
254
255 7. You can try new development kernels safely.
256
257 8. You can run different distributions simultaneously.
258
259 9. It's extremely fun.
260
261
262
263
264
265 22.. CCoommppiilliinngg tthhee kkeerrnneell aanndd mmoodduulleess
266
267
268
269
270 22..11.. CCoommppiilliinngg tthhee kkeerrnneell
271
272
273 Compiling the user mode kernel is just like compiling any other
274 kernel. Let's go through the steps, using 2.4.0-prerelease (current
275 as of this writing) as an example:
276
277
278 1. Download the latest UML patch from
279
280 the download page <http://user-mode-linux.sourceforge.net/dl-
281 sf.html>
282
283 In this example, the file is uml-patch-2.4.0-prerelease.bz2.
284
285
286 2. Download the matching kernel from your favourite kernel mirror,
287 such as:
288
289 ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
290 <ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2>
291 .
292
293
294 3. Make a directory and unpack the kernel into it.
295
296
297
298 host%
299 mkdir ~/uml
300
301
302
303
304
305
306 host%
307 cd ~/uml
308
309
310
311
312
313
314 host%
315 tar -xzvf linux-2.4.0-prerelease.tar.bz2
316
317
318
319
320
321
322 4. Apply the patch using
323
324
325
326 host%
327 cd ~/uml/linux
328
329
330
331 host%
332 bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
333
334
335
336
337
338
339 5. Run your favorite config; `make xconfig ARCH=um' is the most
340 convenient. `make config ARCH=um' and 'make menuconfig ARCH=um'
341 will work as well. The defaults will give you a useful kernel. If
342 you want to change something, go ahead, it probably won't hurt
343 anything.
344
345
346 Note: If the host is configured with a 2G/2G address space split
347 rather than the usual 3G/1G split, then the packaged UML binaries
348 will not run. They will immediately segfault. See ``UML on 2G/2G
349 hosts'' for the scoop on running UML on your system.
350
351
352
353 6. Finish with `make linux ARCH=um': the result is a file called
354 `linux' in the top directory of your source tree.
355
356 Make sure that you don't build this kernel in /usr/src/linux. On some
357 distributions, /usr/include/asm is a link into this pool. The user-
358 mode build changes the other end of that link, and things that include
359 <asm/anything.h> stop compiling.
360
361 The sources are also available from cvs at the project's cvs page,
362 which has directions on getting the sources. You can also browse the
363 CVS pool from there.
364
365 If you get the CVS sources, you will have to check them out into an
366 empty directory. You will then have to copy each file into the
367 corresponding directory in the appropriate kernel pool.
368
369 If you don't have the latest kernel pool, you can get the
370 corresponding user-mode sources with
371
372
373 host% cvs co -r v_2_3_x linux
374
375
376
377
378 where 'x' is the version in your pool. Note that you will not get the
379 bug fixes and enhancements that have gone into subsequent releases.
380
381
382 If you build your own kernel, and want to boot it from one of the
383 filesystems distributed from this site, then, in nearly all cases,
384 devfs must be compiled into the kernel and mounted at boot time. The
385 exception is the SuSE filesystem. For this, devfs must either not be
386 in the kernel at all, or "devfs=nomount" must be on the kernel command
387 line. Any disagreement between the kernel and the filesystem being
388 booted about whether devfs is being used will result in the boot
389 getting no further than single-user mode.
390
391
392 If you don't want to use devfs, you can remove the need for it from a
393 filesystem by copying /dev from someplace, making a bunch of /dev/ubd
394 devices:
395
396
397 UML# for i in 0 1 2 3 4 5 6 7; do mknod ubd$i b 98 $i; done
398
399
400
401
402 and changing /etc/fstab and /etc/inittab to refer to the non-devfs
403 devices.
404
405
406
407 22..22.. CCoommppiilliinngg aanndd iinnssttaalllliinngg kkeerrnneell mmoodduulleess
408
409 UML modules are built in the same way as the native kernel (with the
410 exception of the 'ARCH=um' that you always need for UML):
411
412
413 host% make modules ARCH=um
414
415
416
417
418 Any modules that you want to load into this kernel need to be built in
419 the user-mode pool. Modules from the native kernel won't work.
420
421 You can install them by using ftp or something to copy them into the
422 virtual machine and dropping them into /lib/modules/`uname -r`.
423
424 You can also get the kernel build process to install them as follows:
425
426 1. with the kernel not booted, mount the root filesystem in the top
427 level of the kernel pool:
428
429
430 host% mount root_fs mnt -o loop
431
432
433
434
435
436
437 2. run
438
439
440 host%
441 make modules_install INSTALL_MOD_PATH=`pwd`/mnt ARCH=um
442
443
444
445
446
447
448 3. unmount the filesystem
449
450
451 host% umount mnt
452
453
454
455
456
457
458 4. boot the kernel on it
459
460
461 When the system is booted, you can use insmod as usual to get the
462 modules into the kernel. A number of things have been loaded into UML
463 as modules, especially filesystems and network protocols and filters,
464 so most symbols which need to be exported probably already are.
465 However, if you do find symbols that need exporting, let us
466 <http://user-mode-linux.sourceforge.net/contacts.html> know, and
467 they'll be "taken care of".
468
469
470
471 22..33.. CCoommppiilliinngg aanndd iinnssttaalllliinngg uummll__uuttiilliittiieess
472
473 Many features of the UML kernel require a user-space helper program,
474 so a uml_utilities package is distributed separately from the kernel
475 patch which provides these helpers. Included within this is:
476
477 +o port-helper - Used by consoles which connect to xterms or ports
478
479 +o tunctl - Configuration tool to create and delete tap devices
480
481 +o uml_net - Setuid binary for automatic tap device configuration
482
483 +o uml_switch - User-space virtual switch required for daemon
484 transport
485
486 The uml_utilities tree is compiled with:
487
488
489 host#
490 make && make install
491
492
493
494
495 Note that UML kernel patches may require a specific version of the
496 uml_utilities distribution. If you don't keep up with the mailing
497 lists, ensure that you have the latest release of uml_utilities if you
498 are experiencing problems with your UML kernel, particularly when
499 dealing with consoles or command-line switches to the helper programs
500
501
502
503
504
505
506
507
508 33.. RRuunnnniinngg UUMMLL aanndd llooggggiinngg iinn
509
510
511
512 33..11.. RRuunnnniinngg UUMMLL
513
514 It runs on 2.2.15 or later, and all 2.4 kernels.
515
516
517 Booting UML is straightforward. Simply run 'linux': it will try to
518 mount the file `root_fs' in the current directory. You do not need to
519 run it as root. If your root filesystem is not named `root_fs', then
520 you need to put a `ubd0=root_fs_whatever' switch on the linux command
521 line.
522
523
524 You will need a filesystem to boot UML from. There are a number
525 available for download from here <http://user-mode-
526 linux.sourceforge.net/dl-sf.html> . There are also several tools
527 <http://user-mode-linux.sourceforge.net/fs_making.html> which can be
528 used to generate UML-compatible filesystem images from media.
529 The kernel will boot up and present you with a login prompt.
530
531
532 Note: If the host is configured with a 2G/2G address space split
533 rather than the usual 3G/1G split, then the packaged UML binaries will
534 not run. They will immediately segfault. See ``UML on 2G/2G hosts''
535 for the scoop on running UML on your system.
536
537
538
539 33..22.. LLooggggiinngg iinn
540
541
542
543 The prepackaged filesystems have a root account with password 'root'
544 and a user account with password 'user'. The login banner will
545 generally tell you how to log in. So, you log in and you will find
546 yourself inside a little virtual machine. Our filesystems have a
547 variety of commands and utilities installed (and it is fairly easy to
548 add more), so you will have a lot of tools with which to poke around
549 the system.
550
551 There are a couple of other ways to log in:
552
553 +o On a virtual console
554
555
556
557 Each virtual console that is configured (i.e. the device exists in
558 /dev and /etc/inittab runs a getty on it) will come up in its own
559 xterm. If you get tired of the xterms, read ``Setting up serial
560 lines and consoles'' to see how to attach the consoles to
561 something else, like host ptys.
562
563
564
565 +o Over the serial line
566
567
568 In the boot output, find a line that looks like:
569
570
571
572 serial line 0 assigned pty /dev/ptyp1
573
574
575
576
577 Attach your favorite terminal program to the corresponding tty. I.e.
578 for minicom, the command would be
579
580
581 host% minicom -o -p /dev/ttyp1
582
583
584
585
586
587
588 +o Over the net
589
590
591 If the network is running, then you can telnet to the virtual
592 machine and log in to it. See ``Setting up the network'' to learn
593 about setting up a virtual network.
594
595 When you're done using it, run halt, and the kernel will bring itself
596 down and the process will exit.
597
598
599 33..33.. EExxaammpplleess
600
601 Here are some examples of UML in action:
602
603 +o A login session <http://user-mode-linux.sourceforge.net/login.html>
604
605 +o A virtual network <http://user-mode-linux.sourceforge.net/net.html>
606
607
608
609
610
611
612
613 44.. UUMMLL oonn 22GG//22GG hhoossttss
614
615
616
617
618 44..11.. IInnttrroodduuccttiioonn
619
620
621 Most Linux machines are configured so that the kernel occupies the
622 upper 1G (0xc0000000 - 0xffffffff) of the 4G address space and
623 processes use the lower 3G (0x00000000 - 0xbfffffff). However, some
624 machine are configured with a 2G/2G split, with the kernel occupying
625 the upper 2G (0x80000000 - 0xffffffff) and processes using the lower
626 2G (0x00000000 - 0x7fffffff).
627
628
629
630
631 44..22.. TThhee pprroobblleemm
632
633
634 The prebuilt UML binaries on this site will not run on 2G/2G hosts
635 because UML occupies the upper .5G of the 3G process address space
636 (0xa0000000 - 0xbfffffff). Obviously, on 2G/2G hosts, this is right
637 in the middle of the kernel address space, so UML won't even load - it
638 will immediately segfault.
639
640
641
642
643 44..33.. TThhee ssoolluuttiioonn
644
645
646 The fix for this is to rebuild UML from source after enabling
647 CONFIG_HOST_2G_2G (under 'General Setup'). This will cause UML to
648 load itself in the top .5G of that smaller process address space,
649 where it will run fine. See ``Compiling the kernel and modules'' if
650 you need help building UML from source.
651
652
653
654
655
656
657
658
659
660
661 55.. SSeettttiinngg uupp sseerriiaall lliinneess aanndd ccoonnssoolleess
662
663
664 It is possible to attach UML serial lines and consoles to many types
665 of host I/O channels by specifying them on the command line.
666
667
668 You can attach them to host ptys, ttys, file descriptors, and ports.
669 This allows you to do things like
670
671 +o have a UML console appear on an unused host console,
672
673 +o hook two virtual machines together by having one attach to a pty
674 and having the other attach to the corresponding tty
675
676 +o make a virtual machine accessible from the net by attaching a
677 console to a port on the host.
678
679
680 The general format of the command line option is device=channel.
681
682
683
684 55..11.. SSppeecciiffyyiinngg tthhee ddeevviiccee
685
686 Devices are specified with "con" or "ssl" (console or serial line,
687 respectively), optionally with a device number if you are talking
688 about a specific device.
689
690
691 Using just "con" or "ssl" describes all of the consoles or serial
692 lines. If you want to talk about console #3 or serial line #10, they
693 would be "con3" and "ssl10", respectively.
694
695
696 A specific device name will override a less general "con=" or "ssl=".
697 So, for example, you can assign a pty to each of the serial lines
698 except for the first two like this:
699
700
701 ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1
702
703
704
705
706 The specificity of the device name is all that matters; order on the
707 command line is irrelevant.
708
709
710
711 55..22.. SSppeecciiffyyiinngg tthhee cchhaannnneell
712
713 There are a number of different types of channels to attach a UML
714 device to, each with a different way of specifying exactly what to
715 attach to.
716
717 +o pseudo-terminals - device=pty pts terminals - device=pts
718
719
720 This will cause UML to allocate a free host pseudo-terminal for the
721 device. The terminal that it got will be announced in the boot
722 log. You access it by attaching a terminal program to the
723 corresponding tty:
724
725 +o screen /dev/pts/n
726
727 +o screen /dev/ttyxx
728
729 +o minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
730 devices
731
732 +o kermit - start it up, 'open' the device, then 'connect'
733
734
735
736
737
738 +o terminals - device=tty:tty device file
739
740
741 This will make UML attach the device to the specified tty (i.e
742
743
744 con1=tty:/dev/tty3
745
746
747
748
749 will attach UML's console 1 to the host's /dev/tty3). If the tty that
750 you specify is the slave end of a tty/pty pair, something else must
751 have already opened the corresponding pty in order for this to work.
752
753
754
755
756
757 +o xterms - device=xterm
758
759
760 UML will run an xterm and the device will be attached to it.
761
762
763
764
765
766 +o Port - device=port:port number
767
768
769 This will attach the UML devices to the specified host port.
770 Attaching console 1 to the host's port 9000 would be done like
771 this:
772
773
774 con1=port:9000
775
776
777
778
779 Attaching all the serial lines to that port would be done similarly:
780
781
782 ssl=port:9000
783
784
785
786
787 You access these devices by telnetting to that port. Each active tel-
788 net session gets a different device. If there are more telnets to a
789 port than UML devices attached to it, then the extra telnet sessions
790 will block until an existing telnet detaches, or until another device
791 becomes active (i.e. by being activated in /etc/inittab).
792
793 This channel has the advantage that you can both attach multiple UML
794 devices to it and know how to access them without reading the UML boot
795 log. It is also unique in allowing access to a UML from remote
796 machines without requiring that the UML be networked. This could be
797 useful in allowing public access to UMLs because they would be
798 accessible from the net, but wouldn't need any kind of network
799 filtering or access control because they would have no network access.
800
801
802 If you attach the main console to a portal, then the UML boot will
803 appear to hang. In reality, it's waiting for a telnet to connect, at
804 which point the boot will proceed.
805
806
807
808
809
810 +o already-existing file descriptors - device=file descriptor
811
812
813 If you set up a file descriptor on the UML command line, you can
814 attach a UML device to it. This is most commonly used to put the
815 main console back on stdin and stdout after assigning all the other
816 consoles to something else:
817
818
819 con0=fd:0,fd:1 con=pts
820
821
822
823
824
825
826
827
828 +o Nothing - device=null
829
830
831 This allows the device to be opened, in contrast to 'none', but
832 reads will block, and writes will succeed and the data will be
833 thrown out.
834
835
836
837
838
839 +o None - device=none
840
841
842 This causes the device to disappear. If you are using devfs, the
843 device will not appear in /dev. If not, then attempts to open it
844 will return -ENODEV.
845
846
847
848 You can also specify different input and output channels for a device
849 by putting a comma between them:
850
851
852 ssl3=tty:/dev/tty2,xterm
853
854
855
856
857 will cause serial line 3 to accept input on the host's /dev/tty3 and
858 display output on an xterm. That's a silly example - the most common
859 use of this syntax is to reattach the main console to stdin and stdout
860 as shown above.
861
862
863 If you decide to move the main console away from stdin/stdout, the
864 initial boot output will appear in the terminal that you're running
865 UML in. However, once the console driver has been officially
866 initialized, then the boot output will start appearing wherever you
867 specified that console 0 should be. That device will receive all
868 subsequent output.
869
870
871
872 55..33.. EExxaammpplleess
873
874 There are a number of interesting things you can do with this
875 capability.
876
877
878 First, this is how you get rid of those bleeding console xterms by
879 attaching them to host ptys:
880
881
882 con=pty con0=fd:0,fd:1
883
884
885
886
887 This will make a UML console take over an unused host virtual console,
888 so that when you switch to it, you will see the UML login prompt
889 rather than the host login prompt:
890
891
892 con1=tty:/dev/tty6
893
894
895
896
897 You can attach two virtual machines together with what amounts to a
898 serial line as follows:
899
900 Run one UML with a serial line attached to a pty -
901
902
903 ssl1=pty
904
905
906
907
908 Look at the boot log to see what pty it got (this example will assume
909 that it got /dev/ptyp1).
910
911 Boot the other UML with a serial line attached to the corresponding
912 tty -
913
914
915 ssl1=tty:/dev/ttyp1
916
917
918
919
920 Log in, make sure that it has no getty on that serial line, attach a
921 terminal program like minicom to it, and you should see the login
922 prompt of the other virtual machine.
923
924
925 66.. SSeettttiinngg uupp tthhee nneettwwoorrkk
926
927
928
929 This page describes how to set up the various transports and to
930 provide a UML instance with network access to the host, other machines
931 on the local net, and the rest of the net.
932
933
934 As of 2.4.5, UML networking has been completely redone to make it much
935 easier to set up, fix bugs, and add new features.
936
937
938 There is a new helper, uml_net, which does the host setup that
939 requires root privileges.
940
941
942 There are currently five transport types available for a UML virtual
943 machine to exchange packets with other hosts:
944
945 +o ethertap
946
947 +o TUN/TAP
948
949 +o Multicast
950
951 +o a switch daemon
952
953 +o slip
954
955 +o slirp
956
957 +o pcap
958
959 The TUN/TAP, ethertap, slip, and slirp transports allow a UML
960 instance to exchange packets with the host. They may be directed
961 to the host or the host may just act as a router to provide access
962 to other physical or virtual machines.
963
964
965 The pcap transport is a synthetic read-only interface, using the
966 libpcap binary to collect packets from interfaces on the host and
967 filter them. This is useful for building preconfigured traffic
968 monitors or sniffers.
969
970
971 The daemon and multicast transports provide a completely virtual
972 network to other virtual machines. This network is completely
973 disconnected from the physical network unless one of the virtual
974 machines on it is acting as a gateway.
975
976
977 With so many host transports, which one should you use? Here's when
978 you should use each one:
979
980 +o ethertap - if you want access to the host networking and it is
981 running 2.2
982
983 +o TUN/TAP - if you want access to the host networking and it is
984 running 2.4. Also, the TUN/TAP transport is able to use a
985 preconfigured device, allowing it to avoid using the setuid uml_net
986 helper, which is a security advantage.
987
988 +o Multicast - if you want a purely virtual network and you don't want
989 to set up anything but the UML
990
991 +o a switch daemon - if you want a purely virtual network and you
992 don't mind running the daemon in order to get somewhat better
993 performance
994
995 +o slip - there is no particular reason to run the slip backend unless
996 ethertap and TUN/TAP are just not available for some reason
997
998 +o slirp - if you don't have root access on the host to setup
999 networking, or if you don't want to allocate an IP to your UML
1000
1001 +o pcap - not much use for actual network connectivity, but great for
1002 monitoring traffic on the host
1003
1004 Ethertap is available on 2.4 and works fine. TUN/TAP is preferred
1005 to it because it has better performance and ethertap is officially
1006 considered obsolete in 2.4. Also, the root helper only needs to
1007 run occasionally for TUN/TAP, rather than handling every packet, as
1008 it does with ethertap. This is a slight security advantage since
1009 it provides fewer opportunities for a nasty UML user to somehow
1010 exploit the helper's root privileges.
1011
1012
1013 66..11.. GGeenneerraall sseettuupp
1014
1015 First, you must have the virtual network enabled in your UML. If are
1016 running a prebuilt kernel from this site, everything is already
1017 enabled. If you build the kernel yourself, under the "Network device
1018 support" menu, enable "Network device support", and then the three
1019 transports.
1020
1021
1022 The next step is to provide a network device to the virtual machine.
1023 This is done by describing it on the kernel command line.
1024
1025 The general format is
1026
1027
1028 eth <n> = <transport> , <transport args>
1029
1030
1031
1032
1033 For example, a virtual ethernet device may be attached to a host
1034 ethertap device as follows:
1035
1036
1037 eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
1038
1039
1040
1041
1042 This sets up eth0 inside the virtual machine to attach itself to the
1043 host /dev/tap0, assigns it an ethernet address, and assigns the host
1044 tap0 interface an IP address.
1045
1046
1047
1048 Note that the IP address you assign to the host end of the tap device
1049 must be different than the IP you assign to the eth device inside UML.
1050 If you are short on IPs and don't want to comsume two per UML, then
1051 you can reuse the host's eth IP address for the host ends of the tap
1052 devices. Internally, the UMLs must still get unique IPs for their eth
1053 devices. You can also give the UMLs non-routable IPs (192.168.x.x or
1054 10.x.x.x) and have the host masquerade them. This will let outgoing
1055 connections work, but incoming connections won't without more work,
1056 such as port forwarding from the host.
1057 Also note that when you configure the host side of an interface, it is
1058 only acting as a gateway. It will respond to pings sent to it
1059 locally, but is not useful to do that since it's a host interface.
1060 You are not talking to the UML when you ping that interface and get a
1061 response.
1062
1063
1064 You can also add devices to a UML and remove them at runtime. See the
1065 ``The Management Console'' page for details.
1066
1067
1068 The sections below describe this in more detail.
1069
1070
1071 Once you've decided how you're going to set up the devices, you boot
1072 UML, log in, configure the UML side of the devices, and set up routes
1073 to the outside world. At that point, you will be able to talk to any
1074 other machines, physical or virtual, on the net.
1075
1076
1077 If ifconfig inside UML fails and the network refuses to come up, run
1078 tell you what went wrong.
1079
1080
1081
1082 66..22.. UUsseerrssppaaccee ddaaeemmoonnss
1083
1084 You will likely need the setuid helper, or the switch daemon, or both.
1085 They are both installed with the RPM and deb, so if you've installed
1086 either, you can skip the rest of this section.
1087
1088
1089 If not, then you need to check them out of CVS, build them, and
1090 install them. The helper is uml_net, in CVS /tools/uml_net, and the
1091 daemon is uml_switch, in CVS /tools/uml_router. They are both built
1092 with a plain 'make'. Both need to be installed in a directory that's
1093 in your path - /usr/bin is recommend. On top of that, uml_net needs
1094 to be setuid root.
1095
1096
1097
1098 66..33.. SSppeecciiffyyiinngg eetthheerrnneett aaddddrreesssseess
1099
1100 Below, you will see that the TUN/TAP, ethertap, and daemon interfaces
1101 allow you to specify hardware addresses for the virtual ethernet
1102 devices. This is generally not necessary. If you don't have a
1103 specific reason to do it, you probably shouldn't. If one is not
1104 specified on the command line, the driver will assign one based on the
1105 device IP address. It will provide the address fe:fd:nn:nn:nn:nn
1106 where nn.nn.nn.nn is the device IP address. This is nearly always
1107 sufficient to guarantee a unique hardware address for the device. A
1108 couple of exceptions are:
1109
1110 +o Another set of virtual ethernet devices are on the same network and
1111 they are assigned hardware addresses using a different scheme which
1112 may conflict with the UML IP address-based scheme
1113
1114 +o You aren't going to use the device for IP networking, so you don't
1115 assign the device an IP address
1116
1117 If you let the driver provide the hardware address, you should make
1118 sure that the device IP address is known before the interface is
1119 brought up. So, inside UML, this will guarantee that:
1120
1121
1122
1123 UML#
1124 ifconfig eth0 192.168.0.250 up
1125
1126
1127
1128
1129 If you decide to assign the hardware address yourself, make sure that
1130 the first byte of the address is even. Addresses with an odd first
1131 byte are broadcast addresses, which you don't want assigned to a
1132 device.
1133
1134
1135
1136 66..44.. UUMMLL iinntteerrffaaccee sseettuupp
1137
1138 Once the network devices have been described on the command line, you
1139 should boot UML and log in.
1140
1141
1142 The first thing to do is bring the interface up:
1143
1144
1145 UML# ifconfig ethn ip-address up
1146
1147
1148
1149
1150 You should be able to ping the host at this point.
1151
1152
1153 To reach the rest of the world, you should set a default route to the
1154 host:
1155
1156
1157 UML# route add default gw host ip
1158
1159
1160
1161
1162 Again, with host ip of 192.168.0.4:
1163
1164
1165 UML# route add default gw 192.168.0.4
1166
1167
1168
1169
1170 This page used to recommend setting a network route to your local net.
1171 This is wrong, because it will cause UML to try to figure out hardware
1172 addresses of the local machines by arping on the interface to the
1173 host. Since that interface is basically a single strand of ethernet
1174 with two nodes on it (UML and the host) and arp requests don't cross
1175 networks, they will fail to elicit any responses. So, what you want
1176 is for UML to just blindly throw all packets at the host and let it
1177 figure out what to do with them, which is what leaving out the network
1178 route and adding the default route does.
1179
1180
1181 Note: If you can't communicate with other hosts on your physical
1182 ethernet, it's probably because of a network route that's
1183 automatically set up. If you run 'route -n' and see a route that
1184 looks like this:
1185
1186
1187
1188
1189 Destination Gateway Genmask Flags Metric Ref Use Iface
1190 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
1191
1192
1193
1194
1195 with a mask that's not 255.255.255.255, then replace it with a route
1196 to your host:
1197
1198
1199 UML#
1200 route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0
1201
1202
1203
1204
1205
1206
1207 UML#
1208 route add -host 192.168.0.4 dev eth0
1209
1210
1211
1212
1213 This, plus the default route to the host, will allow UML to exchange
1214 packets with any machine on your ethernet.
1215
1216
1217
1218 66..55.. MMuullttiiccaasstt
1219
1220 The simplest way to set up a virtual network between multiple UMLs is
1221 to use the mcast transport. This was written by Harald Welte and is
1222 present in UML version 2.4.5-5um and later. Your system must have
1223 multicast enabled in the kernel and there must be a multicast-capable
1224 network device on the host. Normally, this is eth0, but if there is
1225 no ethernet card on the host, then you will likely get strange error
1226 messages when you bring the device up inside UML.
1227
1228
1229 To use it, run two UMLs with
1230
1231
1232 eth0=mcast
1233
1234
1235
1236
1237 on their command lines. Log in, configure the ethernet device in each
1238 machine with different IP addresses:
1239
1240
1241 UML1# ifconfig eth0 192.168.0.254
1242
1243
1244
1245
1246
1247
1248 UML2# ifconfig eth0 192.168.0.253
1249
1250
1251
1252
1253 and they should be able to talk to each other.
1254
1255 The full set of command line options for this transport are
1256
1257
1258
1259 ethn=mcast,ethernet address,multicast
1260 address,multicast port,ttl
1261
1262
1263
1264
1265 Harald's original README is here <http://user-mode-linux.source-
1266 forge.net/text/mcast.txt> and explains these in detail, as well as
1267 some other issues.
1268
1269
1270
1271 66..66.. TTUUNN//TTAAPP wwiitthh tthhee uummll__nneett hheellppeerr
1272
1273 TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the
1274 host. The TUN/TAP backend has been in UML since 2.4.9-3um.
1275
1276
1277 The easiest way to get up and running is to let the setuid uml_net
1278 helper do the host setup for you. This involves insmod-ing the tun.o
1279 module if necessary, configuring the device, and setting up IP
1280 forwarding, routing, and proxy arp. If you are new to UML networking,
1281 do this first. If you're concerned about the security implications of
1282 the setuid helper, use it to get up and running, then read the next
1283 section to see how to have UML use a preconfigured tap device, which
1284 avoids the use of uml_net.
1285
1286
1287 If you specify an IP address for the host side of the device, the
1288 uml_net helper will do all necessary setup on the host - the only
1289 requirement is that TUN/TAP be available, either built in to the host
1290 kernel or as the tun.o module.
1291
1292 The format of the command line switch to attach a device to a TUN/TAP
1293 device is
1294
1295
1296 eth <n> =tuntap,,, <IP address>
1297
1298
1299
1300
1301 For example, this argument will attach the UML's eth0 to the next
1302 available tap device and assign an ethernet address to it based on its
1303 IP address
1304
1305
1306 eth0=tuntap,,,192.168.0.254
1307
1308
1309
1310
1311
1312
1313 Note that the IP address that must be used for the eth device inside
1314 UML is fixed by the routing and proxy arp that is set up on the
1315 TUN/TAP device on the host. You can use a different one, but it won't
1316 work because reply packets won't reach the UML. This is a feature.
1317 It prevents a nasty UML user from doing things like setting the UML IP
1318 to the same as the network's nameserver or mail server.
1319
1320
1321 There are a couple potential problems with running the TUN/TAP
1322 transport on a 2.4 host kernel
1323
1324 +o TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
1325 kernel or use the ethertap transport.
1326
1327 +o With an upgraded kernel, TUN/TAP may fail with
1328
1329
1330 File descriptor in bad state
1331
1332
1333
1334
1335 This is due to a header mismatch between the upgraded kernel and the
1336 kernel that was originally installed on the machine. The fix is to
1337 make sure that /usr/src/linux points to the headers for the running
1338 kernel.
1339
1340 These were pointed out by Tim Robinson <timro at trkr dot net> in
1341 <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="this uml-
1342 user post"> .
1343
1344
1345
1346 66..77.. TTUUNN//TTAAPP wwiitthh aa pprreeccoonnffiigguurreedd ttaapp ddeevviiccee
1347
1348 If you prefer not to have UML use uml_net (which is somewhat
1349 insecure), with UML 2.4.17-11, you can set up a TUN/TAP device
1350 beforehand. The setup needs to be done as root, but once that's done,
1351 there is no need for root assistance. Setting up the device is done
1352 as follows:
1353
1354 +o Create the device with tunctl (available from the UML utilities
1355 tarball)
1356
1357
1358
1359
1360 host# tunctl -u uid
1361
1362
1363
1364
1365 where uid is the user id or username that UML will be run as. This
1366 will tell you what device was created.
1367
1368 +o Configure the device IP (change IP addresses and device name to
1369 suit)
1370
1371
1372
1373
1374 host# ifconfig tap0 192.168.0.254 up
1375
1376
1377
1378
1379
1380 +o Set up routing and arping if desired - this is my recipe, there are
1381 other ways of doing the same thing
1382
1383
1384 host#
1385 bash -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'
1386
1387 host#
1388 route add -host 192.168.0.253 dev tap0
1389
1390
1391
1392
1393
1394
1395 host#
1396 bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
1397
1398
1399
1400
1401
1402
1403 host#
1404 arp -Ds 192.168.0.253 eth0 pub
1405
1406
1407
1408
1409 Note that this must be done every time the host boots - this configu-
1410 ration is not stored across host reboots. So, it's probably a good
1411 idea to stick it in an rc file. An even better idea would be a little
1412 utility which reads the information from a config file and sets up
1413 devices at boot time.
1414
1415 +o Rather than using up two IPs and ARPing for one of them, you can
1416 also provide direct access to your LAN by the UML by using a
1417 bridge.
1418
1419
1420 host#
1421 brctl addbr br0
1422
1423
1424
1425
1426
1427
1428 host#
1429 ifconfig eth0 0.0.0.0 promisc up
1430
1431
1432
1433
1434
1435
1436 host#
1437 ifconfig tap0 0.0.0.0 promisc up
1438
1439
1440
1441
1442
1443
1444 host#
1445 ifconfig br0 192.168.0.1 netmask 255.255.255.0 up
1446
1447
1448
1449
1450
1451
1452
1453 host#
1454 brctl stp br0 off
1455
1456
1457
1458
1459
1460
1461 host#
1462 brctl setfd br0 1
1463
1464
1465
1466
1467
1468
1469 host#
1470 brctl sethello br0 1
1471
1472
1473
1474
1475
1476
1477 host#
1478 brctl addif br0 eth0
1479
1480
1481
1482
1483
1484
1485 host#
1486 brctl addif br0 tap0
1487
1488
1489
1490
1491 Note that 'br0' should be setup using ifconfig with the existing IP
1492 address of eth0, as eth0 no longer has its own IP.
1493
1494 +o
1495
1496
1497 Also, the /dev/net/tun device must be writable by the user running
1498 UML in order for the UML to use the device that's been configured
1499 for it. The simplest thing to do is
1500
1501
1502 host# chmod 666 /dev/net/tun
1503
1504
1505
1506
1507 Making it world-writeable looks bad, but it seems not to be
1508 exploitable as a security hole. However, it does allow anyone to cre-
1509 ate useless tap devices (useless because they can't configure them),
1510 which is a DOS attack. A somewhat more secure alternative would to be
1511 to create a group containing all the users who have preconfigured tap
1512 devices and chgrp /dev/net/tun to that group with mode 664 or 660.
1513
1514
1515 +o Once the device is set up, run UML with 'eth0=tuntap,device name'
1516 (i.e. 'eth0=tuntap,tap0') on the command line (or do it with the
1517 mconsole config command).
1518
1519 +o Bring the eth device up in UML and you're in business.
1520
1521 If you don't want that tap device any more, you can make it non-
1522 persistent with
1523
1524
1525 host# tunctl -d tap device
1526
1527
1528
1529
1530 Finally, tunctl has a -b (for brief mode) switch which causes it to
1531 output only the name of the tap device it created. This makes it
1532 suitable for capture by a script:
1533
1534
1535 host# TAP=`tunctl -u 1000 -b`
1536
1537
1538
1539
1540
1541
1542 66..88.. EEtthheerrttaapp
1543
1544 Ethertap is the general mechanism on 2.2 for userspace processes to
1545 exchange packets with the kernel.
1546
1547
1548
1549 To use this transport, you need to describe the virtual network device
1550 on the UML command line. The general format for this is
1551
1552
1553 eth <n> =ethertap, <device> , <ethernet address> , <tap IP address>
1554
1555
1556
1557
1558 So, the previous example
1559
1560
1561 eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
1562
1563
1564
1565
1566 attaches the UML eth0 device to the host /dev/tap0, assigns it the
1567 ethernet address fe:fd:0:0:0:1, and assigns the IP address
1568 192.168.0.254 to the tap device.
1569
1570
1571
1572 The tap device is mandatory, but the others are optional. If the
1573 ethernet address is omitted, one will be assigned to it.
1574
1575
1576 The presence of the tap IP address will cause the helper to run and do
1577 whatever host setup is needed to allow the virtual machine to
1578 communicate with the outside world. If you're not sure you know what
1579 you're doing, this is the way to go.
1580
1581
1582 If it is absent, then you must configure the tap device and whatever
1583 arping and routing you will need on the host. However, even in this
1584 case, the uml_net helper still needs to be in your path and it must be
1585 setuid root if you're not running UML as root. This is because the
1586 tap device doesn't support SIGIO, which UML needs in order to use
1587 something as a source of input. So, the helper is used as a
1588 convenient asynchronous IO thread.
1589
1590 If you're using the uml_net helper, you can ignore the following host
1591 setup - uml_net will do it for you. You just need to make sure you
1592 have ethertap available, either built in to the host kernel or
1593 available as a module.
1594
1595
1596 If you want to set things up yourself, you need to make sure that the
1597 appropriate /dev entry exists. If it doesn't, become root and create
1598 it as follows:
1599
1600
1601 mknod /dev/tap <minor> c 36 <minor> + 16
1602
1603
1604
1605
1606 For example, this is how to create /dev/tap0:
1607
1608
1609 mknod /dev/tap0 c 36 0 + 16
1610
1611
1612
1613
1614 You also need to make sure that the host kernel has ethertap support.
1615 If ethertap is enabled as a module, you apparently need to insmod
1616 ethertap once for each ethertap device you want to enable. So,
1617
1618
1619 host#
1620 insmod ethertap
1621
1622
1623
1624
1625 will give you the tap0 interface. To get the tap1 interface, you need
1626 to run
1627
1628
1629 host#
1630 insmod ethertap unit=1 -o ethertap1
1631
1632
1633
1634
1635
1636
1637
1638 66..99.. TThhee sswwiittcchh ddaaeemmoonn
1639
1640 NNoottee: This is the daemon formerly known as uml_router, but which was
1641 renamed so the network weenies of the world would stop growling at me.
1642
1643
1644 The switch daemon, uml_switch, provides a mechanism for creating a
1645 totally virtual network. By default, it provides no connection to the
1646 host network (but see -tap, below).
1647
1648
1649 The first thing you need to do is run the daemon. Running it with no
1650 arguments will make it listen on a default pair of unix domain
1651 sockets.
1652
1653
1654 If you want it to listen on a different pair of sockets, use
1655
1656
1657 -unix control socket data socket
1658
1659
1660
1661
1662
1663 If you want it to act as a hub rather than a switch, use
1664
1665
1666 -hub
1667
1668
1669
1670
1671
1672 If you want the switch to be connected to host networking (allowing
1673 the umls to get access to the outside world through the host), use
1674
1675
1676 -tap tap0
1677
1678
1679
1680
1681
1682 Note that the tap device must be preconfigured (see "TUN/TAP with a
1683 preconfigured tap device", above). If you're using a different tap
1684 device than tap0, specify that instead of tap0.
1685
1686
1687 uml_switch can be backgrounded as follows
1688
1689
1690 host%
1691 uml_switch [ options ] < /dev/null > /dev/null
1692
1693
1694
1695
1696 The reason it doesn't background by default is that it listens to
1697 stdin for EOF. When it sees that, it exits.
1698
1699
1700 The general format of the kernel command line switch is
1701
1702
1703
1704 ethn=daemon,ethernet address,socket
1705 type,control socket,data socket
1706
1707
1708
1709
1710 You can leave off everything except the 'daemon'. You only need to
1711 specify the ethernet address if the one that will be assigned to it
1712 isn't acceptable for some reason. The rest of the arguments describe
1713 how to communicate with the daemon. You should only specify them if
1714 you told the daemon to use different sockets than the default. So, if
1715 you ran the daemon with no arguments, running the UML on the same
1716 machine with
1717 eth0=daemon
1718
1719
1720
1721
1722 will cause the eth0 driver to attach itself to the daemon correctly.
1723
1724
1725
1726 66..1100.. SSlliipp
1727
1728 Slip is another, less general, mechanism for a process to communicate
1729 with the host networking. In contrast to the ethertap interface,
1730 which exchanges ethernet frames with the host and can be used to
1731 transport any higher-level protocol, it can only be used to transport
1732 IP.
1733
1734
1735 The general format of the command line switch is
1736
1737
1738
1739 ethn=slip,slip IP
1740
1741
1742
1743
1744 The slip IP argument is the IP address that will be assigned to the
1745 host end of the slip device. If it is specified, the helper will run
1746 and will set up the host so that the virtual machine can reach it and
1747 the rest of the network.
1748
1749
1750 There are some oddities with this interface that you should be aware
1751 of. You should only specify one slip device on a given virtual
1752 machine, and its name inside UML will be 'umn', not 'eth0' or whatever
1753 you specified on the command line. These problems will be fixed at
1754 some point.
1755
1756
1757
1758 66..1111.. SSlliirrpp
1759
1760 slirp uses an external program, usually /usr/bin/slirp, to provide IP
1761 only networking connectivity through the host. This is similar to IP
1762 masquerading with a firewall, although the translation is performed in
1763 user-space, rather than by the kernel. As slirp does not set up any
1764 interfaces on the host, or changes routing, slirp does not require
1765 root access or setuid binaries on the host.
1766
1767
1768 The general format of the command line switch for slirp is:
1769
1770
1771
1772 ethn=slirp,ethernet address,slirp path
1773
1774
1775
1776
1777 The ethernet address is optional, as UML will set up the interface
1778 with an ethernet address based upon the initial IP address of the
1779 interface. The slirp path is generally /usr/bin/slirp, although it
1780 will depend on distribution.
1781
1782
1783 The slirp program can have a number of options passed to the command
1784 line and we can't add them to the UML command line, as they will be
1785 parsed incorrectly. Instead, a wrapper shell script can be written or
1786 the options inserted into the /.slirprc file. More information on
1787 all of the slirp options can be found in its man pages.
1788
1789
1790 The eth0 interface on UML should be set up with the IP 10.2.0.15,
1791 although you can use anything as long as it is not used by a network
1792 you will be connecting to. The default route on UML should be set to
1793 use
1794
1795
1796 UML#
1797 route add default dev eth0
1798
1799
1800
1801
1802 slirp provides a number of useful IP addresses which can be used by
1803 UML, such as 10.0.2.3 which is an alias for the DNS server specified
1804 in /etc/resolv.conf on the host or the IP given in the 'dns' option
1805 for slirp.
1806
1807
1808 Even with a baudrate setting higher than 115200, the slirp connection
1809 is limited to 115200. If you need it to go faster, the slirp binary
1810 needs to be compiled with FULL_BOLT defined in config.h.
1811
1812
1813
1814 66..1122.. ppccaapp
1815
1816 The pcap transport is attached to a UML ethernet device on the command
1817 line or with uml_mconsole with the following syntax:
1818
1819
1820
1821 ethn=pcap,host interface,filter
1822 expression,option1,option2
1823
1824
1825
1826
1827 The expression and options are optional.
1828
1829
1830 The interface is whatever network device on the host you want to
1831 sniff. The expression is a pcap filter expression, which is also what
1832 tcpdump uses, so if you know how to specify tcpdump filters, you will
1833 use the same expressions here. The options are up to two of
1834 'promisc', control whether pcap puts the host interface into
1835 promiscuous mode. 'optimize' and 'nooptimize' control whether the pcap
1836 expression optimizer is used.
1837
1838
1839 Example:
1840
1841
1842
1843 eth0=pcap,eth0,tcp
1844
1845 eth1=pcap,eth0,!tcp
1846
1847
1848
1849 will cause the UML eth0 to emit all tcp packets on the host eth0 and
1850 the UML eth1 to emit all non-tcp packets on the host eth0.
1851
1852
1853
1854 66..1133.. SSeettttiinngg uupp tthhee hhoosstt yyoouurrsseellff
1855
1856 If you don't specify an address for the host side of the ethertap or
1857 slip device, UML won't do any setup on the host. So this is what is
1858 needed to get things working (the examples use a host-side IP of
1859 192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your
1860 own network):
1861
1862 +o The device needs to be configured with its IP address. Tap devices
1863 are also configured with an mtu of 1484. Slip devices are
1864 configured with a point-to-point address pointing at the UML ip
1865 address.
1866
1867
1868 host# ifconfig tap0 arp mtu 1484 192.168.0.251 up
1869
1870
1871
1872
1873
1874
1875 host#
1876 ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up
1877
1878
1879
1880
1881
1882 +o If a tap device is being set up, a route is set to the UML IP.
1883
1884
1885 UML# route add -host 192.168.0.250 gw 192.168.0.251
1886
1887
1888
1889
1890
1891 +o To allow other hosts on your network to see the virtual machine,
1892 proxy arp is set up for it.
1893
1894
1895 host# arp -Ds 192.168.0.250 eth0 pub
1896
1897
1898
1899
1900
1901 +o Finally, the host is set up to route packets.
1902
1903
1904 host# echo 1 > /proc/sys/net/ipv4/ip_forward
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915 77.. SShhaarriinngg FFiilleessyysstteemmss bbeettwweeeenn VViirrttuuaall MMaacchhiinneess
1916
1917
1918
1919
1920 77..11.. AA wwaarrnniinngg
1921
1922 Don't attempt to share filesystems simply by booting two UMLs from the
1923 same file. That's the same thing as booting two physical machines
1924 from a shared disk. It will result in filesystem corruption.
1925
1926
1927
1928 77..22.. UUssiinngg llaayyeerreedd bblloocckk ddeevviicceess
1929
1930 The way to share a filesystem between two virtual machines is to use
1931 the copy-on-write (COW) layering capability of the ubd block driver.
1932 As of 2.4.6-2um, the driver supports layering a read-write private
1933 device over a read-only shared device. A machine's writes are stored
1934 in the private device, while reads come from either device - the
1935 private one if the requested block is valid in it, the shared one if
1936 not. Using this scheme, the majority of data which is unchanged is
1937 shared between an arbitrary number of virtual machines, each of which
1938 has a much smaller file containing the changes that it has made. With
1939 a large number of UMLs booting from a large root filesystem, this
1940 leads to a huge disk space saving. It will also help performance,
1941 since the host will be able to cache the shared data using a much
1942 smaller amount of memory, so UML disk requests will be served from the
1943 host's memory rather than its disks.
1944
1945
1946
1947
1948 To add a copy-on-write layer to an existing block device file, simply
1949 add the name of the COW file to the appropriate ubd switch:
1950
1951
1952 ubd0=root_fs_cow,root_fs_debian_22
1953
1954
1955
1956
1957 where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is
1958 the existing shared filesystem. The COW file need not exist. If it
1959 doesn't, the driver will create and initialize it. Once the COW file
1960 has been initialized, it can be used on its own on the command line:
1961
1962
1963 ubd0=root_fs_cow
1964
1965
1966
1967
1968 The name of the backing file is stored in the COW file header, so it
1969 would be redundant to continue specifying it on the command line.
1970
1971
1972
1973 77..33.. NNoottee!!
1974
1975 When checking the size of the COW file in order to see the gobs of
1976 space that you're saving, make sure you use 'ls -ls' to see the actual
1977 disk consumption rather than the length of the file. The COW file is
1978 sparse, so the length will be very different from the disk usage.
1979 Here is a 'ls -l' of a COW file and backing file from one boot and
1980 shutdown:
1981 host% ls -l cow.debian debian2.2
1982 -rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
1983 -rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
1984
1985
1986
1987
1988 Doesn't look like much saved space, does it? Well, here's 'ls -ls':
1989
1990
1991 host% ls -ls cow.debian debian2.2
1992 880 -rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
1993 525832 -rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
1994
1995
1996
1997
1998 Now, you can see that the COW file has less than a meg of disk, rather
1999 than 492 meg.
2000
2001
2002
2003 77..44.. AAnnootthheerr wwaarrnniinngg
2004
2005 Once a filesystem is being used as a readonly backing file for a COW
2006 file, do not boot directly from it or modify it in any way. Doing so
2007 will invalidate any COW files that are using it. The mtime and size
2008 of the backing file are stored in the COW file header at its creation,
2009 and they must continue to match. If they don't, the driver will
2010 refuse to use the COW file.
2011
2012
2013
2014
2015 If you attempt to evade this restriction by changing either the
2016 backing file or the COW header by hand, you will get a corrupted
2017 filesystem.
2018
2019
2020
2021
2022 Among other things, this means that upgrading the distribution in a
2023 backing file and expecting that all of the COW files using it will see
2024 the upgrade will not work.
2025
2026
2027
2028
2029 77..55.. uummll__mmoooo :: MMeerrggiinngg aa CCOOWW ffiillee wwiitthh iittss bbaacckkiinngg ffiillee
2030
2031 Depending on how you use UML and COW devices, it may be advisable to
2032 merge the changes in the COW file into the backing file every once in
2033 a while.
2034
2035
2036
2037
2038 The utility that does this is uml_moo. Its usage is
2039
2040
2041 host% uml_moo COW file new backing file
2042
2043
2044
2045
2046 There's no need to specify the backing file since that information is
2047 already in the COW file header. If you're paranoid, boot the new
2048 merged file, and if you're happy with it, move it over the old backing
2049 file.
2050
2051
2052
2053
2054 uml_moo creates a new backing file by default as a safety measure. It
2055 also has a destructive merge option which will merge the COW file
2056 directly into its current backing file. This is really only usable
2057 when the backing file only has one COW file associated with it. If
2058 there are multiple COWs associated with a backing file, a -d merge of
2059 one of them will invalidate all of the others. However, it is
2060 convenient if you're short of disk space, and it should also be
2061 noticably faster than a non-destructive merge.
2062
2063
2064
2065
2066 uml_moo is installed with the UML deb and RPM. If you didn't install
2067 UML from one of those packages, you can also get it from the UML
2068 utilities <http://user-mode-linux.sourceforge.net/dl-sf.html#UML
2069 utilities> tar file in tools/moo.
2070
2071
2072
2073
2074
2075
2076
2077
2078 88.. CCrreeaattiinngg ffiilleessyysstteemmss
2079
2080
2081 You may want to create and mount new UML filesystems, either because
2082 your root filesystem isn't large enough or because you want to use a
2083 filesystem other than ext2.
2084
2085
2086 This was written on the occasion of reiserfs being included in the
2087 2.4.1 kernel pool, and therefore the 2.4.1 UML, so the examples will
2088 talk about reiserfs. This information is generic, and the examples
2089 should be easy to translate to the filesystem of your choice.
2090
2091
2092 88..11.. CCrreeaattee tthhee ffiilleessyysstteemm ffiillee
2093
2094 dd is your friend. All you need to do is tell dd to create an empty
2095 file of the appropriate size. I usually make it sparse to save time
2096 and to avoid allocating disk space until it's actually used. For
2097 example, the following command will create a sparse 100 meg file full
2098 of zeroes.
2099
2100
2101 host%
2102 dd if=/dev/zero of=new_filesystem seek=100 count=1 bs=1M
2103
2104
2105
2106
2107
2108
2109 88..22.. AAssssiiggnn tthhee ffiillee ttoo aa UUMMLL ddeevviiccee
2110
2111 Add an argument like the following to the UML command line:
2112
2113 ubd4=new_filesystem
2114
2115
2116
2117
2118 making sure that you use an unassigned ubd device number.
2119
2120
2121
2122 88..33.. CCrreeaattiinngg aanndd mmoouunnttiinngg tthhee ffiilleessyysstteemm
2123
2124 Make sure that the filesystem is available, either by being built into
2125 the kernel, or available as a module, then boot up UML and log in. If
2126 the root filesystem doesn't have the filesystem utilities (mkfs, fsck,
2127 etc), then get them into UML by way of the net or hostfs.
2128
2129
2130 Make the new filesystem on the device assigned to the new file:
2131
2132
2133 host# mkreiserfs /dev/ubd/4
2134
2135
2136 <----------- MKREISERFSv2 ----------->
2137
2138 ReiserFS version 3.6.25
2139 Block size 4096 bytes
2140 Block count 25856
2141 Used blocks 8212
2142 Journal - 8192 blocks (18-8209), journal header is in block 8210
2143 Bitmaps: 17
2144 Root block 8211
2145 Hash function "r5"
2146 ATTENTION: ALL DATA WILL BE LOST ON '/dev/ubd/4'! (y/n)y
2147 journal size 8192 (from 18)
2148 Initializing journal - 0%....20%....40%....60%....80%....100%
2149 Syncing..done.
2150
2151
2152
2153
2154 Now, mount it:
2155
2156
2157 UML#
2158 mount /dev/ubd/4 /mnt
2159
2160
2161
2162
2163 and you're in business.
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173 99.. HHoosstt ffiillee aacccceessss
2174
2175
2176 If you want to access files on the host machine from inside UML, you
2177 can treat it as a separate machine and either nfs mount directories
2178 from the host or copy files into the virtual machine with scp or rcp.
2179 However, since UML is running on the the host, it can access those
2180 files just like any other process and make them available inside the
2181 virtual machine without needing to use the network.
2182
2183
2184 This is now possible with the hostfs virtual filesystem. With it, you
2185 can mount a host directory into the UML filesystem and access the
2186 files contained in it just as you would on the host.
2187
2188
2189 99..11.. UUssiinngg hhoossttffss
2190
2191 To begin with, make sure that hostfs is available inside the virtual
2192 machine with
2193
2194
2195 UML# cat /proc/filesystems
2196
2197
2198
2199 . hostfs should be listed. If it's not, either rebuild the kernel
2200 with hostfs configured into it or make sure that hostfs is built as a
2201 module and available inside the virtual machine, and insmod it.
2202
2203
2204 Now all you need to do is run mount:
2205
2206
2207 UML# mount none /mnt/host -t hostfs
2208
2209
2210
2211
2212 will mount the host's / on the virtual machine's /mnt/host.
2213
2214
2215 If you don't want to mount the host root directory, then you can
2216 specify a subdirectory to mount with the -o switch to mount:
2217
2218
2219 UML# mount none /mnt/home -t hostfs -o /home
2220
2221
2222
2223
2224 will mount the hosts's /home on the virtual machine's /mnt/home.
2225
2226
2227
2228 99..22.. hhoossttffss aass tthhee rroooott ffiilleessyysstteemm
2229
2230 It's possible to boot from a directory hierarchy on the host using
2231 hostfs rather than using the standard filesystem in a file.
2232
2233 To start, you need that hierarchy. The easiest way is to loop mount
2234 an existing root_fs file:
2235
2236
2237 host# mount root_fs uml_root_dir -o loop
2238
2239
2240
2241
2242 You need to change the filesystem type of / in etc/fstab to be
2243 'hostfs', so that line looks like this:
2244
2245 /dev/ubd/0 / hostfs defaults 1 1
2246
2247
2248
2249
2250 Then you need to chown to yourself all the files in that directory
2251 that are owned by root. This worked for me:
2252
2253
2254 host# find . -uid 0 -exec chown jdike {} \;
2255
2256
2257
2258
2259 Next, make sure that your UML kernel has hostfs compiled in, not as a
2260 module. Then run UML with the boot device pointing at that directory:
2261
2262
2263 ubd0=/path/to/uml/root/directory
2264
2265
2266
2267
2268 UML should then boot as it does normally.
2269
2270
2271 99..33.. BBuuiillddiinngg hhoossttffss
2272
2273 If you need to build hostfs because it's not in your kernel, you have
2274 two choices:
2275
2276
2277
2278 +o Compiling hostfs into the kernel:
2279
2280
2281 Reconfigure the kernel and set the 'Host filesystem' option under
2282
2283
2284 +o Compiling hostfs as a module:
2285
2286
2287 Reconfigure the kernel and set the 'Host filesystem' option under
2288 be in arch/um/fs/hostfs/hostfs.o. Install that in
2289 /lib/modules/`uname -r`/fs in the virtual machine, boot it up, and
2290
2291
2292 UML# insmod hostfs
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305 1100.. TThhee MMaannaaggeemmeenntt CCoonnssoollee
2306
2307
2308
2309 The UML management console is a low-level interface to the kernel,
2310 somewhat like the i386 SysRq interface. Since there is a full-blown
2311 operating system under UML, there is much greater flexibility possible
2312 than with the SysRq mechanism.
2313
2314
2315 There are a number of things you can do with the mconsole interface:
2316
2317 +o get the kernel version
2318
2319 +o add and remove devices
2320
2321 +o halt or reboot the machine
2322
2323 +o Send SysRq commands
2324
2325 +o Pause and resume the UML
2326
2327
2328 You need the mconsole client (uml_mconsole) which is present in CVS
2329 (/tools/mconsole) in 2.4.5-9um and later, and will be in the RPM in
2330 2.4.6.
2331
2332
2333 You also need CONFIG_MCONSOLE (under 'General Setup') enabled in UML.
2334 When you boot UML, you'll see a line like:
2335
2336
2337 mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole
2338
2339
2340
2341
2342 If you specify a unique machine id one the UML command line, i.e.
2343
2344
2345 umid=debian
2346
2347
2348
2349
2350 you'll see this
2351
2352
2353 mconsole initialized on /home/jdike/.uml/debian/mconsole
2354
2355
2356
2357
2358 That file is the socket that uml_mconsole will use to communicate with
2359 UML. Run it with either the umid or the full path as its argument:
2360
2361
2362 host% uml_mconsole debian
2363
2364
2365
2366
2367 or
2368
2369
2370 host% uml_mconsole /home/jdike/.uml/debian/mconsole
2371
2372
2373
2374
2375 You'll get a prompt, at which you can run one of these commands:
2376
2377 +o version
2378
2379 +o halt
2380
2381 +o reboot
2382
2383 +o config
2384
2385 +o remove
2386
2387 +o sysrq
2388
2389 +o help
2390
2391 +o cad
2392
2393 +o stop
2394
2395 +o go
2396
2397
2398 1100..11.. vveerrssiioonn
2399
2400 This takes no arguments. It prints the UML version.
2401
2402
2403 (mconsole) version
2404 OK Linux usermode 2.4.5-9um #1 Wed Jun 20 22:47:08 EDT 2001 i686
2405
2406
2407
2408
2409 There are a couple actual uses for this. It's a simple no-op which
2410 can be used to check that a UML is running. It's also a way of
2411 sending an interrupt to the UML. This is sometimes useful on SMP
2412 hosts, where there's a bug which causes signals to UML to be lost,
2413 often causing it to appear to hang. Sending such a UML the mconsole
2414 version command is a good way to 'wake it up' before networking has
2415 been enabled, as it does not do anything to the function of the UML.
2416
2417
2418
2419 1100..22.. hhaalltt aanndd rreebboooott
2420
2421 These take no arguments. They shut the machine down immediately, with
2422 no syncing of disks and no clean shutdown of userspace. So, they are
2423 pretty close to crashing the machine.
2424
2425
2426 (mconsole) halt
2427 OK
2428
2429
2430
2431
2432
2433
2434 1100..33.. ccoonnffiigg
2435
2436 "config" adds a new device to the virtual machine. Currently the ubd
2437 and network drivers support this. It takes one argument, which is the
2438 device to add, with the same syntax as the kernel command line.
2439
2440
2441
2442
2443 (mconsole)
2444 config ubd3=/home/jdike/incoming/roots/root_fs_debian22
2445
2446 OK
2447 (mconsole) config eth1=mcast
2448 OK
2449
2450
2451
2452
2453
2454
2455 1100..44.. rreemmoovvee
2456
2457 "remove" deletes a device from the system. Its argument is just the
2458 name of the device to be removed. The device must be idle in whatever
2459 sense the driver considers necessary. In the case of the ubd driver,
2460 the removed block device must not be mounted, swapped on, or otherwise
2461 open, and in the case of the network driver, the device must be down.
2462
2463
2464 (mconsole) remove ubd3
2465 OK
2466 (mconsole) remove eth1
2467 OK
2468
2469
2470
2471
2472
2473
2474 1100..55.. ssyyssrrqq
2475
2476 This takes one argument, which is a single letter. It calls the
2477 generic kernel's SysRq driver, which does whatever is called for by
2478 that argument. See the SysRq documentation in Documentation/sysrq.txt
2479 in your favorite kernel tree to see what letters are valid and what
2480 they do.
2481
2482
2483
2484 1100..66.. hheellpp
2485
2486 "help" returns a string listing the valid commands and what each one
2487 does.
2488
2489
2490
2491 1100..77.. ccaadd
2492
2493 This invokes the Ctl-Alt-Del action on init. What exactly this ends
2494 up doing is up to /etc/inittab. Normally, it reboots the machine.
2495 With UML, this is usually not desired, so if a halt would be better,
2496 then find the section of inittab that looks like this
2497
2498
2499 # What to do when CTRL-ALT-DEL is pressed.
2500 ca:12345:ctrlaltdel:/sbin/shutdown -t1 -a -r now
2501
2502
2503
2504
2505 and change the command to halt.
2506
2507
2508
2509 1100..88.. ssttoopp
2510
2511 This puts the UML in a loop reading mconsole requests until a 'go'
2512 mconsole command is received. This is very useful for making backups
2513 of UML filesystems, as the UML can be stopped, then synced via 'sysrq
2514 s', so that everything is written to the filesystem. You can then copy
2515 the filesystem and then send the UML 'go' via mconsole.
2516
2517
2518 Note that a UML running with more than one CPU will have problems
2519 after you send the 'stop' command, as only one CPU will be held in a
2520 mconsole loop and all others will continue as normal. This is a bug,
2521 and will be fixed.
2522
2523
2524
2525 1100..99.. ggoo
2526
2527 This resumes a UML after being paused by a 'stop' command. Note that
2528 when the UML has resumed, TCP connections may have timed out and if
2529 the UML is paused for a long period of time, crond might go a little
2530 crazy, running all the jobs it didn't do earlier.
2531
2532
2533
2534
2535
2536
2537
2538
2539 1111.. KKeerrnneell ddeebbuuggggiinngg
2540
2541
2542 NNoottee:: The interface that makes debugging, as described here, possible
2543 is present in 2.4.0-test6 kernels and later.
2544
2545
2546 Since the user-mode kernel runs as a normal Linux process, it is
2547 possible to debug it with gdb almost like any other process. It is
2548 slightly different because the kernel's threads are already being
2549 ptraced for system call interception, so gdb can't ptrace them.
2550 However, a mechanism has been added to work around that problem.
2551
2552
2553 In order to debug the kernel, you need build it from source. See
2554 ``Compiling the kernel and modules'' for information on doing that.
2555 Make sure that you enable CONFIG_DEBUGSYM and CONFIG_PT_PROXY during
2556 the config. These will compile the kernel with -g, and enable the
2557 ptrace proxy so that gdb works with UML, respectively.
2558
2559
2560
2561
2562 1111..11.. SSttaarrttiinngg tthhee kkeerrnneell uunnddeerr ggddbb
2563
2564 You can have the kernel running under the control of gdb from the
2565 beginning by putting 'debug' on the command line. You will get an
2566 xterm with gdb running inside it. The kernel will send some commands
2567 to gdb which will leave it stopped at the beginning of start_kernel.
2568 At this point, you can get things going with 'next', 'step', or
2569 'cont'.
2570
2571
2572 There is a transcript of a debugging session here <debug-
2573 session.html> , with breakpoints being set in the scheduler and in an
2574 interrupt handler.
2575 1111..22.. EExxaammiinniinngg sslleeeeppiinngg pprroocceesssseess
2576
2577 Not every bug is evident in the currently running process. Sometimes,
2578 processes hang in the kernel when they shouldn't because they've
2579 deadlocked on a semaphore or something similar. In this case, when
2580 you ^C gdb and get a backtrace, you will see the idle thread, which
2581 isn't very relevant.
2582
2583
2584 What you want is the stack of whatever process is sleeping when it
2585 shouldn't be. You need to figure out which process that is, which is
2586 generally fairly easy. Then you need to get its host process id,
2587 which you can do either by looking at ps on the host or at
2588 task.thread.extern_pid in gdb.
2589
2590
2591 Now what you do is this:
2592
2593 +o detach from the current thread
2594
2595
2596 (UML gdb) det
2597
2598
2599
2600
2601
2602 +o attach to the thread you are interested in
2603
2604
2605 (UML gdb) att <host pid>
2606
2607
2608
2609
2610
2611 +o look at its stack and anything else of interest
2612
2613
2614 (UML gdb) bt
2615
2616
2617
2618
2619 Note that you can't do anything at this point that requires that a
2620 process execute, e.g. calling a function
2621
2622 +o when you're done looking at that process, reattach to the current
2623 thread and continue it
2624
2625
2626 (UML gdb)
2627 att 1
2628
2629
2630
2631
2632
2633
2634 (UML gdb)
2635 c
2636
2637
2638
2639
2640 Here, specifying any pid which is not the process id of a UML thread
2641 will cause gdb to reattach to the current thread. I commonly use 1,
2642 but any other invalid pid would work.
2643
2644
2645
2646 1111..33.. RRuunnnniinngg dddddd oonn UUMMLL
2647
2648 ddd works on UML, but requires a special kludge. The process goes
2649 like this:
2650
2651 +o Start ddd
2652
2653
2654 host% ddd linux
2655
2656
2657
2658
2659
2660 +o With ps, get the pid of the gdb that ddd started. You can ask the
2661 gdb to tell you, but for some reason that confuses things and
2662 causes a hang.
2663
2664 +o run UML with 'debug=parent gdb-pid=<pid>' added to the command line
2665 - it will just sit there after you hit return
2666
2667 +o type 'att 1' to the ddd gdb and you will see something like
2668
2669
2670 0xa013dc51 in __kill ()
2671
2672
2673 (gdb)
2674
2675
2676
2677
2678
2679 +o At this point, type 'c', UML will boot up, and you can use ddd just
2680 as you do on any other process.
2681
2682
2683
2684 1111..44.. DDeebbuuggggiinngg mmoodduulleess
2685
2686 gdb has support for debugging code which is dynamically loaded into
2687 the process. This support is what is needed to debug kernel modules
2688 under UML.
2689
2690
2691 Using that support is somewhat complicated. You have to tell gdb what
2692 object file you just loaded into UML and where in memory it is. Then,
2693 it can read the symbol table, and figure out where all the symbols are
2694 from the load address that you provided. It gets more interesting
2695 when you load the module again (i.e. after an rmmod). You have to
2696 tell gdb to forget about all its symbols, including the main UML ones
2697 for some reason, then load then all back in again.
2698
2699
2700 There's an easy way and a hard way to do this. The easy way is to use
2701 the umlgdb expect script written by Chandan Kudige. It basically
2702 automates the process for you.
2703
2704
2705 First, you must tell it where your modules are. There is a list in
2706 the script that looks like this:
2707 set MODULE_PATHS {
2708 "fat" "/usr/src/uml/linux-2.4.18/fs/fat/fat.o"
2709 "isofs" "/usr/src/uml/linux-2.4.18/fs/isofs/isofs.o"
2710 "minix" "/usr/src/uml/linux-2.4.18/fs/minix/minix.o"
2711 }
2712
2713
2714
2715
2716 You change that to list the names and paths of the modules that you
2717 are going to debug. Then you run it from the toplevel directory of
2718 your UML pool and it basically tells you what to do:
2719
2720
2721
2722
2723 ******** GDB pid is 21903 ********
2724 Start UML as: ./linux <kernel switches> debug gdb-pid=21903
2725
2726
2727
2728 GNU gdb 5.0rh-5 Red Hat Linux 7.1
2729 Copyright 2001 Free Software Foundation, Inc.
2730 GDB is free software, covered by the GNU General Public License, and you are
2731 welcome to change it and/or distribute copies of it under certain conditions.
2732 Type "show copying" to see the conditions.
2733 There is absolutely no warranty for GDB. Type "show warranty" for details.
2734 This GDB was configured as "i386-redhat-linux"...
2735 (gdb) b sys_init_module
2736 Breakpoint 1 at 0xa0011923: file module.c, line 349.
2737 (gdb) att 1
2738
2739
2740
2741
2742 After you run UML and it sits there doing nothing, you hit return at
2743 the 'att 1' and continue it:
2744
2745
2746 Attaching to program: /home/jdike/linux/2.4/um/./linux, process 1
2747 0xa00f4221 in __kill ()
2748 (UML gdb) c
2749 Continuing.
2750
2751
2752
2753
2754 At this point, you debug normally. When you insmod something, the
2755 expect magic will kick in and you'll see something like:
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773 *** Module hostfs loaded ***
2774 Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
2775 mod_user=0x8070e00) at module.c:349
2776 349 char *name, *n_name, *name_tmp = NULL;
2777 (UML gdb) finish
2778 Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
2779 mod_user=0x8070e00) at module.c:349
2780 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
2781 411 else res = EXECUTE_SYSCALL(syscall, regs);
2782 Value returned is $1 = 0
2783 (UML gdb)
2784 p/x (int)module_list + module_list->size_of_struct
2785
2786 $2 = 0xa9021054
2787 (UML gdb) symbol-file ./linux
2788 Load new symbol table from "./linux"? (y or n) y
2789 Reading symbols from ./linux...
2790 done.
2791 (UML gdb)
2792 add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
2793
2794 add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
2795 .text_addr = 0xa9021054
2796 (y or n) y
2797
2798 Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
2799 done.
2800 (UML gdb) p *module_list
2801 $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
2802 size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
2803 nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
2804 init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
2805 ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
2806 persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
2807 kallsyms_end = 0x0,
2808 archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
2809 archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
2810 kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
2811 >> Finished loading symbols for hostfs ...
2812
2813
2814
2815
2816 That's the easy way. It's highly recommended. The hard way is
2817 described below in case you're interested in what's going on.
2818
2819
2820 Boot the kernel under the debugger and load the module with insmod or
2821 modprobe. With gdb, do:
2822
2823
2824 (UML gdb) p module_list
2825
2826
2827
2828
2829 This is a list of modules that have been loaded into the kernel, with
2830 the most recently loaded module first. Normally, the module you want
2831 is at module_list. If it's not, walk down the next links, looking at
2832 the name fields until find the module you want to debug. Take the
2833 address of that structure, and add module.size_of_struct (which in
2834 2.4.10 kernels is 96 (0x60)) to it. Gdb can make this hard addition
2835 for you :-):
2836
2837
2838
2839 (UML gdb)
2840 printf "%#x\n", (int)module_list module_list->size_of_struct
2841
2842
2843
2844
2845 The offset from the module start occasionally changes (before 2.4.0,
2846 it was module.size_of_struct + 4), so it's a good idea to check the
2847 init and cleanup addresses once in a while, as describe below. Now
2848 do:
2849
2850
2851 (UML gdb)
2852 add-symbol-file /path/to/module/on/host that_address
2853
2854
2855
2856
2857 Tell gdb you really want to do it, and you're in business.
2858
2859
2860 If there's any doubt that you got the offset right, like breakpoints
2861 appear not to work, or they're appearing in the wrong place, you can
2862 check it by looking at the module structure. The init and cleanup
2863 fields should look like:
2864
2865
2866 init = 0x588066b0 <init_hostfs>, cleanup = 0x588066c0 <exit_hostfs>
2867
2868
2869
2870
2871 with no offsets on the symbol names. If the names are right, but they
2872 are offset, then the offset tells you how much you need to add to the
2873 address you gave to add-symbol-file.
2874
2875
2876 When you want to load in a new version of the module, you need to get
2877 gdb to forget about the old one. The only way I've found to do that
2878 is to tell gdb to forget about all symbols that it knows about:
2879
2880
2881 (UML gdb) symbol-file
2882
2883
2884
2885
2886 Then reload the symbols from the kernel binary:
2887
2888
2889 (UML gdb) symbol-file /path/to/kernel
2890
2891
2892
2893
2894 and repeat the process above. You'll also need to re-enable break-
2895 points. They were disabled when you dumped all the symbols because
2896 gdb couldn't figure out where they should go.
2897
2898
2899
2900 1111..55.. AAttttaacchhiinngg ggddbb ttoo tthhee kkeerrnneell
2901
2902 If you don't have the kernel running under gdb, you can attach gdb to
2903 it later by sending the tracing thread a SIGUSR1. The first line of
2904 the console output identifies its pid:
2905 tracing thread pid = 20093
2906
2907
2908
2909
2910 When you send it the signal:
2911
2912
2913 host% kill -USR1 20093
2914
2915
2916
2917
2918 you will get an xterm with gdb running in it.
2919
2920
2921 If you have the mconsole compiled into UML, then the mconsole client
2922 can be used to start gdb:
2923
2924
2925 (mconsole) (mconsole) config gdb=xterm
2926
2927
2928
2929
2930 will fire up an xterm with gdb running in it.
2931
2932
2933
2934 1111..66.. UUssiinngg aalltteerrnnaattee ddeebbuuggggeerrss
2935
2936 UML has support for attaching to an already running debugger rather
2937 than starting gdb itself. This is present in CVS as of 17 Apr 2001.
2938 I sent it to Alan for inclusion in the ac tree, and it will be in my
2939 2.4.4 release.
2940
2941
2942 This is useful when gdb is a subprocess of some UI, such as emacs or
2943 ddd. It can also be used to run debuggers other than gdb on UML.
2944 Below is an example of using strace as an alternate debugger.
2945
2946
2947 To do this, you need to get the pid of the debugger and pass it in
2948 with the
2949
2950
2951 If you are using gdb under some UI, then tell it to 'att 1', and
2952 you'll find yourself attached to UML.
2953
2954
2955 If you are using something other than gdb as your debugger, then
2956 you'll need to get it to do the equivalent of 'att 1' if it doesn't do
2957 it automatically.
2958
2959
2960 An example of an alternate debugger is strace. You can strace the
2961 actual kernel as follows:
2962
2963 +o Run the following in a shell
2964
2965
2966 host%
2967 sh -c 'echo pid=$$; echo -n hit return; read x; exec strace -p 1 -o strace.out'
2968
2969
2970
2971 +o Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
2972 by the previous command
2973
2974 +o Hit return in the shell, and UML will start running, and strace
2975 output will start accumulating in the output file.
2976
2977 Note that this is different from running
2978
2979
2980 host% strace ./linux
2981
2982
2983
2984
2985 That will strace only the main UML thread, the tracing thread, which
2986 doesn't do any of the actual kernel work. It just oversees the vir-
2987 tual machine. In contrast, using strace as described above will show
2988 you the low-level activity of the virtual machine.
2989
2990
2991
2992
2993
2994 1122.. KKeerrnneell ddeebbuuggggiinngg eexxaammpplleess
2995
2996 1122..11.. TThhee ccaassee ooff tthhee hhuunngg ffsscckk
2997
2998 When booting up the kernel, fsck failed, and dropped me into a shell
2999 to fix things up. I ran fsck -y, which hung:
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037 Setting hostname uml [ OK ]
3038 Checking root filesystem
3039 /dev/fhd0 was not cleanly unmounted, check forced.
3040 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
3041
3042 /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
3043 (i.e., without -a or -p options)
3044 [ FAILED ]
3045
3046 *** An error occurred during the file system check.
3047 *** Dropping you to a shell; the system will reboot
3048 *** when you leave the shell.
3049 Give root password for maintenance
3050 (or type Control-D for normal startup):
3051
3052 [root@uml /root]# fsck -y /dev/fhd0
3053 fsck -y /dev/fhd0
3054 Parallelizing fsck version 1.14 (9-Jan-1999)
3055 e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
3056 /dev/fhd0 contains a file system with errors, check forced.
3057 Pass 1: Checking inodes, blocks, and sizes
3058 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
3059
3060 Inode 19780, i_blocks is 1548, should be 540. Fix? yes
3061
3062 Pass 2: Checking directory structure
3063 Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
3064
3065 Directory inode 11858, block 0, offset 0: directory corrupted
3066 Salvage? yes
3067
3068 Missing '.' in directory inode 11858.
3069 Fix? yes
3070
3071 Missing '..' in directory inode 11858.
3072 Fix? yes
3073
3074
3075
3076
3077
3078 The standard drill in this sort of situation is to fire up gdb on the
3079 signal thread, which, in this case, was pid 1935. In another window,
3080 I run gdb and attach pid 1935.
3081
3082
3083
3084
3085 ~/linux/2.3.26/um 1016: gdb linux
3086 GNU gdb 4.17.0.11 with Linux support
3087 Copyright 1998 Free Software Foundation, Inc.
3088 GDB is free software, covered by the GNU General Public License, and you are
3089 welcome to change it and/or distribute copies of it under certain conditions.
3090 Type "show copying" to see the conditions.
3091 There is absolutely no warranty for GDB. Type "show warranty" for details.
3092 This GDB was configured as "i386-redhat-linux"...
3093
3094 (gdb) att 1935
3095 Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 1935
3096 0x100756d9 in __wait4 ()
3097
3098
3099
3100
3101
3102
3103 Let's see what's currently running:
3104
3105
3106
3107 (gdb) p current_task.pid
3108 $1 = 0
3109
3110
3111
3112
3113
3114 It's the idle thread, which means that fsck went to sleep for some
3115 reason and never woke up.
3116
3117
3118 Let's guess that the last process in the process list is fsck:
3119
3120
3121
3122 (gdb) p current_task.prev_task.comm
3123 $13 = "fsck.ext2\000\000\000\000\000\000"
3124
3125
3126
3127
3128
3129 It is, so let's see what it thinks it's up to:
3130
3131
3132
3133 (gdb) p current_task.prev_task.thread
3134 $14 = {extern_pid = 1980, tracing = 0, want_tracing = 0, forking = 0,
3135 kernel_stack_page = 0, signal_stack = 1342627840, syscall = {id = 4, args = {
3136 3, 134973440, 1024, 0, 1024}, have_result = 0, result = 50590720},
3137 request = {op = 2, u = {exec = {ip = 1350467584, sp = 2952789424}, fork = {
3138 regs = {1350467584, 2952789424, 0 <repeats 15 times>}, sigstack = 0,
3139 pid = 0}, switch_to = 0x507e8000, thread = {proc = 0x507e8000,
3140 arg = 0xaffffdb0, flags = 0, new_pid = 0}, input_request = {
3141 op = 1350467584, fd = -1342177872, proc = 0, pid = 0}}}}
3142
3143
3144
3145
3146
3147 The interesting things here are the fact that its .thread.syscall.id
3148 is __NR_write (see the big switch in arch/um/kernel/syscall_kern.c or
3149 the defines in include/asm-um/arch/unistd.h), and that it never
3150 returned. Also, its .request.op is OP_SWITCH (see
3151 arch/um/include/user_util.h). These mean that it went into a write,
3152 and, for some reason, called schedule().
3153
3154
3155 The fact that it never returned from write means that its stack should
3156 be fairly interesting. Its pid is 1980 (.thread.extern_pid). That
3157 process is being ptraced by the signal thread, so it must be detached
3158 before gdb can attach it:
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169 (gdb) call detach(1980)
3170
3171 Program received signal SIGSEGV, Segmentation fault.
3172 <function called from gdb>
3173 The program being debugged stopped while in a function called from GDB.
3174 When the function (detach) is done executing, GDB will silently
3175 stop (instead of continuing to evaluate the expression containing
3176 the function call).
3177 (gdb) call detach(1980)
3178 $15 = 0
3179
3180
3181
3182
3183
3184 The first detach segfaults for some reason, and the second one
3185 succeeds.
3186
3187
3188 Now I detach from the signal thread, attach to the fsck thread, and
3189 look at its stack:
3190
3191
3192 (gdb) det
3193 Detaching from program: /home/dike/linux/2.3.26/um/linux Pid 1935
3194 (gdb) att 1980
3195 Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 1980
3196 0x10070451 in __kill ()
3197 (gdb) bt
3198 #0 0x10070451 in __kill ()
3199 #1 0x10068ccd in usr1_pid (pid=1980) at process.c:30
3200 #2 0x1006a03f in _switch_to (prev=0x50072000, next=0x507e8000)
3201 at process_kern.c:156
3202 #3 0x1006a052 in switch_to (prev=0x50072000, next=0x507e8000, last=0x50072000)
3203 at process_kern.c:161
3204 #4 0x10001d12 in schedule () at sched.c:777
3205 #5 0x1006a744 in __down (sem=0x507d241c) at semaphore.c:71
3206 #6 0x1006aa10 in __down_failed () at semaphore.c:157
3207 #7 0x1006c5d8 in segv_handler (sc=0x5006e940) at trap_user.c:174
3208 #8 0x1006c5ec in kern_segv_handler (sig=11) at trap_user.c:182
3209 #9 <signal handler called>
3210 #10 0x10155404 in errno ()
3211 #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
3212 #12 0x1006c5d8 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
3213 #13 0x1006c5ec in kern_segv_handler (sig=11) at trap_user.c:182
3214 #14 <signal handler called>
3215 #15 0xc0fd in ?? ()
3216 #16 0x10016647 in sys_write (fd=3,
3217 buf=0x80b8800 <Address 0x80b8800 out of bounds>, count=1024)
3218 at read_write.c:159
3219 #17 0x1006d5b3 in execute_syscall (syscall=4, args=0x5006ef08)
3220 at syscall_kern.c:254
3221 #18 0x1006af87 in really_do_syscall (sig=12) at syscall_user.c:35
3222 #19 <signal handler called>
3223 #20 0x400dc8b0 in ?? ()
3224
3225
3226
3227
3228
3229 The interesting things here are :
3230
3231 +o There are two segfaults on this stack (frames 9 and 14)
3232
3233 +o The first faulting address (frame 11) is 0x50000800
3234
3235 (gdb) p (void *)1342179328
3236 $16 = (void *) 0x50000800
3237
3238
3239
3240
3241
3242 The initial faulting address is interesting because it is on the idle
3243 thread's stack. I had been seeing the idle thread segfault for no
3244 apparent reason, and the cause looked like stack corruption. In hopes
3245 of catching the culprit in the act, I had turned off all protections
3246 to that stack while the idle thread wasn't running. This apparently
3247 tripped that trap.
3248
3249
3250 However, the more immediate problem is that second segfault and I'm
3251 going to concentrate on that. First, I want to see where the fault
3252 happened, so I have to go look at the sigcontent struct in frame 8:
3253
3254
3255
3256 (gdb) up
3257 #1 0x10068ccd in usr1_pid (pid=1980) at process.c:30
3258 30 kill(pid, SIGUSR1);
3259 (gdb)
3260 #2 0x1006a03f in _switch_to (prev=0x50072000, next=0x507e8000)
3261 at process_kern.c:156
3262 156 usr1_pid(getpid());
3263 (gdb)
3264 #3 0x1006a052 in switch_to (prev=0x50072000, next=0x507e8000, last=0x50072000)
3265 at process_kern.c:161
3266 161 _switch_to(prev, next);
3267 (gdb)
3268 #4 0x10001d12 in schedule () at sched.c:777
3269 777 switch_to(prev, next, prev);
3270 (gdb)
3271 #5 0x1006a744 in __down (sem=0x507d241c) at semaphore.c:71
3272 71 schedule();
3273 (gdb)
3274 #6 0x1006aa10 in __down_failed () at semaphore.c:157
3275 157 }
3276 (gdb)
3277 #7 0x1006c5d8 in segv_handler (sc=0x5006e940) at trap_user.c:174
3278 174 segv(sc->cr2, sc->err & 2);
3279 (gdb)
3280 #8 0x1006c5ec in kern_segv_handler (sig=11) at trap_user.c:182
3281 182 segv_handler(sc);
3282 (gdb) p *sc
3283 Cannot access memory at address 0x0.
3284
3285
3286
3287
3288 That's not very useful, so I'll try a more manual method:
3289
3290
3291 (gdb) p *((struct sigcontext *) (&sig + 1))
3292 $19 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
3293 __dsh = 0, edi = 1342179328, esi = 1350378548, ebp = 1342630440,
3294 esp = 1342630420, ebx = 1348150624, edx = 1280, ecx = 0, eax = 0,
3295 trapno = 14, err = 4, eip = 268480945, cs = 35, __csh = 0, eflags = 66118,
3296 esp_at_signal = 1342630420, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
3297 cr2 = 1280}
3298
3299
3300
3301 The ip is in handle_mm_fault:
3302
3303
3304 (gdb) p (void *)268480945
3305 $20 = (void *) 0x1000b1b1
3306 (gdb) i sym $20
3307 handle_mm_fault + 57 in section .text
3308
3309
3310
3311
3312
3313 Specifically, it's in pte_alloc:
3314
3315
3316 (gdb) i line *$20
3317 Line 124 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3318 starts at address 0x1000b1b1 <handle_mm_fault+57>
3319 and ends at 0x1000b1b7 <handle_mm_fault+63>.
3320
3321
3322
3323
3324
3325 To find where in handle_mm_fault this is, I'll jump forward in the
3326 code until I see an address in that procedure:
3327
3328
3329
3330 (gdb) i line *0x1000b1c0
3331 Line 126 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3332 starts at address 0x1000b1b7 <handle_mm_fault+63>
3333 and ends at 0x1000b1c3 <handle_mm_fault+75>.
3334 (gdb) i line *0x1000b1d0
3335 Line 131 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3336 starts at address 0x1000b1d0 <handle_mm_fault+88>
3337 and ends at 0x1000b1da <handle_mm_fault+98>.
3338 (gdb) i line *0x1000b1e0
3339 Line 61 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3340 starts at address 0x1000b1da <handle_mm_fault+98>
3341 and ends at 0x1000b1e1 <handle_mm_fault+105>.
3342 (gdb) i line *0x1000b1f0
3343 Line 134 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3344 starts at address 0x1000b1f0 <handle_mm_fault+120>
3345 and ends at 0x1000b200 <handle_mm_fault+136>.
3346 (gdb) i line *0x1000b200
3347 Line 135 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3348 starts at address 0x1000b200 <handle_mm_fault+136>
3349 and ends at 0x1000b208 <handle_mm_fault+144>.
3350 (gdb) i line *0x1000b210
3351 Line 139 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3352 starts at address 0x1000b210 <handle_mm_fault+152>
3353 and ends at 0x1000b219 <handle_mm_fault+161>.
3354 (gdb) i line *0x1000b220
3355 Line 1168 of "memory.c" starts at address 0x1000b21e <handle_mm_fault+166>
3356 and ends at 0x1000b222 <handle_mm_fault+170>.
3357
3358
3359
3360
3361
3362 Something is apparently wrong with the page tables or vma_structs, so
3363 lets go back to frame 11 and have a look at them:
3364
3365
3366
3367 #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
3368 50 handle_mm_fault(current, vma, address, is_write);
3369 (gdb) call pgd_offset_proc(vma->vm_mm, address)
3370 $22 = (pgd_t *) 0x80a548c
3371
3372
3373
3374
3375
3376 That's pretty bogus. Page tables aren't supposed to be in process
3377 text or data areas. Let's see what's in the vma:
3378
3379
3380 (gdb) p *vma
3381 $23 = {vm_mm = 0x507d2434, vm_start = 0, vm_end = 134512640,
3382 vm_next = 0x80a4f8c, vm_page_prot = {pgprot = 0}, vm_flags = 31200,
3383 vm_avl_height = 2058, vm_avl_left = 0x80a8c94, vm_avl_right = 0x80d1000,
3384 vm_next_share = 0xaffffdb0, vm_pprev_share = 0xaffffe63,
3385 vm_ops = 0xaffffe7a, vm_pgoff = 2952789626, vm_file = 0xafffffec,
3386 vm_private_data = 0x62}
3387 (gdb) p *vma.vm_mm
3388 $24 = {mmap = 0x507d2434, mmap_avl = 0x0, mmap_cache = 0x8048000,
3389 pgd = 0x80a4f8c, mm_users = {counter = 0}, mm_count = {counter = 134904288},
3390 map_count = 134909076, mmap_sem = {count = {counter = 135073792},
3391 sleepers = -1342177872, wait = {lock = <optimized out or zero length>,
3392 task_list = {next = 0xaffffe63, prev = 0xaffffe7a},
3393 __magic = -1342177670, __creator = -1342177300}, __magic = 98},
3394 page_table_lock = {}, context = 138, start_code = 0, end_code = 0,
3395 start_data = 0, end_data = 0, start_brk = 0, brk = 0, start_stack = 0,
3396 arg_start = 0, arg_end = 0, env_start = 0, env_end = 0, rss = 1350381536,
3397 total_vm = 0, locked_vm = 0, def_flags = 0, cpu_vm_mask = 0, swap_cnt = 0,
3398 swap_address = 0, segments = 0x0}
3399
3400
3401
3402
3403
3404 This also pretty bogus. With all of the 0x80xxxxx and 0xaffffxxx
3405 addresses, this is looking like a stack was plonked down on top of
3406 these structures. Maybe it's a stack overflow from the next page:
3407
3408
3409
3410 (gdb) p vma
3411 $25 = (struct vm_area_struct *) 0x507d2434
3412
3413
3414
3415
3416
3417 That's towards the lower quarter of the page, so that would have to
3418 have been pretty heavy stack overflow:
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433 (gdb) x/100x $25
3434 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
3435 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
3436 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
3437 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
3438 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
3439 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
3440 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
3441 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
3442 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
3443 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
3444 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
3445 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
3446 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
3447 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
3448 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
3449 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
3450 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
3451 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
3452 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
3453 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
3454 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
3455 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
3456 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
3457 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
3458 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
3459
3460
3461
3462
3463
3464 It's not stack overflow. The only "stack-like" piece of this data is
3465 the vma_struct itself.
3466
3467
3468 At this point, I don't see any avenues to pursue, so I just have to
3469 admit that I have no idea what's going on. What I will do, though, is
3470 stick a trap on the segfault handler which will stop if it sees any
3471 writes to the idle thread's stack. That was the thing that happened
3472 first, and it may be that if I can catch it immediately, what's going
3473 on will be somewhat clearer.
3474
3475
3476 1122..22.. EEppiissooddee 22:: TThhee ccaassee ooff tthhee hhuunngg ffsscckk
3477
3478 After setting a trap in the SEGV handler for accesses to the signal
3479 thread's stack, I reran the kernel.
3480
3481
3482 fsck hung again, this time by hitting the trap:
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499 Setting hostname uml [ OK ]
3500 Checking root filesystem
3501 /dev/fhd0 contains a file system with errors, check forced.
3502 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
3503
3504 /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
3505 (i.e., without -a or -p options)
3506 [ FAILED ]
3507
3508 *** An error occurred during the file system check.
3509 *** Dropping you to a shell; the system will reboot
3510 *** when you leave the shell.
3511 Give root password for maintenance
3512 (or type Control-D for normal startup):
3513
3514 [root@uml /root]# fsck -y /dev/fhd0
3515 fsck -y /dev/fhd0
3516 Parallelizing fsck version 1.14 (9-Jan-1999)
3517 e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
3518 /dev/fhd0 contains a file system with errors, check forced.
3519 Pass 1: Checking inodes, blocks, and sizes
3520 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
3521
3522 Pass 2: Checking directory structure
3523 Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
3524
3525 Directory inode 11858, block 0, offset 0: directory corrupted
3526 Salvage? yes
3527
3528 Missing '.' in directory inode 11858.
3529 Fix? yes
3530
3531 Missing '..' in directory inode 11858.
3532 Fix? yes
3533
3534 Untested (4127) [100fe44c]: trap_kern.c line 31
3535
3536
3537
3538
3539
3540 I need to get the signal thread to detach from pid 4127 so that I can
3541 attach to it with gdb. This is done by sending it a SIGUSR1, which is
3542 caught by the signal thread, which detaches the process:
3543
3544
3545 kill -USR1 4127
3546
3547
3548
3549
3550
3551 Now I can run gdb on it:
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565 ~/linux/2.3.26/um 1034: gdb linux
3566 GNU gdb 4.17.0.11 with Linux support
3567 Copyright 1998 Free Software Foundation, Inc.
3568 GDB is free software, covered by the GNU General Public License, and you are
3569 welcome to change it and/or distribute copies of it under certain conditions.
3570 Type "show copying" to see the conditions.
3571 There is absolutely no warranty for GDB. Type "show warranty" for details.
3572 This GDB was configured as "i386-redhat-linux"...
3573 (gdb) att 4127
3574 Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
3575 0x10075891 in __libc_nanosleep ()
3576
3577
3578
3579
3580
3581 The backtrace shows that it was in a write and that the fault address
3582 (address in frame 3) is 0x50000800, which is right in the middle of
3583 the signal thread's stack page:
3584
3585
3586 (gdb) bt
3587 #0 0x10075891 in __libc_nanosleep ()
3588 #1 0x1007584d in __sleep (seconds=1000000)
3589 at ../sysdeps/unix/sysv/linux/sleep.c:78
3590 #2 0x1006ce9a in stop () at user_util.c:191
3591 #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
3592 #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
3593 #5 0x1006c63c in kern_segv_handler (sig=11) at trap_user.c:182
3594 #6 <signal handler called>
3595 #7 0xc0fd in ?? ()
3596 #8 0x10016647 in sys_write (fd=3, buf=0x80b8800 "R.", count=1024)
3597 at read_write.c:159
3598 #9 0x1006d603 in execute_syscall (syscall=4, args=0x5006ef08)
3599 at syscall_kern.c:254
3600 #10 0x1006af87 in really_do_syscall (sig=12) at syscall_user.c:35
3601 #11 <signal handler called>
3602 #12 0x400dc8b0 in ?? ()
3603 #13 <signal handler called>
3604 #14 0x400dc8b0 in ?? ()
3605 #15 0x80545fd in ?? ()
3606 #16 0x804daae in ?? ()
3607 #17 0x8054334 in ?? ()
3608 #18 0x804d23e in ?? ()
3609 #19 0x8049632 in ?? ()
3610 #20 0x80491d2 in ?? ()
3611 #21 0x80596b5 in ?? ()
3612 (gdb) p (void *)1342179328
3613 $3 = (void *) 0x50000800
3614
3615
3616
3617
3618
3619 Going up the stack to the segv_handler frame and looking at where in
3620 the code the access happened shows that it happened near line 110 of
3621 block_dev.c:
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631 (gdb) up
3632 #1 0x1007584d in __sleep (seconds=1000000)
3633 at ../sysdeps/unix/sysv/linux/sleep.c:78
3634 ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
3635 (gdb)
3636 #2 0x1006ce9a in stop () at user_util.c:191
3637 191 while(1) sleep(1000000);
3638 (gdb)
3639 #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
3640 31 KERN_UNTESTED();
3641 (gdb)
3642 #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
3643 174 segv(sc->cr2, sc->err & 2);
3644 (gdb) p *sc
3645 $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
3646 __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
3647 esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
3648 err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
3649 esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
3650 cr2 = 1342179328}
3651 (gdb) p (void *)268550834
3652 $2 = (void *) 0x1001c2b2
3653 (gdb) i sym $2
3654 block_write + 1090 in section .text
3655 (gdb) i line *$2
3656 Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
3657 starts at address 0x1001c2a1 <block_write+1073>
3658 and ends at 0x1001c2bf <block_write+1103>.
3659 (gdb) i line *0x1001c2c0
3660 Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
3661 and ends at 0x1001c2e3 <block_write+1139>.
3662
3663
3664
3665
3666
3667 Looking at the source shows that the fault happened during a call to
3668 copy_to_user to copy the data into the kernel:
3669
3670
3671 107 count -= chars;
3672 108 copy_from_user(p,buf,chars);
3673 109 p += chars;
3674 110 buf += chars;
3675
3676
3677
3678
3679
3680 p is the pointer which must contain 0x50000800, since buf contains
3681 0x80b8800 (frame 8 above). It is defined as:
3682
3683
3684 p = offset + bh->b_data;
3685
3686
3687
3688
3689
3690 I need to figure out what bh is, and it just so happens that bh is
3691 passed as an argument to mark_buffer_uptodate and mark_buffer_dirty a
3692 few lines later, so I do a little disassembly:
3693
3694
3695
3696
3697 (gdb) disas 0x1001c2bf 0x1001c2e0
3698 Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
3699 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
3700 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
3701 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
3702 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
3703 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
3704 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
3705 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
3706 0x1001c2d8 <block_write+1128>: pushl $0x0
3707 0x1001c2da <block_write+1130>: pushl %edx
3708 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
3709 End of assembler dump.
3710
3711
3712
3713
3714
3715 At that point, bh is in %edx (address 0x1001c2da), which is calculated
3716 at 0x1001c2c2 as %ebp + 0xfffffdd4, so I figure exactly what that is,
3717 taking %ebp from the sigcontext_struct above:
3718
3719
3720 (gdb) p (void *)1342631484
3721 $5 = (void *) 0x5006ee3c
3722 (gdb) p 0x5006ee3c+0xfffffdd4
3723 $6 = 1342630928
3724 (gdb) p (void *)$6
3725 $7 = (void *) 0x5006ec10
3726 (gdb) p *((void **)$7)
3727 $8 = (void *) 0x50100200
3728
3729
3730
3731
3732
3733 Now, I look at the structure to see what's in it, and particularly,
3734 what its b_data field contains:
3735
3736
3737 (gdb) p *((struct buffer_head *)0x50100200)
3738 $13 = {b_next = 0x50289380, b_blocknr = 49405, b_size = 1024, b_list = 0,
3739 b_dev = 15872, b_count = {counter = 1}, b_rdev = 15872, b_state = 24,
3740 b_flushtime = 0, b_next_free = 0x501001a0, b_prev_free = 0x50100260,
3741 b_this_page = 0x501001a0, b_reqnext = 0x0, b_pprev = 0x507fcf58,
3742 b_data = 0x50000800 "", b_page = 0x50004000,
3743 b_end_io = 0x10017f60 <end_buffer_io_sync>, b_dev_id = 0x0,
3744 b_rsector = 98810, b_wait = {lock = <optimized out or zero length>,
3745 task_list = {next = 0x50100248, prev = 0x50100248}, __magic = 1343226448,
3746 __creator = 0}, b_kiobuf = 0x0}
3747
3748
3749
3750
3751
3752 The b_data field is indeed 0x50000800, so the question becomes how
3753 that happened. The rest of the structure looks fine, so this probably
3754 is not a case of data corruption. It happened on purpose somehow.
3755
3756
3757 The b_page field is a pointer to the page_struct representing the
3758 0x50000000 page. Looking at it shows the kernel's idea of the state
3759 of that page:
3760
3761
3762
3763 (gdb) p *$13.b_page
3764 $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
3765 index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
3766 next = 0x50008460, prev = 0x50019350}, wait = {
3767 lock = <optimized out or zero length>, task_list = {next = 0x50004024,
3768 prev = 0x50004024}, __magic = 1342193708, __creator = 0},
3769 pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
3770 zone = 0x100c5160}
3771
3772
3773
3774
3775
3776 Some sanity-checking: the virtual field shows the "virtual" address of
3777 this page, which in this kernel is the same as its "physical" address,
3778 and the page_struct itself should be mem_map[0], since it represents
3779 the first page of memory:
3780
3781
3782
3783 (gdb) p (void *)1342177280
3784 $18 = (void *) 0x50000000
3785 (gdb) p mem_map
3786 $19 = (mem_map_t *) 0x50004000
3787
3788
3789
3790
3791
3792 These check out fine.
3793
3794
3795 Now to check out the page_struct itself. In particular, the flags
3796 field shows whether the page is considered free or not:
3797
3798
3799 (gdb) p (void *)132
3800 $21 = (void *) 0x84
3801
3802
3803
3804
3805
3806 The "reserved" bit is the high bit, which is definitely not set, so
3807 the kernel considers the signal stack page to be free and available to
3808 be used.
3809
3810
3811 At this point, I jump to conclusions and start looking at my early
3812 boot code, because that's where that page is supposed to be reserved.
3813
3814
3815 In my setup_arch procedure, I have the following code which looks just
3816 fine:
3817
3818
3819
3820 bootmap_size = init_bootmem(start_pfn, end_pfn - start_pfn);
3821 free_bootmem(__pa(low_physmem) + bootmap_size, high_physmem - low_physmem);
3822
3823
3824
3825
3826
3827 Two stack pages have already been allocated, and low_physmem points to
3828 the third page, which is the beginning of free memory.
3829 The init_bootmem call declares the entire memory to the boot memory
3830 manager, which marks it all reserved. The free_bootmem call frees up
3831 all of it, except for the first two pages. This looks correct to me.
3832
3833
3834 So, I decide to see init_bootmem run and make sure that it is marking
3835 those first two pages as reserved. I never get that far.
3836
3837
3838 Stepping into init_bootmem, and looking at bootmem_map before looking
3839 at what it contains shows the following:
3840
3841
3842
3843 (gdb) p bootmem_map
3844 $3 = (void *) 0x50000000
3845
3846
3847
3848
3849
3850 Aha! The light dawns. That first page is doing double duty as a
3851 stack and as the boot memory map. The last thing that the boot memory
3852 manager does is to free the pages used by its memory map, so this page
3853 is getting freed even its marked as reserved.
3854
3855
3856 The fix was to initialize the boot memory manager before allocating
3857 those two stack pages, and then allocate them through the boot memory
3858 manager. After doing this, and fixing a couple of subsequent buglets,
3859 the stack corruption problem disappeared.
3860
3861
3862
3863
3864
3865 1133.. WWhhaatt ttoo ddoo wwhheenn UUMMLL ddooeessnn''tt wwoorrkk
3866
3867
3868
3869
3870 1133..11.. SSttrraannggee ccoommppiillaattiioonn eerrrroorrss wwhheenn yyoouu bbuuiilldd ffrroomm ssoouurrccee
3871
3872 As of test11, it is necessary to have "ARCH=um" in the environment or
3873 on the make command line for all steps in building UML, including
3874 clean, distclean, or mrproper, config, menuconfig, or xconfig, dep,
3875 and linux. If you forget for any of them, the i386 build seems to
3876 contaminate the UML build. If this happens, start from scratch with
3877
3878
3879 host%
3880 make mrproper ARCH=um
3881
3882
3883
3884
3885 and repeat the build process with ARCH=um on all the steps.
3886
3887
3888 See ``Compiling the kernel and modules'' for more details.
3889
3890
3891 Another cause of strange compilation errors is building UML in
3892 /usr/src/linux. If you do this, the first thing you need to do is
3893 clean up the mess you made. The /usr/src/linux/asm link will now
3894 point to /usr/src/linux/asm-um. Make it point back to
3895 /usr/src/linux/asm-i386. Then, move your UML pool someplace else and
3896 build it there. Also see below, where a more specific set of symptoms
3897 is described.
3898
3899
3900
3901 1133..22.. UUMMLL hhaannggss oonn bboooott aafftteerr mmoouunnttiinngg ddeevvffss
3902
3903 The boot looks like this:
3904
3905
3906 VFS: Mounted root (ext2 filesystem) readonly.
3907 Mounted devfs on /dev
3908
3909
3910
3911
3912 You're probably running a recent distribution on an old machine. I
3913 saw this with the RH7.1 filesystem running on a Pentium. The shared
3914 library loader, ld.so, was executing an instruction (cmove) which the
3915 Pentium didn't support. That instruction was apparently added later.
3916 If you run UML under the debugger, you'll see the hang caused by one
3917 instruction causing an infinite SIGILL stream.
3918
3919
3920 The fix is to boot UML on an older filesystem.
3921
3922
3923
3924 1133..33.. AA vvaarriieettyy ooff ppaanniiccss aanndd hhaannggss wwiitthh //ttmmpp oonn aa rreeiisseerrffss ffiilleessyyss--
3925 tteemm
3926
3927 I saw this on reiserfs 3.5.21 and it seems to be fixed in 3.5.27.
3928 Panics preceded by
3929
3930
3931 Detaching pid nnnn
3932
3933
3934
3935 are diagnostic of this problem. This is a reiserfs bug which causes a
3936 thread to occasionally read stale data from a mmapped page shared with
3937 another thread. The fix is to upgrade the filesystem or to have /tmp
3938 be an ext2 filesystem.
3939
3940
3941
3942 1133..44.. TThhee ccoommppiillee ffaaiillss wwiitthh eerrrroorrss aabboouutt ccoonnfflliiccttiinngg ttyyppeess ffoorr
3943 ''ooppeenn'',, ''dduupp'',, aanndd ''wwaaiittppiidd''
3944
3945 This happens when you build in /usr/src/linux. The UML build makes
3946 the include/asm link point to include/asm-um. /usr/include/asm points
3947 to /usr/src/linux/include/asm, so when that link gets moved, files
3948 which need to include the asm-i386 versions of headers get the
3949 incompatible asm-um versions. The fix is to move the include/asm link
3950 back to include/asm-i386 and to do UML builds someplace else.
3951
3952
3953
3954 1133..55.. UUMMLL ddooeessnn''tt wwoorrkk wwhheenn //ttmmpp iiss aann NNFFSS ffiilleessyysstteemm
3955
3956 This seems to be a similar situation with the resierfs problem above.
3957 Some versions of NFS seems not to handle mmap correctly, which UML
3958 depends on. The workaround is have /tmp be non-NFS directory.
3959
3960
3961 1133..66.. UUMMLL hhaannggss oonn bboooott wwhheenn ccoommppiilleedd wwiitthh ggpprrooff ssuuppppoorrtt
3962
3963 If you build UML with gprof support and, early in the boot, it does
3964 this
3965
3966
3967 kernel BUG at page_alloc.c:100!
3968
3969
3970
3971
3972 you have a buggy gcc. You can work around the problem by removing
3973 UM_FASTCALL from CFLAGS in arch/um/Makefile-i386. This will open up
3974 another bug, but that one is fairly hard to reproduce.
3975
3976
3977
3978 1133..77.. ssyyssllooggdd ddiieess wwiitthh aa SSIIGGTTEERRMM oonn ssttaarrttuupp
3979
3980 The exact boot error depends on the distribution that you're booting,
3981 but Debian produces this:
3982
3983
3984 /etc/rc2.d/S10sysklogd: line 49: 93 Terminated
3985 start-stop-daemon --start --quiet --exec /sbin/syslogd -- $SYSLOGD
3986
3987
3988
3989
3990 This is a syslogd bug. There's a race between a parent process
3991 installing a signal handler and its child sending the signal. See
3992 this uml-devel post <http://www.geocrawler.com/lists/3/Source-
3993 Forge/709/0/6612801> for the details.
3994
3995
3996
3997 1133..88.. TTUUNN//TTAAPP nneettwwoorrkkiinngg ddooeessnn''tt wwoorrkk oonn aa 22..44 hhoosstt
3998
3999 There are a couple of problems which were
4000 <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
4001 out"> by Tim Robinson <timro at trkr dot net>
4002
4003 +o It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
4004 The fix is to upgrade to something more recent and then read the
4005 next item.
4006
4007 +o If you see
4008
4009
4010 File descriptor in bad state
4011
4012
4013
4014 when you bring up the device inside UML, you have a header mismatch
4015 between the original kernel and the upgraded one. Make /usr/src/linux
4016 point at the new headers. This will only be a problem if you build
4017 uml_net yourself.
4018
4019
4020
4021 1133..99.. YYoouu ccaann nneettwwoorrkk ttoo tthhee hhoosstt bbuutt nnoott ttoo ootthheerr mmaacchhiinneess oonn tthhee
4022 nneett
4023
4024 If you can connect to the host, and the host can connect to UML, but
4025 you can not connect to any other machines, then you may need to enable
4026 IP Masquerading on the host. Usually this is only experienced when
4027 using private IP addresses (192.168.x.x or 10.x.x.x) for host/UML
4028 networking, rather than the public address space that your host is
4029 connected to. UML does not enable IP Masquerading, so you will need
4030 to create a static rule to enable it:
4031
4032
4033 host%
4034 iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
4035
4036
4037
4038
4039 Replace eth0 with the interface that you use to talk to the rest of
4040 the world.
4041
4042
4043 Documentation on IP Masquerading, and SNAT, can be found at
4044 www.netfilter.org <http://www.netfilter.org> .
4045
4046
4047 If you can reach the local net, but not the outside Internet, then
4048 that is usually a routing problem. The UML needs a default route:
4049
4050
4051 UML#
4052 route add default gw gateway IP
4053
4054
4055
4056
4057 The gateway IP can be any machine on the local net that knows how to
4058 reach the outside world. Usually, this is the host or the local net-
4059 work's gateway.
4060
4061
4062 Occasionally, we hear from someone who can reach some machines, but
4063 not others on the same net, or who can reach some ports on other
4064 machines, but not others. These are usually caused by strange
4065 firewalling somewhere between the UML and the other box. You track
4066 this down by running tcpdump on every interface the packets travel
4067 over and see where they disappear. When you find a machine that takes
4068 the packets in, but does not send them onward, that's the culprit.
4069
4070
4071
4072 1133..1100.. II hhaavvee nnoo rroooott aanndd II wwaanntt ttoo ssccrreeaamm
4073
4074 Thanks to Birgit Wahlich for telling me about this strange one. It
4075 turns out that there's a limit of six environment variables on the
4076 kernel command line. When that limit is reached or exceeded, argument
4077 processing stops, which means that the 'root=' argument that UML
4078 usually adds is not seen. So, the filesystem has no idea what the
4079 root device is, so it panics.
4080
4081
4082 The fix is to put less stuff on the command line. Glomming all your
4083 setup variables into one is probably the best way to go.
4084
4085
4086
4087 1133..1111.. UUMMLL bbuuiilldd ccoonnfflliicctt bbeettwweeeenn ppttrraaccee..hh aanndd uuccoonntteexxtt..hh
4088
4089 On some older systems, /usr/include/asm/ptrace.h and
4090 /usr/include/sys/ucontext.h define the same names. So, when they're
4091 included together, the defines from one completely mess up the parsing
4092 of the other, producing errors like:
4093 /usr/include/sys/ucontext.h:47: parse error before
4094 `10'
4095
4096
4097
4098
4099 plus a pile of warnings.
4100
4101
4102 This is a libc botch, which has since been fixed, and I don't see any
4103 way around it besides upgrading.
4104
4105
4106
4107 1133..1122.. TThhee UUMMLL BBooggooMMiippss iiss eexxaaccttllyy hhaallff tthhee hhoosstt''ss BBooggooMMiippss
4108
4109 On i386 kernels, there are two ways of running the loop that is used
4110 to calculate the BogoMips rating, using the TSC if it's there or using
4111 a one-instruction loop. The TSC produces twice the BogoMips as the
4112 loop. UML uses the loop, since it has nothing resembling a TSC, and
4113 will get almost exactly the same BogoMips as a host using the loop.
4114 However, on a host with a TSC, its BogoMips will be double the loop
4115 BogoMips, and therefore double the UML BogoMips.
4116
4117
4118
4119 1133..1133.. WWhheenn yyoouu rruunn UUMMLL,, iitt iimmmmeeddiiaatteellyy sseeggffaauullttss
4120
4121 If the host is configured with the 2G/2G address space split, that's
4122 why. See ``UML on 2G/2G hosts'' for the details on getting UML to
4123 run on your host.
4124
4125
4126
4127 1133..1144.. xxtteerrmmss aappppeeaarr,, tthheenn iimmmmeeddiiaatteellyy ddiissaappppeeaarr
4128
4129 If you're running an up to date kernel with an old release of
4130 uml_utilities, the port-helper program will not work properly, so
4131 xterms will exit straight after they appear. The solution is to
4132 upgrade to the latest release of uml_utilities. Usually this problem
4133 occurs when you have installed a packaged release of UML then compiled
4134 your own development kernel without upgrading the uml_utilities from
4135 the source distribution.
4136
4137
4138
4139 1133..1155.. AAnnyy ootthheerr ppaanniicc,, hhaanngg,, oorr ssttrraannggee bbeehhaavviioorr
4140
4141 If you're seeing truly strange behavior, such as hangs or panics that
4142 happen in random places, or you try running the debugger to see what's
4143 happening and it acts strangely, then it could be a problem in the
4144 host kernel. If you're not running a stock Linus or -ac kernel, then
4145 try that. An early version of the preemption patch and a 2.4.10 SuSE
4146 kernel have caused very strange problems in UML.
4147
4148
4149 Otherwise, let me know about it. Send a message to one of the UML
4150 mailing lists - either the developer list - user-mode-linux-devel at
4151 lists dot sourceforge dot net (subscription info) or the user list -
4152 user-mode-linux-user at lists dot sourceforge do net (subscription
4153 info), whichever you prefer. Don't assume that everyone knows about
4154 it and that a fix is imminent.
4155
4156
4157 If you want to be super-helpful, read ``Diagnosing Problems'' and
4158 follow the instructions contained therein.
4159 1144.. DDiiaaggnnoossiinngg PPrroobblleemmss
4160
4161
4162 If you get UML to crash, hang, or otherwise misbehave, you should
4163 report this on one of the project mailing lists, either the developer
4164 list - user-mode-linux-devel at lists dot sourceforge dot net
4165 (subscription info) or the user list - user-mode-linux-user at lists
4166 dot sourceforge dot net (subscription info). When you do, it is
4167 likely that I will want more information. So, it would be helpful to
4168 read the stuff below, do whatever is applicable in your case, and
4169 report the results to the list.
4170
4171
4172 For any diagnosis, you're going to need to build a debugging kernel.
4173 The binaries from this site aren't debuggable. If you haven't done
4174 this before, read about ``Compiling the kernel and modules'' and
4175 ``Kernel debugging'' UML first.
4176
4177
4178 1144..11.. CCaassee 11 :: NNoorrmmaall kkeerrnneell ppaanniiccss
4179
4180 The most common case is for a normal thread to panic. To debug this,
4181 you will need to run it under the debugger (add 'debug' to the command
4182 line). An xterm will start up with gdb running inside it. Continue
4183 it when it stops in start_kernel and make it crash. Now ^C gdb and
4184
4185
4186 If the panic was a "Kernel mode fault", then there will be a segv
4187 frame on the stack and I'm going to want some more information. The
4188 stack might look something like this:
4189
4190
4191 (UML gdb) backtrace
4192 #0 0x1009bf76 in __sigprocmask (how=1, set=0x5f347940, oset=0x0)
4193 at ../sysdeps/unix/sysv/linux/sigprocmask.c:49
4194 #1 0x10091411 in change_sig (signal=10, on=1) at process.c:218
4195 #2 0x10094785 in timer_handler (sig=26) at time_kern.c:32
4196 #3 0x1009bf38 in __restore ()
4197 at ../sysdeps/unix/sysv/linux/i386/sigaction.c:125
4198 #4 0x1009534c in segv (address=8, ip=268849158, is_write=2, is_user=0)
4199 at trap_kern.c:66
4200 #5 0x10095c04 in segv_handler (sig=11) at trap_user.c:285
4201 #6 0x1009bf38 in __restore ()
4202
4203
4204
4205
4206 I'm going to want to see the symbol and line information for the value
4207 of ip in the segv frame. In this case, you would do the following:
4208
4209
4210 (UML gdb) i sym 268849158
4211
4212
4213
4214
4215 and
4216
4217
4218 (UML gdb) i line *268849158
4219
4220
4221
4222
4223 The reason for this is the __restore frame right above the segv_han-
4224 dler frame is hiding the frame that actually segfaulted. So, I have
4225 to get that information from the faulting ip.
4226
4227
4228 1144..22.. CCaassee 22 :: TTrraacciinngg tthhrreeaadd ppaanniiccss
4229
4230 The less common and more painful case is when the tracing thread
4231 panics. In this case, the kernel debugger will be useless because it
4232 needs a healthy tracing thread in order to work. The first thing to
4233 do is get a backtrace from the tracing thread. This is done by
4234 figuring out what its pid is, firing up gdb, and attaching it to that
4235 pid. You can figure out the tracing thread pid by looking at the
4236 first line of the console output, which will look like this:
4237
4238
4239 tracing thread pid = 15851
4240
4241
4242
4243
4244 or by running ps on the host and finding the line that looks like
4245 this:
4246
4247
4248 jdike 15851 4.5 0.4 132568 1104 pts/0 S 21:34 0:05 ./linux [(tracing thread)]
4249
4250
4251
4252
4253 If the panic was 'segfault in signals', then follow the instructions
4254 above for collecting information about the location of the seg fault.
4255
4256
4257 If the tracing thread flaked out all by itself, then send that
4258 backtrace in and wait for our crack debugging team to fix the problem.
4259
4260
4261 1144..33.. CCaassee 33 :: TTrraacciinngg tthhrreeaadd ppaanniiccss ccaauusseedd bbyy ootthheerr tthhrreeaaddss
4262
4263 However, there are cases where the misbehavior of another thread
4264 caused the problem. The most common panic of this type is:
4265
4266
4267 wait_for_stop failed to wait for <pid> to stop with <signal number>
4268
4269
4270
4271
4272 In this case, you'll need to get a backtrace from the process men-
4273 tioned in the panic, which is complicated by the fact that the kernel
4274 debugger is defunct and without some fancy footwork, another gdb can't
4275 attach to it. So, this is how the fancy footwork goes:
4276
4277 In a shell:
4278
4279
4280 host% kill -STOP pid
4281
4282
4283
4284
4285 Run gdb on the tracing thread as described in case 2 and do:
4286
4287
4288 (host gdb) call detach(pid)
4289
4290
4291 If you get a segfault, do it again. It always works the second time.
4292
4293 Detach from the tracing thread and attach to that other thread:
4294
4295
4296 (host gdb) detach
4297
4298
4299
4300
4301
4302
4303 (host gdb) attach pid
4304
4305
4306
4307
4308 If gdb hangs when attaching to that process, go back to a shell and
4309 do:
4310
4311
4312 host%
4313 kill -CONT pid
4314
4315
4316
4317
4318 And then get the backtrace:
4319
4320
4321 (host gdb) backtrace
4322
4323
4324
4325
4326
4327 1144..44.. CCaassee 44 :: HHaannggss
4328
4329 Hangs seem to be fairly rare, but they sometimes happen. When a hang
4330 happens, we need a backtrace from the offending process. Run the
4331 kernel debugger as described in case 1 and get a backtrace. If the
4332 current process is not the idle thread, then send in the backtrace.
4333 You can tell that it's the idle thread if the stack looks like this:
4334
4335
4336 #0 0x100b1401 in __libc_nanosleep ()
4337 #1 0x100a2885 in idle_sleep (secs=10) at time.c:122
4338 #2 0x100a546f in do_idle () at process_kern.c:445
4339 #3 0x100a5508 in cpu_idle () at process_kern.c:471
4340 #4 0x100ec18f in start_kernel () at init/main.c:592
4341 #5 0x100a3e10 in start_kernel_proc (unused=0x0) at um_arch.c:71
4342 #6 0x100a383f in signal_tramp (arg=0x100a3dd8) at trap_user.c:50
4343
4344
4345
4346
4347 If this is the case, then some other process is at fault, and went to
4348 sleep when it shouldn't have. Run ps on the host and figure out which
4349 process should not have gone to sleep and stayed asleep. Then attach
4350 to it with gdb and get a backtrace as described in case 3.
4351
4352
4353
4354
4355
4356
4357 1155.. TThhaannkkss
4358
4359
4360 A number of people have helped this project in various ways, and this
4361 page gives recognition where recognition is due.
4362
4363
4364 If you're listed here and you would prefer a real link on your name,
4365 or no link at all, instead of the despammed email address pseudo-link,
4366 let me know.
4367
4368
4369 If you're not listed here and you think maybe you should be, please
4370 let me know that as well. I try to get everyone, but sometimes my
4371 bookkeeping lapses and I forget about contributions.
4372
4373
4374 1155..11.. CCooddee aanndd DDooccuummeennttaattiioonn
4375
4376 Rusty Russell <rusty at linuxcare.com.au> -
4377
4378 +o wrote the HOWTO <http://user-mode-
4379 linux.sourceforge.net/UserModeLinux-HOWTO.html>
4380
4381 +o prodded me into making this project official and putting it on
4382 SourceForge
4383
4384 +o came up with the way cool UML logo <http://user-mode-
4385 linux.sourceforge.net/uml-small.png>
4386
4387 +o redid the config process
4388
4389
4390 Peter Moulder <reiter at netspace.net.au> - Fixed my config and build
4391 processes, and added some useful code to the block driver
4392
4393
4394 Bill Stearns <wstearns at pobox.com> -
4395
4396 +o HOWTO updates
4397
4398 +o lots of bug reports
4399
4400 +o lots of testing
4401
4402 +o dedicated a box (uml.ists.dartmouth.edu) to support UML development
4403
4404 +o wrote the mkrootfs script, which allows bootable filesystems of
4405 RPM-based distributions to be cranked out
4406
4407 +o cranked out a large number of filesystems with said script
4408
4409
4410 Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
4411 and associated usermode tools
4412
4413 Lars Brinkhoff <http://lars.nocrew.org/> - Contributed the ptrace
4414 proxy from his own project <http://a386.nocrew.org/> to allow easier
4415 kernel debugging
4416
4417
4418 Andrea Arcangeli <andrea at suse.de> - Redid some of the early boot
4419 code so that it would work on machines with Large File Support
4420
4421
4422 Chris Emerson <http://www.chiark.greenend.org.uk/~cemerson/> - Did
4423 the first UML port to Linux/ppc
4424
4425
4426 Harald Welte <laforge at gnumonks.org> - Wrote the multicast
4427 transport for the network driver
4428
4429
4430 Jorgen Cederlof - Added special file support to hostfs
4431
4432
4433 Greg Lonnon <glonnon at ridgerun dot com> - Changed the ubd driver
4434 to allow it to layer a COW file on a shared read-only filesystem and
4435 wrote the iomem emulation support
4436
4437
4438 Henrik Nordstrom <http://hem.passagen.se/hno/> - Provided a variety
4439 of patches, fixes, and clues
4440
4441
4442 Lennert Buytenhek - Contributed various patches, a rewrite of the
4443 network driver, the first implementation of the mconsole driver, and
4444 did the bulk of the work needed to get SMP working again.
4445
4446
4447 Yon Uriarte - Fixed the TUN/TAP network backend while I slept.
4448
4449
4450 Adam Heath - Made a bunch of nice cleanups to the initialization code,
4451 plus various other small patches.
4452
4453
4454 Matt Zimmerman - Matt volunteered to be the UML Debian maintainer and
4455 is doing a real nice job of it. He also noticed and fixed a number of
4456 actually and potentially exploitable security holes in uml_net. Plus
4457 the occasional patch. I like patches.
4458
4459
4460 James McMechan - James seems to have taken over maintenance of the ubd
4461 driver and is doing a nice job of it.
4462
4463
4464 Chandan Kudige - wrote the umlgdb script which automates the reloading
4465 of module symbols.
4466
4467
4468 Steve Schmidtke - wrote the UML slirp transport and hostaudio drivers,
4469 enabling UML processes to access audio devices on the host. He also
4470 submitted patches for the slip transport and lots of other things.
4471
4472
4473 David Coulson <http://davidcoulson.net> -
4474
4475 +o Set up the usermodelinux.org <http://usermodelinux.org> site,
4476 which is a great way of keeping the UML user community on top of
4477 UML goings-on.
4478
4479 +o Site documentation and updates
4480
4481 +o Nifty little UML management daemon UMLd
4482 <http://uml.openconsultancy.com/umld/>
4483
4484 +o Lots of testing and bug reports
4485
4486
4487
4488
4489 1155..22.. FFlluusshhiinngg oouutt bbuuggss
4490
4491
4492
4493 +o Yuri Pudgorodsky
4494
4495 +o Gerald Britton
4496
4497 +o Ian Wehrman
4498
4499 +o Gord Lamb
4500
4501 +o Eugene Koontz
4502
4503 +o John H. Hartman
4504
4505 +o Anders Karlsson
4506
4507 +o Daniel Phillips
4508
4509 +o John Fremlin
4510
4511 +o Rainer Burgstaller
4512
4513 +o James Stevenson
4514
4515 +o Matt Clay
4516
4517 +o Cliff Jefferies
4518
4519 +o Geoff Hoff
4520
4521 +o Lennert Buytenhek
4522
4523 +o Al Viro
4524
4525 +o Frank Klingenhoefer
4526
4527 +o Livio Baldini Soares
4528
4529 +o Jon Burgess
4530
4531 +o Petru Paler
4532
4533 +o Paul
4534
4535 +o Chris Reahard
4536
4537 +o Sverker Nilsson
4538
4539 +o Gong Su
4540
4541 +o johan verrept
4542
4543 +o Bjorn Eriksson
4544
4545 +o Lorenzo Allegrucci
4546
4547 +o Muli Ben-Yehuda
4548
4549 +o David Mansfield
4550
4551 +o Howard Goff
4552
4553 +o Mike Anderson
4554
4555 +o John Byrne
4556
4557 +o Sapan J. Batia
4558
4559 +o Iris Huang
4560
4561 +o Jan Hudec
4562
4563 +o Voluspa
4564
4565
4566
4567
4568 1155..33.. BBuugglleettss aanndd cclleeaann--uuppss
4569
4570
4571
4572 +o Dave Zarzycki
4573
4574 +o Adam Lazur
4575
4576 +o Boria Feigin
4577
4578 +o Brian J. Murrell
4579
4580 +o JS
4581
4582 +o Roman Zippel
4583
4584 +o Wil Cooley
4585
4586 +o Ayelet Shemesh
4587
4588 +o Will Dyson
4589
4590 +o Sverker Nilsson
4591
4592 +o dvorak
4593
4594 +o v.naga srinivas
4595
4596 +o Shlomi Fish
4597
4598 +o Roger Binns
4599
4600 +o johan verrept
4601
4602 +o MrChuoi
4603
4604 +o Peter Cleve
4605
4606 +o Vincent Guffens
4607
4608 +o Nathan Scott
4609
4610 +o Patrick Caulfield
4611
4612 +o jbearce
4613
4614 +o Catalin Marinas
4615
4616 +o Shane Spencer
4617
4618 +o Zou Min
4619
4620
4621 +o Ryan Boder
4622
4623 +o Lorenzo Colitti
4624
4625 +o Gwendal Grignou
4626
4627 +o Andre' Breiler
4628
4629 +o Tsutomu Yasuda
4630
4631
4632
4633 1155..44.. CCaassee SSttuuddiieess
4634
4635
4636 +o Jon Wright
4637
4638 +o William McEwan
4639
4640 +o Michael Richardson
4641
4642
4643
4644 1155..55.. OOtthheerr ccoonnttrriibbuuttiioonnss
4645
4646
4647 Bill Carr <Bill.Carr at compaq.com> made the Red Hat mkrootfs script
4648 work with RH 6.2.
4649
4650 Michael Jennings <mikejen at hevanet.com> sent in some material which
4651 is now gracing the top of the index page <http://user-mode-
4652 linux.sourceforge.net/index.html> of this site.
4653
4654 SGI <http://www.sgi.com> (and more specifically Ralf Baechle <ralf at
4655 uni-koblenz.de> ) gave me an account on oss.sgi.com
4656 <http://www.oss.sgi.com> . The bandwidth there made it possible to
4657 produce most of the filesystems available on the project download
4658 page.
4659
4660 Laurent Bonnaud <Laurent.Bonnaud at inpg.fr> took the old grotty
4661 Debian filesystem that I've been distributing and updated it to 2.2.
4662 It is now available by itself here.
4663
4664 Rik van Riel gave me some ftp space on ftp.nl.linux.org so I can make
4665 releases even when Sourceforge is broken.
4666
4667 Rodrigo de Castro looked at my broken pte code and told me what was
4668 wrong with it, letting me fix a long-standing (several weeks) and
4669 serious set of bugs.
4670
4671 Chris Reahard built a specialized root filesystem for running a DNS
4672 server jailed inside UML. It's available from the download
4673 <http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
4674 Filesysems section.
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686