nbdkit-captive(1)

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] \
11                            --run 'COMMAND ARGS ...'
12
13        nbdkit --exit-with-parent PLUGIN [...]
14

DESCRIPTION

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

CAPTIVE NBDKIT

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

EXIT WITH PARENT

104       The --exit-with-parent option is almost the opposite of "CAPTIVE
105       NBDKIT" described in the previous section.
106
107       Running nbdkit with this option, for example from a script:
108
109        nbdkit --exit-with-parent plugin ... &
110
111       means that nbdkit will exit automatically if the parent program exits
112       for any reason.  This can be used to avoid complicated cleanups or
113       orphaned nbdkit processes.
114
115       --exit-with-parent is incompatible with forking into the background
116       (because when we fork into the background we lose track of the parent
117       process).  Therefore -f / --foreground is implied.
118
119       If the parent application is multithreaded, then (in the Linux
120       implementation) if the parent thread exits, that will cause nbdkit to
121       exit.  Thus in multithreaded applications you usually want to run
122       "nbdkit --exit-with-parent" only from the main thread (unless you
123       actually want nbdkit to exit with the thread, but that may not work
124       reliably on all operating systems).
125
126       To exit when an unrelated process exits, use nbdkit-exitwhen-filter(1)
127       "exit-when-process-exits" feature.
128
129   Support for --exit-with-parent
130       This is currently implemented using a non-POSIX feature available in
131       Linux ≥ 2.1.57, FreeBSD ≥ 11.2 and macOS.  It won't work on other
132       operating systems (patches welcome to make it work).
133
134       To test if the current binary supports this feature the most backwards
135       compatible way is:
136
137        nbdkit --exit-with-parent --version && echo "supported"
138
139       In nbdkit ≥ 1.34, "nbdkit --dump-config" prints either
140       "exit_with_parent=yes" or "exit_with_parent=no" but earlier versions
141       did not have this.
142

AUTHORS

148       Eric Blake
149
150       Richard W.M. Jones
151
152       Pino Toscano
153

COPYRIGHT

155       Copyright Red Hat
156

LICENSE

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