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