NAME

       nbdkit-captive - run nbdkit under another process and have it reliably cleaned up

SYNOPSIS

        nbdkit PLUGIN [...] [-e|--exportname EXPORTNAME] \
                            --run 'COMMAND ARGS ...'

        nbdkit --exit-with-parent PLUGIN [...]

DESCRIPTION

       You can run nbdkit under another process and have nbdkit reliably clean up.  There are two
       techniques depending on whether you want nbdkit to start the other process ("CAPTIVE
       NBDKIT"), or if you want the other process to start nbdkit ("EXIT WITH PARENT").  Another
       way is to have nbdkit exit after the last client connection (nbdkit-exitlast-filter(1)) or
       after an event (nbdkit-exitwhen-filter(1)).

CAPTIVE NBDKIT

       You can run nbdkit as a "captive process", using the --run option.  This means that nbdkit
       runs as long as (for example) qemu(1) or guestfish(1) is running.  When those exit, nbdkit
       is killed.

       Some examples should make this clear.

       To run nbdkit captive under qemu:

        nbdkit file disk.img --run 'qemu -drive file=$nbd,if=virtio'

       On the qemu command line, $nbd is substituted automatically with the right NBD path so it
       can connect to nbdkit.  When qemu exits, nbdkit is killed and cleaned up automatically.

       Running nbdkit captive under guestfish:

        nbdkit file disk.img --run 'guestfish --format=raw -a $nbd -i'

       When guestfish exits, nbdkit is killed.

       Running nbdkit captive under nbdsh for unit testing:

        nbdkit -U - memory 1 --run 'nbdsh -u "$uri" -c "print(h.pread(1, 0))"'

       The following shell variables are available in the --run argument:

       $nbd
       $uri
           A URI that refers to the nbdkit port or socket in the preferred form documented by the
           NBD project.

           As this variable may contain a bare "?" for Unix sockets, it is safest to use $uri
           within double quotes to avoid unintentional globbing.  For plugins that support
           distinct data based on export names, the -e option to nbdkit controls which export
           name will be set in the URI.

           In nbdkit ≤ 1.22 $nbd tried to guess if you were using qemu or guestfish and expanded
           differently.  Since NBD URIs are now widely supported this magic is no longer
           necessary.  In nbdkit ≥ 1.24 both variables expand to the same URI.

       $tls
           Corresponds to the --tls option passed to nbdkit.  If --tls=off this is not set.  If
           --tls=on this is set to "1".  If --tls=require this is set to "2".

       $port
           If ≠ "", the port number that nbdkit is listening on.

       $unixsocket
           If ≠ "", the Unix domain socket that nbdkit is listening on.

       $exportname
           The export name (which may be "") that the process should use when connecting to
           nbdkit, as set by the -e (--exportname) command line option of nbdkit.  This only
           matters to plugins that differentiate what they serve based on the export name
           requested by the client.

       --run implies --foreground.  It is not possible, and probably not desirable, to have
       nbdkit fork into the background when using --run.

       Even when running captive, nbdkit still listens on the regular TCP/IP port, unless you
       specify the -p/-U options.  If you want a truly private captive nbdkit, then you should
       create a private random Unix socket, like this:

        nbdkit -U - plugin [args] --run '...'

   Copying data in and out of plugins with captive nbdkit
       Captive nbdkit + qemu-img(1) can be used to copy data into and out of nbdkit plugins.  For
       example nbdkit-example1-plugin(1) contains an embedded disk image.  To copy it out:

        nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'

       If the source suffers from temporary network failures nbdkit-retry-filter(1) or
       nbdkit-retry-request-filter(1) may help.

       To overwrite a file inside an uncompressed tar file (the file being overwritten must be
       the same size), use nbdkit-tar-filter(1) like this:

        nbdkit -U - file data.tar --filter=tar tar-entry=disk.img \
          --run 'qemu-img convert -n disk.img $nbd'

EXIT WITH PARENT

       The --exit-with-parent option is almost the opposite of "CAPTIVE NBDKIT" described in the
       previous section.

       Running nbdkit with this option, for example from a script:

        nbdkit --exit-with-parent plugin ... &

       means that nbdkit will exit automatically if the parent program exits for any reason.
       This can be used to avoid complicated cleanups or orphaned nbdkit processes.

       --exit-with-parent is incompatible with forking into the background (because when we fork
       into the background we lose track of the parent process).  Therefore -f / --foreground is
       implied.

       If the parent application is multithreaded, then (in the Linux implementation) if the
       parent thread exits, that will cause nbdkit to exit.  Thus in multithreaded applications
       you usually want to run "nbdkit --exit-with-parent" only from the main thread (unless you
       actually want nbdkit to exit with the thread, but that may not work reliably on all
       operating systems).

       To exit when an unrelated process exits, use nbdkit-exitwhen-filter(1)
       "exit-when-process-exits" feature.

   Support for --exit-with-parent
       This is currently implemented using a non-POSIX feature available in Linux ≥ 2.1.57,
       FreeBSD ≥ 11.2 and macOS.  It won't work on other operating systems (patches welcome to
       make it work).

       To test if the current binary supports this feature the most backwards compatible way is:

        nbdkit --exit-with-parent --version && echo "supported"

       In nbdkit ≥ 1.34, "nbdkit --dump-config" prints either "exit_with_parent=yes" or
       "exit_with_parent=no" but earlier versions did not have this.

SEE ALSO

       nbdkit(1), nbdkit-exitlast-filter(1), nbdkit-exitwhen-filter(1), prctl(2) (on Linux),
       procctl(2) (on FreeBSD).

AUTHORS

       Eric Blake

       Richard W.M. Jones

       Pino Toscano

COPYRIGHT

       Copyright Red Hat

LICENSE

       Redistribution and use in source and binary forms, with or without modification, are
       permitted provided that the following conditions are met:

       •   Redistributions of source code must retain the above copyright notice, this list of
           conditions and the following disclaimer.

       •   Redistributions in binary form must reproduce the above copyright notice, this list of
           conditions and the following disclaimer in the documentation and/or other materials
           provided with the distribution.

       •   Neither the name of Red Hat nor the names of its contributors may be used to endorse
           or promote products derived from this software without specific prior written
           permission.

       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED
       WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
       FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS
       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
       OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
       POSSIBILITY OF SUCH DAMAGE.