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