1nbdkit-captive(1) NBDKIT nbdkit-captive(1)
2
3
4
6 nbdkit-captive - run nbdkit under another process and have it reliably
7 cleaned up
8
10 nbdkit PLUGIN [...] [-e|--exportname EXPORTNAME] --run "CMD ARGS ..."
11
12 nbdkit --exit-with-parent PLUGIN [...]
13
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
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 $port
67 If ≠ "", the port number that nbdkit is listening on.
68
69 $unixsocket
70 If ≠ "", the Unix domain socket that nbdkit is listening on.
71
72 $exportname
73 The export name (which may be "") that the process should use when
74 connecting to nbdkit, as set by the -e (--exportname) command line
75 option of nbdkit. This only matters to plugins that differentiate
76 what they serve based on the export name requested by the client.
77
78 --run implies --foreground. It is not possible, and probably not
79 desirable, to have nbdkit fork into the background when using --run.
80
81 Even when running captive, nbdkit still listens on the regular TCP/IP
82 port, unless you specify the -p/-U options. If you want a truly
83 private captive nbdkit, then you should create a private random Unix
84 socket, like this:
85
86 nbdkit -U - plugin [args] --run '...'
87
88 Copying data in and out of plugins with captive nbdkit
89 Captive nbdkit + qemu-img(1) can be used to copy data into and out of
90 nbdkit plugins. For example nbdkit-example1-plugin(1) contains an
91 embedded disk image. To copy it out:
92
93 nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
94
95 If plugin requests have a high overhead (for example making HTTP
96 requests to a remote server), adding nbdkit-readahead-filter(1) may
97 help performance:
98
99 nbdkit -U - --filter=readahead curl https://example.com/disk.img \
100 --run 'qemu-img convert $nbd disk.img'
101
102 If the source suffers from temporary network failures
103 nbdkit-retry-filter(1) may help.
104
105 To overwrite a file inside an uncompressed tar file (the file being
106 overwritten must be the same size), use nbdkit-tar-filter(1) like this:
107
108 nbdkit -U - file data.tar --filter=tar tar-entry=disk.img \
109 --run 'qemu-img convert -n disk.img $nbd'
110
112 The --exit-with-parent option is almost the opposite of "CAPTIVE
113 NBDKIT" described in the previous section.
114
115 Running nbdkit with this option, for example from a script:
116
117 nbdkit --exit-with-parent plugin ... &
118
119 means that nbdkit will exit automatically if the parent program exits
120 for any reason. This can be used to avoid complicated cleanups or
121 orphaned nbdkit processes.
122
123 --exit-with-parent is incompatible with forking into the background
124 (because when we fork into the background we lose track of the parent
125 process). Therefore -f / --foreground is implied.
126
127 This is currently implemented using a non-POSIX feature available in
128 Linux ≥ 2.1.57 and FreeBSD ≥ 11.2, so it won't work on other operating
129 systems (patches welcome to make it work).
130
131 If the parent application is multithreaded, then (in the Linux
132 implementation) if the parent thread exits, that will cause nbdkit to
133 exit. Thus in multithreaded applications you usually want to run
134 "nbdkit --exit-with-parent" only from the main thread (unless you
135 actually want nbdkit to exit with the thread, but that may not work
136 reliably on all operating systems).
137
138 To exit when an unrelated process exits, use nbdkit-exitwhen-filter(1)
139 "exit-when-process-exits" feature.
140
142 nbdkit(1), nbdkit-exitlast-filter(1), nbdkit-exitwhen-filter(1),
143 prctl(2) (on Linux), procctl(2) (on FreeBSD).
144
146 Eric Blake
147
148 Richard W.M. Jones
149
150 Pino Toscano
151
153 Copyright (C) 2013-2020 Red Hat Inc.
154
156 Redistribution and use in source and binary forms, with or without
157 modification, are permitted provided that the following conditions are
158 met:
159
160 • Redistributions of source code must retain the above copyright
161 notice, this list of conditions and the following disclaimer.
162
163 • Redistributions in binary form must reproduce the above copyright
164 notice, this list of conditions and the following disclaimer in the
165 documentation and/or other materials provided with the
166 distribution.
167
168 • Neither the name of Red Hat nor the names of its contributors may
169 be used to endorse or promote products derived from this software
170 without specific prior written permission.
171
172 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
173 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
174 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
175 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
176 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
177 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
178 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
179 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
180 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
181 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
182 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
183
184
185
186nbdkit-1.25.8 2021-05-25 nbdkit-captive(1)