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 (see drivers/lguest/README).
  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 - The easiest way to run lguest is to use same kernel as guest and host.
  27   You can configure them differently, but usually it's easiest not to.
  28
  29   You will need to configure your kernel with the following options:
  30
  31   "General setup":
  32      "Prompt for development and/or incomplete code/drivers" = Y
  33         (CONFIG_EXPERIMENTAL=y)
  34
  35   "Processor type and features":
  36      "Paravirtualized guest support" = Y
  37         "Lguest guest support" = Y
  38      "High Memory Support" = off/4GB
  39      "Alignment value to which kernel should be aligned" = 0x100000
  40         (CONFIG_PARAVIRT=y, CONFIG_LGUEST_GUEST=y, CONFIG_HIGHMEM64G=n and
  41          CONFIG_PHYSICAL_ALIGN=0x100000)
  42
  43   "Device Drivers":
  44      "Network device support"
  45         "Universal TUN/TAP device driver support" = M/Y
  46            (CONFIG_TUN=m)
  47      "Virtualization"
  48         "Linux hypervisor example code" = M/Y
  49            (CONFIG_LGUEST=m)
  50
  51 - A tool called "lguest" is available in this directory: type "make"
  52   to build it.  If you didn't build your kernel in-tree, use "make
  53   O=<builddir>".
  54
  55 - Create or find a root disk image.  There are several useful ones
  56   around, such as the xm-test tiny root image at
  57           http://xm-test.xensource.com/ramdisks/initrd-1.1-i386.img
  58
  59   For more serious work, I usually use a distribution ISO image and
  60   install it under qemu, then make multiple copies:
  61
  62           dd if=/dev/zero of=rootfile bs=1M count=2048
  63           qemu -cdrom image.iso -hda rootfile -net user -net nic -boot d
  64
  65   Make sure that you install a getty on /dev/hvc0 if you want to log in on the
  66   console!
  67
  68 - "modprobe lg" if you built it as a module.
  69
  70 - Run an lguest as root:
  71
  72       Documentation/lguest/lguest 64 vmlinux --tunnet=192.168.19.1 --block=rootfile root=/dev/vda
  73
  74    Explanation:
  75     64: the amount of memory to use, in MB.
  76
  77     vmlinux: the kernel image found in the top of your build directory.  You
  78        can also use a standard bzImage.
  79
  80     --tunnet=192.168.19.1: configures a "tap" device for networking with this
  81        IP address.
  82
  83     --block=rootfile: a file or block device which becomes /dev/vda
  84        inside the guest.
  85
  86     root=/dev/vda: this (and anything else on the command line) are
  87        kernel boot parameters.
  88
  89 - Configuring networking.  I usually have the host masquerade, using
  90   "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE" and "echo 1 >
  91   /proc/sys/net/ipv4/ip_forward".  In this example, I would configure
  92   eth0 inside the guest at 192.168.19.2.
  93
  94   Another method is to bridge the tap device to an external interface
  95   using --tunnet=bridge:<bridgename>, and perhaps run dhcp on the guest
  96   to obtain an IP address.  The bridge needs to be configured first:
  97   this option simply adds the tap interface to it.
  98
  99   A simple example on my system:
 100
 101     ifconfig eth0 0.0.0.0
 102     brctl addbr lg0
 103     ifconfig lg0 up
 104     brctl addif lg0 eth0
 105     dhclient lg0
 106
 107   Then use --tunnet=bridge:lg0 when launching the guest.
 108
 109   See http://linux-net.osdl.org/index.php/Bridge for general information
 110   on how to get bridging working.
 111
 112 - You can also create an inter-guest network using
 113   "--sharenet=<filename>": any two guests using the same file are on
 114   the same network.  This file is created if it does not exist.
 115
 116 There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest
 117
 118 Good luck!
 119 Rusty Russell rusty@rustcorp.com.au.