=head1 NAME

nbdkit-streaming-plugin - nbdkit streaming plugin

=head1 SYNOPSIS

 nbdkit streaming pipe=FILENAME [size=SIZE]

=head1 DESCRIPTION

C<nbdkit-streaming-plugin> is a plugin for L<nbdkit(1)> that can turn
certain kinds of input into a stream.

If the NBD client opens the NBD port, and writes from the start to the
end of the disk without seeking backwards, then this plugin will turn
the resulting disk image into a stream of data which is written to the
named C<pipe> parameter.

               ┌───────────┐
 client        │ nbdkit    │        plugin streams
 writes ──────▶│ streaming │──────▶ data to pipe
               │ plugin    │
               └───────────┘

Typical usage is with qemu tools.  The following command will I<not>
work because the output is a pipe or socket:

 qemu-img convert input -O raw pipe

However this will work:

 nbdkit -U - streaming pipe=pipe --run '
   qemu-img convert -n input -O raw $nbd
 '

              ┌───────────┐       ┌───────────┐
 reads        │ qemu-img  │       │ nbdkit    │        plugin streams
 input ──────▶│ convert   │──────▶│ streaming │──────▶ data to pipe
 file         │ command   │       │ plugin    │
              └───────────┘      ↑└───────────┘
                              Unix domain socket (-U -)

For use of the I<--run> and I<-U -> options, see
L<nbdkit-captive(1)>.

=head1 PARAMETERS

=over 4

=item B<pipe=>FILENAME

Write to the named pipe or socket.  If the pipe or socket does not
exist, then it is created (as a named FIFO), otherwise the existing
pipe or socket is opened and used.

This parameter is required.

=item B<size=>SIZE

Specify the virtual size of the stream.

This parameter is optional.  If not specified, then the virtual disk
appears to the client to be very large (effectively infinite).
Whether you need to specify this parameter depends on the client.
Some clients don't check the size and just write/stream, others do
checks or calculations based on the apparent size.

=back

=head1 FILES

=over 4

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

The plugin.

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

=back

=head1 VERSION

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

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-plugin(3)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright (C) 2014 Red Hat Inc.
