About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / uml / UserModeLinux-HOWTO.txt


Based on kernel version 2.6.39.1. Page generated on 2011-06-03 13:47 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog