plugins/streaming/nbdkit-streaming-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-streaming-plugin - nbdkit streaming plugin
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit streaming pipe=FILENAME [size=SIZE]
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-streaming-plugin> is a plugin for L<nbdkit(1)> that can turn
  12 certain kinds of input into a stream.
  13
  14 If the NBD client opens the NBD port, and writes from the start to the
  15 end of the disk without seeking backwards, then this plugin will turn
  16 the resulting disk image into a stream of data which is written to the
  17 named C<pipe> parameter.
  18
  19                ┌───────────┐
  20  client        │ nbdkit    │        plugin streams
  21  writes ──────▶│ streaming │──────▶ data to pipe
  22                │ plugin    │
  23                └───────────┘
  24
  25 Typical usage is with qemu tools.  The following command will I<not>
  26 work because the output is a pipe or socket:
  27
  28  qemu-img convert input -O raw pipe
  29
  30 However this will work:
  31
  32  nbdkit -U - streaming pipe=pipe --run '
  33    qemu-img convert -n input -O raw $nbd
  34  '
  35
  36               ┌───────────┐       ┌───────────┐
  37  reads        │ qemu-img  │       │ nbdkit    │        plugin streams
  38  input ──────▶│ convert   │──────▶│ streaming │──────▶ data to pipe
  39  file         │ command   │       │ plugin    │
  40               └───────────┘      ↑└───────────┘
  41                               Unix domain socket (-U -)
  42
  43 For use of the I<--run> and I<-U -> options, see
  44 L<nbdkit-captive(1)>.
  45
  46 =head1 PARAMETERS
  47
  48 =over 4
  49
  50 =item B<pipe=>FILENAME
  51
  52 Write to the named pipe or socket.  If the pipe or socket does not
  53 exist, then it is created (as a named FIFO), otherwise the existing
  54 pipe or socket is opened and used.
  55
  56 This parameter is required.
  57
  58 =item B<size=>SIZE
  59
  60 Specify the virtual size of the stream.
  61
  62 This parameter is optional.  If not specified, then the virtual disk
  63 appears to the client to be very large (effectively infinite).
  64 Whether you need to specify this parameter depends on the client.
  65 Some clients don't check the size and just write/stream, others do
  66 checks or calculations based on the apparent size.
  67
  68 =back
  69
  70 =head1 FILES
  71
  72 =over 4
  73
  74 =item F<$plugindir/nbdkit-streaming-plugin.so>
  75
  76 The plugin.
  77
  78 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
  79
  80 =back
  81
  82 =head1 VERSION
  83
  84 C<nbdkit-streaming-plugin> first appeared in nbdkit 1.2.
  85
  86 =head1 SEE ALSO
  87
  88 L<nbdkit(1)>,
  89 L<nbdkit-plugin(3)>.
  90
  91 =head1 AUTHORS
  92
  93 Richard W.M. Jones
  94
  95 =head1 COPYRIGHT
  96
  97 Copyright (C) 2014 Red Hat Inc.