3 virt-bmap - construct a map of disk blocks to files and display files accessed by a guest on boot
7 virt-bmap [-o bmap] [--format raw|qcow2|...] disk.img
9 nbdkit -f bmaplogger file=disk.img [bmap=bmap] [logfile=logfile] \
10 --run ' qemu-kvm -m 2048 -hda $nbd '
14 Virt-bmap is two tools that help you to discover where files and other
15 objects are really located within a virtual machine disk image, and to
16 observe what files a virtual machine accesses when it boots.
18 =head2 virt-bmap: Construct block map from disk image
20 The C<virt-bmap> program takes a disk image, examines it looking for
21 files, directories, partitions and other significant features, and
22 constructs a block map of disk offsets to files. Use it like this:
24 virt-bmap --format raw disk.img
26 =head2 Output block map file
28 The output block map (default name: C<bmap>) is a simple text file
29 which maps disk ranges to files.
31 The mapping is not 1-1. It is possible for multiple files to appear
32 to be mapped to a single disk range, or for disk ranges not to
33 correspond to any object.
35 1 541400 544400 d /dev/sda1 /lost+found
36 1 941000 941400 f /dev/sda1 /.vmlinuz-3.11.10-301.fc20.x86_64.hmac
37 1 941400 961800 f /dev/sda1 /config-3.11.10-301.fc20.x86_64
38 1 961800 995400 f /dev/sda1 /initrd-plymouth.img
40 The first four columns are:
46 the disk image index (always C<1> in the current implementation),
50 the starting byte offset,
54 the ending byte offset + 1
72 (lowercase L) logical volume
86 The following column(s) identify the file or object.
88 =head2 Notes on disk format
90 The virt-bmap tool does I<not> auto-detect the disk format: you have
91 to specify the correct format.
93 Although in theory you can use any disk format, we found that block
94 map detection works much more reliably if the disk is in C<raw>
95 format. With other formats it appears that structures within the
96 format (like the qcow2 header) can confuse disk format detection,
97 resulting in files appearing to be read which are probably not being
98 accessed. Therefore it is recommended that you first convert disks to
99 raw using a tool such as L<qemu-img(1)>.
101 =head2 bmaplogger: nbdkit plugin to observe file accesses
103 The second tool is an L<nbdkit(1)> plugin called C<bmaplogger>. Use
104 this in conjunction with "captive nbdkit" (see L<nbdkit(1)>) to
105 observe the files accessed by a virtual machine when booting:
107 nbdkit -f bmaplogger file=disk.img bmap=bmap \
108 --run ' qemu-kvm -m 2048 -hda $nbd '
110 =head1 VIRT-BMAP OPTIONS
114 =item B<-f> raw|qcow|...
116 =item B<--format> raw|qcow|...
118 Set the format of the input disk image. The default is C<raw>.
120 See L</Notes on disk format> above.
124 Display brief help message and exit.
128 =item B<--output> FILENAME
130 Write the output (block map) to the named file. The default is a file
131 called C<bmap> in the current directory.
137 Display version number and exit.
141 =head1 BMAPLOGGER OPTIONS
143 This section documents the bmaplogger plugin options. For general
144 nbdkit options see L<nbdkit(1)>.
148 =item B<file=>disk.img
156 (Optional: defaults to C<bmap>)
158 The block map, previously prepared using C<virt-bmap>, and
159 corresponding to the same disk image specified in C<file=...>
161 =item B<logfile=>FILENAME
163 (Optional: defaults to stdout)
165 Send the log output to a file.
175 L<http://libguestfs.org/>,
176 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
180 Richard W.M. Jones <rjones @ redhat . com>
184 (C) Copyright 2014 Red Hat Inc.
186 This program is free software; you can redistribute it and/or modify
187 it under the terms of the GNU General Public License as published by
188 the Free Software Foundation; either version 2 of the License, or
189 (at your option) any later version.
191 This program is distributed in the hope that it will be useful,
192 but WITHOUT ANY WARRANTY; without even the implied warranty of
193 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
194 GNU General Public License for more details.
196 You should have received a copy of the GNU General Public License
197 along with this program; if not, write to the Free Software
198 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.