1nbdkit-captive(1) NBDKIT nbdkit-captive(1)
2
6 nbdkit-captive - run nbdkit under another process and have it reliably
7 cleaned up
8
10 nbdkit PLUGIN [...] [-e|--exportname EXPORTNAME] \
11 --run 'COMMAND ARGS ...'
12 nbdkit --exit-with-parent PLUGIN [...]
14
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
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 Some examples should make this clear.
30 To run nbdkit captive under qemu:
32 nbdkit file disk.img --run 'qemu -drive file=$nbd,if=virtio'
34 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 Running nbdkit captive under guestfish:
40 nbdkit file disk.img --run 'guestfish --format=raw -a $nbd -i'
42 When guestfish exits, nbdkit is killed.
44 Running nbdkit captive under nbdsh for unit testing:
46 nbdkit -U - memory 1 --run 'nbdsh -u "$uri" -c "print(h.pread(1, 0))"'
48 The following shell variables are available in the --run argument:
50 $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 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 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 $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 $port
73 If ≠ "", the port number that nbdkit is listening on.
74 $unixsocket
76 If ≠ "", the Unix domain socket that nbdkit is listening on.
77 $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 --run implies --foreground. It is not possible, and probably not
85 desirable, to have nbdkit fork into the background when using --run.
86 Even when running captive, nbdkit still listens on the regular TCP/IP
88 port, unless you specify the -p/-U options. If you want a truly
89 private captive nbdkit, then you should create a private random Unix
90 socket, like this:
91 nbdkit -U - plugin [args] --run '...'
93 Copying data in and out of plugins with captive nbdkit
95 Captive nbdkit + qemu-img(1) can be used to copy data into and out of
96 nbdkit plugins. For example nbdkit-example1-plugin(1) contains an
97 embedded disk image. To copy it out:
98 nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
100 If the source suffers from temporary network failures
102 nbdkit-retry-filter(1) or nbdkit-retry-request-filter(1) may help.
103 To overwrite a file inside an uncompressed tar file (the file being
105 overwritten must be the same size), use nbdkit-tar-filter(1) like this:
106 nbdkit -U - file data.tar --filter=tar tar-entry=disk.img \
108 --run 'qemu-img convert -n disk.img $nbd'
109
111 The --exit-with-parent option is almost the opposite of "CAPTIVE
112 NBDKIT" described in the previous section.
113 Running nbdkit with this option, for example from a script:
115 nbdkit --exit-with-parent plugin ... &
117 means that nbdkit will exit automatically if the parent program exits
119 for any reason. This can be used to avoid complicated cleanups or
120 orphaned nbdkit processes.
121 --exit-with-parent is incompatible with forking into the background
123 (because when we fork into the background we lose track of the parent
124 process). Therefore -f / --foreground is implied.
125 If the parent application is multithreaded, then (in the Linux
127 implementation) if the parent thread exits, that will cause nbdkit to
128 exit. Thus in multithreaded applications you usually want to run
129 "nbdkit --exit-with-parent" only from the main thread (unless you
130 actually want nbdkit to exit with the thread, but that may not work
131 reliably on all operating systems).
132 To exit when an unrelated process exits, use nbdkit-exitwhen-filter(1)
134 "exit-when-process-exits" feature.
135 Support for --exit-with-parent
137 This is currently implemented using a non-POSIX feature available in
138 Linux ≥ 2.1.57, FreeBSD ≥ 11.2 and macOS. It won't work on other
139 operating systems (patches welcome to make it work).
140 To test if the current binary supports this feature the most backwards
142 compatible way is:
143 nbdkit --exit-with-parent --version && echo "supported"
145 In nbdkit ≥ 1.32.3, "nbdkit --dump-config" prints either
147 "exit_with_parent=yes" or "exit_with_parent=no" but earlier versions
148 did not have this.
149
151 nbdkit(1), nbdkit-exitlast-filter(1), nbdkit-exitwhen-filter(1),
152 prctl(2) (on Linux), procctl(2) (on FreeBSD).
153
155 Eric Blake
156 Richard W.M. Jones
158 Pino Toscano
160
162 Copyright (C) 2013-2020 Red Hat Inc.
163
165 Redistribution and use in source and binary forms, with or without
166 modification, are permitted provided that the following conditions are
167 met:
168 • Redistributions of source code must retain the above copyright
170 notice, this list of conditions and the following disclaimer.
171 • Redistributions in binary form must reproduce the above copyright
173 notice, this list of conditions and the following disclaimer in the
174 documentation and/or other materials provided with the
175 distribution.
176 • Neither the name of Red Hat nor the names of its contributors may
178 be used to endorse or promote products derived from this software
179 without specific prior written permission.
180 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
182 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
183 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
184 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
185 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
186 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
187 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
188 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
189 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
190 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
191 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
192nbdkit-1.32.5 2023-01-03 nbdkit-captive(1)