virt-bmap.pod

   1 =head1 NAME
   2
   3 virt-bmap - construct a map of disk blocks to files and display files accessed by a guest on boot
   4
   5 =head1 SUMMARY
   6
   7  virt-bmap [-o bmap] [--format raw|qcow2|...] disk.img
   8
   9  nbdkit -f bmaplogger file=disk.img [bmap=bmap] [logfile=logfile] \
  10      --run ' qemu-kvm -m 2048 -hda $nbd '
  11
  12 =head1 DESCRIPTION
  13
  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.
  17
  18 =head2 virt-bmap: Construct block map from disk image
  19
  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:
  23
  24  virt-bmap --format raw disk.img
  25
  26 =head2 Output block map file
  27
  28 The output block map (default name: C<bmap>) is a simple text file
  29 which maps disk ranges to files.
  30
  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.
  34
  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
  39
  40 The first four columns are:
  41
  42 =over 4
  43
  44 =item *
  45
  46 the disk image index (always C<1> in the current implementation),
  47
  48 =item *
  49
  50 the starting byte offset,
  51
  52 =item *
  53
  54 the ending byte offset + 1
  55
  56 =item *
  57
  58 the object type:
  59
  60 =over 4
  61
  62 =item C<'v'>
  63
  64 whole device
  65
  66 =item C<'p'>
  67
  68 partition
  69
  70 =item C<'l'>
  71
  72 (lowercase L) logical volume
  73
  74 =item C<'d'>
  75
  76 directory
  77
  78 =item C<'f'>
  79
  80 file
  81
  82 =back
  83
  84 =back
  85
  86 The following column(s) identify the file or object.
  87
  88 =head2 Notes on disk format
  89
  90 The virt-bmap tool does I<not> auto-detect the disk format: you have
  91 to specify the correct format.
  92
  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)>.
 100
 101 =head2 bmaplogger: nbdkit plugin to observe file accesses
 102
 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:
 106
 107  nbdkit -f bmaplogger file=disk.img bmap=bmap \
 108      --run ' qemu-kvm -m 2048 -hda $nbd '
 109
 110 =head1 VIRT-BMAP OPTIONS
 111
 112 =over 4
 113
 114 =item B<-f> raw|qcow|...
 115
 116 =item B<--format> raw|qcow|...
 117
 118 Set the format of the input disk image.  The default is C<raw>.
 119
 120 See L</Notes on disk format> above.
 121
 122 =item B<--help>
 123
 124 Display brief help message and exit.
 125
 126 =item B<-o> FILENAME
 127
 128 =item B<--output> FILENAME
 129
 130 Write the output (block map) to the named file.  The default is a file
 131 called C<bmap> in the current directory.
 132
 133 =item B<-V>
 134
 135 =item B<--version>
 136
 137 Display version number and exit.
 138
 139 =back
 140
 141 =head1 BMAPLOGGER OPTIONS
 142
 143 This section documents the bmaplogger plugin options.  For general
 144 nbdkit options see L<nbdkit(1)>.
 145
 146 =over 4
 147
 148 =item B<file=>disk.img
 149
 150 (Required)
 151
 152 The disk image.
 153
 154 =item B<bmap=>BMAP
 155
 156 (Optional: defaults to C<bmap>)
 157
 158 The block map, previously prepared using C<virt-bmap>, and
 159 corresponding to the same disk image specified in C<file=...>
 160
 161 =item B<logfile=>FILENAME
 162
 163 (Optional: defaults to stdout)
 164
 165 Send the log output to a file.
 166
 167 =back
 168
 169 =head1 SEE ALSO
 170
 171 L<nbdkit(1)>,
 172 L<nbdkit-plugin(1)>,
 173 L<guestfs(3)>,
 174 L<qemu-img(1)>,
 175 L<http://libguestfs.org/>,
 176 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
 177
 178 =head1 AUTHORS
 179
 180 Richard W.M. Jones <rjones @ redhat . com>
 181
 182 =head1 COPYRIGHT
 183
 184 (C) Copyright 2014 Red Hat Inc.
 185
 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.
 190
 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.
 195
 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.