1 .. SPDX-License-Identifier: GPL-2.0
7 :Author: User Mode Linux Core Team
8 :Last-updated: Mon Nov 18 14:16:16 EST 2002
10 This document describes the use and abuse of Jeff Dike's User Mode
11 Linux: a port of the Linux kernel as a normal Intel Linux process.
18 1.1 How is User Mode Linux Different?
19 1.2 Why Would I Want User Mode Linux?
21 2. Compiling the kernel and modules
23 2.1 Compiling the kernel
24 2.2 Compiling and installing kernel modules
25 2.3 Compiling and installing uml_utilities
27 3. Running UML and logging in
39 5. Setting up serial lines and consoles
41 5.1 Specifying the device
42 5.2 Specifying the channel
45 6. Setting up the network
49 6.3 Specifying ethernet addresses
50 6.4 UML interface setup
52 6.6 TUN/TAP with the uml_net helper
53 6.7 TUN/TAP with a preconfigured tap device
59 6.13 Setting up the host yourself
61 7. Sharing Filesystems between Virtual Machines
64 7.2 Using layered block devices
67 7.5 uml_moo : Merging a COW file with its backing file
69 8. Creating filesystems
71 8.1 Create the filesystem file
72 8.2 Assign the file to a UML device
73 8.3 Creating and mounting the filesystem
78 9.2 hostfs as the root filesystem
81 10. The Management Console
94 11.1 Starting the kernel under gdb
95 11.2 Examining sleeping processes
96 11.3 Running ddd on UML
97 11.4 Debugging modules
98 11.5 Attaching gdb to the kernel
99 11.6 Using alternate debuggers
101 12. Kernel debugging examples
103 12.1 The case of the hung fsck
104 12.2 Episode 2: The case of the hung fsck
106 13. What to do when UML doesn't work
108 13.1 Strange compilation errors when you build from source
110 13.3 A variety of panics and hangs with /tmp on a reiserfs filesystem
111 13.4 The compile fails with errors about conflicting types for 'open', 'dup', and 'waitpid'
112 13.5 UML doesn't work when /tmp is an NFS filesystem
113 13.6 UML hangs on boot when compiled with gprof support
114 13.7 syslogd dies with a SIGTERM on startup
115 13.8 TUN/TAP networking doesn't work on a 2.4 host
116 13.9 You can network to the host but not to other machines on the net
117 13.10 I have no root and I want to scream
118 13.11 UML build conflict between ptrace.h and ucontext.h
119 13.12 The UML BogoMips is exactly half the host's BogoMips
120 13.13 When you run UML, it immediately segfaults
121 13.14 xterms appear, then immediately disappear
122 13.15 Any other panic, hang, or strange behavior
124 14. Diagnosing Problems
126 14.1 Case 1 : Normal kernel panics
127 14.2 Case 2 : Tracing thread panics
128 14.3 Case 3 : Tracing thread panics caused by other threads
133 15.1 Code and Documentation
134 15.2 Flushing out bugs
135 15.3 Buglets and clean-ups
137 15.5 Other contributions
143 Welcome to User Mode Linux. It's going to be fun.
147 1.1. How is User Mode Linux Different?
148 ---------------------------------------
150 Normally, the Linux Kernel talks straight to your hardware (video
151 card, keyboard, hard drives, etc), and any programs which run ask the
152 kernel to operate the hardware, like so::
156 +-----------+-----------+----+
157 | Process 1 | Process 2 | ...|
158 +-----------+-----------+----+
160 +----------------------------+
162 +----------------------------+
167 The User Mode Linux Kernel is different; instead of talking to the
168 hardware, it talks to a `real` Linux kernel (called the `host kernel`
169 from now on), like any other program. Programs can then run inside
170 User-Mode Linux as if they were running under a normal kernel, like
177 +-----------+----------------+
178 | Process 1 | User-Mode Linux|
179 +----------------------------+
181 +----------------------------+
183 +----------------------------+
189 1.2. Why Would I Want User Mode Linux?
190 ---------------------------------------
193 1. If User Mode Linux crashes, your host kernel is still fine.
195 2. You can run a usermode kernel as a non-root user.
197 3. You can debug the User Mode Linux like any normal process.
199 4. You can run gprof (profiling) and gcov (coverage testing).
201 5. You can play with your kernel without breaking things.
203 6. You can use it as a sandbox for testing new apps.
205 7. You can try new development kernels safely.
207 8. You can run different distributions simultaneously.
209 9. It's extremely fun.
213 .. _Compiling_the_kernel_and_modules:
215 2. Compiling the kernel and modules
216 ====================================
221 2.1. Compiling the kernel
222 --------------------------
225 Compiling the user mode kernel is just like compiling any other
226 kernel. Let's go through the steps, using 2.4.0-prerelease (current
227 as of this writing) as an example:
230 1. Download the latest UML patch from
231 the download page <http://user-mode-linux.sourceforge.net/
233 In this example, the file is uml-patch-2.4.0-prerelease.bz2.
236 2. Download the matching kernel from your favourite kernel mirror,
239 ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
242 3. Make a directory and unpack the kernel into it::
251 tar -xzvf linux-2.4.0-prerelease.tar.bz2
255 4. Apply the patch using::
261 bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
265 5. Run your favorite config; ``make xconfig ARCH=um`` is the most
266 convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um``
267 will work as well. The defaults will give you a useful kernel. If
268 you want to change something, go ahead, it probably won't hurt
272 Note: If the host is configured with a 2G/2G address space split
273 rather than the usual 3G/1G split, then the packaged UML binaries
274 will not run. They will immediately segfault. See
275 :ref:`UML_on_2G/2G_hosts` for the scoop on running UML on your system.
279 6. Finish with ``make linux ARCH=um``: the result is a file called
280 ``linux`` in the top directory of your source tree.
282 Make sure that you don't build this kernel in /usr/src/linux. On some
283 distributions, /usr/include/asm is a link into this pool. The user-
284 mode build changes the other end of that link, and things that include
285 <asm/anything.h> stop compiling.
287 The sources are also available from cvs at the project's cvs page,
288 which has directions on getting the sources. You can also browse the
291 If you get the CVS sources, you will have to check them out into an
292 empty directory. You will then have to copy each file into the
293 corresponding directory in the appropriate kernel pool.
295 If you don't have the latest kernel pool, you can get the
296 corresponding user-mode sources with::
299 host% cvs co -r v_2_3_x linux
304 where 'x' is the version in your pool. Note that you will not get the
305 bug fixes and enhancements that have gone into subsequent releases.
308 2.2. Compiling and installing kernel modules
309 ---------------------------------------------
311 UML modules are built in the same way as the native kernel (with the
312 exception of the 'ARCH=um' that you always need for UML)::
315 host% make modules ARCH=um
320 Any modules that you want to load into this kernel need to be built in
321 the user-mode pool. Modules from the native kernel won't work.
323 You can install them by using ftp or something to copy them into the
324 virtual machine and dropping them into ``/lib/modules/$(uname -r)``.
326 You can also get the kernel build process to install them as follows:
328 1. with the kernel not booted, mount the root filesystem in the top
329 level of the kernel pool::
332 host% mount root_fs mnt -o loop
343 make modules_install INSTALL_MOD_PATH=`pwd`/mnt ARCH=um
350 3. unmount the filesystem::
360 4. boot the kernel on it
363 When the system is booted, you can use insmod as usual to get the
364 modules into the kernel. A number of things have been loaded into UML
365 as modules, especially filesystems and network protocols and filters,
366 so most symbols which need to be exported probably already are.
367 However, if you do find symbols that need exporting, let us
368 <http://user-mode-linux.sourceforge.net/> know, and
369 they'll be "taken care of".
373 2.3. Compiling and installing uml_utilities
374 --------------------------------------------
376 Many features of the UML kernel require a user-space helper program,
377 so a uml_utilities package is distributed separately from the kernel
378 patch which provides these helpers. Included within this is:
380 - port-helper - Used by consoles which connect to xterms or ports
382 - tunctl - Configuration tool to create and delete tap devices
384 - uml_net - Setuid binary for automatic tap device configuration
386 - uml_switch - User-space virtual switch required for daemon
389 The uml_utilities tree is compiled with::
398 Note that UML kernel patches may require a specific version of the
399 uml_utilities distribution. If you don't keep up with the mailing
400 lists, ensure that you have the latest release of uml_utilities if you
401 are experiencing problems with your UML kernel, particularly when
402 dealing with consoles or command-line switches to the helper programs
411 3. Running UML and logging in
412 ==============================
419 It runs on 2.2.15 or later, and all 2.4 kernels.
422 Booting UML is straightforward. Simply run 'linux': it will try to
423 mount the file ``root_fs`` in the current directory. You do not need to
424 run it as root. If your root filesystem is not named ``root_fs``, then
425 you need to put a ``ubd0=root_fs_whatever`` switch on the linux command
429 You will need a filesystem to boot UML from. There are a number
430 available for download from here <http://user-mode-
431 linux.sourceforge.net/> . There are also several tools
432 <http://user-mode-linux.sourceforge.net/> which can be
433 used to generate UML-compatible filesystem images from media.
434 The kernel will boot up and present you with a login prompt.
438 If the host is configured with a 2G/2G address space split
439 rather than the usual 3G/1G split, then the packaged UML binaries will
440 not run. They will immediately segfault. See :ref:`UML_on_2G/2G_hosts`
441 for the scoop on running UML on your system.
450 The prepackaged filesystems have a root account with password 'root'
451 and a user account with password 'user'. The login banner will
452 generally tell you how to log in. So, you log in and you will find
453 yourself inside a little virtual machine. Our filesystems have a
454 variety of commands and utilities installed (and it is fairly easy to
455 add more), so you will have a lot of tools with which to poke around
458 There are a couple of other ways to log in:
460 - On a virtual console
464 Each virtual console that is configured (i.e. the device exists in
465 /dev and /etc/inittab runs a getty on it) will come up in its own
466 xterm. If you get tired of the xterms, read
467 :ref:`setting_up_serial_lines_and_consoles` to see how to attach
468 the consoles to something else, like host ptys.
472 - Over the serial line
475 In the boot output, find a line that looks like::
479 serial line 0 assigned pty /dev/ptyp1
484 Attach your favorite terminal program to the corresponding tty. I.e.
485 for minicom, the command would be::
488 host% minicom -o -p /dev/ttyp1
498 If the network is running, then you can telnet to the virtual
499 machine and log in to it. See :ref:`Setting_up_the_network` to learn
500 about setting up a virtual network.
502 When you're done using it, run halt, and the kernel will bring itself
503 down and the process will exit.
509 Here are some examples of UML in action:
511 - A login session <http://user-mode-linux.sourceforge.net/login.html>
513 - A virtual network <http://user-mode-linux.sourceforge.net/net.html>
520 .. _UML_on_2G/2G_hosts:
522 4. UML on 2G/2G hosts
523 ======================
532 Most Linux machines are configured so that the kernel occupies the
533 upper 1G (0xc0000000 - 0xffffffff) of the 4G address space and
534 processes use the lower 3G (0x00000000 - 0xbfffffff). However, some
535 machine are configured with a 2G/2G split, with the kernel occupying
536 the upper 2G (0x80000000 - 0xffffffff) and processes using the lower
537 2G (0x00000000 - 0x7fffffff).
546 The prebuilt UML binaries on this site will not run on 2G/2G hosts
547 because UML occupies the upper .5G of the 3G process address space
548 (0xa0000000 - 0xbfffffff). Obviously, on 2G/2G hosts, this is right
549 in the middle of the kernel address space, so UML won't even load - it
550 will immediately segfault.
559 The fix for this is to rebuild UML from source after enabling
560 CONFIG_HOST_2G_2G (under 'General Setup'). This will cause UML to
561 load itself in the top .5G of that smaller process address space,
562 where it will run fine. See :ref:`Compiling_the_kernel_and_modules` if
563 you need help building UML from source.
571 .. _setting_up_serial_lines_and_consoles:
574 5. Setting up serial lines and consoles
575 ========================================
578 It is possible to attach UML serial lines and consoles to many types
579 of host I/O channels by specifying them on the command line.
582 You can attach them to host ptys, ttys, file descriptors, and ports.
583 This allows you to do things like:
585 - have a UML console appear on an unused host console,
587 - hook two virtual machines together by having one attach to a pty
588 and having the other attach to the corresponding tty
590 - make a virtual machine accessible from the net by attaching a
591 console to a port on the host.
594 The general format of the command line option is ``device=channel``.
598 5.1. Specifying the device
599 ---------------------------
601 Devices are specified with "con" or "ssl" (console or serial line,
602 respectively), optionally with a device number if you are talking
603 about a specific device.
606 Using just "con" or "ssl" describes all of the consoles or serial
607 lines. If you want to talk about console #3 or serial line #10, they
608 would be "con3" and "ssl10", respectively.
611 A specific device name will override a less general "con=" or "ssl=".
612 So, for example, you can assign a pty to each of the serial lines
613 except for the first two like this::
616 ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1
621 The specificity of the device name is all that matters; order on the
622 command line is irrelevant.
626 5.2. Specifying the channel
627 ----------------------------
629 There are a number of different types of channels to attach a UML
630 device to, each with a different way of specifying exactly what to
633 - pseudo-terminals - device=pty pts terminals - device=pts
636 This will cause UML to allocate a free host pseudo-terminal for the
637 device. The terminal that it got will be announced in the boot
638 log. You access it by attaching a terminal program to the
645 - minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
648 - kermit - start it up, 'open' the device, then 'connect'
654 - terminals - device=tty:tty device file
657 This will make UML attach the device to the specified tty (i.e::
665 will attach UML's console 1 to the host's /dev/tty3). If the tty that
666 you specify is the slave end of a tty/pty pair, something else must
667 have already opened the corresponding pty in order for this to work.
673 - xterms - device=xterm
676 UML will run an xterm and the device will be attached to it.
682 - Port - device=port:port number
685 This will attach the UML devices to the specified host port.
686 Attaching console 1 to the host's port 9000 would be done like
695 Attaching all the serial lines to that port would be done similarly::
703 You access these devices by telnetting to that port. Each active
704 telnet session gets a different device. If there are more telnets to a
705 port than UML devices attached to it, then the extra telnet sessions
706 will block until an existing telnet detaches, or until another device
707 becomes active (i.e. by being activated in /etc/inittab).
709 This channel has the advantage that you can both attach multiple UML
710 devices to it and know how to access them without reading the UML boot
711 log. It is also unique in allowing access to a UML from remote
712 machines without requiring that the UML be networked. This could be
713 useful in allowing public access to UMLs because they would be
714 accessible from the net, but wouldn't need any kind of network
715 filtering or access control because they would have no network access.
718 If you attach the main console to a portal, then the UML boot will
719 appear to hang. In reality, it's waiting for a telnet to connect, at
720 which point the boot will proceed.
726 - already-existing file descriptors - device=file descriptor
729 If you set up a file descriptor on the UML command line, you can
730 attach a UML device to it. This is most commonly used to put the
731 main console back on stdin and stdout after assigning all the other
732 consoles to something else::
735 con0=fd:0,fd:1 con=pts
744 - Nothing - device=null
747 This allows the device to be opened, in contrast to 'none', but
748 reads will block, and writes will succeed and the data will be
758 This causes the device to disappear.
762 You can also specify different input and output channels for a device
763 by putting a comma between them::
766 ssl3=tty:/dev/tty2,xterm
771 will cause serial line 3 to accept input on the host's /dev/tty2 and
772 display output on an xterm. That's a silly example - the most common
773 use of this syntax is to reattach the main console to stdin and stdout
777 If you decide to move the main console away from stdin/stdout, the
778 initial boot output will appear in the terminal that you're running
779 UML in. However, once the console driver has been officially
780 initialized, then the boot output will start appearing wherever you
781 specified that console 0 should be. That device will receive all
789 There are a number of interesting things you can do with this
793 First, this is how you get rid of those bleeding console xterms by
794 attaching them to host ptys::
797 con=pty con0=fd:0,fd:1
802 This will make a UML console take over an unused host virtual console,
803 so that when you switch to it, you will see the UML login prompt
804 rather than the host login prompt::
812 You can attach two virtual machines together with what amounts to a
813 serial line as follows:
815 Run one UML with a serial line attached to a pty::
823 Look at the boot log to see what pty it got (this example will assume
824 that it got /dev/ptyp1).
826 Boot the other UML with a serial line attached to the corresponding
835 Log in, make sure that it has no getty on that serial line, attach a
836 terminal program like minicom to it, and you should see the login
837 prompt of the other virtual machine.
840 .. _setting_up_the_network:
842 6. Setting up the network
843 ==========================
847 This page describes how to set up the various transports and to
848 provide a UML instance with network access to the host, other machines
849 on the local net, and the rest of the net.
852 As of 2.4.5, UML networking has been completely redone to make it much
853 easier to set up, fix bugs, and add new features.
856 There is a new helper, uml_net, which does the host setup that
857 requires root privileges.
860 There are currently five transport types available for a UML virtual
861 machine to exchange packets with other hosts:
877 The TUN/TAP, ethertap, slip, and slirp transports allow a UML
878 instance to exchange packets with the host. They may be directed
879 to the host or the host may just act as a router to provide access
880 to other physical or virtual machines.
883 The pcap transport is a synthetic read-only interface, using the
884 libpcap binary to collect packets from interfaces on the host and
885 filter them. This is useful for building preconfigured traffic
886 monitors or sniffers.
889 The daemon and multicast transports provide a completely virtual
890 network to other virtual machines. This network is completely
891 disconnected from the physical network unless one of the virtual
892 machines on it is acting as a gateway.
895 With so many host transports, which one should you use? Here's when
896 you should use each one:
898 - ethertap - if you want access to the host networking and it is
901 - TUN/TAP - if you want access to the host networking and it is
902 running 2.4. Also, the TUN/TAP transport is able to use a
903 preconfigured device, allowing it to avoid using the setuid uml_net
904 helper, which is a security advantage.
906 - Multicast - if you want a purely virtual network and you don't want
907 to set up anything but the UML
909 - a switch daemon - if you want a purely virtual network and you
910 don't mind running the daemon in order to get somewhat better
913 - slip - there is no particular reason to run the slip backend unless
914 ethertap and TUN/TAP are just not available for some reason
916 - slirp - if you don't have root access on the host to setup
917 networking, or if you don't want to allocate an IP to your UML
919 - pcap - not much use for actual network connectivity, but great for
920 monitoring traffic on the host
922 Ethertap is available on 2.4 and works fine. TUN/TAP is preferred
923 to it because it has better performance and ethertap is officially
924 considered obsolete in 2.4. Also, the root helper only needs to
925 run occasionally for TUN/TAP, rather than handling every packet, as
926 it does with ethertap. This is a slight security advantage since
927 it provides fewer opportunities for a nasty UML user to somehow
928 exploit the helper's root privileges.
934 First, you must have the virtual network enabled in your UML. If are
935 running a prebuilt kernel from this site, everything is already
936 enabled. If you build the kernel yourself, under the "Network device
937 support" menu, enable "Network device support", and then the three
941 The next step is to provide a network device to the virtual machine.
942 This is done by describing it on the kernel command line.
944 The general format is::
947 eth <n> = <transport> , <transport args>
952 For example, a virtual ethernet device may be attached to a host
953 ethertap device as follows::
956 eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
961 This sets up eth0 inside the virtual machine to attach itself to the
962 host /dev/tap0, assigns it an ethernet address, and assigns the host
963 tap0 interface an IP address.
967 Note that the IP address you assign to the host end of the tap device
968 must be different than the IP you assign to the eth device inside UML.
969 If you are short on IPs and don't want to consume two per UML, then
970 you can reuse the host's eth IP address for the host ends of the tap
971 devices. Internally, the UMLs must still get unique IPs for their eth
972 devices. You can also give the UMLs non-routable IPs (192.168.x.x or
973 10.x.x.x) and have the host masquerade them. This will let outgoing
974 connections work, but incoming connections won't without more work,
975 such as port forwarding from the host.
976 Also note that when you configure the host side of an interface, it is
977 only acting as a gateway. It will respond to pings sent to it
978 locally, but is not useful to do that since it's a host interface.
979 You are not talking to the UML when you ping that interface and get a
983 You can also add devices to a UML and remove them at runtime. See the
984 :ref:`The_Management_Console` page for details.
987 The sections below describe this in more detail.
990 Once you've decided how you're going to set up the devices, you boot
991 UML, log in, configure the UML side of the devices, and set up routes
992 to the outside world. At that point, you will be able to talk to any
993 other machines, physical or virtual, on the net.
996 If ifconfig inside UML fails and the network refuses to come up, run
997 tell you what went wrong.
1001 6.2. Userspace daemons
1002 -----------------------
1004 You will likely need the setuid helper, or the switch daemon, or both.
1005 They are both installed with the RPM and deb, so if you've installed
1006 either, you can skip the rest of this section.
1009 If not, then you need to check them out of CVS, build them, and
1010 install them. The helper is uml_net, in CVS /tools/uml_net, and the
1011 daemon is uml_switch, in CVS /tools/uml_router. They are both built
1012 with a plain 'make'. Both need to be installed in a directory that's
1013 in your path - /usr/bin is recommend. On top of that, uml_net needs
1018 6.3. Specifying ethernet addresses
1019 -----------------------------------
1021 Below, you will see that the TUN/TAP, ethertap, and daemon interfaces
1022 allow you to specify hardware addresses for the virtual ethernet
1023 devices. This is generally not necessary. If you don't have a
1024 specific reason to do it, you probably shouldn't. If one is not
1025 specified on the command line, the driver will assign one based on the
1026 device IP address. It will provide the address fe:fd:nn:nn:nn:nn
1027 where nn.nn.nn.nn is the device IP address. This is nearly always
1028 sufficient to guarantee a unique hardware address for the device. A
1029 couple of exceptions are:
1031 - Another set of virtual ethernet devices are on the same network and
1032 they are assigned hardware addresses using a different scheme which
1033 may conflict with the UML IP address-based scheme
1035 - You aren't going to use the device for IP networking, so you don't
1036 assign the device an IP address
1038 If you let the driver provide the hardware address, you should make
1039 sure that the device IP address is known before the interface is
1040 brought up. So, inside UML, this will guarantee that::
1045 ifconfig eth0 192.168.0.250 up
1050 If you decide to assign the hardware address yourself, make sure that
1051 the first byte of the address is even. Addresses with an odd first
1052 byte are broadcast addresses, which you don't want assigned to a
1057 6.4. UML interface setup
1058 -------------------------
1060 Once the network devices have been described on the command line, you
1061 should boot UML and log in.
1064 The first thing to do is bring the interface up::
1067 UML# ifconfig ethn ip-address up
1072 You should be able to ping the host at this point.
1075 To reach the rest of the world, you should set a default route to the
1079 UML# route add default gw host ip
1084 Again, with host ip of 192.168.0.4::
1087 UML# route add default gw 192.168.0.4
1092 This page used to recommend setting a network route to your local net.
1093 This is wrong, because it will cause UML to try to figure out hardware
1094 addresses of the local machines by arping on the interface to the
1095 host. Since that interface is basically a single strand of ethernet
1096 with two nodes on it (UML and the host) and arp requests don't cross
1097 networks, they will fail to elicit any responses. So, what you want
1098 is for UML to just blindly throw all packets at the host and let it
1099 figure out what to do with them, which is what leaving out the network
1100 route and adding the default route does.
1103 Note: If you can't communicate with other hosts on your physical
1104 ethernet, it's probably because of a network route that's
1105 automatically set up. If you run 'route -n' and see a route that
1111 Destination Gateway Genmask Flags Metric Ref Use Iface
1112 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
1117 with a mask that's not 255.255.255.255, then replace it with a route
1122 route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0
1126 route add -host 192.168.0.4 dev eth0
1131 This, plus the default route to the host, will allow UML to exchange
1132 packets with any machine on your ethernet.
1139 The simplest way to set up a virtual network between multiple UMLs is
1140 to use the mcast transport. This was written by Harald Welte and is
1141 present in UML version 2.4.5-5um and later. Your system must have
1142 multicast enabled in the kernel and there must be a multicast-capable
1143 network device on the host. Normally, this is eth0, but if there is
1144 no ethernet card on the host, then you will likely get strange error
1145 messages when you bring the device up inside UML.
1148 To use it, run two UMLs with::
1156 on their command lines. Log in, configure the ethernet device in each
1157 machine with different IP addresses::
1160 UML1# ifconfig eth0 192.168.0.254
1163 UML2# ifconfig eth0 192.168.0.253
1168 and they should be able to talk to each other.
1170 The full set of command line options for this transport are::
1174 ethn=mcast,ethernet address,multicast
1175 address,multicast port,ttl
1180 Harald's original README is here <http://user-mode-linux.source-
1181 forge.net/> and explains these in detail, as well as
1184 There is also a related point-to-point only "ucast" transport.
1185 This is useful when your network does not support multicast, and
1186 all network connections are simple point to point links.
1188 The full set of command line options for this transport are::
1191 ethn=ucast,ethernet address,remote address,listen port,remote port
1196 6.6. TUN/TAP with the uml_net helper
1197 -------------------------------------
1199 TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the
1200 host. The TUN/TAP backend has been in UML since 2.4.9-3um.
1203 The easiest way to get up and running is to let the setuid uml_net
1204 helper do the host setup for you. This involves insmod-ing the tun.o
1205 module if necessary, configuring the device, and setting up IP
1206 forwarding, routing, and proxy arp. If you are new to UML networking,
1207 do this first. If you're concerned about the security implications of
1208 the setuid helper, use it to get up and running, then read the next
1209 section to see how to have UML use a preconfigured tap device, which
1210 avoids the use of uml_net.
1213 If you specify an IP address for the host side of the device, the
1214 uml_net helper will do all necessary setup on the host - the only
1215 requirement is that TUN/TAP be available, either built in to the host
1216 kernel or as the tun.o module.
1218 The format of the command line switch to attach a device to a TUN/TAP
1222 eth <n> =tuntap,,, <IP address>
1227 For example, this argument will attach the UML's eth0 to the next
1228 available tap device and assign an ethernet address to it based on its
1232 eth0=tuntap,,,192.168.0.254
1239 Note that the IP address that must be used for the eth device inside
1240 UML is fixed by the routing and proxy arp that is set up on the
1241 TUN/TAP device on the host. You can use a different one, but it won't
1242 work because reply packets won't reach the UML. This is a feature.
1243 It prevents a nasty UML user from doing things like setting the UML IP
1244 to the same as the network's nameserver or mail server.
1247 There are a couple potential problems with running the TUN/TAP
1248 transport on a 2.4 host kernel
1250 - TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
1251 kernel or use the ethertap transport.
1253 - With an upgraded kernel, TUN/TAP may fail with::
1256 File descriptor in bad state
1261 This is due to a header mismatch between the upgraded kernel and the
1262 kernel that was originally installed on the machine. The fix is to
1263 make sure that /usr/src/linux points to the headers for the running
1266 These were pointed out by Tim Robinson <timro at trkr dot net> in
1267 <http://www.geocrawler.com/> name="this uml-user post"> .
1271 6.7. TUN/TAP with a preconfigured tap device
1272 ---------------------------------------------
1274 If you prefer not to have UML use uml_net (which is somewhat
1275 insecure), with UML 2.4.17-11, you can set up a TUN/TAP device
1276 beforehand. The setup needs to be done as root, but once that's done,
1277 there is no need for root assistance. Setting up the device is done
1280 - Create the device with tunctl (available from the UML utilities
1291 where uid is the user id or username that UML will be run as. This
1292 will tell you what device was created.
1294 - Configure the device IP (change IP addresses and device name to
1300 host# ifconfig tap0 192.168.0.254 up
1306 - Set up routing and arping if desired - this is my recipe, there are
1307 other ways of doing the same thing::
1311 bash -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'
1314 route add -host 192.168.0.253 dev tap0
1317 bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
1320 arp -Ds 192.168.0.253 eth0 pub
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.
1331 - 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
1341 ifconfig eth0 0.0.0.0 promisc up
1345 ifconfig tap0 0.0.0.0 promisc up
1349 ifconfig br0 192.168.0.1 netmask 255.255.255.0 up
1361 brctl sethello br0 1
1365 brctl addif br0 eth0
1369 brctl addif br0 tap0
1374 Note that 'br0' should be setup using ifconfig with the existing IP
1375 address of eth0, as eth0 no longer has its own IP.
1380 Also, the /dev/net/tun device must be writable by the user running
1381 UML in order for the UML to use the device that's been configured
1382 for it. The simplest thing to do is::
1385 host# chmod 666 /dev/net/tun
1390 Making it world-writable looks bad, but it seems not to be
1391 exploitable as a security hole. However, it does allow anyone to cre-
1392 ate useless tap devices (useless because they can't configure them),
1393 which is a DOS attack. A somewhat more secure alternative would to be
1394 to create a group containing all the users who have preconfigured tap
1395 devices and chgrp /dev/net/tun to that group with mode 664 or 660.
1398 - Once the device is set up, run UML with 'eth0=tuntap,device name'
1399 (i.e. 'eth0=tuntap,tap0') on the command line (or do it with the
1400 mconsole config command).
1402 - Bring the eth device up in UML and you're in business.
1404 If you don't want that tap device any more, you can make it non-
1408 host# tunctl -d tap device
1413 Finally, tunctl has a -b (for brief mode) switch which causes it to
1414 output only the name of the tap device it created. This makes it
1415 suitable for capture by a script::
1418 host# TAP=`tunctl -u 1000 -b`
1428 Ethertap is the general mechanism on 2.2 for userspace processes to
1429 exchange packets with the kernel.
1433 To use this transport, you need to describe the virtual network device
1434 on the UML command line. The general format for this is::
1437 eth <n> =ethertap, <device> , <ethernet address> , <tap IP address>
1442 So, the previous example::
1445 eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
1450 attaches the UML eth0 device to the host /dev/tap0, assigns it the
1451 ethernet address fe:fd:0:0:0:1, and assigns the IP address
1452 192.168.0.254 to the tap device.
1456 The tap device is mandatory, but the others are optional. If the
1457 ethernet address is omitted, one will be assigned to it.
1460 The presence of the tap IP address will cause the helper to run and do
1461 whatever host setup is needed to allow the virtual machine to
1462 communicate with the outside world. If you're not sure you know what
1463 you're doing, this is the way to go.
1466 If it is absent, then you must configure the tap device and whatever
1467 arping and routing you will need on the host. However, even in this
1468 case, the uml_net helper still needs to be in your path and it must be
1469 setuid root if you're not running UML as root. This is because the
1470 tap device doesn't support SIGIO, which UML needs in order to use
1471 something as a source of input. So, the helper is used as a
1472 convenient asynchronous IO thread.
1474 If you're using the uml_net helper, you can ignore the following host
1475 setup - uml_net will do it for you. You just need to make sure you
1476 have ethertap available, either built in to the host kernel or
1477 available as a module.
1480 If you want to set things up yourself, you need to make sure that the
1481 appropriate /dev entry exists. If it doesn't, become root and create
1485 mknod /dev/tap <minor> c 36 <minor> + 16
1490 For example, this is how to create /dev/tap0::
1493 mknod /dev/tap0 c 36 0 + 16
1498 You also need to make sure that the host kernel has ethertap support.
1499 If ethertap is enabled as a module, you apparently need to insmod
1500 ethertap once for each ethertap device you want to enable. So,::
1509 will give you the tap0 interface. To get the tap1 interface, you need
1514 insmod ethertap unit=1 -o ethertap1
1522 6.9. The switch daemon
1523 -----------------------
1525 Note: This is the daemon formerly known as uml_router, but which was
1526 renamed so the network weenies of the world would stop growling at me.
1529 The switch daemon, uml_switch, provides a mechanism for creating a
1530 totally virtual network. By default, it provides no connection to the
1531 host network (but see -tap, below).
1534 The first thing you need to do is run the daemon. Running it with no
1535 arguments will make it listen on a default pair of unix domain
1539 If you want it to listen on a different pair of sockets, use::
1542 -unix control socket data socket
1548 If you want it to act as a hub rather than a switch, use::
1557 If you want the switch to be connected to host networking (allowing
1558 the umls to get access to the outside world through the host), use::
1567 Note that the tap device must be preconfigured (see "TUN/TAP with a
1568 preconfigured tap device", above). If you're using a different tap
1569 device than tap0, specify that instead of tap0.
1572 uml_switch can be backgrounded as follows::
1576 uml_switch [ options ] < /dev/null > /dev/null
1581 The reason it doesn't background by default is that it listens to
1582 stdin for EOF. When it sees that, it exits.
1585 The general format of the kernel command line switch is::
1589 ethn=daemon,ethernet address,socket
1590 type,control socket,data socket
1595 You can leave off everything except the 'daemon'. You only need to
1596 specify the ethernet address if the one that will be assigned to it
1597 isn't acceptable for some reason. The rest of the arguments describe
1598 how to communicate with the daemon. You should only specify them if
1599 you told the daemon to use different sockets than the default. So, if
1600 you ran the daemon with no arguments, running the UML on the same
1608 will cause the eth0 driver to attach itself to the daemon correctly.
1615 Slip is another, less general, mechanism for a process to communicate
1616 with the host networking. In contrast to the ethertap interface,
1617 which exchanges ethernet frames with the host and can be used to
1618 transport any higher-level protocol, it can only be used to transport
1622 The general format of the command line switch is::
1631 The slip IP argument is the IP address that will be assigned to the
1632 host end of the slip device. If it is specified, the helper will run
1633 and will set up the host so that the virtual machine can reach it and
1634 the rest of the network.
1637 There are some oddities with this interface that you should be aware
1638 of. You should only specify one slip device on a given virtual
1639 machine, and its name inside UML will be 'umn', not 'eth0' or whatever
1640 you specified on the command line. These problems will be fixed at
1648 slirp uses an external program, usually /usr/bin/slirp, to provide IP
1649 only networking connectivity through the host. This is similar to IP
1650 masquerading with a firewall, although the translation is performed in
1651 user-space, rather than by the kernel. As slirp does not set up any
1652 interfaces on the host, or changes routing, slirp does not require
1653 root access or setuid binaries on the host.
1656 The general format of the command line switch for slirp is::
1660 ethn=slirp,ethernet address,slirp path
1665 The ethernet address is optional, as UML will set up the interface
1666 with an ethernet address based upon the initial IP address of the
1667 interface. The slirp path is generally /usr/bin/slirp, although it
1668 will depend on distribution.
1671 The slirp program can have a number of options passed to the command
1672 line and we can't add them to the UML command line, as they will be
1673 parsed incorrectly. Instead, a wrapper shell script can be written or
1674 the options inserted into the /.slirprc file. More information on
1675 all of the slirp options can be found in its man pages.
1678 The eth0 interface on UML should be set up with the IP 10.2.0.15,
1679 although you can use anything as long as it is not used by a network
1680 you will be connecting to. The default route on UML should be set to
1685 route add default dev eth0
1690 slirp provides a number of useful IP addresses which can be used by
1691 UML, such as 10.0.2.3 which is an alias for the DNS server specified
1692 in /etc/resolv.conf on the host or the IP given in the 'dns' option
1696 Even with a baudrate setting higher than 115200, the slirp connection
1697 is limited to 115200. If you need it to go faster, the slirp binary
1698 needs to be compiled with FULL_BOLT defined in config.h.
1705 The pcap transport is attached to a UML ethernet device on the command
1706 line or with uml_mconsole with the following syntax::
1710 ethn=pcap,host interface,filter
1711 expression,option1,option2
1716 The expression and options are optional.
1719 The interface is whatever network device on the host you want to
1720 sniff. The expression is a pcap filter expression, which is also what
1721 tcpdump uses, so if you know how to specify tcpdump filters, you will
1722 use the same expressions here. The options are up to two of
1723 'promisc', control whether pcap puts the host interface into
1724 promiscuous mode. 'optimize' and 'nooptimize' control whether the pcap
1725 expression optimizer is used.
1738 will cause the UML eth0 to emit all tcp packets on the host eth0 and
1739 the UML eth1 to emit all non-tcp packets on the host eth0.
1743 6.13. Setting up the host yourself
1744 -----------------------------------
1746 If you don't specify an address for the host side of the ethertap or
1747 slip device, UML won't do any setup on the host. So this is what is
1748 needed to get things working (the examples use a host-side IP of
1749 192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your
1752 - The device needs to be configured with its IP address. Tap devices
1753 are also configured with an mtu of 1484. Slip devices are
1754 configured with a point-to-point address pointing at the UML ip
1758 host# ifconfig tap0 arp mtu 1484 192.168.0.251 up
1762 ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up
1768 - If a tap device is being set up, a route is set to the UML IP::
1771 UML# route add -host 192.168.0.250 gw 192.168.0.251
1777 - To allow other hosts on your network to see the virtual machine,
1778 proxy arp is set up for it::
1781 host# arp -Ds 192.168.0.250 eth0 pub
1787 - Finally, the host is set up to route packets::
1790 host# echo 1 > /proc/sys/net/ipv4/ip_forward
1801 7. Sharing Filesystems between Virtual Machines
1802 ================================================
1810 Don't attempt to share filesystems simply by booting two UMLs from the
1811 same file. That's the same thing as booting two physical machines
1812 from a shared disk. It will result in filesystem corruption.
1816 7.2. Using layered block devices
1817 ---------------------------------
1819 The way to share a filesystem between two virtual machines is to use
1820 the copy-on-write (COW) layering capability of the ubd block driver.
1821 As of 2.4.6-2um, the driver supports layering a read-write private
1822 device over a read-only shared device. A machine's writes are stored
1823 in the private device, while reads come from either device - the
1824 private one if the requested block is valid in it, the shared one if
1825 not. Using this scheme, the majority of data which is unchanged is
1826 shared between an arbitrary number of virtual machines, each of which
1827 has a much smaller file containing the changes that it has made. With
1828 a large number of UMLs booting from a large root filesystem, this
1829 leads to a huge disk space saving. It will also help performance,
1830 since the host will be able to cache the shared data using a much
1831 smaller amount of memory, so UML disk requests will be served from the
1832 host's memory rather than its disks.
1837 To add a copy-on-write layer to an existing block device file, simply
1838 add the name of the COW file to the appropriate ubd switch::
1841 ubd0=root_fs_cow,root_fs_debian_22
1846 where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is
1847 the existing shared filesystem. The COW file need not exist. If it
1848 doesn't, the driver will create and initialize it. Once the COW file
1849 has been initialized, it can be used on its own on the command line::
1857 The name of the backing file is stored in the COW file header, so it
1858 would be redundant to continue specifying it on the command line.
1865 When checking the size of the COW file in order to see the gobs of
1866 space that you're saving, make sure you use 'ls -ls' to see the actual
1867 disk consumption rather than the length of the file. The COW file is
1868 sparse, so the length will be very different from the disk usage.
1869 Here is a 'ls -l' of a COW file and backing file from one boot and
1872 host% ls -l cow.debian debian2.2
1873 -rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
1874 -rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
1879 Doesn't look like much saved space, does it? Well, here's 'ls -ls'::
1882 host% ls -ls cow.debian debian2.2
1883 880 -rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
1884 525832 -rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
1889 Now, you can see that the COW file has less than a meg of disk, rather
1894 7.4. Another warning
1895 ---------------------
1897 Once a filesystem is being used as a readonly backing file for a COW
1898 file, do not boot directly from it or modify it in any way. Doing so
1899 will invalidate any COW files that are using it. The mtime and size
1900 of the backing file are stored in the COW file header at its creation,
1901 and they must continue to match. If they don't, the driver will
1902 refuse to use the COW file.
1907 If you attempt to evade this restriction by changing either the
1908 backing file or the COW header by hand, you will get a corrupted
1914 Among other things, this means that upgrading the distribution in a
1915 backing file and expecting that all of the COW files using it will see
1916 the upgrade will not work.
1921 7.5. uml_moo : Merging a COW file with its backing file
1922 --------------------------------------------------------
1924 Depending on how you use UML and COW devices, it may be advisable to
1925 merge the changes in the COW file into the backing file every once in
1931 The utility that does this is uml_moo. Its usage is::
1934 host% uml_moo COW file new backing file
1939 There's no need to specify the backing file since that information is
1940 already in the COW file header. If you're paranoid, boot the new
1941 merged file, and if you're happy with it, move it over the old backing
1947 uml_moo creates a new backing file by default as a safety measure. It
1948 also has a destructive merge option which will merge the COW file
1949 directly into its current backing file. This is really only usable
1950 when the backing file only has one COW file associated with it. If
1951 there are multiple COWs associated with a backing file, a -d merge of
1952 one of them will invalidate all of the others. However, it is
1953 convenient if you're short of disk space, and it should also be
1954 noticeably faster than a non-destructive merge.
1959 uml_moo is installed with the UML deb and RPM. If you didn't install
1960 UML from one of those packages, you can also get it from the UML
1961 utilities <http://user-mode-linux.sourceforge.net/
1962 utilities> tar file in tools/moo.
1971 8. Creating filesystems
1972 ========================
1975 You may want to create and mount new UML filesystems, either because
1976 your root filesystem isn't large enough or because you want to use a
1977 filesystem other than ext2.
1980 This was written on the occasion of reiserfs being included in the
1981 2.4.1 kernel pool, and therefore the 2.4.1 UML, so the examples will
1982 talk about reiserfs. This information is generic, and the examples
1983 should be easy to translate to the filesystem of your choice.
1986 8.1. Create the filesystem file
1987 ================================
1989 dd is your friend. All you need to do is tell dd to create an empty
1990 file of the appropriate size. I usually make it sparse to save time
1991 and to avoid allocating disk space until it's actually used. For
1992 example, the following command will create a sparse 100 meg file full
1997 dd if=/dev/zero of=new_filesystem seek=100 count=1 bs=1M
2004 8.2. Assign the file to a UML device
2006 Add an argument like the following to the UML command line::
2013 making sure that you use an unassigned ubd device number.
2017 8.3. Creating and mounting the filesystem
2019 Make sure that the filesystem is available, either by being built into
2020 the kernel, or available as a module, then boot up UML and log in. If
2021 the root filesystem doesn't have the filesystem utilities (mkfs, fsck,
2022 etc), then get them into UML by way of the net or hostfs.
2025 Make the new filesystem on the device assigned to the new file::
2028 host# mkreiserfs /dev/ubd/4
2031 <----------- MKREISERFSv2 ----------->
2033 ReiserFS version 3.6.25
2034 Block size 4096 bytes
2037 Journal - 8192 blocks (18-8209), journal header is in block 8210
2041 ATTENTION: ALL DATA WILL BE LOST ON '/dev/ubd/4'! (y/n)y
2042 journal size 8192 (from 18)
2043 Initializing journal - 0%....20%....40%....60%....80%....100%
2053 mount /dev/ubd/4 /mnt
2058 and you're in business.
2069 ====================
2072 If you want to access files on the host machine from inside UML, you
2073 can treat it as a separate machine and either nfs mount directories
2074 from the host or copy files into the virtual machine with scp or rcp.
2075 However, since UML is running on the host, it can access those
2076 files just like any other process and make them available inside the
2077 virtual machine without needing to use the network.
2080 This is now possible with the hostfs virtual filesystem. With it, you
2081 can mount a host directory into the UML filesystem and access the
2082 files contained in it just as you would on the host.
2088 To begin with, make sure that hostfs is available inside the virtual
2092 UML# cat /proc/filesystems
2096 . hostfs should be listed. If it's not, either rebuild the kernel
2097 with hostfs configured into it or make sure that hostfs is built as a
2098 module and available inside the virtual machine, and insmod it.
2101 Now all you need to do is run mount::
2104 UML# mount none /mnt/host -t hostfs
2109 will mount the host's / on the virtual machine's /mnt/host.
2112 If you don't want to mount the host root directory, then you can
2113 specify a subdirectory to mount with the -o switch to mount::
2116 UML# mount none /mnt/home -t hostfs -o /home
2121 will mount the hosts's /home on the virtual machine's /mnt/home.
2125 9.2. hostfs as the root filesystem
2126 -----------------------------------
2128 It's possible to boot from a directory hierarchy on the host using
2129 hostfs rather than using the standard filesystem in a file.
2131 To start, you need that hierarchy. The easiest way is to loop mount
2132 an existing root_fs file::
2135 host# mount root_fs uml_root_dir -o loop
2140 You need to change the filesystem type of / in etc/fstab to be
2141 'hostfs', so that line looks like this::
2143 /dev/ubd/0 / hostfs defaults 1 1
2148 Then you need to chown to yourself all the files in that directory
2149 that are owned by root. This worked for me::
2152 host# find . -uid 0 -exec chown jdike {} \;
2157 Next, make sure that your UML kernel has hostfs compiled in, not as a
2158 module. Then run UML with the boot device pointing at that directory::
2161 ubd0=/path/to/uml/root/directory
2166 UML should then boot as it does normally.
2169 9.3. Building hostfs
2170 ---------------------
2172 If you need to build hostfs because it's not in your kernel, you have
2177 - Compiling hostfs into the kernel:
2180 Reconfigure the kernel and set the 'Host filesystem' option under
2183 - Compiling hostfs as a module:
2186 Reconfigure the kernel and set the 'Host filesystem' option under
2187 be in arch/um/fs/hostfs/hostfs.o. Install that in
2188 ``/lib/modules/$(uname -r)/fs`` in the virtual machine, boot it up, and::
2194 .. _The_Management_Console:
2196 10. The Management Console
2197 ===========================
2201 The UML management console is a low-level interface to the kernel,
2202 somewhat like the i386 SysRq interface. Since there is a full-blown
2203 operating system under UML, there is much greater flexibility possible
2204 than with the SysRq mechanism.
2207 There are a number of things you can do with the mconsole interface:
2209 - get the kernel version
2211 - add and remove devices
2213 - halt or reboot the machine
2215 - Send SysRq commands
2217 - Pause and resume the UML
2220 You need the mconsole client (uml_mconsole) which is present in CVS
2221 (/tools/mconsole) in 2.4.5-9um and later, and will be in the RPM in
2225 You also need CONFIG_MCONSOLE (under 'General Setup') enabled in UML.
2226 When you boot UML, you'll see a line like::
2229 mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole
2234 If you specify a unique machine id one the UML command line, i.e.::
2245 mconsole initialized on /home/jdike/.uml/debian/mconsole
2250 That file is the socket that uml_mconsole will use to communicate with
2251 UML. Run it with either the umid or the full path as its argument::
2254 host% uml_mconsole debian
2262 host% uml_mconsole /home/jdike/.uml/debian/mconsole
2267 You'll get a prompt, at which you can run one of these commands:
2293 This takes no arguments. It prints the UML version::
2297 OK Linux usermode 2.4.5-9um #1 Wed Jun 20 22:47:08 EDT 2001 i686
2302 There are a couple actual uses for this. It's a simple no-op which
2303 can be used to check that a UML is running. It's also a way of
2304 sending an interrupt to the UML. This is sometimes useful on SMP
2305 hosts, where there's a bug which causes signals to UML to be lost,
2306 often causing it to appear to hang. Sending such a UML the mconsole
2307 version command is a good way to 'wake it up' before networking has
2308 been enabled, as it does not do anything to the function of the UML.
2312 10.2. halt and reboot
2313 ----------------------
2315 These take no arguments. They shut the machine down immediately, with
2316 no syncing of disks and no clean shutdown of userspace. So, they are
2317 pretty close to crashing the machine::
2331 "config" adds a new device to the virtual machine. Currently the ubd
2332 and network drivers support this. It takes one argument, which is the
2333 device to add, with the same syntax as the kernel command line::
2339 config ubd3=/home/jdike/incoming/roots/root_fs_debian22
2342 (mconsole) config eth1=mcast
2353 "remove" deletes a device from the system. Its argument is just the
2354 name of the device to be removed. The device must be idle in whatever
2355 sense the driver considers necessary. In the case of the ubd driver,
2356 the removed block device must not be mounted, swapped on, or otherwise
2357 open, and in the case of the network driver, the device must be down::
2360 (mconsole) remove ubd3
2362 (mconsole) remove eth1
2373 This takes one argument, which is a single letter. It calls the
2374 generic kernel's SysRq driver, which does whatever is called for by
2375 that argument. See the SysRq documentation in
2376 Documentation/admin-guide/sysrq.rst in your favorite kernel tree to
2377 see what letters are valid and what they do.
2384 "help" returns a string listing the valid commands and what each one
2392 This invokes the Ctl-Alt-Del action on init. What exactly this ends
2393 up doing is up to /etc/inittab. Normally, it reboots the machine.
2394 With UML, this is usually not desired, so if a halt would be better,
2395 then find the section of inittab that looks like this::
2398 # What to do when CTRL-ALT-DEL is pressed.
2399 ca:12345:ctrlaltdel:/sbin/shutdown -t1 -a -r now
2404 and change the command to halt.
2411 This puts the UML in a loop reading mconsole requests until a 'go'
2412 mconsole command is received. This is very useful for making backups
2413 of UML filesystems, as the UML can be stopped, then synced via 'sysrq
2414 s', so that everything is written to the filesystem. You can then copy
2415 the filesystem and then send the UML 'go' via mconsole.
2418 Note that a UML running with more than one CPU will have problems
2419 after you send the 'stop' command, as only one CPU will be held in a
2420 mconsole loop and all others will continue as normal. This is a bug,
2428 This resumes a UML after being paused by a 'stop' command. Note that
2429 when the UML has resumed, TCP connections may have timed out and if
2430 the UML is paused for a long period of time, crond might go a little
2431 crazy, running all the jobs it didn't do earlier.
2438 .. _Kernel_debugging:
2440 11. Kernel debugging
2441 =====================
2444 Note: The interface that makes debugging, as described here, possible
2445 is present in 2.4.0-test6 kernels and later.
2448 Since the user-mode kernel runs as a normal Linux process, it is
2449 possible to debug it with gdb almost like any other process. It is
2450 slightly different because the kernel's threads are already being
2451 ptraced for system call interception, so gdb can't ptrace them.
2452 However, a mechanism has been added to work around that problem.
2455 In order to debug the kernel, you need build it from source. See
2456 :ref:`Compiling_the_kernel_and_modules` for information on doing that.
2457 Make sure that you enable CONFIG_DEBUGSYM and CONFIG_PT_PROXY during
2458 the config. These will compile the kernel with ``-g``, and enable the
2459 ptrace proxy so that gdb works with UML, respectively.
2464 11.1. Starting the kernel under gdb
2465 ------------------------------------
2467 You can have the kernel running under the control of gdb from the
2468 beginning by putting 'debug' on the command line. You will get an
2469 xterm with gdb running inside it. The kernel will send some commands
2470 to gdb which will leave it stopped at the beginning of start_kernel.
2471 At this point, you can get things going with 'next', 'step', or
2475 There is a transcript of a debugging session here <debug-
2476 session.html> , with breakpoints being set in the scheduler and in an
2480 11.2. Examining sleeping processes
2481 -----------------------------------
2484 Not every bug is evident in the currently running process. Sometimes,
2485 processes hang in the kernel when they shouldn't because they've
2486 deadlocked on a semaphore or something similar. In this case, when
2487 you ^C gdb and get a backtrace, you will see the idle thread, which
2488 isn't very relevant.
2491 What you want is the stack of whatever process is sleeping when it
2492 shouldn't be. You need to figure out which process that is, which is
2493 generally fairly easy. Then you need to get its host process id,
2494 which you can do either by looking at ps on the host or at
2495 task.thread.extern_pid in gdb.
2498 Now what you do is this:
2500 - detach from the current thread::
2509 - attach to the thread you are interested in::
2512 (UML gdb) att <host pid>
2518 - look at its stack and anything else of interest::
2526 Note that you can't do anything at this point that requires that a
2527 process execute, e.g. calling a function
2529 - when you're done looking at that process, reattach to the current
2530 thread and continue it::
2543 Here, specifying any pid which is not the process id of a UML thread
2544 will cause gdb to reattach to the current thread. I commonly use 1,
2545 but any other invalid pid would work.
2549 11.3. Running ddd on UML
2550 -------------------------
2552 ddd works on UML, but requires a special kludge. The process goes
2564 - With ps, get the pid of the gdb that ddd started. You can ask the
2565 gdb to tell you, but for some reason that confuses things and
2568 - run UML with 'debug=parent gdb-pid=<pid>' added to the command line
2569 - it will just sit there after you hit return
2571 - type 'att 1' to the ddd gdb and you will see something like::
2574 0xa013dc51 in __kill ()
2583 - At this point, type 'c', UML will boot up, and you can use ddd just
2584 as you do on any other process.
2588 11.4. Debugging modules
2589 ------------------------
2592 gdb has support for debugging code which is dynamically loaded into
2593 the process. This support is what is needed to debug kernel modules
2597 Using that support is somewhat complicated. You have to tell gdb what
2598 object file you just loaded into UML and where in memory it is. Then,
2599 it can read the symbol table, and figure out where all the symbols are
2600 from the load address that you provided. It gets more interesting
2601 when you load the module again (i.e. after an rmmod). You have to
2602 tell gdb to forget about all its symbols, including the main UML ones
2603 for some reason, then load then all back in again.
2606 There's an easy way and a hard way to do this. The easy way is to use
2607 the umlgdb expect script written by Chandan Kudige. It basically
2608 automates the process for you.
2611 First, you must tell it where your modules are. There is a list in
2612 the script that looks like this::
2615 "fat" "/usr/src/uml/linux-2.4.18/fs/fat/fat.o"
2616 "isofs" "/usr/src/uml/linux-2.4.18/fs/isofs/isofs.o"
2617 "minix" "/usr/src/uml/linux-2.4.18/fs/minix/minix.o"
2623 You change that to list the names and paths of the modules that you
2624 are going to debug. Then you run it from the toplevel directory of
2625 your UML pool and it basically tells you what to do::
2628 ******** GDB pid is 21903 ********
2629 Start UML as: ./linux <kernel switches> debug gdb-pid=21903
2633 GNU gdb 5.0rh-5 Red Hat Linux 7.1
2634 Copyright 2001 Free Software Foundation, Inc.
2635 GDB is free software, covered by the GNU General Public License, and you are
2636 welcome to change it and/or distribute copies of it under certain conditions.
2637 Type "show copying" to see the conditions.
2638 There is absolutely no warranty for GDB. Type "show warranty" for details.
2639 This GDB was configured as "i386-redhat-linux"...
2640 (gdb) b sys_init_module
2641 Breakpoint 1 at 0xa0011923: file module.c, line 349.
2647 After you run UML and it sits there doing nothing, you hit return at
2648 the 'att 1' and continue it::
2651 Attaching to program: /home/jdike/linux/2.4/um/./linux, process 1
2652 0xa00f4221 in __kill ()
2659 At this point, you debug normally. When you insmod something, the
2660 expect magic will kick in and you'll see something like::
2663 *** Module hostfs loaded ***
2664 Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
2665 mod_user=0x8070e00) at module.c:349
2666 349 char *name, *n_name, *name_tmp = NULL;
2668 Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
2669 mod_user=0x8070e00) at module.c:349
2670 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
2671 411 else res = EXECUTE_SYSCALL(syscall, regs);
2672 Value returned is $1 = 0
2674 p/x (int)module_list + module_list->size_of_struct
2677 (UML gdb) symbol-file ./linux
2678 Load new symbol table from "./linux"? (y or n) y
2679 Reading symbols from ./linux...
2682 add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
2684 add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
2685 .text_addr = 0xa9021054
2688 Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
2690 (UML gdb) p *module_list
2691 $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
2692 size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
2693 nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
2694 init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
2695 ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
2696 persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
2698 archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
2699 archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
2700 kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
2701 >> Finished loading symbols for hostfs ...
2706 That's the easy way. It's highly recommended. The hard way is
2707 described below in case you're interested in what's going on.
2710 Boot the kernel under the debugger and load the module with insmod or
2711 modprobe. With gdb, do::
2714 (UML gdb) p module_list
2719 This is a list of modules that have been loaded into the kernel, with
2720 the most recently loaded module first. Normally, the module you want
2721 is at module_list. If it's not, walk down the next links, looking at
2722 the name fields until find the module you want to debug. Take the
2723 address of that structure, and add module.size_of_struct (which in
2724 2.4.10 kernels is 96 (0x60)) to it. Gdb can make this hard addition
2730 printf "%#x\n", (int)module_list module_list->size_of_struct
2735 The offset from the module start occasionally changes (before 2.4.0,
2736 it was module.size_of_struct + 4), so it's a good idea to check the
2737 init and cleanup addresses once in a while, as describe below. Now
2742 add-symbol-file /path/to/module/on/host that_address
2747 Tell gdb you really want to do it, and you're in business.
2750 If there's any doubt that you got the offset right, like breakpoints
2751 appear not to work, or they're appearing in the wrong place, you can
2752 check it by looking at the module structure. The init and cleanup
2753 fields should look like::
2756 init = 0x588066b0 <init_hostfs>, cleanup = 0x588066c0 <exit_hostfs>
2761 with no offsets on the symbol names. If the names are right, but they
2762 are offset, then the offset tells you how much you need to add to the
2763 address you gave to add-symbol-file.
2766 When you want to load in a new version of the module, you need to get
2767 gdb to forget about the old one. The only way I've found to do that
2768 is to tell gdb to forget about all symbols that it knows about::
2771 (UML gdb) symbol-file
2776 Then reload the symbols from the kernel binary::
2779 (UML gdb) symbol-file /path/to/kernel
2784 and repeat the process above. You'll also need to re-enable break-
2785 points. They were disabled when you dumped all the symbols because
2786 gdb couldn't figure out where they should go.
2790 11.5. Attaching gdb to the kernel
2791 ----------------------------------
2793 If you don't have the kernel running under gdb, you can attach gdb to
2794 it later by sending the tracing thread a SIGUSR1. The first line of
2795 the console output identifies its pid::
2797 tracing thread pid = 20093
2802 When you send it the signal::
2805 host% kill -USR1 20093
2810 you will get an xterm with gdb running in it.
2813 If you have the mconsole compiled into UML, then the mconsole client
2814 can be used to start gdb::
2817 (mconsole) (mconsole) config gdb=xterm
2822 will fire up an xterm with gdb running in it.
2826 11.6. Using alternate debuggers
2827 --------------------------------
2829 UML has support for attaching to an already running debugger rather
2830 than starting gdb itself. This is present in CVS as of 17 Apr 2001.
2831 I sent it to Alan for inclusion in the ac tree, and it will be in my
2835 This is useful when gdb is a subprocess of some UI, such as emacs or
2836 ddd. It can also be used to run debuggers other than gdb on UML.
2837 Below is an example of using strace as an alternate debugger.
2840 To do this, you need to get the pid of the debugger and pass it in
2844 If you are using gdb under some UI, then tell it to 'att 1', and
2845 you'll find yourself attached to UML.
2848 If you are using something other than gdb as your debugger, then
2849 you'll need to get it to do the equivalent of 'att 1' if it doesn't do
2853 An example of an alternate debugger is strace. You can strace the
2854 actual kernel as follows:
2856 - Run the following in a shell::
2860 sh -c 'echo pid=$$; echo -n hit return; read x; exec strace -p 1 -o strace.out'
2864 - Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
2865 by the previous command
2867 - Hit return in the shell, and UML will start running, and strace
2868 output will start accumulating in the output file.
2870 Note that this is different from running::
2873 host% strace ./linux
2878 That will strace only the main UML thread, the tracing thread, which
2879 doesn't do any of the actual kernel work. It just oversees the vir-
2880 tual machine. In contrast, using strace as described above will show
2881 you the low-level activity of the virtual machine.
2887 12. Kernel debugging examples
2888 ==============================
2890 12.1. The case of the hung fsck
2891 --------------------------------
2893 When booting up the kernel, fsck failed, and dropped me into a shell
2894 to fix things up. I ran fsck -y, which hung::
2897 Setting hostname uml [ OK ]
2898 Checking root filesystem
2899 /dev/fhd0 was not cleanly unmounted, check forced.
2900 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
2902 /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
2903 (i.e., without -a or -p options)
2906 *** An error occurred during the file system check.
2907 *** Dropping you to a shell; the system will reboot
2908 *** when you leave the shell.
2909 Give root password for maintenance
2910 (or type Control-D for normal startup):
2912 [root@uml /root]# fsck -y /dev/fhd0
2914 Parallelizing fsck version 1.14 (9-Jan-1999)
2915 e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
2916 /dev/fhd0 contains a file system with errors, check forced.
2917 Pass 1: Checking inodes, blocks, and sizes
2918 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
2920 Inode 19780, i_blocks is 1548, should be 540. Fix? yes
2922 Pass 2: Checking directory structure
2923 Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
2925 Directory inode 11858, block 0, offset 0: directory corrupted
2928 Missing '.' in directory inode 11858.
2931 Missing '..' in directory inode 11858.
2935 The standard drill in this sort of situation is to fire up gdb on the
2936 signal thread, which, in this case, was pid 1935. In another window,
2937 I run gdb and attach pid 1935::
2940 ~/linux/2.3.26/um 1016: gdb linux
2941 GNU gdb 4.17.0.11 with Linux support
2942 Copyright 1998 Free Software Foundation, Inc.
2943 GDB is free software, covered by the GNU General Public License, and you are
2944 welcome to change it and/or distribute copies of it under certain conditions.
2945 Type "show copying" to see the conditions.
2946 There is absolutely no warranty for GDB. Type "show warranty" for details.
2947 This GDB was configured as "i386-redhat-linux"...
2950 Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 1935
2951 0x100756d9 in __wait4 ()
2954 Let's see what's currently running::
2958 (gdb) p current_task.pid
2965 It's the idle thread, which means that fsck went to sleep for some
2966 reason and never woke up.
2969 Let's guess that the last process in the process list is fsck::
2973 (gdb) p current_task.prev_task.comm
2974 $13 = "fsck.ext2\000\000\000\000\000\000"
2980 It is, so let's see what it thinks it's up to::
2984 (gdb) p current_task.prev_task.thread
2985 $14 = {extern_pid = 1980, tracing = 0, want_tracing = 0, forking = 0,
2986 kernel_stack_page = 0, signal_stack = 1342627840, syscall = {id = 4, args = {
2987 3, 134973440, 1024, 0, 1024}, have_result = 0, result = 50590720},
2988 request = {op = 2, u = {exec = {ip = 1350467584, sp = 2952789424}, fork = {
2989 regs = {1350467584, 2952789424, 0 <repeats 15 times>}, sigstack = 0,
2990 pid = 0}, switch_to = 0x507e8000, thread = {proc = 0x507e8000,
2991 arg = 0xaffffdb0, flags = 0, new_pid = 0}, input_request = {
2992 op = 1350467584, fd = -1342177872, proc = 0, pid = 0}}}}
2996 The interesting things here are the fact that its .thread.syscall.id
2997 is __NR_write (see the big switch in arch/um/kernel/syscall_kern.c or
2998 the defines in include/asm-um/arch/unistd.h), and that it never
2999 returned. Also, its .request.op is OP_SWITCH (see
3000 arch/um/include/user_util.h). These mean that it went into a write,
3001 and, for some reason, called schedule().
3004 The fact that it never returned from write means that its stack should
3005 be fairly interesting. Its pid is 1980 (.thread.extern_pid). That
3006 process is being ptraced by the signal thread, so it must be detached
3007 before gdb can attach it::
3011 (gdb) call detach(1980)
3013 Program received signal SIGSEGV, Segmentation fault.
3014 <function called from gdb>
3015 The program being debugged stopped while in a function called from GDB.
3016 When the function (detach) is done executing, GDB will silently
3017 stop (instead of continuing to evaluate the expression containing
3019 (gdb) call detach(1980)
3023 The first detach segfaults for some reason, and the second one
3027 Now I detach from the signal thread, attach to the fsck thread, and
3032 Detaching from program: /home/dike/linux/2.3.26/um/linux Pid 1935
3034 Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 1980
3035 0x10070451 in __kill ()
3037 #0 0x10070451 in __kill ()
3038 #1 0x10068ccd in usr1_pid (pid=1980) at process.c:30
3039 #2 0x1006a03f in _switch_to (prev=0x50072000, next=0x507e8000)
3040 at process_kern.c:156
3041 #3 0x1006a052 in switch_to (prev=0x50072000, next=0x507e8000, last=0x50072000)
3042 at process_kern.c:161
3043 #4 0x10001d12 in schedule () at core.c:777
3044 #5 0x1006a744 in __down (sem=0x507d241c) at semaphore.c:71
3045 #6 0x1006aa10 in __down_failed () at semaphore.c:157
3046 #7 0x1006c5d8 in segv_handler (sc=0x5006e940) at trap_user.c:174
3047 #8 0x1006c5ec in kern_segv_handler (sig=11) at trap_user.c:182
3048 #9 <signal handler called>
3049 #10 0x10155404 in errno ()
3050 #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
3051 #12 0x1006c5d8 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
3052 #13 0x1006c5ec in kern_segv_handler (sig=11) at trap_user.c:182
3053 #14 <signal handler called>
3055 #16 0x10016647 in sys_write (fd=3,
3056 buf=0x80b8800 <Address 0x80b8800 out of bounds>, count=1024)
3058 #17 0x1006d5b3 in execute_syscall (syscall=4, args=0x5006ef08)
3059 at syscall_kern.c:254
3060 #18 0x1006af87 in really_do_syscall (sig=12) at syscall_user.c:35
3061 #19 <signal handler called>
3062 #20 0x400dc8b0 in ?? ()
3068 The interesting things here are:
3070 - There are two segfaults on this stack (frames 9 and 14)
3072 - The first faulting address (frame 11) is 0x50000800::
3074 (gdb) p (void *)1342179328
3075 $16 = (void *) 0x50000800
3081 The initial faulting address is interesting because it is on the idle
3082 thread's stack. I had been seeing the idle thread segfault for no
3083 apparent reason, and the cause looked like stack corruption. In hopes
3084 of catching the culprit in the act, I had turned off all protections
3085 to that stack while the idle thread wasn't running. This apparently
3089 However, the more immediate problem is that second segfault and I'm
3090 going to concentrate on that. First, I want to see where the fault
3091 happened, so I have to go look at the sigcontent struct in frame 8::
3096 #1 0x10068ccd in usr1_pid (pid=1980) at process.c:30
3097 30 kill(pid, SIGUSR1);
3099 #2 0x1006a03f in _switch_to (prev=0x50072000, next=0x507e8000)
3100 at process_kern.c:156
3101 156 usr1_pid(getpid());
3103 #3 0x1006a052 in switch_to (prev=0x50072000, next=0x507e8000, last=0x50072000)
3104 at process_kern.c:161
3105 161 _switch_to(prev, next);
3107 #4 0x10001d12 in schedule () at core.c:777
3108 777 switch_to(prev, next, prev);
3110 #5 0x1006a744 in __down (sem=0x507d241c) at semaphore.c:71
3113 #6 0x1006aa10 in __down_failed () at semaphore.c:157
3116 #7 0x1006c5d8 in segv_handler (sc=0x5006e940) at trap_user.c:174
3117 174 segv(sc->cr2, sc->err & 2);
3119 #8 0x1006c5ec in kern_segv_handler (sig=11) at trap_user.c:182
3120 182 segv_handler(sc);
3122 Cannot access memory at address 0x0.
3127 That's not very useful, so I'll try a more manual method::
3130 (gdb) p *((struct sigcontext *) (&sig + 1))
3131 $19 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
3132 __dsh = 0, edi = 1342179328, esi = 1350378548, ebp = 1342630440,
3133 esp = 1342630420, ebx = 1348150624, edx = 1280, ecx = 0, eax = 0,
3134 trapno = 14, err = 4, eip = 268480945, cs = 35, __csh = 0, eflags = 66118,
3135 esp_at_signal = 1342630420, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
3140 The ip is in handle_mm_fault::
3143 (gdb) p (void *)268480945
3144 $20 = (void *) 0x1000b1b1
3146 handle_mm_fault + 57 in section .text
3152 Specifically, it's in pte_alloc::
3156 Line 124 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3157 starts at address 0x1000b1b1 <handle_mm_fault+57>
3158 and ends at 0x1000b1b7 <handle_mm_fault+63>.
3164 To find where in handle_mm_fault this is, I'll jump forward in the
3165 code until I see an address in that procedure::
3169 (gdb) i line *0x1000b1c0
3170 Line 126 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3171 starts at address 0x1000b1b7 <handle_mm_fault+63>
3172 and ends at 0x1000b1c3 <handle_mm_fault+75>.
3173 (gdb) i line *0x1000b1d0
3174 Line 131 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3175 starts at address 0x1000b1d0 <handle_mm_fault+88>
3176 and ends at 0x1000b1da <handle_mm_fault+98>.
3177 (gdb) i line *0x1000b1e0
3178 Line 61 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3179 starts at address 0x1000b1da <handle_mm_fault+98>
3180 and ends at 0x1000b1e1 <handle_mm_fault+105>.
3181 (gdb) i line *0x1000b1f0
3182 Line 134 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3183 starts at address 0x1000b1f0 <handle_mm_fault+120>
3184 and ends at 0x1000b200 <handle_mm_fault+136>.
3185 (gdb) i line *0x1000b200
3186 Line 135 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3187 starts at address 0x1000b200 <handle_mm_fault+136>
3188 and ends at 0x1000b208 <handle_mm_fault+144>.
3189 (gdb) i line *0x1000b210
3190 Line 139 of "/home/dike/linux/2.3.26/um/include/asm/pgalloc.h"
3191 starts at address 0x1000b210 <handle_mm_fault+152>
3192 and ends at 0x1000b219 <handle_mm_fault+161>.
3193 (gdb) i line *0x1000b220
3194 Line 1168 of "memory.c" starts at address 0x1000b21e <handle_mm_fault+166>
3195 and ends at 0x1000b222 <handle_mm_fault+170>.
3201 Something is apparently wrong with the page tables or vma_structs, so
3202 lets go back to frame 11 and have a look at them::
3206 #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
3207 50 handle_mm_fault(current, vma, address, is_write);
3208 (gdb) call pgd_offset_proc(vma->vm_mm, address)
3209 $22 = (pgd_t *) 0x80a548c
3215 That's pretty bogus. Page tables aren't supposed to be in process
3216 text or data areas. Let's see what's in the vma::
3220 $23 = {vm_mm = 0x507d2434, vm_start = 0, vm_end = 134512640,
3221 vm_next = 0x80a4f8c, vm_page_prot = {pgprot = 0}, vm_flags = 31200,
3222 vm_avl_height = 2058, vm_avl_left = 0x80a8c94, vm_avl_right = 0x80d1000,
3223 vm_next_share = 0xaffffdb0, vm_pprev_share = 0xaffffe63,
3224 vm_ops = 0xaffffe7a, vm_pgoff = 2952789626, vm_file = 0xafffffec,
3225 vm_private_data = 0x62}
3227 $24 = {mmap = 0x507d2434, mmap_avl = 0x0, mmap_cache = 0x8048000,
3228 pgd = 0x80a4f8c, mm_users = {counter = 0}, mm_count = {counter = 134904288},
3229 map_count = 134909076, mmap_sem = {count = {counter = 135073792},
3230 sleepers = -1342177872, wait = {lock = <optimized out or zero length>,
3231 task_list = {next = 0xaffffe63, prev = 0xaffffe7a},
3232 __magic = -1342177670, __creator = -1342177300}, __magic = 98},
3233 page_table_lock = {}, context = 138, start_code = 0, end_code = 0,
3234 start_data = 0, end_data = 0, start_brk = 0, brk = 0, start_stack = 0,
3235 arg_start = 0, arg_end = 0, env_start = 0, env_end = 0, rss = 1350381536,
3236 total_vm = 0, locked_vm = 0, def_flags = 0, cpu_vm_mask = 0, swap_cnt = 0,
3237 swap_address = 0, segments = 0x0}
3241 This also pretty bogus. With all of the 0x80xxxxx and 0xaffffxxx
3242 addresses, this is looking like a stack was plonked down on top of
3243 these structures. Maybe it's a stack overflow from the next page::
3247 $25 = (struct vm_area_struct *) 0x507d2434
3251 That's towards the lower quarter of the page, so that would have to
3252 have been pretty heavy stack overflow::
3256 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
3257 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
3258 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
3259 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
3260 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
3261 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
3262 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
3263 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
3264 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
3265 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
3266 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
3267 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
3268 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
3269 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
3270 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
3271 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
3272 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
3273 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
3274 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
3275 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
3276 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
3277 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
3278 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
3279 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
3280 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
3284 It's not stack overflow. The only "stack-like" piece of this data is
3285 the vma_struct itself.
3288 At this point, I don't see any avenues to pursue, so I just have to
3289 admit that I have no idea what's going on. What I will do, though, is
3290 stick a trap on the segfault handler which will stop if it sees any
3291 writes to the idle thread's stack. That was the thing that happened
3292 first, and it may be that if I can catch it immediately, what's going
3293 on will be somewhat clearer.
3296 12.2. Episode 2: The case of the hung fsck
3297 -------------------------------------------
3299 After setting a trap in the SEGV handler for accesses to the signal
3300 thread's stack, I reran the kernel.
3303 fsck hung again, this time by hitting the trap::
3307 Setting hostname uml [ OK ]
3308 Checking root filesystem
3309 /dev/fhd0 contains a file system with errors, check forced.
3310 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
3312 /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
3313 (i.e., without -a or -p options)
3316 *** An error occurred during the file system check.
3317 *** Dropping you to a shell; the system will reboot
3318 *** when you leave the shell.
3319 Give root password for maintenance
3320 (or type Control-D for normal startup):
3322 [root@uml /root]# fsck -y /dev/fhd0
3324 Parallelizing fsck version 1.14 (9-Jan-1999)
3325 e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
3326 /dev/fhd0 contains a file system with errors, check forced.
3327 Pass 1: Checking inodes, blocks, and sizes
3328 Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
3330 Pass 2: Checking directory structure
3331 Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
3333 Directory inode 11858, block 0, offset 0: directory corrupted
3336 Missing '.' in directory inode 11858.
3339 Missing '..' in directory inode 11858.
3342 Untested (4127) [100fe44c]: trap_kern.c line 31
3348 I need to get the signal thread to detach from pid 4127 so that I can
3349 attach to it with gdb. This is done by sending it a SIGUSR1, which is
3350 caught by the signal thread, which detaches the process::
3359 Now I can run gdb on it::
3362 ~/linux/2.3.26/um 1034: gdb linux
3363 GNU gdb 4.17.0.11 with Linux support
3364 Copyright 1998 Free Software Foundation, Inc.
3365 GDB is free software, covered by the GNU General Public License, and you are
3366 welcome to change it and/or distribute copies of it under certain conditions.
3367 Type "show copying" to see the conditions.
3368 There is absolutely no warranty for GDB. Type "show warranty" for details.
3369 This GDB was configured as "i386-redhat-linux"...
3371 Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
3372 0x10075891 in __libc_nanosleep ()
3378 The backtrace shows that it was in a write and that the fault address
3379 (address in frame 3) is 0x50000800, which is right in the middle of
3380 the signal thread's stack page::
3384 #0 0x10075891 in __libc_nanosleep ()
3385 #1 0x1007584d in __sleep (seconds=1000000)
3386 at ../sysdeps/unix/sysv/linux/sleep.c:78
3387 #2 0x1006ce9a in stop () at user_util.c:191
3388 #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
3389 #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
3390 #5 0x1006c63c in kern_segv_handler (sig=11) at trap_user.c:182
3391 #6 <signal handler called>
3393 #8 0x10016647 in sys_write (fd=3, buf=0x80b8800 "R.", count=1024)
3395 #9 0x1006d603 in execute_syscall (syscall=4, args=0x5006ef08)
3396 at syscall_kern.c:254
3397 #10 0x1006af87 in really_do_syscall (sig=12) at syscall_user.c:35
3398 #11 <signal handler called>
3399 #12 0x400dc8b0 in ?? ()
3400 #13 <signal handler called>
3401 #14 0x400dc8b0 in ?? ()
3402 #15 0x80545fd in ?? ()
3403 #16 0x804daae in ?? ()
3404 #17 0x8054334 in ?? ()
3405 #18 0x804d23e in ?? ()
3406 #19 0x8049632 in ?? ()
3407 #20 0x80491d2 in ?? ()
3408 #21 0x80596b5 in ?? ()
3409 (gdb) p (void *)1342179328
3410 $3 = (void *) 0x50000800
3414 Going up the stack to the segv_handler frame and looking at where in
3415 the code the access happened shows that it happened near line 110 of
3421 #1 0x1007584d in __sleep (seconds=1000000)
3422 at ../sysdeps/unix/sysv/linux/sleep.c:78
3423 ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
3425 #2 0x1006ce9a in stop () at user_util.c:191
3426 191 while(1) sleep(1000000);
3428 #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
3431 #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
3432 174 segv(sc->cr2, sc->err & 2);
3434 $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
3435 __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
3436 esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
3437 err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
3438 esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
3440 (gdb) p (void *)268550834
3441 $2 = (void *) 0x1001c2b2
3443 block_write + 1090 in section .text
3445 Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
3446 starts at address 0x1001c2a1 <block_write+1073>
3447 and ends at 0x1001c2bf <block_write+1103>.
3448 (gdb) i line *0x1001c2c0
3449 Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
3450 and ends at 0x1001c2e3 <block_write+1139>.
3454 Looking at the source shows that the fault happened during a call to
3455 copy_from_user to copy the data into the kernel::
3459 108 copy_from_user(p,buf,chars);
3465 p is the pointer which must contain 0x50000800, since buf contains
3466 0x80b8800 (frame 8 above). It is defined as::
3469 p = offset + bh->b_data;
3475 I need to figure out what bh is, and it just so happens that bh is
3476 passed as an argument to mark_buffer_uptodate and mark_buffer_dirty a
3477 few lines later, so I do a little disassembly::
3480 (gdb) disas 0x1001c2bf 0x1001c2e0
3481 Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
3482 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
3483 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
3484 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
3485 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
3486 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
3487 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
3488 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
3489 0x1001c2d8 <block_write+1128>: pushl $0x0
3490 0x1001c2da <block_write+1130>: pushl %edx
3491 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
3492 End of assembler dump.
3498 At that point, bh is in %edx (address 0x1001c2da), which is calculated
3499 at 0x1001c2c2 as %ebp + 0xfffffdd4, so I figure exactly what that is,
3500 taking %ebp from the sigcontext_struct above::
3503 (gdb) p (void *)1342631484
3504 $5 = (void *) 0x5006ee3c
3505 (gdb) p 0x5006ee3c+0xfffffdd4
3508 $7 = (void *) 0x5006ec10
3509 (gdb) p *((void **)$7)
3510 $8 = (void *) 0x50100200
3516 Now, I look at the structure to see what's in it, and particularly,
3517 what its b_data field contains::
3520 (gdb) p *((struct buffer_head *)0x50100200)
3521 $13 = {b_next = 0x50289380, b_blocknr = 49405, b_size = 1024, b_list = 0,
3522 b_dev = 15872, b_count = {counter = 1}, b_rdev = 15872, b_state = 24,
3523 b_flushtime = 0, b_next_free = 0x501001a0, b_prev_free = 0x50100260,
3524 b_this_page = 0x501001a0, b_reqnext = 0x0, b_pprev = 0x507fcf58,
3525 b_data = 0x50000800 "", b_page = 0x50004000,
3526 b_end_io = 0x10017f60 <end_buffer_io_sync>, b_dev_id = 0x0,
3527 b_rsector = 98810, b_wait = {lock = <optimized out or zero length>,
3528 task_list = {next = 0x50100248, prev = 0x50100248}, __magic = 1343226448,
3529 __creator = 0}, b_kiobuf = 0x0}
3535 The b_data field is indeed 0x50000800, so the question becomes how
3536 that happened. The rest of the structure looks fine, so this probably
3537 is not a case of data corruption. It happened on purpose somehow.
3540 The b_page field is a pointer to the page_struct representing the
3541 0x50000000 page. Looking at it shows the kernel's idea of the state
3547 $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
3548 index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
3549 next = 0x50008460, prev = 0x50019350}, wait = {
3550 lock = <optimized out or zero length>, task_list = {next = 0x50004024,
3551 prev = 0x50004024}, __magic = 1342193708, __creator = 0},
3552 pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
3559 Some sanity-checking: the virtual field shows the "virtual" address of
3560 this page, which in this kernel is the same as its "physical" address,
3561 and the page_struct itself should be mem_map[0], since it represents
3562 the first page of memory::
3566 (gdb) p (void *)1342177280
3567 $18 = (void *) 0x50000000
3569 $19 = (mem_map_t *) 0x50004000
3575 These check out fine.
3578 Now to check out the page_struct itself. In particular, the flags
3579 field shows whether the page is considered free or not::
3589 The "reserved" bit is the high bit, which is definitely not set, so
3590 the kernel considers the signal stack page to be free and available to
3594 At this point, I jump to conclusions and start looking at my early
3595 boot code, because that's where that page is supposed to be reserved.
3598 In my setup_arch procedure, I have the following code which looks just
3603 bootmap_size = init_bootmem(start_pfn, end_pfn - start_pfn);
3604 free_bootmem(__pa(low_physmem) + bootmap_size, high_physmem - low_physmem);
3610 Two stack pages have already been allocated, and low_physmem points to
3611 the third page, which is the beginning of free memory.
3612 The init_bootmem call declares the entire memory to the boot memory
3613 manager, which marks it all reserved. The free_bootmem call frees up
3614 all of it, except for the first two pages. This looks correct to me.
3617 So, I decide to see init_bootmem run and make sure that it is marking
3618 those first two pages as reserved. I never get that far.
3621 Stepping into init_bootmem, and looking at bootmem_map before looking
3622 at what it contains shows the following::
3627 $3 = (void *) 0x50000000
3633 Aha! The light dawns. That first page is doing double duty as a
3634 stack and as the boot memory map. The last thing that the boot memory
3635 manager does is to free the pages used by its memory map, so this page
3636 is getting freed even its marked as reserved.
3639 The fix was to initialize the boot memory manager before allocating
3640 those two stack pages, and then allocate them through the boot memory
3641 manager. After doing this, and fixing a couple of subsequent buglets,
3642 the stack corruption problem disappeared.
3648 13. What to do when UML doesn't work
3649 =====================================
3654 13.1. Strange compilation errors when you build from source
3655 ------------------------------------------------------------
3657 As of test11, it is necessary to have "ARCH=um" in the environment or
3658 on the make command line for all steps in building UML, including
3659 clean, distclean, or mrproper, config, menuconfig, or xconfig, dep,
3660 and linux. If you forget for any of them, the i386 build seems to
3661 contaminate the UML build. If this happens, start from scratch with::
3665 make mrproper ARCH=um
3670 and repeat the build process with ARCH=um on all the steps.
3673 See :ref:`Compiling_the_kernel_and_modules` for more details.
3676 Another cause of strange compilation errors is building UML in
3677 /usr/src/linux. If you do this, the first thing you need to do is
3678 clean up the mess you made. The /usr/src/linux/asm link will now
3679 point to /usr/src/linux/asm-um. Make it point back to
3680 /usr/src/linux/asm-i386. Then, move your UML pool someplace else and
3681 build it there. Also see below, where a more specific set of symptoms
3686 13.3. A variety of panics and hangs with /tmp on a reiserfs filesystem
3687 -----------------------------------------------------------------------
3689 I saw this on reiserfs 3.5.21 and it seems to be fixed in 3.5.27.
3690 Panics preceded by::
3697 are diagnostic of this problem. This is a reiserfs bug which causes a
3698 thread to occasionally read stale data from a mmapped page shared with
3699 another thread. The fix is to upgrade the filesystem or to have /tmp
3700 be an ext2 filesystem.
3704 13.4. The compile fails with errors about conflicting types for
3705 'open', 'dup', and 'waitpid'
3707 This happens when you build in /usr/src/linux. The UML build makes
3708 the include/asm link point to include/asm-um. /usr/include/asm points
3709 to /usr/src/linux/include/asm, so when that link gets moved, files
3710 which need to include the asm-i386 versions of headers get the
3711 incompatible asm-um versions. The fix is to move the include/asm link
3712 back to include/asm-i386 and to do UML builds someplace else.
3716 13.5. UML doesn't work when /tmp is an NFS filesystem
3717 ------------------------------------------------------
3719 This seems to be a similar situation with the ReiserFS problem above.
3720 Some versions of NFS seems not to handle mmap correctly, which UML
3721 depends on. The workaround is have /tmp be a non-NFS directory.
3724 13.6. UML hangs on boot when compiled with gprof support
3725 ---------------------------------------------------------
3727 If you build UML with gprof support and, early in the boot, it does
3731 kernel BUG at page_alloc.c:100!
3736 you have a buggy gcc. You can work around the problem by removing
3737 UM_FASTCALL from CFLAGS in arch/um/Makefile-i386. This will open up
3738 another bug, but that one is fairly hard to reproduce.
3742 13.7. syslogd dies with a SIGTERM on startup
3743 ---------------------------------------------
3745 The exact boot error depends on the distribution that you're booting,
3746 but Debian produces this::
3749 /etc/rc2.d/S10sysklogd: line 49: 93 Terminated
3750 start-stop-daemon --start --quiet --exec /sbin/syslogd -- $SYSLOGD
3755 This is a syslogd bug. There's a race between a parent process
3756 installing a signal handler and its child sending the signal. See
3757 this uml-devel post <http://www.geocrawler.com/lists/3/Source-
3758 Forge/709/0/6612801> for the details.
3762 13.8. TUN/TAP networking doesn't work on a 2.4 host
3763 ----------------------------------------------------
3765 There are a couple of problems which were
3766 <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
3767 out"> by Tim Robinson <timro at trkr dot net>
3769 - It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
3770 The fix is to upgrade to something more recent and then read the
3776 File descriptor in bad state
3780 when you bring up the device inside UML, you have a header mismatch
3781 between the original kernel and the upgraded one. Make /usr/src/linux
3782 point at the new headers. This will only be a problem if you build
3787 13.9. You can network to the host but not to other machines on the net
3788 =======================================================================
3790 If you can connect to the host, and the host can connect to UML, but
3791 you cannot connect to any other machines, then you may need to enable
3792 IP Masquerading on the host. Usually this is only experienced when
3793 using private IP addresses (192.168.x.x or 10.x.x.x) for host/UML
3794 networking, rather than the public address space that your host is
3795 connected to. UML does not enable IP Masquerading, so you will need
3796 to create a static rule to enable it::
3800 iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
3805 Replace eth0 with the interface that you use to talk to the rest of
3809 Documentation on IP Masquerading, and SNAT, can be found at
3810 www.netfilter.org <http://www.netfilter.org> .
3813 If you can reach the local net, but not the outside Internet, then
3814 that is usually a routing problem. The UML needs a default route::
3818 route add default gw gateway IP
3823 The gateway IP can be any machine on the local net that knows how to
3824 reach the outside world. Usually, this is the host or the local net-
3828 Occasionally, we hear from someone who can reach some machines, but
3829 not others on the same net, or who can reach some ports on other
3830 machines, but not others. These are usually caused by strange
3831 firewalling somewhere between the UML and the other box. You track
3832 this down by running tcpdump on every interface the packets travel
3833 over and see where they disappear. When you find a machine that takes
3834 the packets in, but does not send them onward, that's the culprit.
3838 13.10. I have no root and I want to scream
3839 ===========================================
3841 Thanks to Birgit Wahlich for telling me about this strange one. It
3842 turns out that there's a limit of six environment variables on the
3843 kernel command line. When that limit is reached or exceeded, argument
3844 processing stops, which means that the 'root=' argument that UML
3845 usually adds is not seen. So, the filesystem has no idea what the
3846 root device is, so it panics.
3849 The fix is to put less stuff on the command line. Glomming all your
3850 setup variables into one is probably the best way to go.
3854 13.11. UML build conflict between ptrace.h and ucontext.h
3855 ==========================================================
3857 On some older systems, /usr/include/asm/ptrace.h and
3858 /usr/include/sys/ucontext.h define the same names. So, when they're
3859 included together, the defines from one completely mess up the parsing
3860 of the other, producing errors like::
3862 /usr/include/sys/ucontext.h:47: parse error before
3868 plus a pile of warnings.
3871 This is a libc botch, which has since been fixed, and I don't see any
3872 way around it besides upgrading.
3876 13.12. The UML BogoMips is exactly half the host's BogoMips
3877 ------------------------------------------------------------
3879 On i386 kernels, there are two ways of running the loop that is used
3880 to calculate the BogoMips rating, using the TSC if it's there or using
3881 a one-instruction loop. The TSC produces twice the BogoMips as the
3882 loop. UML uses the loop, since it has nothing resembling a TSC, and
3883 will get almost exactly the same BogoMips as a host using the loop.
3884 However, on a host with a TSC, its BogoMips will be double the loop
3885 BogoMips, and therefore double the UML BogoMips.
3889 13.13. When you run UML, it immediately segfaults
3890 --------------------------------------------------
3892 If the host is configured with the 2G/2G address space split, that's
3893 why. See ref:`UML_on_2G/2G_hosts` for the details on getting UML to
3898 13.14. xterms appear, then immediately disappear
3899 -------------------------------------------------
3901 If you're running an up to date kernel with an old release of
3902 uml_utilities, the port-helper program will not work properly, so
3903 xterms will exit straight after they appear. The solution is to
3904 upgrade to the latest release of uml_utilities. Usually this problem
3905 occurs when you have installed a packaged release of UML then compiled
3906 your own development kernel without upgrading the uml_utilities from
3907 the source distribution.
3911 13.15. Any other panic, hang, or strange behavior
3912 --------------------------------------------------
3914 If you're seeing truly strange behavior, such as hangs or panics that
3915 happen in random places, or you try running the debugger to see what's
3916 happening and it acts strangely, then it could be a problem in the
3917 host kernel. If you're not running a stock Linus or -ac kernel, then
3918 try that. An early version of the preemption patch and a 2.4.10 SuSE
3919 kernel have caused very strange problems in UML.
3922 Otherwise, let me know about it. Send a message to one of the UML
3923 mailing lists - either the developer list - user-mode-linux-devel at
3924 lists dot sourceforge dot net (subscription info) or the user list -
3925 user-mode-linux-user at lists dot sourceforge do net (subscription
3926 info), whichever you prefer. Don't assume that everyone knows about
3927 it and that a fix is imminent.
3930 If you want to be super-helpful, read :ref:`Diagnosing_Problems` and
3931 follow the instructions contained therein.
3933 .. _Diagnosing_Problems:
3935 14. Diagnosing Problems
3936 ========================
3939 If you get UML to crash, hang, or otherwise misbehave, you should
3940 report this on one of the project mailing lists, either the developer
3941 list - user-mode-linux-devel at lists dot sourceforge dot net
3942 (subscription info) or the user list - user-mode-linux-user at lists
3943 dot sourceforge dot net (subscription info). When you do, it is
3944 likely that I will want more information. So, it would be helpful to
3945 read the stuff below, do whatever is applicable in your case, and
3946 report the results to the list.
3949 For any diagnosis, you're going to need to build a debugging kernel.
3950 The binaries from this site aren't debuggable. If you haven't done
3951 this before, read about :ref:`Compiling_the_kernel_and_modules` and
3952 :ref:`Kernel_debugging` UML first.
3955 14.1. Case 1 : Normal kernel panics
3956 ------------------------------------
3958 The most common case is for a normal thread to panic. To debug this,
3959 you will need to run it under the debugger (add 'debug' to the command
3960 line). An xterm will start up with gdb running inside it. Continue
3961 it when it stops in start_kernel and make it crash. Now ``^C gdb`` and
3964 If the panic was a "Kernel mode fault", then there will be a segv
3965 frame on the stack and I'm going to want some more information. The
3966 stack might look something like this::
3970 #0 0x1009bf76 in __sigprocmask (how=1, set=0x5f347940, oset=0x0)
3971 at ../sysdeps/unix/sysv/linux/sigprocmask.c:49
3972 #1 0x10091411 in change_sig (signal=10, on=1) at process.c:218
3973 #2 0x10094785 in timer_handler (sig=26) at time_kern.c:32
3974 #3 0x1009bf38 in __restore ()
3975 at ../sysdeps/unix/sysv/linux/i386/sigaction.c:125
3976 #4 0x1009534c in segv (address=8, ip=268849158, is_write=2, is_user=0)
3978 #5 0x10095c04 in segv_handler (sig=11) at trap_user.c:285
3979 #6 0x1009bf38 in __restore ()
3984 I'm going to want to see the symbol and line information for the value
3985 of ip in the segv frame. In this case, you would do the following::
3988 (UML gdb) i sym 268849158
3996 (UML gdb) i line *268849158
4001 The reason for this is the __restore frame right above the segv_han-
4002 dler frame is hiding the frame that actually segfaulted. So, I have
4003 to get that information from the faulting ip.
4006 14.2. Case 2 : Tracing thread panics
4007 -------------------------------------
4009 The less common and more painful case is when the tracing thread
4010 panics. In this case, the kernel debugger will be useless because it
4011 needs a healthy tracing thread in order to work. The first thing to
4012 do is get a backtrace from the tracing thread. This is done by
4013 figuring out what its pid is, firing up gdb, and attaching it to that
4014 pid. You can figure out the tracing thread pid by looking at the
4015 first line of the console output, which will look like this::
4018 tracing thread pid = 15851
4023 or by running ps on the host and finding the line that looks like
4027 jdike 15851 4.5 0.4 132568 1104 pts/0 S 21:34 0:05 ./linux [(tracing thread)]
4032 If the panic was 'segfault in signals', then follow the instructions
4033 above for collecting information about the location of the seg fault.
4036 If the tracing thread flaked out all by itself, then send that
4037 backtrace in and wait for our crack debugging team to fix the problem.
4040 14.3. Case 3 : Tracing thread panics caused by other threads
4042 However, there are cases where the misbehavior of another thread
4043 caused the problem. The most common panic of this type is::
4046 wait_for_stop failed to wait for <pid> to stop with <signal number>
4051 In this case, you'll need to get a backtrace from the process men-
4052 tioned in the panic, which is complicated by the fact that the kernel
4053 debugger is defunct and without some fancy footwork, another gdb can't
4054 attach to it. So, this is how the fancy footwork goes:
4059 host% kill -STOP pid
4064 Run gdb on the tracing thread as described in case 2 and do::
4067 (host gdb) call detach(pid)
4070 If you get a segfault, do it again. It always works the second time.
4072 Detach from the tracing thread and attach to that other thread::
4082 (host gdb) attach pid
4087 If gdb hangs when attaching to that process, go back to a shell and
4097 And then get the backtrace::
4100 (host gdb) backtrace
4106 14.4. Case 4 : Hangs
4107 ---------------------
4109 Hangs seem to be fairly rare, but they sometimes happen. When a hang
4110 happens, we need a backtrace from the offending process. Run the
4111 kernel debugger as described in case 1 and get a backtrace. If the
4112 current process is not the idle thread, then send in the backtrace.
4113 You can tell that it's the idle thread if the stack looks like this::
4116 #0 0x100b1401 in __libc_nanosleep ()
4117 #1 0x100a2885 in idle_sleep (secs=10) at time.c:122
4118 #2 0x100a546f in do_idle () at process_kern.c:445
4119 #3 0x100a5508 in cpu_idle () at process_kern.c:471
4120 #4 0x100ec18f in start_kernel () at init/main.c:592
4121 #5 0x100a3e10 in start_kernel_proc (unused=0x0) at um_arch.c:71
4122 #6 0x100a383f in signal_tramp (arg=0x100a3dd8) at trap_user.c:50
4127 If this is the case, then some other process is at fault, and went to
4128 sleep when it shouldn't have. Run ps on the host and figure out which
4129 process should not have gone to sleep and stayed asleep. Then attach
4130 to it with gdb and get a backtrace as described in case 3.
4141 A number of people have helped this project in various ways, and this
4142 page gives recognition where recognition is due.
4145 If you're listed here and you would prefer a real link on your name,
4146 or no link at all, instead of the despammed email address pseudo-link,
4150 If you're not listed here and you think maybe you should be, please
4151 let me know that as well. I try to get everyone, but sometimes my
4152 bookkeeping lapses and I forget about contributions.
4155 15.1. Code and Documentation
4156 -----------------------------
4158 Rusty Russell <rusty at linuxcare.com.au> -
4160 - wrote the HOWTO <http://user-mode-
4161 linux.sourceforge.net/UserModeLinux-HOWTO.html>
4163 - prodded me into making this project official and putting it on
4166 - came up with the way cool UML logo <http://user-mode-
4167 linux.sourceforge.net/uml-small.png>
4169 - redid the config process
4172 Peter Moulder <reiter at netspace.net.au> - Fixed my config and build
4173 processes, and added some useful code to the block driver
4176 Bill Stearns <wstearns at pobox.com> -
4180 - lots of bug reports
4184 - dedicated a box (uml.ists.dartmouth.edu) to support UML development
4186 - wrote the mkrootfs script, which allows bootable filesystems of
4187 RPM-based distributions to be cranked out
4189 - cranked out a large number of filesystems with said script
4192 Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
4193 and associated usermode tools
4195 Lars Brinkhoff <http://lars.nocrew.org/> - Contributed the ptrace
4196 proxy from his own project <http://a386.nocrew.org/> to allow easier
4200 Andrea Arcangeli <andrea at suse.de> - Redid some of the early boot
4201 code so that it would work on machines with Large File Support
4204 Chris Emerson <http://www.chiark.greenend.org.uk/~cemerson/> - Did
4205 the first UML port to Linux/ppc
4208 Harald Welte <laforge at gnumonks.org> - Wrote the multicast
4209 transport for the network driver
4212 Jorgen Cederlof - Added special file support to hostfs
4215 Greg Lonnon <glonnon at ridgerun dot com> - Changed the ubd driver
4216 to allow it to layer a COW file on a shared read-only filesystem and
4217 wrote the iomem emulation support
4220 Henrik Nordstrom <http://hem.passagen.se/hno/> - Provided a variety
4221 of patches, fixes, and clues
4224 Lennert Buytenhek - Contributed various patches, a rewrite of the
4225 network driver, the first implementation of the mconsole driver, and
4226 did the bulk of the work needed to get SMP working again.
4229 Yon Uriarte - Fixed the TUN/TAP network backend while I slept.
4232 Adam Heath - Made a bunch of nice cleanups to the initialization code,
4233 plus various other small patches.
4236 Matt Zimmerman - Matt volunteered to be the UML Debian maintainer and
4237 is doing a real nice job of it. He also noticed and fixed a number of
4238 actually and potentially exploitable security holes in uml_net. Plus
4239 the occasional patch. I like patches.
4242 James McMechan - James seems to have taken over maintenance of the ubd
4243 driver and is doing a nice job of it.
4246 Chandan Kudige - wrote the umlgdb script which automates the reloading
4250 Steve Schmidtke - wrote the UML slirp transport and hostaudio drivers,
4251 enabling UML processes to access audio devices on the host. He also
4252 submitted patches for the slip transport and lots of other things.
4255 David Coulson <http://davidcoulson.net> -
4257 - Set up the usermodelinux.org <http://usermodelinux.org> site,
4258 which is a great way of keeping the UML user community on top of
4261 - Site documentation and updates
4263 - Nifty little UML management daemon UMLd
4264 <http://uml.openconsultancy.com/umld/>
4266 - Lots of testing and bug reports
4271 15.2. Flushing out bugs
4272 ------------------------
4294 - Rainer Burgstaller
4308 - Frank Klingenhoefer
4310 - Livio Baldini Soares
4328 - Lorenzo Allegrucci
4351 15.3. Buglets and clean-ups
4352 ----------------------------
4425 - Michael Richardson
4429 15.5. Other contributions
4430 --------------------------
4433 Bill Carr <Bill.Carr at compaq.com> made the Red Hat mkrootfs script
4436 Michael Jennings <mikejen at hevanet.com> sent in some material which
4437 is now gracing the top of the index page <http://user-mode-
4438 linux.sourceforge.net/> of this site.
4440 SGI <http://www.sgi.com> (and more specifically Ralf Baechle <ralf at
4441 uni-koblenz.de> ) gave me an account on oss.sgi.com
4442 <http://www.oss.sgi.com> . The bandwidth there made it possible to
4443 produce most of the filesystems available on the project download
4446 Laurent Bonnaud <Laurent.Bonnaud at inpg.fr> took the old grotty
4447 Debian filesystem that I've been distributing and updated it to 2.2.
4448 It is now available by itself here.
4450 Rik van Riel gave me some ftp space on ftp.nl.linux.org so I can make
4451 releases even when Sourceforge is broken.
4453 Rodrigo de Castro looked at my broken pte code and told me what was
4454 wrong with it, letting me fix a long-standing (several weeks) and
4455 serious set of bugs.
4457 Chris Reahard built a specialized root filesystem for running a DNS
4458 server jailed inside UML. It's available from the download
4459 <http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
4460 Filesystems section.