Commit | Line | Data |
---|---|---|
8ca47e00 RR |
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]. |