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]
  10
  11  virt-alignment-scan [--options] -d domname
  12
  13  virt-alignment-scan [--options] -a disk.img [-a disk.img ...]
  14
  15 =head1 DESCRIPTION
  16
  17 When older operating systems install themselves, the partitioning
  18 tools place partitions at a sector misaligned with the underlying
  19 storage (commonly the first partition starts on sector C<63>).
  20 Misaligned partitions can result in an operating system issuing more
  21 I/O than should be necessary.
  22
  23 The virt-alignment-scan tool checks the alignment of partitions in
  24 virtual machines and disk images and warns you if there are alignment
  25 problems.
  26
  27 Currently there is no virt tool for fixing alignment problems, except
  28 to reinstall the operating system.  The following NetApp document
  29 summarises the problem and possible solutions:
  30 L<http://media.netapp.com/documents/tr-3747.pdf>
  31
  32 =head1 OUTPUT
  33
  34 To run this tool on a disk image directly, use the I<-a> option:
  35
  36  $ virt-alignment-scan -a winxp.img
  37  /dev/sda1        32256          512    bad (alignment < 4K)
  38
  39  $ virt-alignment-scan -a fedora16.img
  40  /dev/sda1      1048576         1024K   ok
  41  /dev/sda2      2097152         2048K   ok
  42  /dev/sda3    526385152         2048K   ok
  43
  44 To run the tool on a guest known to libvirt, use the I<-d> option and
  45 possibly the I<-c> option:
  46
  47  # virt-alignment-scan -d RHEL5
  48  /dev/sda1        32256          512    bad (alignment < 4K)
  49  /dev/sda2    106928640          512    bad (alignment < 4K)
  50
  51  $ virt-alignment-scan -c qemu:///system -d Win7TwoDisks
  52  /dev/sda1      1048576         1024K   ok
  53  /dev/sda2    105906176         1024K   ok
  54  /dev/sdb1        65536           64K   ok
  55
  56 The output consists of 4 or more whitespace-separated columns.  Only
  57 the first 4 columns are signficant if you want to parse this from a
  58 program.  The columns are:
  59
  60 =over 4
  61
  62 =item col 1
  63
  64 the device and partition name (eg. C</dev/sda1> meaning the
  65 first partition on the first block device)
  66
  67 =item col 2
  68
  69 the start of the partition in bytes
  70
  71 =item col 3
  72
  73 the alignment in bytes or Kbytes (eg. C<512> or C<4K>)
  74
  75 =item col 4
  76
  77 C<ok> if the alignment is best for performance, or C<bad> if the
  78 alignment can cause performance problems
  79
  80 =item cols 5+
  81
  82 optional free-text explanation.
  83
  84 =back
  85
  86 The exit code from the program changes depending on whether poorly
  87 aligned partitions were found.  See L</EXIT STATUS> below.
  88
  89 If you just want the exit code with no output, use the I<-q> option.
  90
  91 =head1 OPTIONS
  92
  93 =over 4
  94
  95 =item B<--help>
  96
  97 Display brief help.
  98
  99 =item B<-a> file
 100
 101 =item B<--add> file
 102
 103 Add I<file> which should be a disk image from a virtual machine.
 104
 105 The format of the disk image is auto-detected.  To override this and
 106 force a particular format use the I<--format=..> option.
 107
 108 =item B<-c> URI
 109
 110 =item B<--connect> URI
 111
 112 If using libvirt, connect to the given I<URI>.  If omitted, then we
 113 connect to the default libvirt hypervisor.
 114
 115 If you specify guest block devices directly (I<-a>), then libvirt is
 116 not used at all.
 117
 118 =item B<-d> guest
 119
 120 =item B<--domain> guest
 121
 122 Add all the disks from the named libvirt guest.  Domain UUIDs can be
 123 used instead of names.
 124
 125 =item B<--format=raw|qcow2|..>
 126
 127 =item B<--format>
 128
 129 The default for the I<-a> option is to auto-detect the format of the
 130 disk image.  Using this forces the disk format for I<-a> options which
 131 follow on the command line.  Using I<--format> with no argument
 132 switches back to auto-detection for subsequent I<-a> options.
 133
 134 For example:
 135
 136  virt-alignment-scan --format=raw -a disk.img
 137
 138 forces raw format (no auto-detection) for C<disk.img>.
 139
 140  virt-alignment-scan --format=raw -a disk.img --format -a another.img
 141
 142 forces raw format (no auto-detection) for C<disk.img> and reverts to
 143 auto-detection for C<another.img>.
 144
 145 If you have untrusted raw-format guest disk images, you should use
 146 this option to specify the disk format.  This avoids a possible
 147 security problem with malicious guests (CVE-2010-3851).
 148
 149 =item B<-q>
 150
 151 =item B<--quiet>
 152
 153 Don't produce any output.  Just set the exit code
 154 (see L</EXIT STATUS> below).
 155
 156 =item B<-v>
 157
 158 =item B<--verbose>
 159
 160 Enable verbose messages for debugging.
 161
 162 =item B<-V>
 163
 164 =item B<--version>
 165
 166 Display version number and exit.
 167
 168 =item B<-x>
 169
 170 Enable tracing of libguestfs API calls.
 171
 172 =back
 173
 174 =head1 SHELL QUOTING
 175
 176 Libvirt guest names can contain arbitrary characters, some of which
 177 have meaning to the shell such as C<#> and space.  You may need to
 178 quote or escape these characters on the command line.  See the shell
 179 manual page L<sh(1)> for details.
 180
 181 =head1 EXIT STATUS
 182
 183 This program returns:
 184
 185 =over 4
 186
 187 =item code 0
 188
 189 successful exit, all partitions are aligned E<ge> 64K for best performance
 190
 191 =item code 1
 192
 193 an error scanning the disk image or guest
 194
 195 =item code 2
 196
 197 successful exit, some partitions have alignment E<lt> 64K which can result
 198 in poor performance on high end network storage
 199
 200 =item code 3
 201
 202 successful exit, some partitions have alignment E<lt> 4K which can result
 203 in poor performance on most hypervisors
 204
 205 =back
 206
 207 =head1 SEE ALSO
 208
 209 L<guestfs(3)>,
 210 L<guestfish(1)>,
 211 L<virt-filesystems(1)>,
 212 L<http://libguestfs.org/>.
 213
 214 =head1 AUTHOR
 215
 216 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 217
 218 =head1 COPYRIGHT
 219
 220 Copyright (C) 2011 Red Hat Inc.
 221
 222 This program is free software; you can redistribute it and/or modify
 223 it under the terms of the GNU General Public License as published by
 224 the Free Software Foundation; either version 2 of the License, or
 225 (at your option) any later version.
 226
 227 This program is distributed in the hope that it will be useful,
 228 but WITHOUT ANY WARRANTY; without even the implied warranty of
 229 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 230 GNU General Public License for more details.
 231
 232 You should have received a copy of the GNU General Public License
 233 along with this program; if not, write to the Free Software
 234 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.