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 [...] [-e|--exportname EXPORTNAME] --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").  Another way is to have
19       nbdkit exit after the last client connection
20       (nbdkit-exitlast-filter(1)) or after an event
21       (nbdkit-exitwhen-filter(1)).
22

CAPTIVE NBDKIT

24       You can run nbdkit as a "captive process", using the --run option.
25       This means that nbdkit runs as long as (for example) qemu(1) or
26       guestfish(1) is running.  When those exit, nbdkit is killed.
27
28       Some examples should make this clear.
29
30       To run nbdkit captive under qemu:
31
32        nbdkit file disk.img --run 'qemu -drive file=$nbd,if=virtio'
33
34       On the qemu command line, $nbd is substituted automatically with the
35       right NBD path so it can connect to nbdkit.  When qemu exits, nbdkit is
36       killed and cleaned up automatically.
37
38       Running nbdkit captive under guestfish:
39
40        nbdkit file disk.img --run 'guestfish --format=raw -a $nbd -i'
41
42       When guestfish exits, nbdkit is killed.
43
44       Running nbdkit captive under nbdsh for unit testing:
45
46        nbdkit -U - memory 1 --run 'nbdsh -u "$uri" -c "print(h.pread(1, 0))"'
47
48       The following shell variables are available in the --run argument:
49
50       $nbd
51       $uri
52           A URI that refers to the nbdkit port or socket in the preferred
53           form documented by the NBD project.
54
55           As this variable may contain a bare "?" for Unix sockets, it is
56           safest to use $uri within double quotes to avoid unintentional
57           globbing.  For plugins that support distinct data based on export
58           names, the -e option to nbdkit controls which export name will be
59           set in the URI.
60
61           In nbdkit ≤ 1.22 $nbd tried to guess if you were using qemu or
62           guestfish and expanded differently.  Since NBD URIs are now widely
63           supported this magic is no longer necessary.  In nbdkit ≥ 1.24 both
64           variables expand to the same URI.
65
66       $tls
67           Corresponds to the --tls option passed to nbdkit.  If --tls=off
68           this is not set.  If --tls=on this is set to "1".  If --tls=require
69           this is set to "2".
70
71       $port
72           If ≠ "", the port number that nbdkit is listening on.
73
74       $unixsocket
75           If ≠ "", the Unix domain socket that nbdkit is listening on.
76
77       $exportname
78           The export name (which may be "") that the process should use when
79           connecting to nbdkit, as set by the -e (--exportname) command line
80           option of nbdkit.  This only matters to plugins that differentiate
81           what they serve based on the export name requested by the client.
82
83       --run implies --foreground.  It is not possible, and probably not
84       desirable, to have nbdkit fork into the background when using --run.
85
86       Even when running captive, nbdkit still listens on the regular TCP/IP
87       port, unless you specify the -p/-U options.  If you want a truly
88       private captive nbdkit, then you should create a private random Unix
89       socket, like this:
90
91        nbdkit -U - plugin [args] --run '...'
92
93   Copying data in and out of plugins with captive nbdkit
94       Captive nbdkit + qemu-img(1) can be used to copy data into and out of
95       nbdkit plugins.  For example nbdkit-example1-plugin(1) contains an
96       embedded disk image.  To copy it out:
97
98        nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
99
100       If plugin requests have a high overhead (for example making HTTP
101       requests to a remote server), adding nbdkit-readahead-filter(1) may
102       help performance:
103
104        nbdkit -U - --filter=readahead curl https://example.com/disk.img \
105               --run 'qemu-img convert $nbd disk.img'
106
107       If the source suffers from temporary network failures
108       nbdkit-retry-filter(1) may help.
109
110       To overwrite a file inside an uncompressed tar file (the file being
111       overwritten must be the same size), use nbdkit-tar-filter(1) like this:
112
113        nbdkit -U - file data.tar --filter=tar tar-entry=disk.img \
114          --run 'qemu-img convert -n disk.img $nbd'
115

EXIT WITH PARENT

117       The --exit-with-parent option is almost the opposite of "CAPTIVE
118       NBDKIT" described in the previous section.
119
120       Running nbdkit with this option, for example from a script:
121
122        nbdkit --exit-with-parent plugin ... &
123
124       means that nbdkit will exit automatically if the parent program exits
125       for any reason.  This can be used to avoid complicated cleanups or
126       orphaned nbdkit processes.
127
128       --exit-with-parent is incompatible with forking into the background
129       (because when we fork into the background we lose track of the parent
130       process).  Therefore -f / --foreground is implied.
131
132       This is currently implemented using a non-POSIX feature available in
133       Linux ≥ 2.1.57 and FreeBSD ≥ 11.2, so it won't work on other operating
134       systems (patches welcome to make it work).
135
136       If the parent application is multithreaded, then (in the Linux
137       implementation) if the parent thread exits, that will cause nbdkit to
138       exit.  Thus in multithreaded applications you usually want to run
139       "nbdkit --exit-with-parent" only from the main thread (unless you
140       actually want nbdkit to exit with the thread, but that may not work
141       reliably on all operating systems).
142
143       To exit when an unrelated process exits, use nbdkit-exitwhen-filter(1)
144       "exit-when-process-exits" feature.
145

SEE ALSO

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

AUTHORS

151       Eric Blake
152
153       Richard W.M. Jones
154
155       Pino Toscano
156
158       Copyright (C) 2013-2020 Red Hat Inc.
159

LICENSE

161       Redistribution and use in source and binary forms, with or without
162       modification, are permitted provided that the following conditions are
163       met:
164
165       •   Redistributions of source code must retain the above copyright
166           notice, this list of conditions and the following disclaimer.
167
168       •   Redistributions in binary form must reproduce the above copyright
169           notice, this list of conditions and the following disclaimer in the
170           documentation and/or other materials provided with the
171           distribution.
172
173       •   Neither the name of Red Hat nor the names of its contributors may
174           be used to endorse or promote products derived from this software
175           without specific prior written permission.
176
177       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
178       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
179       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
180       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
181       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
182       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
183       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
184       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
185       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
186       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
187       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
188
189
190
191nbdkit-1.28.2                     2021-11-09                 nbdkit-captive(1)
Impressum