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