daemon: Don't use files with fixed names in /tmp (thanks Steve Kemp).
[libguestfs.git] / align / virt-alignment-scan.pod
index dff587b..601c5e8 100755 (executable)
@@ -6,8 +6,6 @@ virt-alignment-scan - Check alignment of virtual machine partitions
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 
- virt-alignment-scan [--options]
-
  virt-alignment-scan [--options] -d domname
 
  virt-alignment-scan [--options] -a disk.img [-a disk.img ...]
  virt-alignment-scan [--options] -d domname
 
  virt-alignment-scan [--options] -a disk.img [-a disk.img ...]
@@ -24,9 +22,9 @@ The virt-alignment-scan tool checks the alignment of partitions in
 virtual machines and disk images and warns you if there are alignment
 problems.
 
 virtual machines and disk images and warns you if there are alignment
 problems.
 
-Currently there is no virt tool for fixing alignment problems, except
-to reinstall the operating system.  The following NetApp document
-summarises the problem and possible solutions:
+Currently there is no virt tool for fixing alignment problems.  You
+can only reinstall the guest operating system.  The following NetApp
+document summarises the problem and possible solutions:
 L<http://media.netapp.com/documents/tr-3747.pdf>
 
 =head1 OUTPUT
 L<http://media.netapp.com/documents/tr-3747.pdf>
 
 =head1 OUTPUT
@@ -171,6 +169,145 @@ Enable tracing of libguestfs API calls.
 
 =back
 
 
 =back
 
