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