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.