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 bmaplogger: nbdkit plugin to observe file accesses
  89
  90 The second tool is an L<nbdkit(1)> plugin called C<bmaplogger>.  Use
  91 this in conjunction with "captive nbdkit" (see L<nbdkit(1)>) to
  92 observe the files accessed by a virtual machine when booting:
  93
  94  nbdkit -f bmaplogger file=disk.img bmap=bmap \
  95      --run ' qemu-kvm -m 2048 -hda $nbd '
  96
  97 =head1 VIRT-BMAP OPTIONS
  98
  99 =over 4
 100
 101 =item B<-f> raw|qcow|...
 102
 103 =item B<--format> raw|qcow|...
 104
 105 Set the format of the input disk image.  The default is C<raw>.
 106
 107 Note this is I<not> auto-detected, you I<have to> specify the
 108 correct format.
 109
 110 =item B<--help>
 111
 112 Display brief help message and exit.
 113
 114 =item B<-o> FILENAME
 115
 116 =item B<--output> FILENAME
 117
 118 Write the output (block map) to the named file.  The default is a file
 119 called C<bmap> in the current directory.
 120
 121 =item B<-V>
 122
 123 =item B<--version>
 124
 125 Display version number and exit.
 126
 127 =back
 128
 129 =head1 BMAPLOGGER OPTIONS
 130
 131 This section documents the bmaplogger plugin options.  For general
 132 nbdkit options see L<nbdkit(1)>.
 133
 134 =over 4
 135
 136 =item B<file=>disk.img
 137
 138 (Required)
 139
 140 The disk image.
 141
 142 =item B<bmap=>BMAP
 143
 144 (Optional: defaults to C<bmap>)
 145
 146 The block map, previously prepared using C<virt-bmap>, and
 147 corresponding to the same disk image specified in C<file=...>
 148
 149 =item B<logfile=>FILENAME
 150
 151 (Optional: defaults to stdout)
 152
 153 Send the log output to a file.
 154
 155 =back
 156
 157 =head1 SEE ALSO
 158
 159 L<nbdkit(1)>,
 160 L<nbdkit-plugin(1)>,
 161 L<guestfs(3)>,
 162 L<http://libguestfs.org/>,
 163 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
 164
 165 =head1 AUTHORS
 166
 167 Richard W.M. Jones <rjones @ redhat . com>
 168
 169 =head1 COPYRIGHT
 170
 171 (C) Copyright 2014 Red Hat Inc.
 172
 173 This program is free software; you can redistribute it and/or modify
 174 it under the terms of the GNU General Public License as published by
 175 the Free Software Foundation; either version 2 of the License, or
 176 (at your option) any later version.
 177
 178 This program is distributed in the hope that it will be useful,
 179 but WITHOUT ANY WARRANTY; without even the implied warranty of
 180 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 181 GNU General Public License for more details.
 182
 183 You should have received a copy of the GNU General Public License
 184 along with this program; if not, write to the Free Software
 185 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.