Commit | Line | Data |
---|---|---|
b488f22d TA |
1 | __ |
2 | (___()'`; Rusty's Remarkably Unreliable Guide to Lguest | |
3 | /, /` - or, A Young Coder's Illustrated Hypervisor | |
4 | \\"--\\ http://lguest.ozlabs.org | |
8ca47e00 | 5 | |
38cfe968 RR |
6 | Lguest is designed to be a minimal 32-bit x86 hypervisor for the Linux kernel, |
7 | for Linux developers and users to experiment with virtualization with the | |
8 | minimum of complexity. Nonetheless, it should have sufficient features to | |
9 | make it useful for specific tasks, and, of course, you are encouraged to fork | |
10 | and enhance it (see drivers/lguest/README). | |
8ca47e00 RR |
11 | |
12 | Features: | |
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 | ||
19 | Developer 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 | ||
25 | Running Lguest: | |
26 | ||
9653c4af RR |
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. | |
8ca47e00 RR |
29 | |
30 | You will need to configure your kernel with the following options: | |
31 | ||
9653c4af RR |
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 | |
38cfe968 | 40 | "PAE (Physical Address Extension) Support" = N |
9653c4af RR |
41 | "Alignment value to which kernel should be aligned" = 0x100000 |
42 | (CONFIG_PARAVIRT=y, CONFIG_LGUEST_GUEST=y, CONFIG_HIGHMEM64G=n and | |
43 | CONFIG_PHYSICAL_ALIGN=0x100000) | |
44 | ||
45 | "Device Drivers": | |
9b7a448e PB |
46 | "Block devices" |
47 | "Virtio block driver (EXPERIMENTAL)" = M/Y | |
9653c4af RR |
48 | "Network device support" |
49 | "Universal TUN/TAP device driver support" = M/Y | |
9b7a448e PB |
50 | "Virtio network driver (EXPERIMENTAL)" = M/Y |
51 | (CONFIG_VIRTIO_BLK=m, CONFIG_VIRTIO_NET=m and CONFIG_TUN=m) | |
52 | ||
53 | "Virtualization" | |
54 | "Linux hypervisor example code" = M/Y | |
55 | (CONFIG_LGUEST=m) | |
8ca47e00 RR |
56 | |
57 | - A tool called "lguest" is available in this directory: type "make" | |
58 | to build it. If you didn't build your kernel in-tree, use "make | |
59 | O=<builddir>". | |
60 | ||
61 | - Create or find a root disk image. There are several useful ones | |
62 | around, such as the xm-test tiny root image at | |
63 | http://xm-test.xensource.com/ramdisks/initrd-1.1-i386.img | |
64 | ||
65 | For more serious work, I usually use a distribution ISO image and | |
66 | install it under qemu, then make multiple copies: | |
67 | ||
68 | dd if=/dev/zero of=rootfile bs=1M count=2048 | |
69 | qemu -cdrom image.iso -hda rootfile -net user -net nic -boot d | |
70 | ||
9653c4af RR |
71 | Make sure that you install a getty on /dev/hvc0 if you want to log in on the |
72 | console! | |
73 | ||
8ca47e00 RR |
74 | - "modprobe lg" if you built it as a module. |
75 | ||
76 | - Run an lguest as root: | |
77 | ||
1f5a2902 | 78 | Documentation/lguest/lguest 64 vmlinux --tunnet=192.168.19.1 --block=rootfile root=/dev/vda |
8ca47e00 RR |
79 | |
80 | Explanation: | |
9653c4af | 81 | 64: the amount of memory to use, in MB. |
8ca47e00 RR |
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 | ||
1f5a2902 | 89 | --block=rootfile: a file or block device which becomes /dev/vda |
8ca47e00 RR |
90 | inside the guest. |
91 | ||
1f5a2902 | 92 | root=/dev/vda: this (and anything else on the command line) are |
8ca47e00 RR |
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 http://linux-net.osdl.org/index.php/Bridge for general information | |
116 | on how to get bridging working. | |
117 | ||
9653c4af | 118 | There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest |
8ca47e00 | 119 | |
9653c4af | 120 | Good luck! |
8ca47e00 | 121 | Rusty Russell rusty@rustcorp.com.au. |