UserModeLinux-HOWTO.txt 117 KB
Newer Older
Linus Torvalds's avatar
Linus Torvalds committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
  User Mode Linux HOWTO
  User Mode Linux Core Team
  Mon Nov 18 14:16:16 EST 2002

  This document describes the use and abuse of Jeff Dike's User Mode
  Linux: a port of the Linux kernel as a normal Intel Linux process.
  ______________________________________________________________________

  Table of Contents

  1. Introduction

     1.1 How is User Mode Linux Different?
     1.2 Why Would I Want User Mode Linux?

  2. Compiling the kernel and modules

     2.1 Compiling the kernel
     2.2 Compiling and installing kernel modules
     2.3 Compiling and installing uml_utilities

  3. Running UML and logging in

     3.1 Running UML
     3.2 Logging in
     3.3 Examples

  4. UML on 2G/2G hosts

     4.1 Introduction
     4.2 The problem
     4.3 The solution

  5. Setting up serial lines and consoles

     5.1 Specifying the device
     5.2 Specifying the channel
     5.3 Examples

  6. Setting up the network

     6.1 General setup
     6.2 Userspace daemons
     6.3 Specifying ethernet addresses
     6.4 UML interface setup
     6.5 Multicast
     6.6 TUN/TAP with the uml_net helper
     6.7 TUN/TAP with a preconfigured tap device
     6.8 Ethertap
     6.9 The switch daemon
     6.10 Slip
     6.11 Slirp
     6.12 pcap
     6.13 Setting up the host yourself

  7. Sharing Filesystems between Virtual Machines

     7.1 A warning
     7.2 Using layered block devices
     7.3 Note!
     7.4 Another warning
     7.5 uml_moo : Merging a COW file with its backing file

  8. Creating filesystems

     8.1 Create the filesystem file
     8.2 Assign the file to a UML device
     8.3 Creating and mounting the filesystem

  9. Host file access

     9.1 Using hostfs
     9.2 hostfs as the root filesystem
     9.3 Building hostfs

  10. The Management Console
     10.1 version
     10.2 halt and reboot
     10.3 config
     10.4 remove
     10.5 sysrq
     10.6 help
     10.7 cad
     10.8 stop
     10.9 go

  11. Kernel debugging

     11.1 Starting the kernel under gdb
     11.2 Examining sleeping processes
     11.3 Running ddd on UML
     11.4 Debugging modules
     11.5 Attaching gdb to the kernel
     11.6 Using alternate debuggers

  12. Kernel debugging examples

     12.1 The case of the hung fsck
     12.2 Episode 2: The case of the hung fsck

  13. What to do when UML doesn't work

     13.1 Strange compilation errors when you build from source
104
     13.2 (obsolete)
Linus Torvalds's avatar
Linus Torvalds committed
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
     13.3 A variety of panics and hangs with /tmp on a reiserfs  filesystem
     13.4 The compile fails with errors about conflicting types for 'open', 'dup', and 'waitpid'
     13.5 UML doesn't work when /tmp is an NFS filesystem
     13.6 UML hangs on boot when compiled with gprof support
     13.7 syslogd dies with a SIGTERM on startup
     13.8 TUN/TAP networking doesn't work on a 2.4 host
     13.9 You can network to the host but not to other machines on the net
     13.10 I have no root and I want to scream
     13.11 UML build conflict between ptrace.h and ucontext.h
     13.12 The UML BogoMips is exactly half the host's BogoMips
     13.13 When you run UML, it immediately segfaults
     13.14 xterms appear, then immediately disappear
     13.15 Any other panic, hang, or strange behavior

  14. Diagnosing Problems

     14.1 Case 1 : Normal kernel panics
     14.2 Case 2 : Tracing thread panics
     14.3 Case 3 : Tracing thread panics caused by other threads
     14.4 Case 4 : Hangs

  15. Thanks

     15.1 Code and Documentation
     15.2 Flushing out bugs
     15.3 Buglets and clean-ups
     15.4 Case Studies
     15.5 Other contributions


  ______________________________________________________________________

137
  1.  Introduction
Linus Torvalds's avatar
Linus Torvalds committed
138 139 140 141 142

  Welcome to User Mode Linux.  It's going to be fun.



143
  1.1.  How is User Mode Linux Different?
Linus Torvalds's avatar
Linus Torvalds committed
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183

  Normally, the Linux Kernel talks straight to your hardware (video
  card, keyboard, hard drives, etc), and any programs which run ask the
  kernel to operate the hardware, like so:



         +-----------+-----------+----+
         | Process 1 | Process 2 | ...|
         +-----------+-----------+----+
         |       Linux Kernel         |
         +----------------------------+
         |         Hardware           |
         +----------------------------+




  The User Mode Linux Kernel is different; instead of talking to the
  hardware, it talks to a `real' Linux kernel (called the `host kernel'
  from now on), like any other program.  Programs can then run inside
  User-Mode Linux as if they were running under a normal kernel, like
  so:



                     +----------------+
                     | Process 2 | ...|
         +-----------+----------------+
         | Process 1 | User-Mode Linux|
         +----------------------------+
         |       Linux Kernel         |
         +----------------------------+
         |         Hardware           |
         +----------------------------+





184
  1.2.  Why Would I Want User Mode Linux?
Linus Torvalds's avatar
Linus Torvalds committed
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208


  1. If User Mode Linux crashes, your host kernel is still fine.

  2. You can run a usermode kernel as a non-root user.

  3. You can debug the User Mode Linux like any normal process.

  4. You can run gprof (profiling) and gcov (coverage testing).

  5. You can play with your kernel without breaking things.

  6. You can use it as a sandbox for testing new apps.

  7. You can try new development kernels safely.

  8. You can run different distributions simultaneously.

  9. It's extremely fun.





209
  2.  Compiling the kernel and modules
Linus Torvalds's avatar
Linus Torvalds committed
210 211 212 213




214
  2.1.  Compiling the kernel
Linus Torvalds's avatar
Linus Torvalds committed
215 216 217 218 219 220 221 222 223


  Compiling the user mode kernel is just like compiling any other
  kernel.  Let's go through the steps, using 2.4.0-prerelease (current
  as of this writing) as an example:


  1. Download the latest UML patch from

224
     the download page <http://user-mode-linux.sourceforge.net/
