linux/tools/lguest/lguest.txt
<<
>>
Prefs
   1      __
   2 (___()'`;  Rusty's Remarkably Unreliable Guide to Lguest
   3 /,    /`      - or, A Young Coder's Illustrated Hypervisor
   4 \\"--\\    http://lguest.ozlabs.org
   5
   6Lguest is designed to be a minimal 32-bit x86 hypervisor for the Linux kernel,
   7for Linux developers and users to experiment with virtualization with the
   8minimum of complexity.  Nonetheless, it should have sufficient features to
   9make it useful for specific tasks, and, of course, you are encouraged to fork
  10and enhance it (see drivers/lguest/README).
  11
  12Features:
  13
  14- Kernel module which runs in a normal kernel.
  15- Simple I/O model for communication.
  16- Simple program to create new guests.
  17- Logo contains cute puppies: http://lguest.ozlabs.org
  18
  19Developer features:
  20
  21- Fun to hack on.
  22- No ABI: being tied to a specific kernel anyway, you can change anything.
  23- Many opportunities for improvement or feature implementation.
  24
  25Running Lguest:
  26
  27- The easiest way to run lguest is to use same kernel as guest and host.
  28  You can configure them differently, but usually it's easiest not to.
  29
  30  You will need to configure your kernel with the following options:
  31
  32  "General setup":
  33     "Prompt for development and/or incomplete code/drivers" = Y
  34        (CONFIG_EXPERIMENTAL=y)
  35
  36  "Processor type and features":
  37     "Paravirtualized guest support" = Y
  38        "Lguest guest support" = Y
  39     "High Memory Support" = off/4GB
  40     "Alignment value to which kernel should be aligned" = 0x100000
  41        (CONFIG_PARAVIRT=y, CONFIG_LGUEST_GUEST=y, CONFIG_HIGHMEM64G=n and
  42         CONFIG_PHYSICAL_ALIGN=0x100000)
  43
  44  "Device Drivers":
  45     "Block devices"
  46        "Virtio block driver (EXPERIMENTAL)" = M/Y
  47     "Network device support"
  48        "Universal TUN/TAP device driver support" = M/Y
  49        "Virtio network driver (EXPERIMENTAL)" = M/Y
  50           (CONFIG_VIRTIO_BLK=m, CONFIG_VIRTIO_NET=m and CONFIG_TUN=m)
  51
  52  "Virtualization"
  53     "Linux hypervisor example code" = M/Y
  54        (CONFIG_LGUEST=m)
  55
  56- A tool called "lguest" is available in this directory: type "make"
  57  to build it.  If you didn't build your kernel in-tree, use "make
  58  O=<builddir>".
  59
  60- Create or find a root disk image.  There are several useful ones
  61  around, such as the xm-test tiny root image at
  62          http://xm-test.xensource.com/ramdisks/initrd-1.1-i386.img
  63
  64  For more serious work, I usually use a distribution ISO image and
  65  install it under qemu, then make multiple copies:
  66
  67          dd if=/dev/zero of=rootfile bs=1M count=2048
  68          qemu -cdrom image.iso -hda rootfile -net user -net nic -boot d
  69
  70  Make sure that you install a getty on /dev/hvc0 if you want to log in on the
  71  console!
  72
  73- "modprobe lg" if you built it as a module.
  74
  75- Run an lguest as root:
  76
  77      Documentation/virtual/lguest/lguest 64 vmlinux --tunnet=192.168.19.1 \
  78        --block=rootfile root=/dev/vda
  79
  80   Explanation:
  81    64: the amount of memory to use, in MB.
  82
  83    vmlinux: the kernel image found in the top of your build directory.  You
  84       can also use a standard bzImage.
  85
  86    --tunnet=192.168.19.1: configures a "tap" device for networking with this
  87       IP address.
  88
  89    --block=rootfile: a file or block device which becomes /dev/vda
  90       inside the guest.
  91
  92    root=/dev/vda: this (and anything else on the command line) are
  93       kernel boot parameters.
  94
  95- Configuring networking.  I usually have the host masquerade, using
  96  "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE" and "echo 1 >
  97  /proc/sys/net/ipv4/ip_forward".  In this example, I would configure
  98  eth0 inside the guest at 192.168.19.2.
  99
 100  Another method is to bridge the tap device to an external interface
 101  using --tunnet=bridge:<bridgename>, and perhaps run dhcp on the guest
 102  to obtain an IP address.  The bridge needs to be configured first:
 103  this option simply adds the tap interface to it.
 104
 105  A simple example on my system:
 106
 107    ifconfig eth0 0.0.0.0
 108    brctl addbr lg0
 109    ifconfig lg0 up
 110    brctl addif lg0 eth0
 111    dhclient lg0
 112
 113  Then use --tunnet=bridge:lg0 when launching the guest.
 114
 115  See:
 116  
 117    http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge
 118    
 119  for general information on how to get bridging to work.
 120
 121- Random number generation. Using the --rng option will provide a
 122  /dev/hwrng in the guest that will read from the host's /dev/random.
 123  Use this option in conjunction with rng-tools (see ../hw_random.txt)
 124  to provide entropy to the guest kernel's /dev/random.
 125
 126There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest
 127
 128Good luck!
 129Rusty Russell rusty@rustcorp.com.au.
 130
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.