fish: Add MD devices to guestfish device autocompletion.
[libguestfs.git] / align / virt-alignment-scan.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 virt-alignment-scan - Check alignment of virtual machine partitions
6
7 =head1 SYNOPSIS
8
9  virt-alignment-scan [--options] -d domname
10
11  virt-alignment-scan [--options] -a disk.img [-a disk.img ...]
12
13 =head1 DESCRIPTION
14
15 When older operating systems install themselves, the partitioning
16 tools place partitions at a sector misaligned with the underlying
17 storage (commonly the first partition starts on sector C<63>).
18 Misaligned partitions can result in an operating system issuing more
19 I/O than should be necessary.
20
21 The virt-alignment-scan tool checks the alignment of partitions in
22 virtual machines and disk images and warns you if there are alignment
23 problems.
24
25 Currently there is no virt tool for fixing alignment problems.  You
26 can only reinstall the guest operating system.  The following NetApp
27 document summarises the problem and possible solutions:
28 L<http://media.netapp.com/documents/tr-3747.pdf>
29
30 =head1 OUTPUT
31
32 To run this tool on a disk image directly, use the I<-a> option:
33
34  $ virt-alignment-scan -a winxp.img
35  /dev/sda1        32256          512    bad (alignment < 4K)
36
37  $ virt-alignment-scan -a fedora16.img
38  /dev/sda1      1048576         1024K   ok
39  /dev/sda2      2097152         2048K   ok
40  /dev/sda3    526385152         2048K   ok
41
42 To run the tool on a guest known to libvirt, use the I<-d> option and
43 possibly the I<-c> option:
44
45  # virt-alignment-scan -d RHEL5
46  /dev/sda1        32256          512    bad (alignment < 4K)
47  /dev/sda2    106928640          512    bad (alignment < 4K)
48
49  $ virt-alignment-scan -c qemu:///system -d Win7TwoDisks
50  /dev/sda1      1048576         1024K   ok
51  /dev/sda2    105906176         1024K   ok
52  /dev/sdb1        65536           64K   ok
53
54 The output consists of 4 or more whitespace-separated columns.  Only
55 the first 4 columns are signficant if you want to parse this from a
56 program.  The columns are:
57
58 =over 4
59
60 =item col 1
61
62 the device and partition name (eg. C</dev/sda1> meaning the
63 first partition on the first block device)
64
65 =item col 2
66
67 the start of the partition in bytes
68
69 =item col 3
70
71 the alignment in bytes or Kbytes (eg. C<512> or C<4K>)
72
73 =item col 4
74
75 C<ok> if the alignment is best for performance, or C<bad> if the
76 alignment can cause performance problems
77
78 =item cols 5+
79
80 optional free-text explanation.
81
82 =back
83
84 The exit code from the program changes depending on whether poorly
85 aligned partitions were found.  See L</EXIT STATUS> below.
86
87 If you just want the exit code with no output, use the I<-q> option.
88
89 =head1 OPTIONS
90
91 =over 4
92
93 =item B<--help>
94
95 Display brief help.
96
97 =item B<-a> file
98
99 =item B<--add> file
100
101 Add I<file> which should be a disk image from a virtual machine.
102
103 The format of the disk image is auto-detected.  To override this and
104 force a particular format use the I<--format=..> option.
105
106 =item B<-c> URI
107
108 =item B<--connect> URI
109
110 If using libvirt, connect to the given I<URI>.  If omitted, then we
111 connect to the default libvirt hypervisor.
112
113 If you specify guest block devices directly (I<-a>), then libvirt is
114 not used at all.
115
116 =item B<-d> guest
117
118 =item B<--domain> guest
119
120 Add all the disks from the named libvirt guest.  Domain UUIDs can be
121 used instead of names.
122
123 =item B<--format=raw|qcow2|..>
124
125 =item B<--format>
126
127 The default for the I<-a> option is to auto-detect the format of the
128 disk image.  Using this forces the disk format for I<-a> options which
129 follow on the command line.  Using I<--format> with no argument
130 switches back to auto-detection for subsequent I<-a> options.
131
132 For example:
133
134  virt-alignment-scan --format=raw -a disk.img
135
136 forces raw format (no auto-detection) for C<disk.img>.
137
138  virt-alignment-scan --format=raw -a disk.img --format -a another.img
139
140 forces raw format (no auto-detection) for C<disk.img> and reverts to
141 auto-detection for C<another.img>.
142
143 If you have untrusted raw-format guest disk images, you should use
144 this option to specify the disk format.  This avoids a possible
145 security problem with malicious guests (CVE-2010-3851).
146
147 =item B<-q>
148
149 =item B<--quiet>
150
151 Don't produce any output.  Just set the exit code
152 (see L</EXIT STATUS> below).
153
154 =item B<-v>
155
156 =item B<--verbose>
157
158 Enable verbose messages for debugging.
159
160 =item B<-V>
161
162 =item B<--version>
163
164 Display version number and exit.
165
166 =item B<-x>
167
168 Enable tracing of libguestfs API calls.
169
170 =back
171
172 =head1 RECOMMENDED ALIGNMENT
173
174 Operating systems older than Windows 2008 and Linux before ca.2010
175 place the first sector of the first partition at sector 63, with a 512
176 byte sector size.  This happens because of a historical accident.
177 Drives have to report a cylinder / head / sector (CHS) geometry to the
178 BIOS.  The geometry is completely meaningless on modern drives, but it
179 happens that the geometry reported always has 63 sectors per track.
180 The operating system therefore places the first partition at the start
181 of the second "track", at sector 63.
182
183 When the guest OS is virtualized, the host operating system and
184 hypervisor may prefer accesses aligned to one of:
185
186 =over 4
187
188 =item * 512 bytes
189
190 if the host OS uses local storage directly on hard drive partitions,
191 and the hard drive has 512 byte physical sectors.
192
193 =item * 4 Kbytes
194
195 for local storage on new hard drives with 4Kbyte physical sectors; for
196 file-backed storage on filesystems with 4Kbyte block size; or for some
197 types of network-attached storage.
198
199 =item * 64 Kbytes
200
201 for high-end network-attached storage.  This is the optimal block size
202 for some NetApp hardware.
203
204 =item * 1 Mbyte
205
206 see L</1 MB PARTITION ALIGNMENT> below.
207
208 =back
209
210 Partitions which are not aligned correctly to the underlying
211 storage cause extra I/O.  For example:
212
213                        sect#63
214                        +--------------------------+------
215                        |         guest            |
216                        |    filesystem block      |
217  ---+------------------+------+-------------------+-----+---
218     |  host block             |  host block             |
219     |                         |                         |
220  ---+-------------------------+-------------------------+---
221
222 In this example, each time a 4K guest block is read, two blocks on the
223 host must be accessed (so twice as much I/O is done).  When a 4K guest
224 block is written, two host blocks must first be read, the old and new
225 data combined, and the two blocks written back (4x I/O).
226
227 =head2 LINUX HOST BLOCK AND I/O SIZE
228
229 New versions of the Linux kernel expose the physical and logical block
230 size, and minimum and recommended I/O size.
231
232 For a typical consumer hard drive with 512 byte sectors:
233
234  $ cat /sys/block/sda/queue/hw_sector_size
235  512
236  $ cat /sys/block/sda/queue/physical_block_size
237  512
238  $ cat /sys/block/sda/queue/logical_block_size
239  512
240  $ cat /sys/block/sda/queue/minimum_io_size
241  512
242  $ cat /sys/block/sda/queue/optimal_io_size
243  0
244
245 For a new consumer hard drive with 4Kbyte sectors:
246
247  $ cat /sys/block/sda/queue/hw_sector_size
248  4096
249  $ cat /sys/block/sda/queue/physical_block_size
250  4096
251  $ cat /sys/block/sda/queue/logical_block_size
252  4096
253  $ cat /sys/block/sda/queue/minimum_io_size
254  4096
255  $ cat /sys/block/sda/queue/optimal_io_size
256  0
257
258 For a NetApp LUN:
259
260  $ cat /sys/block/sdc/queue/logical_block_size
261  512
262  $ cat /sys/block/sdc/queue/physical_block_size
263  512
264  $ cat /sys/block/sdc/queue/minimum_io_size
265  4096
266  $ cat /sys/block/sdc/queue/optimal_io_size
267  65536
268
269 The NetApp allows 512 byte accesses (but they will be very
270 inefficient), prefers a minimum 4K I/O size, but the optimal I/O size
271 is 64K.
272
273 For detailed information about what these numbers mean, see
274 L<http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/newstorage-iolimits.html>
275
276 [Thanks to Matt Booth for providing 4K drive data.  Thanks to Mike
277 Snitzer for providing NetApp data and additional information.]
278
279 =head2 1 MB PARTITION ALIGNMENT
280
281 Microsoft picked 1 MB as the default alignment for all partitions
282 starting with Windows 2008 Server, and Linux has followed this.
283
284 Assuming 512 byte sectors in the guest, you will now see the first
285 partition starting at sector 2048, and subsequent partitions (if any)
286 will start at a multiple of 2048 sectors.
287
288 1 MB alignment is compatible with all current alignment requirements
289 (4K, 64K) and provides room for future growth in physical block sizes.
290
291 =head2 SETTING ALIGNMENT
292
293 L<virt-resize(1)> can change the alignment of the partitions of some
294 guests.  Currently it can fully align all the partitions of all
295 Windows guests, and it will fix the bootloader where necessary.  For
296 Linux guests, it can align the second and subsequent partitions, so
297 the majority of OS accesses except at boot will be aligned.
298
299 Another way to correct partition alignment problems is to reinstall
300 your guest operating systems.  If you install operating systems from
301 templates, ensure these have correct partition alignment too.
302
303 For older versions of Windows, the following NetApp document contains
304 useful information: L<http://media.netapp.com/documents/tr-3747.pdf>
305
306 For Red Hat Enterprise Linux E<le> 5, use a Kickstart script that
307 contains an explicit C<%pre> section that creates aligned partitions
308 using L<parted(8)>.  Do not use the Kickstart C<part> command.  The
309 NetApp document above contains an example.
310
311 =head1 SHELL QUOTING
312
313 Libvirt guest names can contain arbitrary characters, some of which
314 have meaning to the shell such as C<#> and space.  You may need to
315 quote or escape these characters on the command line.  See the shell
316 manual page L<sh(1)> for details.
317
318 =head1 EXIT STATUS
319
320 This program returns:
321
322 =over 4
323
324 =item *
325
326 0
327
328 successful exit, all partitions are aligned E<ge> 64K for best performance
329
330 =item *
331
332 1
333
334 an error scanning the disk image or guest
335
336 =item *
337
338 2
339
340 successful exit, some partitions have alignment E<lt> 64K which can result
341 in poor performance on high end network storage
342
343 =item *
344
345 3
346
347 successful exit, some partitions have alignment E<lt> 4K which can result
348 in poor performance on most hypervisors
349
350 =back
351
352 =head1 SEE ALSO
353
354 L<guestfs(3)>,
355 L<guestfish(1)>,
356 L<virt-filesystems(1)>,
357 L<virt-rescue(1)>,
358 L<virt-resize(1)>,
359 L<http://libguestfs.org/>.
360
361 =head1 AUTHOR
362
363 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
364
365 =head1 COPYRIGHT
366
367 Copyright (C) 2011 Red Hat Inc.
368
369 This program is free software; you can redistribute it and/or modify
370 it under the terms of the GNU General Public License as published by
371 the Free Software Foundation; either version 2 of the License, or
372 (at your option) any later version.
373
374 This program is distributed in the hope that it will be useful,
375 but WITHOUT ANY WARRANTY; without even the implied warranty of
376 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
377 GNU General Public License for more details.
378
379 You should have received a copy of the GNU General Public License
380 along with this program; if not, write to the Free Software
381 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.