Documentation/lguest/lguest.txt

   1 Rusty's Remarkably Unreliable Guide to Lguest
   2         - or, A Young Coder's Illustrated Hypervisor
   3 http://lguest.ozlabs.org
   4
   5 Lguest is designed to be a minimal hypervisor for the Linux kernel, for
   6 Linux developers and users to experiment with virtualization with the
   7 minimum of complexity.  Nonetheless, it should have sufficient
   8 features to make it useful for specific tasks, and, of course, you are
   9 encouraged to fork and enhance it.
  10
  11 Features:
  12
  13 - Kernel module which runs in a normal kernel.
  14 - Simple I/O model for communication.
  15 - Simple program to create new guests.
  16 - Logo contains cute puppies: http://lguest.ozlabs.org
  17
  18 Developer features:
  19
  20 - Fun to hack on.
  21 - No ABI: being tied to a specific kernel anyway, you can change anything.
  22 - Many opportunities for improvement or feature implementation.
  23
  24 Running Lguest:
  25
  26 - Lguest runs the same kernel as guest and host.  You can configure
  27   them differently, but usually it's easiest not to.
  28
  29   You will need to configure your kernel with the following options:
  30
  31   CONFIG_HIGHMEM64G=n ("High Memory Support" "64GB")[1]
  32   CONFIG_TUN=y/m ("Universal TUN/TAP device driver support")
  33   CONFIG_EXPERIMENTAL=y ("Prompt for development and/or incomplete code/drivers")
  34   CONFIG_PARAVIRT=y ("Paravirtualization support (EXPERIMENTAL)")
  35   CONFIG_LGUEST=y/m ("Linux hypervisor example code")
  36
  37   and I recommend:
  38   CONFIG_HZ=100 ("Timer frequency")[2]
  39
  40 - A tool called "lguest" is available in this directory: type "make"
  41   to build it.  If you didn't build your kernel in-tree, use "make
  42   O=<builddir>".
  43
  44 - Create or find a root disk image.  There are several useful ones
  45   around, such as the xm-test tiny root image at
  46           http://xm-test.xensource.com/ramdisks/initrd-1.1-i386.img
  47
  48   For more serious work, I usually use a distribution ISO image and
  49   install it under qemu, then make multiple copies:
  50
  51           dd if=/dev/zero of=rootfile bs=1M count=2048
  52           qemu -cdrom image.iso -hda rootfile -net user -net nic -boot d
  53
  54 - "modprobe lg" if you built it as a module.
  55
  56 - Run an lguest as root:
  57
  58       Documentation/lguest/lguest 64m vmlinux --tunnet=192.168.19.1 --block=rootfile root=/dev/lgba
  59
  60    Explanation:
  61     64m: the amount of memory to use.
  62
  63     vmlinux: the kernel image found in the top of your build directory.  You
  64        can also use a standard bzImage.
  65
  66     --tunnet=192.168.19.1: configures a "tap" device for networking with this
  67        IP address.
  68
  69     --block=rootfile: a file or block device which becomes /dev/lgba
  70        inside the guest.
  71
  72     root=/dev/lgba: this (and anything else on the command line) are
  73        kernel boot parameters.
  74
  75 - Configuring networking.  I usually have the host masquerade, using
  76   "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE" and "echo 1 >
  77   /proc/sys/net/ipv4/ip_forward".  In this example, I would configure
  78   eth0 inside the guest at 192.168.19.2.
  79
  80   Another method is to bridge the tap device to an external interface
  81   using --tunnet=bridge:<bridgename>, and perhaps run dhcp on the guest
  82   to obtain an IP address.  The bridge needs to be configured first:
  83   this option simply adds the tap interface to it.
  84
  85   A simple example on my system:
  86
  87     ifconfig eth0 0.0.0.0
  88     brctl addbr lg0
  89     ifconfig lg0 up
  90     brctl addif lg0 eth0
  91     dhclient lg0
  92
  93   Then use --tunnet=bridge:lg0 when launching the guest.
  94
  95   See http://linux-net.osdl.org/index.php/Bridge for general information
  96   on how to get bridging working.
  97
  98 - You can also create an inter-guest network using
  99   "--sharenet=<filename>": any two guests using the same file are on
 100   the same network.  This file is created if it does not exist.
 101
 102 Lguest I/O model:
 103
 104 Lguest uses a simplified DMA model plus shared memory for I/O.  Guests
 105 can communicate with each other if they share underlying memory
 106 (usually by the lguest program mmaping the same file), but they can
 107 use any non-shared memory to communicate with the lguest process.
 108
 109 Guests can register DMA buffers at any key (must be a valid physical
 110 address) using the LHCALL_BIND_DMA(key, dmabufs, num<<8|irq)
 111 hypercall.  "dmabufs" is the physical address of an array of "num"
 112 "struct lguest_dma": each contains a used_len, and an array of
 113 physical addresses and lengths.  When a transfer occurs, the
 114 "used_len" field of one of the buffers which has used_len 0 will be
 115 set to the length transferred and the irq will fire.
 116
 117 Using an irq value of 0 unbinds the dma buffers.
 118
 119 To send DMA, the LHCALL_SEND_DMA(key, dma_physaddr) hypercall is used,
 120 and the bytes used is written to the used_len field.  This can be 0 if
 121 noone else has bound a DMA buffer to that key or some other error.
 122 DMA buffers bound by the same guest are ignored.
 123
 124 Cheers!
 125 Rusty Russell rusty@rustcorp.com.au.
 126
 127 [1] These are on various places on the TODO list, waiting for you to
 128     get annoyed enough at the limitation to fix it.
 129 [2] Lguest is not yet tickless when idle.  See [1].