1virt-alignment-scan(1)      Virtualization Support      virt-alignment-scan(1)
2
3
4

NAME

6       virt-alignment-scan - Check alignment of virtual machine partitions
7

SYNOPSIS

9        virt-alignment-scan [--options] -d domname
10
11        virt-alignment-scan [--options] -a disk.img [-a disk.img ...]
12
13        virt-alignment-scan [--options]
14

DESCRIPTION

16       When older operating systems install themselves, the partitioning tools
17       place partitions at a sector misaligned with the underlying storage
18       (commonly the first partition starts on sector 63).  Misaligned
19       partitions can result in an operating system issuing more I/O than
20       should be necessary.
21
22       The virt-alignment-scan tool checks the alignment of partitions in
23       virtual machines and disk images and warns you if there are alignment
24       problems.
25
26       Currently there is no virt tool for fixing alignment problems.  You can
27       only reinstall the guest operating system.  The following NetApp
28       document summarises the problem and possible solutions:
29       http://media.netapp.com/documents/tr-3747.pdf
30

OUTPUT

32       To run this tool on a disk image directly, use the -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 -d option and
43       possibly the -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       Run virt-alignment-scan without any -a or -d options to scan all
55       libvirt domains.
56
57        # virt-alignment-scan
58        F16x64:/dev/sda1      1048576         1024K   ok
59        F16x64:/dev/sda2      2097152         2048K   ok
60        F16x64:/dev/sda3    526385152         2048K   ok
61
62       The output consists of 4 or more whitespace-separated columns.  Only
63       the first 4 columns are significant if you want to parse this from a
64       program.  The columns are:
65
66       col 1
67           The device and partition name (eg. /dev/sda1 meaning the first
68           partition on the first block device).
69
70           When listing all libvirt domains (no -a or -d option given) this
71           column is prefixed by the libvirt name or UUID (if --uuid is
72           given).  eg: "WinXP:/dev/sda1"
73
74       col 2
75           the start of the partition in bytes
76
77       col 3
78           the alignment in bytes or Kbytes (eg. 512 or "4K")
79
80       col 4
81           "ok" if the alignment is best for performance, or "bad" if the
82           alignment can cause performance problems
83
84       cols 5+
85           optional free-text explanation.
86
87       The exit code from the program changes depending on whether poorly
88       aligned partitions were found.  See "EXIT STATUS" below.
89
90       If you just want the exit code with no output, use the -q option.
91

OPTIONS

