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