blob: 29510dc515109ad5dd8a16b5936f1f6086ae417c [file] [log] [blame]
Tim Ansellb488f222008-02-11 18:13:42 +10301 __
2 (___()'`; Rusty's Remarkably Unreliable Guide to Lguest
3 /, /` - or, A Young Coder's Illustrated Hypervisor
4 \\"--\\ http://lguest.ozlabs.org
Rusty Russell8ca47e02007-07-19 01:49:29 -07005
6Lguest is designed to be a minimal hypervisor for the Linux kernel, for
7Linux developers and users to experiment with virtualization with the
8minimum of complexity. Nonetheless, it should have sufficient
9features to make it useful for specific tasks, and, of course, you are
Rusty Russell9653c4a2007-10-22 10:56:23 +100010encouraged to fork and enhance it (see drivers/lguest/README).
Rusty Russell8ca47e02007-07-19 01:49:29 -070011
12Features:
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
19Developer 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
25Running Lguest:
26
Rusty Russell9653c4a2007-10-22 10:56:23 +100027- 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.
Rusty Russell8ca47e02007-07-19 01:49:29 -070029
30 You will need to configure your kernel with the following options:
31
Rusty Russell9653c4a2007-10-22 10:56:23 +100032 "General setup":
33 "Prompt for development and/or incomplete code/drivers" = Y
34 (CONFIG_EXPERIMENTAL=y)
Rusty Russell8ca47e02007-07-19 01:49:29 -070035
Rusty Russell9653c4a2007-10-22 10:56:23 +100036 "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":
Paul Bolle9b7a4482008-03-11 13:36:14 +010045 "Block devices"
46 "Virtio block driver (EXPERIMENTAL)" = M/Y
Rusty Russell9653c4a2007-10-22 10:56:23 +100047 "Network device support"
48 "Universal TUN/TAP device driver support" = M/Y
Paul Bolle9b7a4482008-03-11 13:36:14 +010049 "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)
Rusty Russell8ca47e02007-07-19 01:49:29 -070055
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
Rusty Russell9653c4a2007-10-22 10:56:23 +100070 Make sure that you install a getty on /dev/hvc0 if you want to log in on the
71 console!
72
Rusty Russell8ca47e02007-07-19 01:49:29 -070073- "modprobe lg" if you built it as a module.
74
75- Run an lguest as root:
76
Chris Malley1f5a2902007-10-22 11:27:54 +100077 Documentation/lguest/lguest 64 vmlinux --tunnet=192.168.19.1 --block=rootfile root=/dev/vda
Rusty Russell8ca47e02007-07-19 01:49:29 -070078
79 Explanation:
Rusty Russell9653c4a2007-10-22 10:56:23 +100080 64: the amount of memory to use, in MB.
Rusty Russell8ca47e02007-07-19 01:49:29 -070081
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
Chris Malley1f5a2902007-10-22 11:27:54 +100088 --block=rootfile: a file or block device which becomes /dev/vda
Rusty Russell8ca47e02007-07-19 01:49:29 -070089 inside the guest.
90
Chris Malley1f5a2902007-10-22 11:27:54 +100091 root=/dev/vda: this (and anything else on the command line) are
Rusty Russell8ca47e02007-07-19 01:49:29 -070092 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
Rusty Russell9653c4a2007-10-22 10:56:23 +1000117There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest
Rusty Russell8ca47e02007-07-19 01:49:29 -0700118
Rusty Russell9653c4a2007-10-22 10:56:23 +1000119Good luck!
Rusty Russell8ca47e02007-07-19 01:49:29 -0700120Rusty Russell rusty@rustcorp.com.au.