virt-alignment-scan: More information in man page.

Thanks Mike Snitzer.

diff --git a/align/virt-alignment-scan.pod b/align/virt-alignment-scan.pod
index dff587b..e5e7e31 100755 (executable)
--- a/align/virt-alignment-scan.pod
+++ b/align/virt-alignment-scan.pod
@@ -24,9 +24,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 +171,136 @@ 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 hard drive with 512 byte sectors:
+
+ $ 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 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.
+
+[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
+
+Currently there is no virt tool for fixing alignment problems in
+guests.  This is a difficult problem to fix because simply moving
+partitions around breaks the bootloader, necessitating either manual
+reinstallation of the bootloader using a rescue disk, or complex and
+error-prone hacks.
+
+L<virt-resize(1)> does not change the alignment of the first
+partition, but it does align the second and subsequent partitions to a
+multiple of 64 or 128 sectors (depending on the version of
+virt-resize, 128 in virt-resize E<ge> 1.13.19).  For operating systems
+that have a separate boot partition, virt-resize could be used to
+align the main OS partition, so that the majority of OS accesses
+except at boot will be aligned.
+
+The easiest 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 +314,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 +347,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