=head1 NAME

nbdkit-qcow2dec-filter - decode qcow2 files

=head1 SYNOPSIS

 nbdkit --filter=qcow2dec PLUGIN

=head1 DESCRIPTION

C<nbdkit-qcow2dec-filter> is a filter for L<nbdkit(1)> that can decode
some qcow2 files.  You can use it on top of plugins that provide qcow2
data, such as L<nbdkit-file-plugin(1)> or L<nbdkit-curl-plugin(1)>.
For example to expose a local qcow2 file as raw format over NBD:

 nbdkit -r --filter=qcow2dec file image.qcow2

This filter can only decode qcow2 files, it cannot write to them, and
it has other limitations.  See L</LIMITATIONS> below.  The NBD export
will be read-only unless you use L<nbdkit-cow-filter(1)> on top.

L<qemu-nbd(8)> is an alternate NBD server with native support for
qcow2.

=head1 LIMITATIONS

This filter has several limitations, and some of them we never intend
to implement.  For general qcow2 access, especially creating and
writing to qcow2 files, it is always better to use qemu and tools such
as L<qemu-img(1)> and L<qemu-nbd(8)>.

=over 4

=item Read-only

This filter only supports decoding qcow2 into raw format.  You cannot
write to the qcow2 file.  The NBD export will be read-only.

=item Versions 2 and 3 only

Only qcow2 subversions 2 and 3 (a.k.a. C<compat=0.10> and
C<compat=1.1>) are supported.

=item Deflate or Zstd compression only

The most common types of qcow2 compression are supported if nbdkit was
built with the correct libraries.  To find out which types of
compression are supported, use:

 $ nbdkit null --filter=qcow2dec --dump-plugin
 ...
 qcow2dec_deflate=yes       # printed if Deflate (zlib) is supported
 qcow2dec_zstd=yes          # printed if Zstd is supported

=item No snapshots

We may add the ability to extract an internal snapshot in future.

=item No bitmaps

It may be possible to support bitmaps in future.

=item No backing files

=item No dirty or corrupted qcow2 files

=item No encryption

=item No extended L2 entries

=item No external data files

These features are not currently supported and unlikely to be
supported in future.

=back

=head1 PARAMETERS

There are no parameters specific to this filter.  Parameters are
passed through to the underlying plugin.

=head1 FILES

=over 4

=item F<$filterdir/nbdkit-qcow2dec-filter.so>

The filter.

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

=back

=head1 VERSION

C<nbdkit-qcow2dec-filter> first appeared in nbdkit 1.36.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-cow-filter(1)>,
L<nbdkit-curl-plugin(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-filter(3)>,
L<https://github.com/qemu/qemu/blob/master/docs/interop/qcow2.txt>,
L<https://web.archive.org/web/20201006212750/https://people.gnome.org/~markmc/qcow-image-format-version-1.html>,
L<qemu-img(1)>,
L<qemu-nbd(8)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