+=head1 RECOMMENDED ALIGNMENT
+
+Operating systems older than Windows 2008 and Linux before ca.2010
+place the first sector of the first partition at sector 63, with a 512
+byte sector size.  This happens because of a historical accident.
+Drives have to report a cylinder / head / sector (CHS) geometry to the
+BIOS.  The geometry is completely meaningless on modern drives, but it
+happens that the geometry reported always has 63 sectors per track.
+The operating system therefore places the first partition at the start
+of the second "track", at sector 63.
+
+When the guest OS is virtualized, the host operating system and
+hypervisor may prefer accesses aligned to one of:
+
+=over 4
+
+=item * 512 bytes
+
+if the host OS uses local storage directly on hard drive partitions,
+and the hard drive has 512 byte physical sectors.
+
+=item * 4 Kbytes
+
+for local storage on new hard drives with 4Kbyte physical sectors; for
+file-backed storage on filesystems with 4Kbyte block size; or for some
+types of network-attached storage.
+
+=item * 64 Kbytes
+
+for high-end network-attached storage.  This is the optimal block size
+for some NetApp hardware.
+
+=item * 1 Mbyte
+
+see L</1 MB PARTITION ALIGNMENT> below.
+
+=back
+
+Partitions which are not aligned correctly to the underlying
+storage cause extra I/O.  For example:
+
+                       sect#63
+                       +--------------------------+------
+                       |         guest            |
+                       |    filesystem block      |
+ ---+------------------+------+-------------------+-----+---
+    |  host block             |  host block             |
+    |                         |                         |
+ ---+-------------------------+-------------------------+---
+
+In this example, each time a 4K guest block is read, two blocks on the
+host must be accessed (so twice as much I/O is done).  When a 4K guest
+block is written, two host blocks must first be read, the old and new
+data combined, and the two blocks written back (4x I/O).
+
+=head2 LINUX HOST BLOCK AND I/O SIZE
+
+New versions of the Linux kernel expose the physical and logical block
+size, and minimum and recommended I/O size.
+
+For a typical consumer hard drive with 512 byte sectors:
+
+ $ cat /sys/block/sda/queue/hw_sector_size
+ 512
+ $ cat /sys/block/sda/queue/physical_block_size
+ 512
+ $ cat /sys/block/sda/queue/logical_block_size
+ 512
+ $ cat /sys/block/sda/queue/minimum_io_size
+ 512
+ $ cat /sys/block/sda/queue/optimal_io_size
+ 0
+
+For a new consumer hard drive with 4Kbyte sectors:
+
+ $ cat /sys/block/sda/queue/hw_sector_size
+ 4096
+ $ cat /sys/block/sda/queue/physical_block_size
+ 4096
+ $ cat /sys/block/sda/queue/logical_block_size
+ 4096
+ $ cat /sys/block/sda/queue/minimum_io_size
+ 4096
+ $ cat /sys/block/sda/queue/optimal_io_size
+ 0
+
+For a NetApp LUN:
+
+ $ cat /sys/block/sdc/queue/logical_block_size
+ 512
+ $ cat /sys/block/sdc/queue/physical_block_size
+ 512
+ $ cat /sys/block/sdc/queue/minimum_io_size
+ 4096
+ $ cat /sys/block/sdc/queue/optimal_io_size
+ 65536
+
+The NetApp allows 512 byte accesses (but they will be very
+inefficient), prefers a minimum 4K I/O size, but the optimal I/O size
+is 64K.
+
+For detailed information about what these numbers mean, see
+L<http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/newstorage-iolimits.html>
+
+[Thanks to Matt Booth for providing 4K drive data.  Thanks to Mike
+Snitzer for providing NetApp data and additional information.]
+
+=head2 1 MB PARTITION ALIGNMENT
+
+Microsoft picked 1 MB as the default alignment for all partitions
+starting with Windows 2008 Server, and Linux has followed this.
+
+Assuming 512 byte sectors in the guest, you will now see the first
+partition starting at sector 2048, and subsequent partitions (if any)
+will start at a multiple of 2048 sectors.
+
+1 MB alignment is compatible with all current alignment requirements
+(4K, 64K) and provides room for future growth in physical block sizes.
+
+=head2 SETTING ALIGNMENT
+
+L<virt-resize(1)> can change the alignment of the partitions of some
+guests.  Currently it can fully align all the partitions of all
+Windows guests, and it will fix the bootloader where necessary.  For
+Linux guests, it can align the second and subsequent partitions, so
+the majority of OS accesses except at boot will be aligned.
+
+Another way to correct partition alignment problems is to reinstall
+your guest operating systems.  If you install operating systems from
+templates, ensure these have correct partition alignment too.
+
+For older versions of Windows, the following NetApp document contains
+useful information: L<http://media.netapp.com/documents/tr-3747.pdf>
+
+For Red Hat Enterprise Linux E<le> 5, use a Kickstart script that
+contains an explicit C<%pre> section that creates aligned partitions
+using L<parted(8)>.  Do not use the Kickstart C<part> command.  The
+NetApp document above contains an example.
+
 =head1 SHELL QUOTING
 
 Libvirt guest names can contain arbitrary characters, some of which
 =head1 SHELL QUOTING
 
 Libvirt guest names can contain arbitrary characters, some of which
@@ -184,20 +321,28 @@ This program returns:
 
 =over 4
 
 
 =over 4
 
-=item code 0
+=item *
+
+0
 
 successful exit, all partitions are aligned E<ge> 64K for best performance
 
 
 successful exit, all partitions are aligned E<ge> 64K for best performance
 
-=item code 1
+=item *
+
+1
 
 an error scanning the disk image or guest
 
 
 an error scanning the disk image or guest
 
-=item code 2
+=item *
+
+2
 
 successful exit, some partitions have alignment E<lt> 64K which can result
 in poor performance on high end network storage
 
 
 successful exit, some partitions have alignment E<lt> 64K which can result
 in poor performance on high end network storage
 
-=item code 3
+=item *
+
+3
 
 successful exit, some partitions have alignment E<lt> 4K which can result
 in poor performance on most hypervisors
 
 successful exit, some partitions have alignment E<lt> 4K which can result
 in poor performance on most hypervisors
@@ -209,6 +354,8 @@ in poor performance on most hypervisors
 L<guestfs(3)>,
 L<guestfish(1)>,
 L<virt-filesystems(1)>,
 L<guestfs(3)>,
 L<guestfish(1)>,
 L<virt-filesystems(1)>,
+L<virt-rescue(1)>,
+L<virt-resize(1)>,
 L<http://libguestfs.org/>.
 
 =head1 AUTHOR
 L<http://libguestfs.org/>.
 
 =head1 AUTHOR