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 [Thanks to Mike Snitzer for providing NetApp data and additional
 261 information.]
 262
 263 =head2 1 MB PARTITION ALIGNMENT
 264
 265 Microsoft picked 1 MB as the default alignment for all partitions
 266 starting with Windows 2008 Server, and Linux has followed this.
 267
 268 Assuming 512 byte sectors in the guest, you will now see the first
 269 partition starting at sector 2048, and subsequent partitions (if any)
 270 will start at a multiple of 2048 sectors.
 271
 272 1 MB alignment is compatible with all current alignment requirements
 273 (4K, 64K) and provides room for future growth in physical block sizes.
 274
 275 =head2 SETTING ALIGNMENT
 276
 277 Currently there is no virt tool for fixing alignment problems in
 278 guests.  This is a difficult problem to fix because simply moving
 279 partitions around breaks the bootloader, necessitating either manual
 280 reinstallation of the bootloader using a rescue disk, or complex and
 281 error-prone hacks.
 282
 283 L<virt-resize(1)> does not change the alignment of the first
 284 partition, but it does align the second and subsequent partitions to a
 285 multiple of 64 or 128 sectors (depending on the version of
 286 virt-resize, 128 in virt-resize E<ge> 1.13.19).  For operating systems
 287 that have a separate boot partition, virt-resize could be used to
 288 align the main OS partition, so that the majority of OS accesses
 289 except at boot will be aligned.
 290
 291 The easiest way to correct partition alignment problems is to
 292 reinstall your guest operating systems.  If you install operating
 293 systems from templates, ensure these have correct partition alignment
 294 too.
 295
 296 For older versions of Windows, the following NetApp document contains
 297 useful information: L<http://media.netapp.com/documents/tr-3747.pdf>
 298
 299 For Red Hat Enterprise Linux E<le> 5, use a Kickstart script that
 300 contains an explicit C<%pre> section that creates aligned partitions
 301 using L<parted(8)>.  Do not use the Kickstart C<part> command.  The
 302 NetApp document above contains an example.
 303
 304 =head1 SHELL QUOTING
 305
 306 Libvirt guest names can contain arbitrary characters, some of which
 307 have meaning to the shell such as C<#> and space.  You may need to
 308 quote or escape these characters on the command line.  See the shell
 309 manual page L<sh(1)> for details.
 310
 311 =head1 EXIT STATUS
 312
 313 This program returns:
 314
 315 =over 4
 316
 317 =item *
 318
 319 0
 320
 321 successful exit, all partitions are aligned E<ge> 64K for best performance
 322
 323 =item *
 324
 325 1
 326
 327 an error scanning the disk image or guest
 328
 329 =item *
 330
 331 2
 332
 333 successful exit, some partitions have alignment E<lt> 64K which can result
 334 in poor performance on high end network storage
 335
 336 =item *
 337
 338 3
 339
 340 successful exit, some partitions have alignment E<lt> 4K which can result
 341 in poor performance on most hypervisors
 342
 343 =back
 344
 345 =head1 SEE ALSO
 346
 347 L<guestfs(3)>,
 348 L<guestfish(1)>,
 349 L<virt-filesystems(1)>,
 350 L<virt-rescue(1)>,
 351 L<virt-resize(1)>,
 352 L<http://libguestfs.org/>.
 353
 354 =head1 AUTHOR
 355
 356 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 357
 358 =head1 COPYRIGHT
 359
 360 Copyright (C) 2011 Red Hat Inc.
 361
 362 This program is free software; you can redistribute it and/or modify
 363 it under the terms of the GNU General Public License as published by
 364 the Free Software Foundation; either version 2 of the License, or
 365 (at your option) any later version.
 366
 367 This program is distributed in the hope that it will be useful,
 368 but WITHOUT ANY WARRANTY; without even the implied warranty of
 369 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 370 GNU General Public License for more details.
 371
 372 You should have received a copy of the GNU General Public License
 373 along with this program; if not, write to the Free Software
 374 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.