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<$uri>
  46
  47 A URI that refers to the nbdkit port or socket in the preferred form
  48 documented by the NBD project.  If nbdkit was started with the B<-e>
  49 option to set the preferred export name, this is included in the URI.
  50
  51 =item C<$nbd>
  52
  53 An older URL that refers to the nbdkit port or socket in a manner
  54 specific to certain tools.  This form does not include an export name,
  55 even if B<-e> was used.
  56
  57 Note there is some magic here, since qemu and guestfish URLs have a
  58 different format, so nbdkit tries to guess which you are running.  If
  59 the magic doesn't work, try using the variables below instead.
  60
  61 =item C<$port>
  62
  63 If E<ne> "", the port number that nbdkit is listening on.
  64
  65 =item C<$unixsocket>
  66
  67 If E<ne> "", the Unix domain socket that nbdkit is listening on.
  68
  69 =item C<$exportname>
  70
  71 The default export name (which may be "") that nbdkit will advertise
  72 in response to NBD_OPT_LIST.  This comes from the B<-e>
  73 (B<--exportname>) command line option.
  74
  75 =back
  76
  77 I<--run> implies I<--foreground>.  It is not possible, and probably
  78 not desirable, to have nbdkit fork into the background when using
  79 I<--run>.
  80
  81 Even when running captive, nbdkit still listens on the regular TCP/IP
  82 port, unless you specify the I<-p>/I<-U> options.  If you want a truly
  83 private captive nbdkit, then you should create a private random
  84 Unix socket, like this:
  85
  86  nbdkit -U - plugin [args] --run '...'
  87
  88 =head2 Copying data in and out of plugins with captive nbdkit
  89
  90 Captive nbdkit + L<qemu-img(1)> can be used to copy data into and out
  91 of nbdkit plugins.  For example L<nbdkit-example1-plugin(1)> contains
  92 an embedded disk image.  To copy it out:
  93
  94  nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
  95
  96 If plugin requests have a high overhead (for example making HTTP
  97 requests to a remote server), adding L<nbdkit-readahead-filter(1)> may
  98 help performance:
  99
 100  nbdkit -U - --filter=readahead curl https://example.com/disk.img \
 101         --run 'qemu-img convert $nbd disk.img'
 102
 103 If the source suffers from temporary network failures
 104 L<nbdkit-retry-filter(1)> may help.
 105
 106 To overwrite a file inside an uncompressed tar file (the file being
 107 overwritten must be the same size), use L<nbdkit-tar-plugin(1)> like
 108 this:
 109
 110  nbdkit -U - tar tar=data.tar file=disk.img \
 111    --run 'qemu-img convert -n disk.img $nbd'
 112
 113 =head1 EXIT WITH PARENT
 114
 115 The I<--exit-with-parent> option is almost the opposite of
 116 L</CAPTIVE NBDKIT> described in the previous section.
 117
 118 Running nbdkit with this option, for example from a script:
 119
 120  nbdkit --exit-with-parent plugin ... &
 121
 122 means that nbdkit will exit automatically if the parent program exits
 123 for any reason.  This can be used to avoid complicated cleanups or
 124 orphaned nbdkit processes.
 125
 126 I<--exit-with-parent> is incompatible with forking into the background
 127 (because when we fork into the background we lose track of the parent
 128 process).  Therefore I<-f> / I<--foreground> is implied.
 129
 130 This is currently implemented using a non-POSIX feature available in
 131 S<Linux ≥ 2.1.57> and S<FreeBSD ≥ 11.2>, so it won't work on other
 132 operating systems (patches welcome to make it work).
 133
 134 If the parent application is multithreaded, then (in the Linux
 135 implementation) if the parent I<thread> exits, that will cause nbdkit
 136 to exit.  Thus in multithreaded applications you usually want to run
 137 C<nbdkit --exit-with-parent> only from the main thread (unless you
 138 actually want nbdkit to exit with the thread, but that may not work
 139 reliably on all operating systems).
 140
 141 =head1 SEE ALSO
 142
 143 L<nbdkit(1)>,
 144 L<prctl(2)> (on Linux),
 145 L<procctl(2)> (on FreeBSD).
 146
 147 =head1 AUTHORS
 148
 149 Eric Blake
 150
 151 Richard W.M. Jones
 152
 153 Pino Toscano
 154
 155 =head1 COPYRIGHT
 156
 157 Copyright (C) 2013-2018 Red Hat Inc.