Linus Torvalds's avatar
Linus Torvalds committed
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324

     In this example, the file is uml-patch-2.4.0-prerelease.bz2.


  2. Download the matching kernel from your favourite kernel mirror,
     such as:

     ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
     <ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2>
     .


  3. Make a directory and unpack the kernel into it.



       host%
       mkdir ~/uml






       host%
       cd ~/uml






       host%
       tar -xzvf linux-2.4.0-prerelease.tar.bz2






  4. Apply the patch using



       host%
       cd ~/uml/linux



       host%
       bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1






  5. Run your favorite config; `make xconfig ARCH=um' is the most
     convenient.  `make config ARCH=um' and 'make menuconfig ARCH=um'
     will work as well.  The defaults will give you a useful kernel.  If
     you want to change something, go ahead, it probably won't hurt
     anything.


     Note:  If the host is configured with a 2G/2G address space split
     rather than the usual 3G/1G split, then the packaged UML binaries
     will not run.  They will immediately segfault.  See ``UML on 2G/2G
     hosts''  for the scoop on running UML on your system.



  6. Finish with `make linux ARCH=um': the result is a file called
     `linux' in the top directory of your source tree.

  Make sure that you don't build this kernel in /usr/src/linux.  On some
  distributions, /usr/include/asm is a link into this pool.  The user-
  mode build changes the other end of that link, and things that include
  <asm/anything.h> stop compiling.

  The sources are also available from cvs at the project's cvs page,
  which has directions on getting the sources. You can also browse the
  CVS pool from there.

  If you get the CVS sources, you will have to check them out into an
  empty directory. You will then have to copy each file into the
  corresponding directory in the appropriate kernel pool.

  If you don't have the latest kernel pool, you can get the
  corresponding user-mode sources with


       host% cvs co -r v_2_3_x linux




  where 'x' is the version in your pool. Note that you will not get the
  bug fixes and enhancements that have gone into subsequent releases.


325
  2.2.  Compiling and installing kernel modules
Linus Torvalds's avatar
Linus Torvalds committed
326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383

  UML modules are built in the same way as the native kernel (with the
  exception of the 'ARCH=um' that you always need for UML):


       host% make modules ARCH=um




  Any modules that you want to load into this kernel need to be built in
  the user-mode pool.  Modules from the native kernel won't work.

  You can install them by using ftp or something to copy them into the
  virtual machine and dropping them into /lib/modules/`uname -r`.

  You can also get the kernel build process to install them as follows:

  1. with the kernel not booted, mount the root filesystem in the top
     level of the kernel pool:


       host% mount root_fs mnt -o loop






  2. run


       host%
       make modules_install INSTALL_MOD_PATH=`pwd`/mnt ARCH=um






  3. unmount the filesystem


       host% umount mnt






  4. boot the kernel on it


  When the system is booted, you can use insmod as usual to get the
  modules into the kernel.  A number of things have been loaded into UML
  as modules, especially filesystems and network protocols and filters,
  so most symbols which need to be exported probably already are.
  However, if you do find symbols that need exporting, let  us
384
  <http://user-mode-linux.sourceforge.net/>  know, and
Linus Torvalds's avatar
Linus Torvalds committed
385 386 387 388
  they'll be "taken care of".



389
  2.3.  Compiling and installing uml_utilities
Linus Torvalds's avatar
Linus Torvalds committed
390 391 392 393 394

  Many features of the UML kernel require a user-space helper program,
  so a uml_utilities package is distributed separately from the kernel
  patch which provides these helpers. Included within this is:

395
  o  port-helper - Used by consoles which connect to xterms or ports
Linus Torvalds's avatar
Linus Torvalds committed
396

397
  o  tunctl - Configuration tool to create and delete tap devices
Linus Torvalds's avatar
Linus Torvalds committed
398

399
  o  uml_net - Setuid binary for automatic tap device configuration
Linus Torvalds's avatar
Linus Torvalds committed
400

401
  o  uml_switch - User-space virtual switch required for daemon
Linus Torvalds's avatar
Linus Torvalds committed
402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425
     transport

     The uml_utilities tree is compiled with:


       host#
       make && make install




  Note that UML kernel patches may require a specific version of the
  uml_utilities distribution. If you don't keep up with the mailing
  lists, ensure that you have the latest release of uml_utilities if you
  are experiencing problems with your UML kernel, particularly when
  dealing with consoles or command-line switches to the helper programs








426
  3.  Running UML and logging in
Linus Torvalds's avatar
Linus Torvalds committed
427 428 429



430
  3.1.  Running UML
