.\" Automatically generated by Podwrapper::Man 1.24.1 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-captive 1"
.TH nbdkit-captive 1 "2021-01-20" "nbdkit-1.24.1" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-captive \- run nbdkit under another process and have it
reliably cleaned up
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& nbdkit PLUGIN [...] [\-e|\-\-exportname EXPORTNAME] \-\-run "CMD ARGS ..."
\&
\& nbdkit \-\-exit\-with\-parent PLUGIN [...]
.Ve
.SH "DESCRIPTION"
.IX Header "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 (\*(L"\s-1CAPTIVE NBDKIT\*(R"\s0), or if you want
the other process to start nbdkit (\*(L"\s-1EXIT WITH PARENT\*(R"\s0).  Another way
is to have nbdkit exit after the last client connection
(\fBnbdkit\-exitlast\-filter\fR\|(1)) or after an event
(\fBnbdkit\-exitwhen\-filter\fR\|(1)).
.SH "CAPTIVE NBDKIT"
.IX Header "CAPTIVE NBDKIT"
You can run nbdkit as a \*(L"captive process\*(R", using the \fI\-\-run\fR option.
This means that nbdkit runs as long as (for example) \fBqemu\fR\|(1) or
\&\fBguestfish\fR\|(1) is running.  When those exit, nbdkit is killed.
.PP
Some examples should make this clear.
.PP
To run nbdkit captive under qemu:
.PP
.Vb 1
\& nbdkit file disk.img \-\-run \*(Aqqemu \-drive file=$nbd,if=virtio\*(Aq
.Ve
.PP
On the qemu command line, \f(CW$nbd\fR is substituted automatically with
the right \s-1NBD\s0 path so it can connect to nbdkit.  When qemu exits,
nbdkit is killed and cleaned up automatically.
.PP
Running nbdkit captive under guestfish:
.PP
.Vb 1
\& nbdkit file disk.img \-\-run \*(Aqguestfish \-\-format=raw \-a $nbd \-i\*(Aq
.Ve
.PP
When guestfish exits, nbdkit is killed.
.PP
Running nbdkit captive under nbdsh for unit testing:
.PP
.Vb 1
\& nbdkit \-U \- memory 1 \-\-run \*(Aqnbdsh \-u "$uri" \-c "print(h.pread(1, 0))"\*(Aq
.Ve
.PP
The following shell variables are available in the \fI\-\-run\fR argument:
.ie n .IP "$nbd" 4
.el .IP "\f(CW$nbd\fR" 4
.IX Item "$nbd"
.PD 0
.ie n .IP "$uri" 4
.el .IP "\f(CW$uri\fR" 4
.IX Item "$uri"
.PD
A \s-1URI\s0 that refers to the nbdkit port or socket in the preferred form
documented by the \s-1NBD\s0 project.
.Sp
As this variable may contain a bare \f(CW\*(C`?\*(C'\fR for Unix sockets, it is
safest to use \f(CW$uri\fR within double quotes to avoid unintentional
globbing.  For plugins that support distinct data based on export
names, the \fB\-e\fR option to nbdkit controls which export name will be
set in the \s-1URI.\s0
.Sp
In nbdkit ≤ 1.22 \f(CW$nbd\fR tried to guess if you were using qemu or
guestfish and expanded differently.  Since \s-1NBD\s0 URIs are now widely
supported this magic is no longer necessary.  In nbdkit ≥ 1.24
both variables expand to the same \s-1URI.\s0
.ie n .IP "$port" 4
.el .IP "\f(CW$port\fR" 4
.IX Item "$port"
If ≠ "", the port number that nbdkit is listening on.
.ie n .IP "$unixsocket" 4
.el .IP "\f(CW$unixsocket\fR" 4
.IX Item "$unixsocket"
If ≠ "", the Unix domain socket that nbdkit is listening on.
.ie n .IP "$exportname" 4
.el .IP "\f(CW$exportname\fR" 4
.IX Item "$exportname"
The export name (which may be "") that the process should use when
connecting to nbdkit, as set by the \fB\-e\fR (\fB\-\-exportname\fR) command
line option of nbdkit.  This only matters to plugins that
differentiate what they serve based on the export name requested by
the client.
.PP
\&\fI\-\-run\fR implies \fI\-\-foreground\fR.  It is not possible, and probably
not desirable, to have nbdkit fork into the background when using
\&\fI\-\-run\fR.
.PP
Even when running captive, nbdkit still listens on the regular \s-1TCP/IP\s0
port, unless you specify the \fI\-p\fR/\fI\-U\fR options.  If you want a truly
private captive nbdkit, then you should create a private random
Unix socket, like this:
.PP
.Vb 1
\& nbdkit \-U \- plugin [args] \-\-run \*(Aq...\*(Aq
.Ve
.SS "Copying data in and out of plugins with captive nbdkit"
.IX Subsection "Copying data in and out of plugins with captive nbdkit"
Captive nbdkit + \fBqemu\-img\fR\|(1) can be used to copy data into and out
of nbdkit plugins.  For example \fBnbdkit\-example1\-plugin\fR\|(1) contains
an embedded disk image.  To copy it out:
.PP
.Vb 1
\& nbdkit \-U \- example1 \-\-run \*(Aqqemu\-img convert $nbd disk.img\*(Aq
.Ve
.PP
If plugin requests have a high overhead (for example making \s-1HTTP\s0
requests to a remote server), adding \fBnbdkit\-readahead\-filter\fR\|(1) may
help performance:
.PP
.Vb 2
\& nbdkit \-U \- \-\-filter=readahead curl https://example.com/disk.img \e
\&        \-\-run \*(Aqqemu\-img convert $nbd disk.img\*(Aq
.Ve
.PP
If the source suffers from temporary network failures
\&\fBnbdkit\-retry\-filter\fR\|(1) may help.
.PP
To overwrite a file inside an uncompressed tar file (the file being
overwritten must be the same size), use \fBnbdkit\-tar\-filter\fR\|(1) like
this:
.PP
.Vb 2
\& nbdkit \-U \- file data.tar \-\-filter=tar tar\-entry=disk.img \e
\&   \-\-run \*(Aqqemu\-img convert \-n disk.img $nbd\*(Aq
.Ve
.SH "EXIT WITH PARENT"
.IX Header "EXIT WITH PARENT"
The \fI\-\-exit\-with\-parent\fR option is almost the opposite of
\&\*(L"\s-1CAPTIVE NBDKIT\*(R"\s0 described in the previous section.
.PP
Running nbdkit with this option, for example from a script:
.PP
.Vb 1
\& nbdkit \-\-exit\-with\-parent plugin ... &
.Ve
.PP
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.
.PP
\&\fI\-\-exit\-with\-parent\fR is incompatible with forking into the background
(because when we fork into the background we lose track of the parent
process).  Therefore \fI\-f\fR / \fI\-\-foreground\fR is implied.
.PP
This is currently implemented using a non-POSIX feature available in
Linux ≥ 2.1.57 and FreeBSD ≥ 11.2, so it won't work on other
operating systems (patches welcome to make it work).
.PP
If the parent application is multithreaded, then (in the Linux
implementation) if the parent \fIthread\fR exits, that will cause nbdkit
to exit.  Thus in multithreaded applications you usually want to run
\&\f(CW\*(C`nbdkit \-\-exit\-with\-parent\*(C'\fR 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).
.PP
To exit when an unrelated process exits, use
\&\fBnbdkit\-exitwhen\-filter\fR\|(1) \f(CW\*(C`exit\-when\-process\-exits\*(C'\fR feature.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-exitlast\-filter\fR\|(1),
\&\fBnbdkit\-exitwhen\-filter\fR\|(1),
\&\fBprctl\fR\|(2) (on Linux),
\&\fBprocctl\fR\|(2) (on FreeBSD).
.SH "AUTHORS"
.IX Header "AUTHORS"
Eric Blake
.PP
Richard W.M. Jones
.PP
Pino Toscano
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2013\-2020 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0