=head1 NAME

nbdkit-guestfs-plugin - nbdkit libguestfs plugin

=head1 SYNOPSIS

 nbdkit [-r] guestfs
   [disk=DISK] [domain=DOMAIN] [format=FORMAT] [connect=URI]
   [mount=inspect|MOUNT] [trace=on] [debug=on] export=DEVICE|FILE

=head1 WARNING

Using nbdkit-guestfs-plugin in read-write mode on live virtual
machines can be dangerous, potentially causing disk corruption.  Use
the I<-r> (read-only) option to use this plugin safely if the disk
image or virtual machine might be live.

=head1 EXAMPLES

Export the first partition I<inside> a disk image called C<disk.img>,
and allow writes:

 nbdkit guestfs disk=disk.img export=/dev/sda1

Export a disk image which is located I<inside> a libvirt guest called
C<Guest>, read-only (I<-r> option):

 nbdkit -r guestfs domain=Guest mount=inspect export=/images/disk.img

=head1 DESCRIPTION

C<nbdkit-guestfs-plugin> is an L<nbdkit(1)> plugin that lets you
access the contents of disk images over NBD.  There are many weird and
wonderful uses for this, and this man page only covers the simpler
ones.

The parameters control:

=over 4

=item *

Which disk(s) are added to libguestfs.  Specifically C<disk=DISK> and
C<domain=DOMAIN> add a single disk or all the disks from a particular
libvirt guest.

=item *

What, if any, filesystems inside the disk image / guest have to be
mounted.  Use C<mount=inspect> to do this automatically (like
L<guestfish(1)> I<-i> option), else mount individual filesystems.

=item *

What device or file I<from inside the disk image or guest> you want to
export over NBD.  Use C<export=DEVICE|FILE> to specify the thing that
you want to export.

=item *

Use the I<-r> option to export read-only.  The default is read-write.

=back

=head1 PARAMETERS

=over 4

=item B<connect=>URI

This optional parameter specifies the libvirt connection URI.  This is
only used with the C<domain> parameter.

=item B<debug=on>

Enable full debugging of libguestfs.  Note you'll probably also have
to use the L<nbdkit(1)> option I<-v> in order to see the messages.

=item B<disk=>DISK

Add the named disk image.  You may specify this option multiple times.

=item B<domain=>DOMAIN

Add the disk(s) from the libvirt guest called C<DOMAIN>.

=item B<export=>DEVICE

=item B<export=>FILE

Export C<DEVICE> or C<FILE> (from inside the disk image or guest) over
NBD.

Device names are the usual libguestfs names like F</dev/sda1> (meaning
the first partition of the first disk), or F</dev/VG/LV> (a logical
volume), or RAID arrays etc.  The device name should not be confused
with host devices.

Filenames are similarly those located inside the guest or disk image,
and always start with a C</> character (even for Windows guests).

B<Exports are writable by default>.  Use the I<-r> option to make them
read-only.  B<Exporting read-write a live disk image or virtual
machine will probably cause disk corruption>.

=item B<format=>FORMAT

This can be used to specify the format of the disk.  Use it B<before>
the C<disk=DISK> argument.  It works like the I<--format> option of
L<guestfish(1)>.

=item B<mount=inspect>

Use guest inspection to mount disks.  This is like C<guestfish -i>.

=item B<mount=>DEV

=item B<mount=>DEVB<:>MOUNTPOINT

Mount C<DEV> from inside the guest on C<MOUNTPOINT> (defaults to
F</>).  This is like C<guestfish -m>.

=item B<trace=on>

Enable tracing of libguestfs calls.  Note you'll probably also have to
use the L<nbdkit(1)> option I<-v> in order to see the messages.

=back

=head1 WORKED EXAMPLES

=head2 Exporting a partition or logical volume inside a disk image

L<disk.img> is a host file that contains partitions or LVM logical
volumes.  Use the C<disk=disk.img> option to add the disk.  Because
you don't want to access filesystem contents, C<mount=...> is not
needed.

 nbdkit guestfs disk=disk.img export=/dev/sda1

 nbdkit guestfs disk=disk.img export=/dev/VG/LV

Use L<virt-filesystems(1)> to find out what devices, partitions, LVs,
filesystems etc a disk image contains.

=head2 Exporting a partition or logical volume inside guest

L<Guest> is the name (in libvirt) of a guest.  Since the guest might
be live, we use the I<-r> option to open the guest read-only.  Because
you don't want to access filesystem contents, C<mount=...> is not
needed.

 nbdkit -r guestfs domain=Guest export=/dev/sda1

 nbdkit -r guestfs domain=Guest export=/dev/VG/LV

=head2 Exporting a file inside a disk image

L<disk.img> is a partitioned disk image with one filesystem that
contains a file that we want to export.  Use the C<disk=disk.img>
option to add the disk, and C<mount=/dev/sda1> to specify the
filesystem in the disk image.  Use C<export=/image> to specify the
name of the file in that filesystem that we want to export.

 nbdkit guestfs disk=disk.img mount=/dev/sda1 export=/image

=head2 Exporting a file inside a virtual machine disk image

L<windows.img> is the disk from a Windows virtual machine.  Use the
C<disk=windows.img> option to add the disk, and C<mount=inspect> to
auto-mount the filesystem(s) in the disk image.  Use
C<export=/Users/rich/AppData/image> to specify the name of the file
from the guest that we want to export.

 nbdkit guestfs disk=windows.img mount=inspect \
   export=/Users/rich/AppData/image

=head1 DEBUGGING

To debug this plugin, use the following options:

 nbdkit -f -v guestfs debug=on trace=on [...]

This enables libguestfs debugging and tracing (see L<guestfs-faq(1)>).
It also ensures that the messages are displayed by nbdkit (because of
I<-f> and I<-v>).

=head1 FILES

=over 4

=item F<$plugindir/nbdkit-guestfs-plugin.so>

The plugin.

Use C<nbdkit --dump-config> to find the location of C<$plugindir>.

=back

=head1 VERSION

C<nbdkit-guestfs-plugin> first appeared in nbdkit 1.2.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-plugin(3)>,
L<guestfish(1)>,
L<guestfs(3)>,
L<virt-filesystems(1)>,
L<http://libguestfs.org>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright (C) 2013 Red Hat Inc.