Linus Torvalds's avatar
Linus Torvalds committed
431 432 433 434 435 436 437 438 439 440 441 442 443

  It runs on 2.2.15 or later, and all 2.4 kernels.


  Booting UML is straightforward.  Simply run 'linux': it will try to
  mount the file `root_fs' in the current directory.  You do not need to
  run it as root.  If your root filesystem is not named `root_fs', then
  you need to put a `ubd0=root_fs_whatever' switch on the linux command
  line.


  You will need a filesystem to boot UML from.  There are a number
  available for download from  here  <http://user-mode-
444 445
  linux.sourceforge.net/> .  There are also  several tools
  <http://user-mode-linux.sourceforge.net/>  which can be
Linus Torvalds's avatar
Linus Torvalds committed
446 447 448 449 450 451 452 453 454 455 456
  used to generate UML-compatible filesystem images from media.
  The kernel will boot up and present you with a login prompt.


  Note:  If the host is configured with a 2G/2G address space split
  rather than the usual 3G/1G split, then the packaged UML binaries will
  not run.  They will immediately segfault.  See ``UML on 2G/2G hosts''
  for the scoop on running UML on your system.



457
  3.2.  Logging in
Linus Torvalds's avatar
Linus Torvalds committed
458 459 460 461 462 463 464 465 466 467 468 469 470



  The prepackaged filesystems have a root account with password 'root'
  and a user account with password 'user'.  The login banner will
  generally tell you how to log in.  So, you log in and you will find
  yourself inside a little virtual machine. Our filesystems have a
  variety of commands and utilities installed (and it is fairly easy to
  add more), so you will have a lot of tools with which to poke around
  the system.

  There are a couple of other ways to log in:

471
  o  On a virtual console
Linus Torvalds's avatar
Linus Torvalds committed
472 473 474 475 476 477 478 479 480 481 482



     Each virtual console that is configured (i.e. the device exists in
     /dev and /etc/inittab runs a getty on it) will come up in its own
     xterm.  If you get tired of the xterms, read ``Setting up serial
     lines and consoles''  to see how to attach the consoles to
     something else, like host ptys.



483
  o  Over the serial line
Linus Torvalds's avatar
Linus Torvalds committed
484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505


     In the boot output, find a line that looks like:



       serial line 0 assigned pty /dev/ptyp1




  Attach your favorite terminal program to the corresponding tty.  I.e.
  for minicom, the command would be


       host% minicom -o -p /dev/ttyp1






506
  o  Over the net
Linus Torvalds's avatar
Linus Torvalds committed
507 508 509 510 511 512 513 514 515 516


     If the network is running, then you can telnet to the virtual
     machine and log in to it.  See ``Setting up the network''  to learn
     about setting up a virtual network.

  When you're done using it, run halt, and the kernel will bring itself
  down and the process will exit.


517
  3.3.  Examples
Linus Torvalds's avatar
Linus Torvalds committed
518 519 520

  Here are some examples of UML in action:

521
  o  A login session <http://user-mode-linux.sourceforge.net/login.html>
Linus Torvalds's avatar
Linus Torvalds committed
522

523
  o  A virtual network <http://user-mode-linux.sourceforge.net/net.html>
Linus Torvalds's avatar
Linus Torvalds committed
524 525 526 527 528 529 530







531
  4.  UML on 2G/2G hosts
Linus Torvalds's avatar
Linus Torvalds committed
532 533 534 535




536
  4.1.  Introduction
Linus Torvalds's avatar
Linus Torvalds committed
537 538 539 540 541 542 543 544 545 546 547 548


  Most Linux machines are configured so that the kernel occupies the
  upper 1G (0xc0000000 - 0xffffffff) of the 4G address space and
  processes use the lower 3G (0x00000000 - 0xbfffffff).  However, some
  machine are configured with a 2G/2G split, with the kernel occupying
  the upper 2G (0x80000000 - 0xffffffff) and processes using the lower
  2G (0x00000000 - 0x7fffffff).




549
  4.2.  The problem
Linus Torvalds's avatar
Linus Torvalds committed
550 551 552 553 554 555 556 557 558 559 560


  The prebuilt UML binaries on this site will not run on 2G/2G hosts
  because UML occupies the upper .5G of the 3G process address space
  (0xa0000000 - 0xbfffffff).  Obviously, on 2G/2G hosts, this is right
  in the middle of the kernel address space, so UML won't even load - it
  will immediately segfault.




561
  4.3.  The solution
Linus Torvalds's avatar
Linus Torvalds committed
562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578


  The fix for this is to rebuild UML from source after enabling
  CONFIG_HOST_2G_2G (under 'General Setup').  This will cause UML to
  load itself in the top .5G of that smaller process address space,
  where it will run fine.  See ``Compiling the kernel and modules''  if
  you need help building UML from source.










579
  5.  Setting up serial lines and consoles
Linus Torvalds's avatar
Linus Torvalds committed
580 581 582 583 584 585 586 587 588


  It is possible to attach UML serial lines and consoles to many types
  of host I/O channels by specifying them on the command line.


  You can attach them to host ptys, ttys, file descriptors, and ports.
  This allows you to do things like

589
  o  have a UML console appear on an unused host console,
Linus Torvalds's avatar
Linus Torvalds committed
590

591
  o  hook two virtual machines together by having one attach to a pty
Linus Torvalds's avatar
Linus Torvalds committed
592 593
     and having the other attach to the corresponding tty

594
  o  make a virtual machine accessible from the net by attaching a
Linus Torvalds's avatar
Linus Torvalds committed
595 596 597 598 599 600 601
     console to a port on the host.


  The general format of the command line option is device=channel.



602
  5.1.  Specifying the device
Linus Torvalds's avatar
Linus Torvalds committed
603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628

  Devices are specified with "con" or "ssl" (console or serial line,
  respectively), optionally with a device number if you are talking
  about a specific device.


  Using just "con" or "ssl" describes all of the consoles or serial
  lines.  If you want to talk about console #3 or serial line #10, they
  would be "con3" and "ssl10", respectively.


  A specific device name will override a less general "con=" or "ssl=".
  So, for example, you can assign a pty to each of the serial lines
  except for the first two like this:


        ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1




  The specificity of the device name is all that matters; order on the
  command line is irrelevant.



629
  5.2.  Specifying the channel
Linus Torvalds's avatar
Linus Torvalds committed
630 631 632 633 634

  There are a number of different types of channels to attach a UML
  device to, each with a different way of specifying exactly what to
  attach to.

635
  o  pseudo-terminals - device=pty pts terminals - device=pts
Linus Torvalds's avatar
Linus Torvalds committed
636 637 638 639 640 641 642


     This will cause UML to allocate a free host pseudo-terminal for the
     device.  The terminal that it got will be announced in the boot
     log.  You access it by attaching a terminal program to the
     corresponding tty:

643
  o  screen /dev/pts/n
Linus Torvalds's avatar
Linus Torvalds committed
644

645
  o  screen /dev/ttyxx
Linus Torvalds's avatar
Linus Torvalds committed
646

647
  o  minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
Linus Torvalds's avatar
Linus Torvalds committed
648 649
     devices

650
  o  kermit - start it up, 'open' the device, then 'connect'
Linus Torvalds's avatar
Linus Torvalds committed
651 652 653 654 655





656
  o  terminals - device=tty:tty device file
Linus Torvalds's avatar
Linus Torvalds committed
657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674


     This will make UML attach the device to the specified tty (i.e


        con1=tty:/dev/tty3




  will attach UML's console 1 to the host's /dev/tty3).  If the tty that
  you specify is the slave end of a tty/pty pair, something else must
  have already opened the corresponding pty in order for this to work.





675
  o  xterms - device=xterm
Linus Torvalds's avatar
Linus Torvalds committed
676 677 678 679 680 681 682 683


     UML will run an xterm and the device will be attached to it.





684
  o  Port - device=port:port number
Linus Torvalds's avatar
Linus Torvalds committed
685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727


     This will attach the UML devices to the specified host port.
     Attaching console 1 to the host's port 9000 would be done like
     this:


        con1=port:9000




  Attaching all the serial lines to that port would be done similarly:


        ssl=port:9000




  You access these devices by telnetting to that port.  Each active tel-
  net session gets a different device.  If there are more telnets to a
  port than UML devices attached to it, then the extra telnet sessions
  will block until an existing telnet detaches, or until another device
  becomes active (i.e. by being activated in /etc/inittab).

  This channel has the advantage that you can both attach multiple UML
  devices to it and know how to access them without reading the UML boot
  log.  It is also unique in allowing access to a UML from remote
  machines without requiring that the UML be networked.  This could be
  useful in allowing public access to UMLs because they would be
  accessible from the net, but wouldn't need any kind of network
  filtering or access control because they would have no network access.


  If you attach the main console to a portal, then the UML boot will
  appear to hang.  In reality, it's waiting for a telnet to connect, at
  which point the boot will proceed.





728
  o  already-existing file descriptors - device=file descriptor
Linus Torvalds's avatar
Linus Torvalds committed
729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745


     If you set up a file descriptor on the UML command line, you can
     attach a UML device to it.  This is most commonly used to put the
     main console back on stdin and stdout after assigning all the other
     consoles to something else:


        con0=fd:0,fd:1 con=pts








746
  o  Nothing - device=null
Linus Torvalds's avatar
Linus Torvalds committed
747 748 749 750 751 752 753 754 755 756


     This allows the device to be opened, in contrast to 'none', but
     reads will block, and writes will succeed and the data will be
     thrown out.





757
  o  None - device=none
Linus Torvalds's avatar
Linus Torvalds committed
758 759


760
     This causes the device to disappear.
Linus Torvalds's avatar
Linus Torvalds committed
761 762 763 764 765 766 767 768 769 770 771 772



  You can also specify different input and output channels for a device
  by putting a comma between them:


        ssl3=tty:/dev/tty2,xterm




773
  will cause serial line 3 to accept input on the host's /dev/tty2 and
Linus Torvalds's avatar
Linus Torvalds committed
774 775 776 777 778 779 780 781 782 783 784 785 786 787
  display output on an xterm.  That's a silly example - the most common
  use of this syntax is to reattach the main console to stdin and stdout
  as shown above.


  If you decide to move the main console away from stdin/stdout, the
  initial boot output will appear in the terminal that you're running
  UML in.  However, once the console driver has been officially
  initialized, then the boot output will start appearing wherever you
  specified that console 0 should be.  That device will receive all
  subsequent output.



788
  5.3.  Examples
Linus Torvalds's avatar
Linus Torvalds committed
789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840

  There are a number of interesting things you can do with this
  capability.


  First, this is how you get rid of those bleeding console xterms by
  attaching them to host ptys:


        con=pty con0=fd:0,fd:1




  This will make a UML console take over an unused host virtual console,
  so that when you switch to it, you will see the UML login prompt
  rather than the host login prompt:


        con1=tty:/dev/tty6




  You can attach two virtual machines together with what amounts to a
  serial line as follows:

  Run one UML with a serial line attached to a pty -


        ssl1=pty




  Look at the boot log to see what pty it got (this example will assume
  that it got /dev/ptyp1).

  Boot the other UML with a serial line attached to the corresponding
  tty -


        ssl1=tty:/dev/ttyp1




  Log in, make sure that it has no getty on that serial line, attach a
  terminal program like minicom to it, and you should see the login
  prompt of the other virtual machine.


841
  6.  Setting up the network
Linus Torvalds's avatar
Linus Torvalds committed
842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860



  This page describes how to set up the various transports and to
  provide a UML instance with network access to the host, other machines
  on the local net, and the rest of the net.


  As of 2.4.5, UML networking has been completely redone to make it much
  easier to set up, fix bugs, and add new features.


  There is a new helper, uml_net, which does the host setup that
  requires root privileges.


  There are currently five transport types available for a UML virtual
  machine to exchange packets with other hosts:

861
  o  ethertap
Linus Torvalds's avatar
Linus Torvalds committed
862

863
  o  TUN/TAP
Linus Torvalds's avatar
Linus Torvalds committed
864

865
  o  Multicast
Linus Torvalds's avatar
Linus Torvalds committed
866

867
  o  a switch daemon
Linus Torvalds's avatar
Linus Torvalds committed
868

869
  o  slip
Linus Torvalds's avatar
Linus Torvalds committed
870

871
  o  slirp
Linus Torvalds's avatar
Linus Torvalds committed
872

873
  o  pcap
Linus Torvalds's avatar
Linus Torvalds committed
874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895

     The TUN/TAP, ethertap, slip, and slirp transports allow a UML
     instance to exchange packets with the host.  They may be directed
     to the host or the host may just act as a router to provide access
     to other physical or virtual machines.


  The pcap transport is a synthetic read-only interface, using the
  libpcap binary to collect packets from interfaces on the host and
  filter them.  This is useful for building preconfigured traffic
  monitors or sniffers.


  The daemon and multicast transports provide a completely virtual
  network to other virtual machines.  This network is completely
  disconnected from the physical network unless one of the virtual
  machines on it is acting as a gateway.


  With so many host transports, which one should you use?  Here's when
  you should use each one:

896
  o  ethertap - if you want access to the host networking and it is
Linus Torvalds's avatar
Linus Torvalds committed
897 898
     running 2.2

899
  o  TUN/TAP - if you want access to the host networking and it is
Linus Torvalds's avatar
Linus Torvalds committed
900 901 902 903
     running 2.4.  Also, the TUN/TAP transport is able to use a
     preconfigured device, allowing it to avoid using the setuid uml_net
     helper, which is a security advantage.

904
  o  Multicast - if you want a purely virtual network and you don't want
Linus Torvalds's avatar
Linus Torvalds committed
905 906
     to set up anything but the UML

907
  o  a switch daemon - if you want a purely virtual network and you
Linus Torvalds's avatar
Linus Torvalds committed
908 909 910
     don't mind running the daemon in order to get somewhat better
     performance

911
  o  slip - there is no particular reason to run the slip backend unless
Linus Torvalds's avatar
Linus Torvalds committed
912 913
     ethertap and TUN/TAP are just not available for some reason

914
  o  slirp - if you don't have root access on the host to setup
Linus Torvalds's avatar
Linus Torvalds committed
915 916
     networking, or if you don't want to allocate an IP to your UML

917
  o  pcap - not much use for actual network connectivity, but great for
Linus Torvalds's avatar
Linus Torvalds committed
918 919 920 921 922 923 924 925 926 927 928
     monitoring traffic on the host

     Ethertap is available on 2.4 and works fine.  TUN/TAP is preferred
     to it because it has better performance and ethertap is officially
     considered obsolete in 2.4.  Also, the root helper only needs to
     run occasionally for TUN/TAP, rather than handling every packet, as
     it does with ethertap.  This is a slight security advantage since
     it provides fewer opportunities for a nasty UML user to somehow
     exploit the helper's root privileges.


929
  6.1.  General setup
Linus Torvalds's avatar
Linus Torvalds committed
930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965

  First, you must have the virtual network enabled in your UML.  If are
  running a prebuilt kernel from this site, everything is already
  enabled.  If you build the kernel yourself, under the "Network device
  support" menu, enable "Network device support", and then the three
  transports.


  The next step is to provide a network device to the virtual machine.
  This is done by describing it on the kernel command line.

  The general format is


       eth <n> = <transport> , <transport args>




  For example, a virtual ethernet device may be attached to a host
  ethertap device as follows:


       eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254




  This sets up eth0 inside the virtual machine to attach itself to the
  host /dev/tap0, assigns it an ethernet address, and assigns the host
  tap0 interface an IP address.



  Note that the IP address you assign to the host end of the tap device
  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
Linus Torvalds's avatar
Linus Torvalds committed
967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997
  you can reuse the host's eth IP address for the host ends of the tap
  devices.  Internally, the UMLs must still get unique IPs for their eth
  devices.  You can also give the UMLs non-routable IPs (192.168.x.x or
  10.x.x.x) and have the host masquerade them.  This will let outgoing
  connections work, but incoming connections won't without more work,
  such as port forwarding from the host.
  Also note that when you configure the host side of an interface, it is
  only acting as a gateway.  It will respond to pings sent to it
  locally, but is not useful to do that since it's a host interface.
  You are not talking to the UML when you ping that interface and get a
  response.


  You can also add devices to a UML and remove them at runtime.  See the
  ``The Management Console''  page for details.


  The sections below describe this in more detail.


  Once you've decided how you're going to set up the devices, you boot
  UML, log in, configure the UML side of the devices, and set up routes
  to the outside world.  At that point, you will be able to talk to any
  other machines, physical or virtual, on the net.


  If ifconfig inside UML fails and the network refuses to come up, run
  tell you what went wrong.



998
  6.2.  Userspace daemons
Linus Torvalds's avatar
Linus Torvalds committed
999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013

  You will likely need the setuid helper, or the switch daemon, or both.
  They are both installed with the RPM and deb, so if you've installed
  either, you can skip the rest of this section.


  If not, then you need to check them out of CVS, build them, and
  install them.  The helper is uml_net, in CVS /tools/uml_net, and the
  daemon is uml_switch, in CVS /tools/uml_router.  They are both built
  with a plain 'make'.  Both need to be installed in a directory that's
  in your path - /usr/bin is recommend.  On top of that, uml_net needs
  to be setuid root.



1014
  6.3.  Specifying ethernet addresses
Linus Torvalds's avatar
Linus Torvalds committed
1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025

  Below, you will see that the TUN/TAP, ethertap, and daemon interfaces
  allow you to specify hardware addresses for the virtual ethernet
  devices.  This is generally not necessary.  If you don't have a
  specific reason to do it, you probably shouldn't.  If one is not
  specified on the command line, the driver will assign one based on the
  device IP address.  It will provide the address fe:fd:nn:nn:nn:nn
  where nn.nn.nn.nn is the device IP address.  This is nearly always
  sufficient to guarantee a unique hardware address for the device.  A
  couple of exceptions are:

1026
  o  Another set of virtual ethernet devices are on the same network and
Linus Torvalds's avatar
Linus Torvalds committed
1027 1028 1029
     they are assigned hardware addresses using a different scheme which
     may conflict with the UML IP address-based scheme

1030
  o  You aren't going to use the device for IP networking, so you don't
Linus Torvalds's avatar
Linus Torvalds committed
1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051
     assign the device an IP address

     If you let the driver provide the hardware address, you should make
     sure that the device IP address is known before the interface is
     brought up.  So, inside UML, this will guarantee that:



  UML#
  ifconfig eth0 192.168.0.250 up




  If you decide to assign the hardware address yourself, make sure that
  the first byte of the address is even.  Addresses with an odd first
  byte are broadcast addresses, which you don't want assigned to a
  device.



1052
  6.4.  UML interface setup
Linus Torvalds's avatar
Linus Torvalds committed
1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133

  Once the network devices have been described on the command line, you
  should boot UML and log in.


  The first thing to do is bring the interface up:


       UML# ifconfig ethn ip-address up




  You should be able to ping the host at this point.


  To reach the rest of the world, you should set a default route to the
  host:


       UML# route add default gw host ip




  Again, with host ip of 192.168.0.4:


       UML# route add default gw 192.168.0.4




  This page used to recommend setting a network route to your local net.
  This is wrong, because it will cause UML to try to figure out hardware
  addresses of the local machines by arping on the interface to the
  host.  Since that interface is basically a single strand of ethernet
  with two nodes on it (UML and the host) and arp requests don't cross
  networks, they will fail to elicit any responses.  So, what you want
  is for UML to just blindly throw all packets at the host and let it
  figure out what to do with them, which is what leaving out the network
  route and adding the default route does.


  Note: If you can't communicate with other hosts on your physical
  ethernet, it's probably because of a network route that's
  automatically set up.  If you run 'route -n' and see a route that
  looks like this:




  Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
  192.168.0.0     0.0.0.0         255.255.255.0   U     0      0      0   eth0




  with a mask that's not 255.255.255.255, then replace it with a route
  to your host:


       UML#
       route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0






       UML#
       route add -host 192.168.0.4 dev eth0




  This, plus the default route to the host, will allow UML to exchange
  packets with any machine on your ethernet.



1134
  6.5.  Multicast
Linus Torvalds's avatar
Linus Torvalds committed
1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181

  The simplest way to set up a virtual network between multiple UMLs is
  to use the mcast transport.  This was written by Harald Welte and is
  present in UML version 2.4.5-5um and later.  Your system must have
  multicast enabled in the kernel and there must be a multicast-capable
  network device on the host.  Normally, this is eth0, but if there is
  no ethernet card on the host, then you will likely get strange error
  messages when you bring the device up inside UML.


  To use it, run two UMLs with


        eth0=mcast




  on their command lines.  Log in, configure the ethernet device in each
  machine with different IP addresses:


       UML1# ifconfig eth0 192.168.0.254






       UML2# ifconfig eth0 192.168.0.253




  and they should be able to talk to each other.

  The full set of command line options for this transport are



       ethn=mcast,ethernet address,multicast
       address,multicast port,ttl




  Harald's original README is here <http://user-mode-linux.source-
1182
  forge.net/>  and explains these in detail, as well as
Linus Torvalds's avatar
Linus Torvalds committed
1183 1184
  some other issues.

Nolan Leake's avatar
Nolan Leake committed
1185 1186 1187 1188 1189 1190 1191 1192 1193 1194
  There is also a related point-to-point only "ucast" transport.
  This is useful when your network does not support multicast, and
  all network connections are simple point to point links.

  The full set of command line options for this transport are


       ethn=ucast,ethernet address,remote address,listen port,remote port


Linus Torvalds's avatar
Linus Torvalds committed
1195 1196


1197
  6.6.  TUN/TAP with the uml_net helper
Linus Torvalds's avatar
Linus Torvalds committed
1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249

  TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the
  host.  The TUN/TAP backend has been in UML since 2.4.9-3um.


  The easiest way to get up and running is to let the setuid uml_net
  helper do the host setup for you.  This involves insmod-ing the tun.o
  module if necessary, configuring the device, and setting up IP
  forwarding, routing, and proxy arp.  If you are new to UML networking,
  do this first.  If you're concerned about the security implications of
  the setuid helper, use it to get up and running, then read the next
  section to see how to have UML use a preconfigured tap device, which
  avoids the use of uml_net.


  If you specify an IP address for the host side of the device, the
  uml_net helper will do all necessary setup on the host - the only
  requirement is that TUN/TAP be available, either built in to the host
  kernel or as the tun.o module.

  The format of the command line switch to attach a device to a TUN/TAP
  device is


       eth <n> =tuntap,,, <IP address>




  For example, this argument will attach the UML's eth0 to the next
  available tap device and assign an ethernet address to it based on its
  IP address


       eth0=tuntap,,,192.168.0.254






  Note that the IP address that must be used for the eth device inside
  UML is fixed by the routing and proxy arp that is set up on the
  TUN/TAP device on the host.  You can use a different one, but it won't
  work because reply packets won't reach the UML.  This is a feature.
  It prevents a nasty UML user from doing things like setting the UML IP
  to the same as the network's nameserver or mail server.


  There are a couple potential problems with running the TUN/TAP
  transport on a 2.4 host kernel

1250
  o  TUN/TAP seems not to work on 2.4.3 and earlier.  Upgrade the host
Linus Torvalds's avatar
Linus Torvalds committed
1251 1252
     kernel or use the ethertap transport.

1253
  o  With an upgraded kernel, TUN/TAP may fail with
Linus Torvalds's avatar
Linus Torvalds committed
1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266


       File descriptor in bad state




  This is due to a header mismatch between the upgraded kernel and the
  kernel that was originally installed on the machine.  The fix is to
  make sure that /usr/src/linux points to the headers for the running
  kernel.

  These were pointed out by Tim Robinson <timro at trkr dot net> in
1267
  <http://www.geocrawler.com/> name="this uml-
Linus Torvalds's avatar
Linus Torvalds committed
1268 1269 1270 1271
  user post"> .



1272
  6.7.  TUN/TAP with a preconfigured tap device
Linus Torvalds's avatar
Linus Torvalds committed
1273 1274 1275 1276 1277 1278 1279

  If you prefer not to have UML use uml_net (which is somewhat
  insecure), with UML 2.4.17-11, you can set up a TUN/TAP device
  beforehand.  The setup needs to be done as root, but once that's done,
  there is no need for root assistance.  Setting up the device is done
  as follows:

1280
  o  Create the device with tunctl (available from the UML utilities
Linus Torvalds's avatar
Linus Torvalds committed
1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293
     tarball)




       host#  tunctl -u uid




  where uid is the user id or username that UML will be run as.  This
  will tell you what device was created.

1294
  o  Configure the device IP (change IP addresses and device name to
Linus Torvalds's avatar
Linus Torvalds committed
1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305
     suit)




       host#  ifconfig tap0 192.168.0.254 up





1306
  o  Set up routing and arping if desired - this is my recipe, there are
Linus Torvalds's avatar
Linus Torvalds committed
1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340
     other ways of doing the same thing


       host#
       bash -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'

       host#
       route add -host 192.168.0.253 dev tap0






       host#
       bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'






       host#
       arp -Ds 192.168.0.253 eth0 pub




  Note that this must be done every time the host boots - this configu-
  ration is not stored across host reboots.  So, it's probably a good
  idea to stick it in an rc file.  An even better idea would be a little
  utility which reads the information from a config file and sets up
  devices at boot time.

1341
  o  Rather than using up two IPs and ARPing for one of them, you can
Linus Torvalds's avatar
Linus Torvalds committed
1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419
     also provide direct access to your LAN by the UML by using a
     bridge.


       host#
       brctl addbr br0






       host#
       ifconfig eth0 0.0.0.0 promisc up






       host#
       ifconfig tap0 0.0.0.0 promisc up






       host#
       ifconfig br0 192.168.0.1 netmask 255.255.255.0 up







  host#
  brctl stp br0 off






       host#
       brctl setfd br0 1






       host#
       brctl sethello br0 1






       host#
       brctl addif br0 eth0






       host#
       brctl addif br0 tap0




  Note that 'br0' should be setup using ifconfig with the existing IP
  address of eth0, as eth0 no longer has its own IP.

1420
  o
Linus Torvalds's avatar
Linus Torvalds committed
1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432


     Also, the /dev/net/tun device must be writable by the user running
     UML in order for the UML to use the device that's been configured
     for it.  The simplest thing to do is


       host#  chmod 666 /dev/net/tun




1433
  Making it world-writable looks bad, but it seems not to be
Linus Torvalds's avatar
Linus Torvalds committed
1434 1435 1436 1437 1438 1439 1440
  exploitable as a security hole.  However, it does allow anyone to cre-
  ate useless tap devices (useless because they can't configure them),
  which is a DOS attack.  A somewhat more secure alternative would to be
  to create a group containing all the users who have preconfigured tap
  devices and chgrp /dev/net/tun to that group with mode 664 or 660.


1441
  o  Once the device is set up, run UML with 'eth0=tuntap,device name'
Linus Torvalds's avatar
Linus Torvalds committed
1442 1443 1444
     (i.e. 'eth0=tuntap,tap0') on the command line (or do it with the
     mconsole config command).

1445
  o  Bring the eth device up in UML and you're in business.
Linus Torvalds's avatar
Linus Torvalds committed
1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467

     If you don't want that tap device any more, you can make it non-
     persistent with


       host#  tunctl -d tap device




  Finally, tunctl has a -b (for brief mode) switch which causes it to
  output only the name of the tap device it created.  This makes it
  suitable for capture by a script:


       host#  TAP=`tunctl -u 1000 -b`






1468
  6.8.  Ethertap
Linus Torvalds's avatar
Linus Torvalds committed
1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563

  Ethertap is the general mechanism on 2.2 for userspace processes to
  exchange packets with the kernel.



  To use this transport, you need to describe the virtual network device
  on the UML command line.  The general format for this is


       eth <n> =ethertap, <device> , <ethernet address> , <tap IP address>




  So, the previous example


       eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254




  attaches the UML eth0 device to the host /dev/tap0, assigns it the
  ethernet address fe:fd:0:0:0:1, and assigns the IP address
  192.168.0.254 to the tap device.



  The tap device is mandatory, but the others are optional.  If the
  ethernet address is omitted, one will be assigned to it.


  The presence of the tap IP address will cause the helper to run and do
  whatever host setup is needed to allow the virtual machine to
  communicate with the outside world.  If you're not sure you know what
  you're doing, this is the way to go.


  If it is absent, then you must configure the tap device and whatever
  arping and routing you will need on the host.  However, even in this
  case, the uml_net helper still needs to be in your path and it must be
  setuid root if you're not running UML as root.  This is because the
  tap device doesn't support SIGIO, which UML needs in order to use
  something as a source of input.  So, the helper is used as a
  convenient asynchronous IO thread.

  If you're using the uml_net helper, you can ignore the following host
  setup - uml_net will do it for you.  You just need to make sure you
  have ethertap available, either built in to the host kernel or
  available as a module.


  If you want to set things up yourself, you need to make sure that the
  appropriate /dev entry exists.  If it doesn't, become root and create
  it as follows:


       mknod /dev/tap <minor>  c 36  <minor>  + 16




  For example, this is how to create /dev/tap0:


       mknod /dev/tap0 c 36 0 + 16




  You also need to make sure that the host kernel has ethertap support.
  If ethertap is enabled as a module, you apparently need to insmod
  ethertap once for each ethertap device you want to enable.  So,


       host#
       insmod ethertap




  will give you the tap0 interface.  To get the tap1 interface, you need
  to run


       host#
       insmod ethertap unit=1 -o ethertap1







1564
  6.9.  The switch daemon
Linus Torvalds's avatar
Linus Torvalds committed
1565

1566
  Note: This is the daemon formerly known as uml_router, but which was
Linus Torvalds's avatar
Linus Torvalds committed
1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651
  renamed so the network weenies of the world would stop growling at me.


  The switch daemon, uml_switch, provides a mechanism for creating a
  totally virtual network.  By default, it provides no connection to the
  host network (but see -tap, below).


  The first thing you need to do is run the daemon.  Running it with no
  arguments will make it listen on a default pair of unix domain
  sockets.


  If you want it to listen on a different pair of sockets, use


        -unix control socket data socket





  If you want it to act as a hub rather than a switch, use


        -hub





  If you want the switch to be connected to host networking (allowing
  the umls to get access to the outside world through the host), use


        -tap tap0





  Note that the tap device must be preconfigured (see "TUN/TAP with a
  preconfigured tap device", above).  If you're using a different tap
  device than tap0, specify that instead of tap0.


  uml_switch can be backgrounded as follows


       host%
       uml_switch [ options ] < /dev/null > /dev/null




  The reason it doesn't background by default is that it listens to
  stdin for EOF.  When it sees that, it exits.


  The general format of the kernel command line switch is



       ethn=daemon,ethernet address,socket
       type,control socket,data socket




  You can leave off everything except the 'daemon'.  You only need to
  specify the ethernet address if the one that will be assigned to it
  isn't acceptable for some reason.  The rest of the arguments describe
  how to communicate with the daemon.  You should only specify them if
  you told the daemon to use different sockets than the default.  So, if
  you ran the daemon with no arguments, running the UML on the same
  machine with
       eth0=daemon




  will cause the eth0 driver to attach itself to the daemon correctly.



1652
  6.10.  Slip
Linus Torvalds's avatar
Linus Torvalds committed
1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683

  Slip is another, less general, mechanism for a process to communicate
  with the host networking.  In contrast to the ethertap interface,
  which exchanges ethernet frames with the host and can be used to
  transport any higher-level protocol, it can only be used to transport
  IP.


  The general format of the command line switch is



       ethn=slip,slip IP




  The slip IP argument is the IP address that will be assigned to the
  host end of the slip device.  If it is specified, the helper will run
  and will set up the host so that the virtual machine can reach it and
  the rest of the network.


  There are some oddities with this interface that you should be aware
  of.  You should only specify one slip device on a given virtual
  machine, and its name inside UML will be 'umn', not 'eth0' or whatever
  you specified on the command line.  These problems will be fixed at
  some point.



1684
  6.11.  Slirp
Linus Torvalds's avatar
Linus Torvalds committed
1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739

  slirp uses an external program, usually /usr/bin/slirp, to provide IP
  only networking connectivity through the host. This is similar to IP
  masquerading with a firewall, although the translation is performed in
  user-space, rather than by the kernel.  As slirp does not set up any
  interfaces on the host, or changes routing, slirp does not require
  root access or setuid binaries on the host.


  The general format of the command line switch for slirp is:



       ethn=slirp,ethernet address,slirp path




  The ethernet address is optional, as UML will set up the interface
  with an ethernet address based upon the initial IP address of the
  interface.  The slirp path is generally /usr/bin/slirp, although it
  will depend on distribution.


  The slirp program can have a number of options passed to the command
  line and we can't add them to the UML command line, as they will be
  parsed incorrectly.  Instead, a wrapper shell script can be written or
  the options inserted into the  /.slirprc file.  More information on
  all of the slirp options can be found in its man pages.


  The eth0 interface on UML should be set up with the IP 10.2.0.15,
  although you can use anything as long as it is not used by a network
  you will be connecting to. The default route on UML should be set to
  use


       UML#
       route add default dev eth0




  slirp provides a number of useful IP addresses which can be used by
  UML, such as 10.0.2.3 which is an alias for the DNS server specified
  in /etc/resolv.conf on the host or the IP given in the 'dns' option
  for slirp.


  Even with a baudrate setting higher than 115200, the slirp connection
  is limited to 115200. If you need it to go faster, the slirp binary
  needs to be compiled with FULL_BOLT defined in config.h.



1740
  6.12.  pcap
Linus Torvalds's avatar
Linus Torvalds committed
1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779

  The pcap transport is attached to a UML ethernet device on the command
  line or with uml_mconsole with the following syntax:



       ethn=pcap,host interface,filter
       expression,option1,option2




  The expression and options are optional.


  The interface is whatever network device on the host you want to
  sniff.  The expression is a pcap filter expression, which is also what
  tcpdump uses, so if you know how to specify tcpdump filters, you will
  use the same expressions here.  The options are up to two of
  'promisc', control whether pcap puts the host interface into
  promiscuous mode. 'optimize' and 'nooptimize' control whether the pcap
  expression optimizer is used.


  Example:



       eth0=pcap,eth0,tcp

       eth1=pcap,eth0,!tcp



  will cause the UML eth0 to emit all tcp packets on the host eth0 and
  the UML eth1 to emit all non-tcp packets on the host eth0.



1780
  6.13.  Setting up the host yourself
Linus Torvalds's avatar
Linus Torvalds committed
1781 1782 1783 1784 1785 1786 1787

  If you don't specify an address for the host side of the ethertap or
  slip device, UML won't do any setup on the host.  So this is what is
  needed to get things working (the examples use a host-side IP of
  192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your
  own network):

1788
  o  The device needs to be configured with its IP address.  Tap devices
Linus Torvalds's avatar
Linus Torvalds committed
1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807
     are also configured with an mtu of 1484.  Slip devices are
     configured with a point-to-point address pointing at the UML ip
     address.


       host#  ifconfig tap0 arp mtu 1484 192.168.0.251 up






       host#
       ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up





1808
  o  If a tap device is being set up, a route is set to the UML IP.
Linus Torvalds's avatar
Linus Torvalds committed
1809 1810 1811 1812 1813 1814 1815 1816


       UML# route add -host 192.168.0.250 gw 192.168.0.251





1817
  o  To allow other hosts on your network to see the virtual machine,
Linus Torvalds's avatar
Linus Torvalds committed
1818 1819 1820 1821 1822 1823 1824 1825 1826
     proxy arp is set up for it.


       host#  arp -Ds 192.168.0.250 eth0 pub





1827
  o  Finally, the host is set up to route packets.
Linus Torvalds's avatar
Linus Torvalds committed
1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840


       host#  echo 1 > /proc/sys/net/ipv4/ip_forward










1841
  7.  Sharing Filesystems between Virtual Machines
Linus Torvalds's avatar
Linus Torvalds committed
1842 1843 1844 1845




1846
  7.1.  A warning
Linus Torvalds's avatar
Linus Torvalds committed
1847 1848 1849 1850 1851 1852 1853

  Don't attempt to share filesystems simply by booting two UMLs from the
  same file.  That's the same thing as booting two physical machines
  from a shared disk.  It will result in filesystem corruption.



1854
  7.2.  Using layered block devices
Linus Torvalds's avatar
Linus Torvalds committed
1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898

  The way to share a filesystem between two virtual machines is to use
  the copy-on-write (COW) layering capability of the ubd block driver.
  As of 2.4.6-2um, the driver supports layering a read-write private
  device over a read-only shared device.  A machine's writes are stored
  in the private device, while reads come from either device - the
  private one if the requested block is valid in it, the shared one if
  not.  Using this scheme, the majority of data which is unchanged is
  shared between an arbitrary number of virtual machines, each of which
  has a much smaller file containing the changes that it has made.  With
  a large number of UMLs booting from a large root filesystem, this
  leads to a huge disk space saving.  It will also help performance,
  since the host will be able to cache the shared data using a much
  smaller amount of memory, so UML disk requests will be served from the
  host's memory rather than its disks.




  To add a copy-on-write layer to an existing block device file, simply
  add the name of the COW file to the appropriate ubd switch:


        ubd0=root_fs_cow,root_fs_debian_22




  where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is
  the existing shared filesystem.  The COW file need not exist.  If it
  doesn't, the driver will create and initialize it.  Once the COW file
  has been initialized, it can be used on its own on the command line:


        ubd0=root_fs_cow




  The name of the backing file is stored in the COW file header, so it
  would be redundant to continue specifying it on the command line.



1899
  7.3.  Note!
Linus Torvalds's avatar
Linus Torvalds committed
1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928

  When checking the size of the COW file in order to see the gobs of
  space that you're saving, make sure you use 'ls -ls' to see the actual
  disk consumption rather than the length of the file.  The COW file is
  sparse, so the length will be very different from the disk usage.
  Here is a 'ls -l' of a COW file and backing file from one boot and
  shutdown:
       host% ls -l cow.debian debian2.2
       -rw-r--r--    1 jdike    jdike    492504064 Aug  6 21:16 cow.debian
       -rwxrw-rw-    1 jdike    jdike    537919488 Aug  6 20:42 debian2.2




  Doesn't look like much saved space, does it?  Well, here's 'ls -ls':


       host% ls -ls cow.debian debian2.2
          880 -rw-r--r--    1 jdike    jdike    492504064 Aug  6 21:16 cow.debian
       525832 -rwxrw-rw-    1 jdike    jdike    537919488 Aug  6 20:42 debian2.2




  Now, you can see that the COW file has less than a meg of disk, rather
  than 492 meg.



1929
  7.4.  Another warning
Linus Torvalds's avatar
Linus Torvalds committed
1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954

  Once a filesystem is being used as a readonly backing file for a COW
  file, do not boot directly from it or modify it in any way.  Doing so
  will invalidate any COW files that are using it.  The mtime and size
  of the backing file are stored in the COW file header at its creation,
  and they must continue to match.  If they don't, the driver will
  refuse to use the COW file.




  If you attempt to evade this restriction by changing either the
  backing file or the COW header by hand, you will get a corrupted
  filesystem.




  Among other things, this means that upgrading the distribution in a
  backing file and expecting that all of the COW files using it will see
  the upgrade will not work.




1955
  7.5.  uml_moo : Merging a COW file with its backing file
Linus Torvalds's avatar
Linus Torvalds committed
1956 1957 1958 1959 1960 1961 1962