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