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 [...] --run "CMD ARGS ..."
   9
  10  nbdkit --exit-with-parent PLUGIN [...]
  11
  12 =head1 DESCRIPTION
  13
  14 You can run nbdkit under another process and have nbdkit reliably
  15 clean up.  There are two techniques depending on whether you want
  16 nbdkit to start the other process (L</CAPTIVE NBDKIT>), or if you want
  17 the other process to start nbdkit (L</EXIT WITH PARENT>).
  18
  19 =head1 CAPTIVE NBDKIT
  20
  21 You can run nbdkit as a "captive process", using the I<--run> option.
  22 This means that nbdkit runs as long as (for example) L<qemu(1)> or
  23 L<guestfish(1)> is running.  When those exit, nbdkit is killed.
  24
  25 Some examples should make this clear.
  26
  27 To run nbdkit captive under qemu:
  28
  29  nbdkit file disk.img --run 'qemu -drive file=$nbd,if=virtio'
  30
  31 On the qemu command line, C<$nbd> is substituted automatically with
  32 the right NBD path so it can connect to nbdkit.  When qemu exits,
  33 nbdkit is killed and cleaned up automatically.
  34
  35 Running nbdkit captive under guestfish:
  36
  37  nbdkit file disk.img --run 'guestfish --format=raw -a $nbd -i'
  38
  39 When guestfish exits, nbdkit is killed.
  40
  41 The following shell variables are available in the I<--run> argument:
  42
  43 =over 4
  44
  45 =item C<$nbd>
  46
  47 A URL that refers to the nbdkit port or socket.
  48
  49 Note there is some magic here, since qemu and guestfish URLs have a
  50 different format, so nbdkit tries to guess which you are running.  If
  51 the magic doesn't work, try using the variables below instead.
  52
  53 =item C<$port>
  54
  55 If E<ne> "", the port number that nbdkit is listening on.
  56
  57 =item C<$unixsocket>
  58
  59 If E<ne> "", the Unix domain socket that nbdkit is listening on.
  60
  61 =back
  62
  63 I<--run> implies I<--foreground>.  It is not possible, and probably
  64 not desirable, to have nbdkit fork into the background when using
  65 I<--run>.
  66
  67 Even when running captive, nbdkit still listens on the regular TCP/IP
  68 port, unless you specify the I<-p>/I<-U> options.  If you want a truly
  69 private captive nbdkit, then you should create a private random
  70 Unix socket, like this:
  71
  72  nbdkit -U - plugin [args] --run '...'
  73
  74 =head2 Copying data in and out of plugins with captive nbdkit
  75
  76 Captive nbdkit + L<qemu-img(1)> can be used to copy data into and out
  77 of nbdkit plugins.  For example L<nbdkit-example1-plugin(1)> contains
  78 an embedded disk image.  To copy it out:
  79
  80  nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
  81
  82 If plugin requests have a high overhead (for example making HTTP
  83 requests to a remote server), adding L<nbdkit-readahead-filter(1)> may
  84 help performance:
  85
  86  nbdkit -U - --filter=readahead curl https://example.com/disk.img \
  87         --run 'qemu-img convert $nbd disk.img'
  88
  89 To overwrite a file inside an uncompressed tar file (the file being
  90 overwritten must be the same size), use L<nbdkit-tar-plugin(1)> like
  91 this:
  92
  93  nbdkit -U - tar tar=data.tar file=disk.img \
  94    --run 'qemu-img convert -n disk.img $nbd'
  95
  96 =head1 EXIT WITH PARENT
  97
  98 The I<--exit-with-parent> option is almost the opposite of
  99 L</CAPTIVE NBDKIT> described in the previous section.
 100
 101 Running nbdkit with this option, for example from a script:
 102
 103  nbdkit --exit-with-parent plugin ... &
 104
 105 means that nbdkit will exit automatically if the parent program exits
 106 for any reason.  This can be used to avoid complicated cleanups or
 107 orphaned nbdkit processes.
 108
 109 I<--exit-with-parent> is incompatible with forking into the background
 110 (because when we fork into the background we lose track of the parent
 111 process).  Therefore I<-f> / I<--foreground> is implied.
 112
 113 This is currently implemented using a non-POSIX feature available in
 114 S<Linux ≥ 2.1.57> and S<FreeBSD ≥ 11.2>, so it won't work on other
 115 operating systems (patches welcome to make it work).
 116
 117 If the parent application is multithreaded, then (in the Linux
 118 implementation) if the parent I<thread> exits, that will cause nbdkit
 119 to exit.  Thus in multithreaded applications you usually want to run
 120 C<nbdkit --exit-with-parent> only from the main thread (unless you
 121 actually want nbdkit to exit with the thread, but that may not work
 122 reliably on all operating systems).
 123
 124 =head1 SEE ALSO
 125
 126 L<nbdkit(1)>,
 127 L<prctl(2)> (on Linux),
 128 L<procctl(2)> (on FreeBSD).
 129
 130 =head1 AUTHORS
 131
 132 Eric Blake
 133
 134 Richard W.M. Jones
 135
 136 Pino Toscano
 137
 138 =head1 COPYRIGHT
 139
 140 Copyright (C) 2013-2018 Red Hat Inc.