Rusty Russell | 8ca47e0 | 2007-07-19 01:49:29 -0700 | [diff] [blame] | 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]. |