]>
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 | "Processor type and features": |
33 | "Paravirtualized guest support" = Y | |
34 | "Lguest guest support" = Y | |
35 | "High Memory Support" = off/4GB | |
36 | "Alignment value to which kernel should be aligned" = 0x100000 | |
37 | (CONFIG_PARAVIRT=y, CONFIG_LGUEST_GUEST=y, CONFIG_HIGHMEM64G=n and | |
38 | CONFIG_PHYSICAL_ALIGN=0x100000) | |
39 | ||
40 | "Device Drivers": | |
9b7a448e | 41 | "Block devices" |
483ea607 | 42 | "Virtio block driver" = M/Y |
9653c4af RR |
43 | "Network device support" |
44 | "Universal TUN/TAP device driver support" = M/Y | |
483ea607 | 45 | "Virtio network driver" = M/Y |
9b7a448e PB |
46 | (CONFIG_VIRTIO_BLK=m, CONFIG_VIRTIO_NET=m and CONFIG_TUN=m) |
47 | ||
48 | "Virtualization" | |
49 | "Linux hypervisor example code" = M/Y | |
50 | (CONFIG_LGUEST=m) | |
8ca47e00 RR |
51 | |
52 | - A tool called "lguest" is available in this directory: type "make" | |
53 | to build it. If you didn't build your kernel in-tree, use "make | |
54 | O=<builddir>". | |
55 | ||
56 | - Create or find a root disk image. There are several useful ones | |
57 | around, such as the xm-test tiny root image at | |
58 | http://xm-test.xensource.com/ramdisks/initrd-1.1-i386.img | |
59 | ||
60 | For more serious work, I usually use a distribution ISO image and | |
61 | install it under qemu, then make multiple copies: | |
62 | ||
63 | dd if=/dev/zero of=rootfile bs=1M count=2048 | |
64 | qemu -cdrom image.iso -hda rootfile -net user -net nic -boot d | |
65 | ||
9653c4af RR |
66 | Make sure that you install a getty on /dev/hvc0 if you want to log in on the |
67 | console! | |
68 | ||
8ca47e00 RR |
69 | - "modprobe lg" if you built it as a module. |
70 | ||
71 | - Run an lguest as root: | |
72 | ||
289d1054 | 73 | tools/lguest/lguest 64 vmlinux --tunnet=192.168.19.1 \ |
61516587 | 74 | --block=rootfile root=/dev/vda |
8ca47e00 RR |
75 | |
76 | Explanation: | |
9653c4af | 77 | 64: the amount of memory to use, in MB. |
8ca47e00 RR |
78 | |
79 | vmlinux: the kernel image found in the top of your build directory. You | |
80 | can also use a standard bzImage. | |
81 | ||
82 | --tunnet=192.168.19.1: configures a "tap" device for networking with this | |
83 | IP address. | |
84 | ||
1f5a2902 | 85 | --block=rootfile: a file or block device which becomes /dev/vda |
8ca47e00 RR |
86 | inside the guest. |
87 | ||
1f5a2902 | 88 | root=/dev/vda: this (and anything else on the command line) are |
8ca47e00 RR |
89 | kernel boot parameters. |
90 | ||
91 | - Configuring networking. I usually have the host masquerade, using | |
92 | "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE" and "echo 1 > | |
93 | /proc/sys/net/ipv4/ip_forward". In this example, I would configure | |
94 | eth0 inside the guest at 192.168.19.2. | |
95 | ||
96 | Another method is to bridge the tap device to an external interface | |
97 | using --tunnet=bridge:<bridgename>, and perhaps run dhcp on the guest | |
98 | to obtain an IP address. The bridge needs to be configured first: | |
99 | this option simply adds the tap interface to it. | |
100 | ||
101 | A simple example on my system: | |
102 | ||
103 | ifconfig eth0 0.0.0.0 | |
104 | brctl addbr lg0 | |
105 | ifconfig lg0 up | |
106 | brctl addif lg0 eth0 | |
107 | dhclient lg0 | |
108 | ||
109 | Then use --tunnet=bridge:lg0 when launching the guest. | |
110 | ||
c996d8b9 MW |
111 | See: |
112 | ||
113 | http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge | |
114 | ||
115 | for general information on how to get bridging to work. | |
8ca47e00 | 116 | |
85c06472 PS |
117 | - Random number generation. Using the --rng option will provide a |
118 | /dev/hwrng in the guest that will read from the host's /dev/random. | |
119 | Use this option in conjunction with rng-tools (see ../hw_random.txt) | |
120 | to provide entropy to the guest kernel's /dev/random. | |
121 | ||
9653c4af | 122 | There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest |
8ca47e00 | 123 | |
9653c4af | 124 | Good luck! |
8ca47e00 | 125 | Rusty Russell rusty@rustcorp.com.au. |