plugins/guestfs/nbdkit-guestfs-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-guestfs-plugin - nbdkit libguestfs plugin
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit [-r] guestfs
   8    [disk=DISK] [domain=DOMAIN] [format=FORMAT] [connect=URI]
   9    [mount=inspect|MOUNT] [trace=on] [debug=on] export=DEVICE|FILE
  10
  11 =head1 WARNING
  12
  13 Using nbdkit-guestfs-plugin in read-write mode on live virtual
  14 machines can be dangerous, potentially causing disk corruption.  Use
  15 the I<-r> (read-only) option to use this plugin safely if the disk
  16 image or virtual machine might be live.
  17
  18 =head1 EXAMPLES
  19
  20 Export the first partition I<inside> a disk image called C<disk.img>,
  21 and allow writes:
  22
  23  nbdkit guestfs disk=disk.img export=/dev/sda1
  24
  25 Export a disk image which is located I<inside> a libvirt guest called
  26 C<Guest>, read-only (I<-r> option):
  27
  28  nbdkit -r guestfs domain=Guest mount=inspect export=/images/disk.img
  29
  30 =head1 DESCRIPTION
  31
  32 C<nbdkit-guestfs-plugin> is an L<nbdkit(1)> plugin that lets you
  33 access the contents of disk images over NBD.  There are many weird and
  34 wonderful uses for this, and this man page only covers the simpler
  35 ones.
  36
  37 The parameters control:
  38
  39 =over 4
  40
  41 =item *
  42
  43 Which disk(s) are added to libguestfs.  Specifically C<disk=DISK> and
  44 C<domain=DOMAIN> add a single disk or all the disks from a particular
  45 libvirt guest.
  46
  47 =item *
  48
  49 What, if any, filesystems inside the disk image / guest have to be
  50 mounted.  Use C<mount=inspect> to do this automatically (like
  51 L<guestfish(1)> I<-i> option), else mount individual filesystems.
  52
  53 =item *
  54
  55 What device or file I<from inside the disk image or guest> you want to
  56 export over NBD.  Use C<export=DEVICE|FILE> to specify the thing that
  57 you want to export.
  58
  59 =item *
  60
  61 Use the I<-r> option to export read-only.  The default is read-write.
  62
  63 =back
  64
  65 =head1 PARAMETERS
  66
  67 =over 4
  68
  69 =item B<connect=>URI
  70
  71 This optional parameter specifies the libvirt connection URI.  This is
  72 only used with the C<domain> parameter.
  73
  74 =item B<debug=on>
  75
  76 Enable full debugging of libguestfs.  Note you'll probably also have
  77 to use the L<nbdkit(1)> option I<-v> in order to see the messages.
  78
  79 =item B<disk=>DISK
  80
  81 Add the named disk image.  You may specify this option multiple times.
  82
  83 =item B<domain=>DOMAIN
  84
  85 Add the disk(s) from the libvirt guest called C<DOMAIN>.
  86
  87 =item B<export=>DEVICE
  88
  89 =item B<export=>FILE
  90
  91 Export C<DEVICE> or C<FILE> (from inside the disk image or guest) over
  92 NBD.
  93
  94 Device names are the usual libguestfs names like F</dev/sda1> (meaning
  95 the first partition of the first disk), or F</dev/VG/LV> (a logical
  96 volume), or RAID arrays etc.  The device name should not be confused
  97 with host devices.
  98
  99 Filenames are similarly those located inside the guest or disk image,
 100 and always start with a C</> character (even for Windows guests).
 101
 102 B<Exports are writable by default>.  Use the I<-r> option to make them
 103 read-only.  B<Exporting read-write a live disk image or virtual
 104 machine will probably cause disk corruption>.
 105
 106 =item B<format=>FORMAT
 107
 108 This can be used to specify the format of the disk.  Use it B<before>
 109 the C<disk=DISK> argument.  It works like the I<--format> option of
 110 L<guestfish(1)>.
 111
 112 =item B<mount=inspect>
 113
 114 Use guest inspection to mount disks.  This is like C<guestfish -i>.
 115
 116 =item B<mount=>DEV
 117
 118 =item B<mount=>DEVB<:>MOUNTPOINT
 119
 120 Mount C<DEV> from inside the guest on C<MOUNTPOINT> (defaults to
 121 F</>).  This is like C<guestfish -m>.
 122
 123 =item B<trace=on>
 124
 125 Enable tracing of libguestfs calls.  Note you'll probably also have to
 126 use the L<nbdkit(1)> option I<-v> in order to see the messages.
 127
 128 =back
 129
 130 =head1 WORKED EXAMPLES
 131
 132 =head2 Exporting a partition or logical volume inside a disk image
 133
 134 L<disk.img> is a host file that contains partitions or LVM logical
 135 volumes.  Use the C<disk=disk.img> option to add the disk.  Because
 136 you don't want to access filesystem contents, C<mount=...> is not
 137 needed.
 138
 139  nbdkit guestfs disk=disk.img export=/dev/sda1
 140
 141 =for paragraph
 142
 143  nbdkit guestfs disk=disk.img export=/dev/VG/LV
 144
 145 Use L<virt-filesystems(1)> to find out what devices, partitions, LVs,
 146 filesystems etc a disk image contains.
 147
 148 =head2 Exporting a partition or logical volume inside guest
 149
 150 L<Guest> is the name (in libvirt) of a guest.  Since the guest might
 151 be live, we use the I<-r> option to open the guest read-only.  Because
 152 you don't want to access filesystem contents, C<mount=...> is not
 153 needed.
 154
 155  nbdkit -r guestfs domain=Guest export=/dev/sda1
 156
 157 =for paragraph
 158
 159  nbdkit -r guestfs domain=Guest export=/dev/VG/LV
 160
 161 =head2 Exporting a file inside a disk image
 162
 163 L<disk.img> is a partitioned disk image with one filesystem that
 164 contains a file that we want to export.  Use the C<disk=disk.img>
 165 option to add the disk, and C<mount=/dev/sda1> to specify the
 166 filesystem in the disk image.  Use C<export=/image> to specify the
 167 name of the file in that filesystem that we want to export.
 168
 169  nbdkit guestfs disk=disk.img mount=/dev/sda1 export=/image
 170
 171 =head2 Exporting a file inside a virtual machine disk image
 172
 173 L<windows.img> is the disk from a Windows virtual machine.  Use the
 174 C<disk=windows.img> option to add the disk, and C<mount=inspect> to
 175 auto-mount the filesystem(s) in the disk image.  Use
 176 C<export=/Users/rich/AppData/image> to specify the name of the file
 177 from the guest that we want to export.
 178
 179  nbdkit guestfs disk=windows.img mount=inspect \
 180    export=/Users/rich/AppData/image
 181
 182 =head1 DEBUGGING
 183
 184 To debug this plugin, use the following options:
 185
 186  nbdkit -f -v guestfs debug=on trace=on [...]
 187
 188 This enables libguestfs debugging and tracing (see L<guestfs-faq(1)>).
 189 It also ensures that the messages are displayed by nbdkit (because of
 190 I<-f> and I<-v>).
 191
 192 =head1 FILES
 193
 194 =over 4
 195
 196 =item F<$plugindir/nbdkit-guestfs-plugin.so>
 197
 198 The plugin.
 199
 200 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 201
 202 =back
 203
 204 =head1 VERSION
 205
 206 C<nbdkit-guestfs-plugin> first appeared in nbdkit 1.2.
 207
 208 =head1 SEE ALSO
 209
 210 L<nbdkit(1)>,
 211 L<nbdkit-plugin(3)>,
 212 L<guestfish(1)>,
 213 L<guestfs(3)>,
 214 L<virt-filesystems(1)>,
 215 L<http://libguestfs.org>.
 216
 217 =head1 AUTHORS
 218
 219 Richard W.M. Jones
 220
 221 =head1 COPYRIGHT
 222
 223 Copyright Red Hat