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

Thanks Mike Snitzer.

1 files changed, 147 insertions, 7 deletions

diff --git a/align/virt-alignment-scan.pod b/align/virt-alignment-scan.pod
index dff587b5..e5e7e311 100755
--- 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.
 
-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
@@ -171,6 +171,136 @@ Enable tracing of libguestfs API calls.
 
 =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
@@ -184,20 +314,28 @@ This program returns:
 
 =over 4
 
-=item code 0
+=item *
+
+0
 
 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
 
-=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
 
-=item code 3
+=item *
+
+3
 
 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<virt-rescue(1)>,
+L<virt-resize(1)>,
 L<http://libguestfs.org/>.
 
 =head1 AUTHOR