1nbdkit-captive(1)                   NBDKIT                   nbdkit-captive(1)
2
3
4

NAME

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

SYNOPSIS

10        nbdkit PLUGIN [...] --run "CMD ARGS ..."
11
12        nbdkit --exit-with-parent PLUGIN [...]
13

DESCRIPTION

15       You can run nbdkit under another process and have nbdkit reliably clean
16       up.  There are two techniques depending on whether you want nbdkit to
17       start the other process ("CAPTIVE NBDKIT"), or if you want the other
18       process to start nbdkit ("EXIT WITH PARENT").
19

CAPTIVE NBDKIT

21       You can run nbdkit as a "captive process", using the --run option.
22       This means that nbdkit runs as long as (for example) qemu(1) or
23       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, $nbd is substituted automatically with the
32       right NBD path so it can connect to nbdkit.  When qemu exits, nbdkit is
33       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 --run argument:
42
43       $nbd
44           A URL that refers to the nbdkit port or socket.
45
46           Note there is some magic here, since qemu and guestfish URLs have a
47           different format, so nbdkit tries to guess which you are running.
48           If the magic doesn't work, try using the variables below instead.
49
50       $port
51           If ≠ "", the port number that nbdkit is listening on.
52
53       $unixsocket
54           If ≠ "", the Unix domain socket that nbdkit is listening on.
55
56       --run implies --foreground.  It is not possible, and probably not
57       desirable, to have nbdkit fork into the background when using --run.
58
59       Even when running captive, nbdkit still listens on the regular TCP/IP
60       port, unless you specify the -p/-U options.  If you want a truly
61       private captive nbdkit, then you should create a private random Unix
62       socket, like this:
63
64        nbdkit -U - plugin [args] --run '...'
65
66   Copying data in and out of plugins with captive nbdkit
67       Captive nbdkit + qemu-img(1) can be used to copy data into and out of
68       nbdkit plugins.  For example nbdkit-example1-plugin(1) contains an
69       embedded disk image.  To copy it out:
70
71        nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
72
73       If plugin requests have a high overhead (for example making HTTP
74       requests to a remote server), adding nbdkit-readahead-filter(1) may
75       help performance:
76
77        nbdkit -U - --filter=readahead curl https://example.com/disk.img \
78               --run 'qemu-img convert $nbd disk.img'
79
80       To overwrite a file inside an uncompressed tar file (the file being
81       overwritten must be the same size), use nbdkit-tar-plugin(1) like this:
82
83        nbdkit -U - tar tar=data.tar file=disk.img \
84          --run 'qemu-img convert -n disk.img $nbd'
85

EXIT WITH PARENT

87       The --exit-with-parent option is almost the opposite of "CAPTIVE
88       NBDKIT" described in the previous section.
89
90       Running nbdkit with this option, for example from a script:
91
92        nbdkit --exit-with-parent plugin ... &
93
94       means that nbdkit will exit automatically if the parent program exits
95       for any reason.  This can be used to avoid complicated cleanups or
96       orphaned nbdkit processes.
97
98       --exit-with-parent is incompatible with forking into the background
99       (because when we fork into the background we lose track of the parent
100       process).  Therefore -f / --foreground is implied.
101
102       This is currently implemented using a non-POSIX feature available in
103       Linux ≥ 2.1.57 and FreeBSD ≥ 11.2, so it won't work on other operating
104       systems (patches welcome to make it work).
105
106       If the parent application is multithreaded, then (in the Linux
107       implementation) if the parent thread exits, that will cause nbdkit to
108       exit.  Thus in multithreaded applications you usually want to run
109       "nbdkit --exit-with-parent" only from the main thread (unless you
110       actually want nbdkit to exit with the thread, but that may not work
111       reliably on all operating systems).
112

SEE ALSO

114       nbdkit(1), prctl(2) (on Linux), procctl(2) (on FreeBSD).
115

AUTHORS

117       Eric Blake
118
119       Richard W.M. Jones
120
121       Pino Toscano
122
124       Copyright (C) 2013-2018 Red Hat Inc.
125

LICENSE

127       Redistribution and use in source and binary forms, with or without
128       modification, are permitted provided that the following conditions are
129       met:
130
131       ·   Redistributions of source code must retain the above copyright
132           notice, this list of conditions and the following disclaimer.
133
134       ·   Redistributions in binary form must reproduce the above copyright
135           notice, this list of conditions and the following disclaimer in the
136           documentation and/or other materials provided with the
137           distribution.
138
139       ·   Neither the name of Red Hat nor the names of its contributors may
140           be used to endorse or promote products derived from this software
141           without specific prior written permission.
142
143       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
144       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
145       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
146       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
147       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
148       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
149       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
150       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
151       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
152       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
153       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
154
155
156
157nbdkit-1.12.3                     2019-05-22                 nbdkit-captive(1)
Impressum