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 RR |
5 | |
6 | Lguest is designed to be a minimal hypervisor for the Linux kernel, for | |
7 | Linux developers and users to experiment with virtualization with the | |
8 | minimum of complexity. Nonetheless, it should have sufficient | |
9 | features to make it useful for specific tasks, and, of course, you are | |
9653c4af | 10 | encouraged to fork 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 | |
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": | |
9b7a448e PB |
45 | "Block devices" |
46 | "Virtio block driver (EXPERIMENTAL)" = M/Y | |
9653c4af RR |
47 | "Network device support" |
48 | "Universal TUN/TAP device driver support" = M/Y | |
9b7a448e PB |
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) | |
8ca47e00 RR |
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 | ||
9653c4af RR |
70 | Make sure that you install a getty on /dev/hvc0 if you want to log in on the |
71 | console! | |
72 | ||
8ca47e00 RR |
73 | - "modprobe lg" if you built it as a module. |
74 | ||
75 | - Run an lguest as root: | |
76 | ||
1f5a2902 | 77 | Documentation/lguest/lguest 64 vmlinux --tunnet=192.168.19.1 --block=rootfile root=/dev/vda |
8ca47e00 RR |
78 | |
79 | Explanation: | |
9653c4af | 80 | 64: the amount of memory to use, in MB. |
8ca47e00 RR |
81 | |
82 | vmlinux: the kernel image found in the top of your build directory. You | |
83 | can also use a standard bzImage. | |
84 | ||
85 | --tunnet=192.168.19.1: configures a "tap" device for networking with this | |
86 | IP address. | |
87 | ||
1f5a2902 | 88 | --block=rootfile: a file or block device which becomes /dev/vda |
8ca47e00 RR |
89 | inside the guest. |
90 | ||
1f5a2902 | 91 | root=/dev/vda: this (and anything else on the command line) are |
8ca47e00 RR |
92 | kernel boot parameters. |
93 | ||
94 | - Configuring networking. I usually have the host masquerade, using | |
95 | "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE" and "echo 1 > | |
96 | /proc/sys/net/ipv4/ip_forward". In this example, I would configure | |
97 | eth0 inside the guest at 192.168.19.2. | |
98 | ||
99 | Another method is to bridge the tap device to an external interface | |
100 | using --tunnet=bridge:<bridgename>, and perhaps run dhcp on the guest | |
101 | to obtain an IP address. The bridge needs to be configured first: | |
102 | this option simply adds the tap interface to it. | |
103 | ||
104 | A simple example on my system: | |
105 | ||
106 | ifconfig eth0 0.0.0.0 | |
107 | brctl addbr lg0 | |
108 | ifconfig lg0 up | |
109 | brctl addif lg0 eth0 | |
110 | dhclient lg0 | |
111 | ||
112 | Then use --tunnet=bridge:lg0 when launching the guest. | |
113 | ||
114 | See http://linux-net.osdl.org/index.php/Bridge for general information | |
115 | on how to get bridging working. | |
116 | ||
9653c4af | 117 | There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest |
8ca47e00 | 118 | |
9653c4af | 119 | Good luck! |
8ca47e00 | 120 | Rusty Russell rusty@rustcorp.com.au. |