docs/nbdkit-captive.pod

   1 =head1 NAME
   2
   3 nbdkit-captive - run nbdkit under another process and have it
   4 reliably cleaned up
   5
   6 =head1 SYNOPSIS
   7
   8  nbdkit PLUGIN [...] [-e|--exportname EXPORTNAME] \
   9                      --run 'COMMAND ARGS ...'
  10
  11 =for paragraph
  12
  13  nbdkit --exit-with-parent PLUGIN [...]
  14
  15 =head1 DESCRIPTION
  16
  17 You can run nbdkit under another process and have nbdkit reliably
  18 clean up.  There are two techniques depending on whether you want
  19 nbdkit to start the other process (L</CAPTIVE NBDKIT>), or if you want
  20 the other process to start nbdkit (L</EXIT WITH PARENT>).  Another way
  21 is to have nbdkit exit after the last client connection
  22 (L<nbdkit-exitlast-filter(1)>) or after an event
  23 (L<nbdkit-exitwhen-filter(1)>).
  24
  25 =head1 CAPTIVE NBDKIT
  26
  27 You can run nbdkit as a "captive process", using the I<--run> option.
  28 This means that nbdkit runs as long as (for example) L<qemu(1)> or
  29 L<guestfish(1)> is running.  When those exit, nbdkit is killed.
  30
  31 Some examples should make this clear.
  32
  33 To run nbdkit captive under qemu:
  34
  35  nbdkit file disk.img --run 'qemu -drive file=$nbd,if=virtio'
  36
  37 On the qemu command line, C<$nbd> is substituted automatically with
  38 the right NBD path so it can connect to nbdkit.  When qemu exits,
  39 nbdkit is killed and cleaned up automatically.
  40
  41 Running nbdkit captive under guestfish:
  42
  43  nbdkit file disk.img --run 'guestfish --format=raw -a $nbd -i'
  44
  45 When guestfish exits, nbdkit is killed.
  46
  47 Running nbdkit captive under nbdsh for unit testing:
  48
  49  nbdkit -U - memory 1 --run 'nbdsh -u "$uri" -c "print(h.pread(1, 0))"'
  50
  51 The following shell variables are available in the I<--run> argument:
  52
  53 =over 4
  54
  55 =item C<$nbd>
  56
  57 =item C<$uri>
  58
  59 A URI that refers to the nbdkit port or socket in the preferred form
  60 documented by the NBD project.
  61
  62 As this variable may contain a bare C<?> for Unix sockets, it is
  63 safest to use $uri within double quotes to avoid unintentional
  64 globbing.  For plugins that support distinct data based on export
  65 names, the I<-e> option to nbdkit controls which export name will be
  66 set in the URI.
  67
  68 In nbdkit E<le> 1.22 C<$nbd> tried to guess if you were using qemu or
  69 guestfish and expanded differently.  Since NBD URIs are now widely
  70 supported this magic is no longer necessary.  In nbdkit E<ge> 1.24
  71 both variables expand to the same URI.
  72
  73 =item C<$tls>
  74
  75 Corresponds to the I<--tls> option passed to nbdkit.  If I<--tls=off>
  76 this is not set.  If I<--tls=on> this is set to C<"1">.  If
  77 I<--tls=require> this is set to C<"2">.
  78
  79 =item C<$port>
  80
  81 If E<ne> "", the port number that nbdkit is listening on.
  82
  83 =item C<$unixsocket>
  84
  85 If E<ne> "", the Unix domain socket that nbdkit is listening on.
  86
  87 =item C<$exportname>
  88
  89 The export name (which may be "") that the process should use when
  90 connecting to nbdkit, as set by the I<-e> (I<--exportname>) command
  91 line option of nbdkit.  This only matters to plugins that
  92 differentiate what they serve based on the export name requested by
  93 the client.
  94
  95 =back
  96
  97 I<--run> implies I<--foreground>.  It is not possible, and probably
  98 not desirable, to have nbdkit fork into the background when using
  99 I<--run>.
 100
 101 Even when running captive, nbdkit still listens on the regular TCP/IP
 102 port, unless you specify the I<-p>/I<-U> options.  If you want a truly
 103 private captive nbdkit, then you should create a private random
 104 Unix socket, like this:
 105
 106  nbdkit -U - plugin [args] --run '...'
 107
 108 =head2 Copying data in and out of plugins with captive nbdkit
 109
 110 Captive nbdkit + L<qemu-img(1)> can be used to copy data into and out
 111 of nbdkit plugins.  For example L<nbdkit-example1-plugin(1)> contains
 112 an embedded disk image.  To copy it out:
 113
 114  nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
 115
 116 If the source suffers from temporary network failures
 117 L<nbdkit-retry-filter(1)> or L<nbdkit-retry-request-filter(1)> may
 118 help.
 119
 120 To overwrite a file inside an uncompressed tar file (the file being
 121 overwritten must be the same size), use L<nbdkit-tar-filter(1)> like
 122 this:
 123
 124  nbdkit -U - file data.tar --filter=tar tar-entry=disk.img \
 125    --run 'qemu-img convert -n disk.img $nbd'
 126
 127 =head1 EXIT WITH PARENT
 128
 129 The I<--exit-with-parent> option is almost the opposite of
 130 L</CAPTIVE NBDKIT> described in the previous section.
 131
 132 Running nbdkit with this option, for example from a script:
 133
 134  nbdkit --exit-with-parent plugin ... &
 135
 136 means that nbdkit will exit automatically if the parent program exits
 137 for any reason.  This can be used to avoid complicated cleanups or
 138 orphaned nbdkit processes.
 139
 140 I<--exit-with-parent> is incompatible with forking into the background
 141 (because when we fork into the background we lose track of the parent
 142 process).  Therefore I<-f> / I<--foreground> is implied.
 143
 144 If the parent application is multithreaded, then (in the Linux
 145 implementation) if the parent I<thread> exits, that will cause nbdkit
 146 to exit.  Thus in multithreaded applications you usually want to run
 147 C<nbdkit --exit-with-parent> only from the main thread (unless you
 148 actually want nbdkit to exit with the thread, but that may not work
 149 reliably on all operating systems).
 150
 151 To exit when an unrelated process exits, use
 152 L<nbdkit-exitwhen-filter(1)> C<exit-when-process-exits> feature.
 153
 154 =head2 Support for --exit-with-parent
 155
 156 This is currently implemented using a non-POSIX feature available in
 157 S<Linux ≥ 2.1.57>, S<FreeBSD ≥ 11.2> and macOS.  It won't work on
 158 other operating systems (patches welcome to make it work).
 159
 160 To test if the current binary supports this feature the most backwards
 161 compatible way is:
 162
 163  nbdkit --exit-with-parent --version && echo "supported"
 164
 165 In nbdkit E<ge> 1.34, S<C<nbdkit --dump-config>> prints either
 166 C<exit_with_parent=yes> or C<exit_with_parent=no> but earlier versions
 167 did not have this.
 168
 169 =head1 SEE ALSO
 170
 171 L<nbdkit(1)>,
 172 L<nbdkit-exitlast-filter(1)>,
 173 L<nbdkit-exitwhen-filter(1)>,
 174 L<prctl(2)> (on Linux),
 175 L<procctl(2)> (on FreeBSD).
 176
 177 =head1 AUTHORS
 178
 179 Eric Blake
 180
 181 Richard W.M. Jones
 182
 183 Pino Toscano
 184
 185 =head1 COPYRIGHT
 186
 187 Copyright Red Hat