view docs/VBD-HOWTO.txt @ 1052:cc2a9e8d1568

bitkeeper revision 1.691 (4011c6d3g_Q_DeG3-esCCO1ROch6Rw)

XenoUtil.py, VBD-HOWTO.txt:
Fix location of xen vbd dataase file.
author kaf24@scramble.cl.cam.ac.uk
date Sat Jan 24 01:13:55 2004 +0000 (2004-01-24)
parents 7c3b17193b4b
children 4d8a0cc41eb6
line source
1 Virtual Block Devices / Virtual Disks in Xen - HOWTO
2 ====================================================
4 HOWTO for Xen 1.2
6 Mark A. Williamson (mark.a.williamson@intel.com)
7 (C) Intel Research Cambridge 2004
9 Introduction
10 ------------
12 This document describes the new Virtual Block Device (VBD) and Virtual Disk
13 features available in Xen release 1.2. First, a brief introduction to some
14 basic disk concepts on a Xen system:
16 Virtual Block Devices (VBDs):
17 VBDs are the disk abstraction provided by Xen. All XenoLinux disk accesses
18 go through the VBD driver. Using the VBD functionality, it is possible
19 to selectively grant domains access to portions of the physical disks
20 in the system.
22 A virtual block device can also consist of multiple extents from the
23 physical disks in the system, allowing them to be accessed as a single
24 uniform device from the domain with access to that VBD.
26 Everyone who uses Xen / XenoLinux uses VBDs but for less advanced uses
27 they can almost be ignored.
29 Virtual Disks (VDs):
30 VDs are an abstraction built on top of the functionality provided by
31 VBDs. The VD management code maintains a "free pool" of disk space on
32 the system that has been reserved for use with VDs. The tools can
33 automatically allocate collections of extents from this free pool to
34 create "virtual disks" on demand.
36 VDs can then be used just like normal disks by domains. VDs appear
37 just like any other disk to guest domains, since they use the same VBD
38 abstraction, as provided by Xen.
40 Using VDs is optional, since it's always possible to dedicate
41 partitions, or entire disks to your virtual machines. VDs are handy
42 when you have a dynamically changing set of virtual machines and you
43 don't want to have to keep repartitioning in order to provide them with
44 disk space.
46 If that didn't all make sense, it doesn't matter too much ;-) Using the
47 functionality is fairly straightforward and some examples will clarify things.
48 The text below expands a bit on the concepts involved, finishing up with a
49 walkthrough of some simple virtual disk management tasks.
52 Virtual Block Devices
53 ---------------------
55 Before covering VD management, it's worth discussing some aspects of the VBD
56 functionality that will be useful to know.
58 A VBD is made up of a number of extents from physical disk devices. The
59 extents for a VBD don't have to be contiguous, or even on the same device. Xen
60 performs address translation so that they appear as a single contiguous
61 device.
63 When the VBD layer is used to give access to entire drives or entire
64 partitions, the VBDs simply consist of a single extent, corresponding to the
65 drive or partition used. When used with Virtual Disks, the extent list
66 functionality will be used (discussed later).
68 Xen 1.2 and its associated XenoLinux release support automatic registration /
69 removal of VBDs. It has always been possible to add a VBD to a running
70 XenoLinux domain but it was then necessary to run "xen_vbd_refresh" in order
71 for the new device to be detected. Nowadays, when a VBD is added, the domain
72 it's added to automatically registers the disk.
74 Note that it is possible to use the VBD functionality to allow multiple domains
75 write access to the same areas of disk. This is almost always a bad thing!
77 The provided example script createlinuxdom.py does its best to check that disk
78 areas are not shared unsafely and will catch many cases of this. Setting the
79 vbd_expert variable in that script controls how unsafe it allows VBD mappings
80 to be - 0 should be right for most people ;-)
83 Virtual Disk Management
84 -----------------------
86 The VD management code runs entirely in userspace. The code is written in
87 Python and can therefore be accessed from custom scripts, as well as from the
88 convenience scripts provided. The underlying VD database is a SQLite database
89 in /var/lib/xen_vdisks.sqlite.
91 The scripts provided are as follows:
93 vd_format.py - "Formats" a partition or disk device for use storing
94 virtual disks. This does not actually write data to the
95 specified device. Rather, it adds the device to the VD
96 free-space pool, for later allocation.
98 You should only add devices that correspond directly to
99 physical disks / partitions - trying to use a VBD that you
100 have created yourself as part of the free space pool has
101 undefined (possibly nasty) results.
103 vd_create.py - Creates a virtual disk of specified size by allocating space
104 from the free space pool. The virtual disk is identified
105 in future by the unique ID returned by this script.
107 The disk can be given an expiry time, if desired. For
108 most users, the best idea is to specify a time of 0 (which
109 has the special meaning "never expire") and then
110 explicitly delete the VD when finished with it -
111 otherwise, VDs could disappear unexpectedly...
113 vd_refresh.py - Allows the expiry time of a (not yet expired) virtual disk to
114 be modified. Be aware the VD will disappear when the time has
115 expired.
117 vd_delete.py - Explicitly delete a VD. Makes it disappear immediately.
120 The functionality provided by these scripts is also available directly from
121 Python functions in the XenoUtil module - you can use this functionality in
122 your own scripts.
124 Populating VDs:
126 Once you've created a VD, you might want to populate it from DOM0 (for
127 instance, to put a root filesystem onto it for a guest domain). This can be
128 done by dynamically creating a VBD - this is discussed below.
130 More detail:
132 When you use vd_format.py to add a device to the free space pool, the device is
133 logically split up into extents. These extents are recorded in the Virtual
134 Disk Management database in /var/lib/xen_vdisks.sqlite.
136 When you use vd_create.py to add create a virtual disk, some of the extents in
137 the free space pool are reallocated for that virtual disk and a record for that
138 VD is added to the database. When VDs are mapped into domains as VBDs, the
139 system looks up the allocated extents for the virtual disk in order to set up
140 the underlying VBD.
142 Free space is identified by the fact that it belongs to an "expired" disk.
143 When vd_format.py adds a real device to the free pool, it actually divides it
144 into extents and adds them to an already-expired virtual disk.
146 If you set an expiry time on a VD, its extents will be liable to be reallocated
147 to new VDs as soon as that expiry time runs out. Therefore, be careful when
148 setting expiry times.
150 Finally, vd_delete.py can be used to delete virtual disks when they are no
151 longer needed. It works by causing them to expire immediately.
153 Security note:
155 The disk space for VDs is not zeroed when it is initially added to the free
156 space pool OR when a VD expires OR when a VD is created. Therefore, if this is
157 not done manually it is possible for a domain to read a VD to determine what
158 was written by previous owners of its constituent extents. If this is a
159 problem, users should manually clean the VD in some way before allocating
162 Dynamically Registering VBDs
163 ----------------------------
165 Two scripts are included to make it easy to add VDs to domains.
167 add_vbd_to_dom.py - Creates a VBD corresponding to either a physical
168 device or a virtual disk and adds it as a specified
169 device under the target domain, with either read or
170 write access.
172 remove_vbd_from_dom.py - Removes the VBD associated with a specified device
173 node from the target domain.
175 These scripts are most useful when populating VDs. VDs can't be populated
176 directly, since they don't correspond to real devices. Using:
178 add_vbd_to_dom.py vd:your_vd_id /dev/wherever 0 rw
180 You can make a virtual disk available to DOM0. Sensible devices to map VDs to
181 in DOM0 are the /dev/xvd* nodes, since that makes it obvious that they are Xen
182 virtual devices that don't correspond to real physical devices.
184 You can then format, mount and populate the VD through the nominated device
185 node. When you've finished, use:
187 remove_vbd_from_dom.py /dev/whatever 0
189 To revoke DOM0's access to it. It's then ready for use in a guest domain.
193 You can also use add_vbd_to_dom.py to grant access to a physical device to a
194 guest - you might use this to temporarily share a partition, or to add access
195 to a partition that wasn't granted at boot time. Again, remove_vbd_from_dom.py
196 allows you to revoke access.
198 When playing with VBDs, remember that in general, it is only safe for two
199 domains to have access to a filesystem if they both have read-only access. You
200 shouldn't be trying to share anything which is writeable, even if only by one
201 domain, unless you're really sure you know what you're doing!
205 Walkthrough: Booting a domain from a VD
206 ---------------------------------------
208 As an example, here is a sequence of commands you might use to create a virtual
209 disk, populate it with a root filesystem and boot a domain from it. These
210 steps assume that you've installed the example scripts somewhere on your PATH -
211 if you haven't done that, you'll need to specify a fully qualified pathname in
212 the examples below. The steps also assume that you know how to use the
213 createlinuxdom.py script provided and have already set it up for your local
214 configuration, apart from the virtual disks info.
216 First, if you haven't done so already, you'll initialise the free space pool by
217 adding a real partition to it. The details are stored in the database, so
218 you'll only need to do it once. You can also use this command to add further
219 partitions to the existing free space pool.
221 > vd_format.py /dev/<real partition>
223 Now you'll want to allocate the space for your virtual disk. Do so using the
224 following, specifying the size in megabytes.
226 > vd_create.py <chosen size>
228 At this point, the vd_create.py program will tell you the virtual disk ID.
229 Note it down, as it is how you will identify the virtual device in future.
231 If you don't want the VD to be bootable (i.e. you're booting a domain from some
232 other medium and just want it to be able to access this VD), you can simply add
233 it to the vbds list in your custom createlinuxdom.py (step 5) and then run that
234 script. Any formatting / populating of the VD can be done from that domain.
236 If you want to boot off your new VD as well then you need to populate it with a
237 standard Linux root filesystem. You'll need to temporarily add the VD to DOM0
238 in order to do this. To give DOM0 r/w access to the VD, use the following
239 command line, substituting the ID you got earlier.
241 > add_vbd_to_dom.py vd:<id> /dev/xvda 0 rw
243 This attaches the VD to the device /dev/xvda - you can use other devices if you
244 choose too but with the xvd* devices it's obvious you're using a virtual device.
246 Now make a filesystem on this device, mount it and populate it with a root
247 filesystem. These steps are exactly the same as under normal Linux. When
248 you've finished, unmount the filesystem again.
250 You should now remove the VD from DOM0. This will prevent you accidentally
251 changing it in DOM0, whilst the guest domain is using it.
253 > remove_vbd_from_dom.py /dev/xvda 0
255 It should now be possible to boot a guest domain from the VD. To do this, you
256 should add the VD's details to the vbds list in step 5 of createlinuxdom.py and
257 set the value of rootbit in step 6. For instance, you might add:
259 ('vd:<id>', '/dev/xvda', 'w')
261 To the vbds list in step 5 - this gives the domain writeable access to the VD
262 as if it were the domain's /dev/xvda.
264 Then you would set:
266 rootbit = "root=/dev/xvda ro"
268 In step 6 to tell the kernel where the root filesystem is.
272 Once these variables are set, you can run createlinuxdom.py to start your new
273 domain.