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