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