93       --help
94           Display brief help.
95
96       -a file
97       --add file
98           Add file which should be a disk image from a virtual machine.
99
100           The format of the disk image is auto-detected.  To override this
101           and force a particular format use the --format=.. option.
102
103       -a URI
104       --add URI
105           Add a remote disk.  See "ADDING REMOTE STORAGE" in guestfish(1).
106
107       -c URI
108       --connect URI
109           If using libvirt, connect to the given URI.  If omitted, then we
110           connect to the default libvirt hypervisor.
111
112           If you specify guest block devices directly (-a), then libvirt is
113           not used at all.
114
115       -d guest
116       --domain guest
117           Add all the disks from the named libvirt guest.  Domain UUIDs can
118           be used instead of names.
119
120       --format=raw|qcow2|..
121       --format
122           The default for the -a option is to auto-detect the format of the
123           disk image.  Using this forces the disk format for -a options which
124           follow on the command line.  Using --format with no argument
125           switches back to auto-detection for subsequent -a options.
126
127           For example:
128
129            virt-alignment-scan --format=raw -a disk.img
130
131           forces raw format (no auto-detection) for disk.img.
132
133            virt-alignment-scan --format=raw -a disk.img --format -a another.img
134
135           forces raw format (no auto-detection) for disk.img and reverts to
136           auto-detection for another.img.
137
138           If you have untrusted raw-format guest disk images, you should use
139           this option to specify the disk format.  This avoids a possible
140           security problem with malicious guests (CVE-2010-3851).
141
142       -P nr_threads
143           Since libguestfs 1.22, virt-alignment-scan is multithreaded and
144           examines guests in parallel.  By default the number of threads to
145           use is chosen based on the amount of free memory available at the
146           time that virt-alignment-scan is started.  You can force virt-
147           alignment-scan to use at most "nr_threads" by using the -P option.
148
149           Note that -P 0 means to autodetect, and -P 1 means to use a single
150           thread.
151
152       -q
153       --quiet
154           Don’t produce any output.  Just set the exit code (see "EXIT
155           STATUS" below).
156
157       --uuid
158           Print UUIDs instead of names.  This is useful for following a guest
159           even when the guest is migrated or renamed, or when two guests
160           happen to have the same name.
161
162           This option only applies when listing all libvirt domains (when no
163           -a or -d options are specified).
164
165       -v
166       --verbose
167           Enable verbose messages for debugging.
168
169       -V
170       --version
171           Display version number and exit.
172
173       -x  Enable tracing of libguestfs API calls.
174
176       Operating systems older than Windows 2008 and Linux before ca.2010
177       place the first sector of the first partition at sector 63, with a 512
178       byte sector size.  This happens because of a historical accident.
179       Drives have to report a cylinder / head / sector (CHS) geometry to the
180       BIOS.  The geometry is completely meaningless on modern drives, but it
181       happens that the geometry reported always has 63 sectors per track.
182       The operating system therefore places the first partition at the start
183       of the second "track", at sector 63.
184
185       When the guest OS is virtualized, the host operating system and
186       hypervisor may prefer accesses aligned to one of:
187
188       ·   512 bytes
189
190           if the host OS uses local storage directly on hard drive
191           partitions, and the hard drive has 512 byte physical sectors.
192
193       ·   4 Kbytes
194
195           for local storage on new hard drives with 4Kbyte physical sectors;
196           for file-backed storage on filesystems with 4Kbyte block size; or
197           for some types of network-attached storage.
198
199       ·   64 Kbytes
200
201           for high-end network-attached storage.  This is the optimal block
202           size for some NetApp hardware.
203
204       ·   1 Mbyte
205
206           see "1 MB PARTITION ALIGNMENT" below.
207
208       Partitions which are not aligned correctly to the underlying storage
209       cause extra I/O.  For example:
210
211                              sect#63
212                              ┌──────────────────────────┬ ─ ─ ─ ─
213                              │         guest            │
214                              │    filesystem block      │
215         ─ ┬──────────────────┴──────┬───────────────────┴─────┬ ─ ─
216           │  host block             │  host block             │
217           │                         │                         │
218         ─ ┴─────────────────────────┴─────────────────────────┴ ─ ─
219
220       In this example, each time a 4K guest block is read, two blocks on the
221       host must be accessed (so twice as much I/O is done).  When a 4K guest
222       block is written, two host blocks must first be read, the old and new
223       data combined, and the two blocks written back (4x I/O).
224
225   LINUX HOST BLOCK AND I/O SIZE
226       New versions of the Linux kernel expose the physical and logical block
227       size, and minimum and recommended I/O size.
228
229       For a typical consumer hard drive with 512 byte sectors:
230
231        $ cat /sys/block/sda/queue/hw_sector_size
232        512
233        $ cat /sys/block/sda/queue/physical_block_size
234        512
235        $ cat /sys/block/sda/queue/logical_block_size
236        512
237        $ cat /sys/block/sda/queue/minimum_io_size
238        512
239        $ cat /sys/block/sda/queue/optimal_io_size
240        0
241
242       For a new consumer hard drive with 4Kbyte sectors:
243
244        $ cat /sys/block/sda/queue/hw_sector_size
245        4096
246        $ cat /sys/block/sda/queue/physical_block_size
247        4096
248        $ cat /sys/block/sda/queue/logical_block_size
249        4096
250        $ cat /sys/block/sda/queue/minimum_io_size
251        4096
252        $ cat /sys/block/sda/queue/optimal_io_size
253        0
254
255       For a NetApp LUN:
256
257        $ cat /sys/block/sdc/queue/logical_block_size
258        512
259        $ cat /sys/block/sdc/queue/physical_block_size
260        512
261        $ cat /sys/block/sdc/queue/minimum_io_size
262        4096
263        $ cat /sys/block/sdc/queue/optimal_io_size
264        65536
265
266       The NetApp allows 512 byte accesses (but they will be very
267       inefficient), prefers a minimum 4K I/O size, but the optimal I/O size
268       is 64K.
269
270       For detailed information about what these numbers mean, see
271       http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/newstorage-iolimits.html
272
273       [Thanks to Matt Booth for providing 4K drive data.  Thanks to Mike
274       Snitzer for providing NetApp data and additional information.]
275
276   1 MB PARTITION ALIGNMENT
277       Microsoft picked 1 MB as the default alignment for all partitions
278       starting with Windows 2008 Server, and Linux has followed this.
279
280       Assuming 512 byte sectors in the guest, you will now see the first
281       partition starting at sector 2048, and subsequent partitions (if any)
282       will start at a multiple of 2048 sectors.
283
284       1 MB alignment is compatible with all current alignment requirements
285       (4K, 64K) and provides room for future growth in physical block sizes.
286
287   SETTING ALIGNMENT
288       virt-resize(1) can change the alignment of the partitions of some
289       guests.  Currently it can fully align all the partitions of all Windows
290       guests, and it will fix the bootloader where necessary.  For Linux
291       guests, it can align the second and subsequent partitions, so the
292       majority of OS accesses except at boot will be aligned.
293
294       Another way to correct partition alignment problems is to reinstall
295       your guest operating systems.  If you install operating systems from
296       templates, ensure these have correct partition alignment too.
297
298       For older versions of Windows, the following NetApp document contains
299       useful information: http://media.netapp.com/documents/tr-3747.pdf
300
301       For Red Hat Enterprise Linux ≤ 5, use a Kickstart script that contains
302       an explicit %pre section that creates aligned partitions using
303       parted(8).  Do not use the Kickstart "part" command.  The NetApp
304       document above contains an example.
305

EXIT STATUS

307       This program returns:
308
309       ·   0
310
311           successful exit, all partitions are aligned ≥ 64K for best
312           performance
313
314       ·   1
315
316           an error scanning the disk image or guest
317
318       ·   2
319
320           successful exit, some partitions have alignment < 64K which can
321           result in poor performance on high end network storage
322
323       ·   3
324
325           successful exit, some partitions have alignment < 4K which can
326           result in poor performance on most hypervisors
327

SEE ALSO

329       guestfs(3), guestfish(1), virt-filesystems(1), virt-rescue(1),
330       virt-resize(1), http://libguestfs.org/.
331

AUTHOR

333       Richard W.M. Jones http://people.redhat.com/~rjones/
334
336       Copyright (C) 2011 Red Hat Inc.
337

LICENSE

339       This program is free software; you can redistribute it and/or modify it
340       under the terms of the GNU General Public License as published by the
341       Free Software Foundation; either version 2 of the License, or (at your
342       option) any later version.
343
344       This program is distributed in the hope that it will be useful, but
345       WITHOUT ANY WARRANTY; without even the implied warranty of
346       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
347       General Public License for more details.
348
349       You should have received a copy of the GNU General Public License along
350       with this program; if not, write to the Free Software Foundation, Inc.,
351       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
352

BUGS

354       To get a list of bugs against libguestfs, use this link:
355       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
356
357       To report a new bug against libguestfs, use this link:
358       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
359
360       When reporting a bug, please supply:
361
362       ·   The version of libguestfs.
363
364       ·   Where you got libguestfs (eg. which Linux distro, compiled from
365           source, etc)
366
367       ·   Describe the bug accurately and give a way to reproduce it.
368
369       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
370           into the bug report.
371
372
373
374libguestfs-1.38.2                 2018-05-15            virt-alignment-scan(1)
Impressum