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 [...] --run "CMD ARGS ..."
11 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").
19
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 Some examples should make this clear.
26 To run nbdkit captive under qemu:
28 nbdkit file disk.img --run 'qemu -drive file=$nbd,if=virtio'
30 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 Running nbdkit captive under guestfish:
36 nbdkit file disk.img --run 'guestfish --format=raw -a $nbd -i'
38 When guestfish exits, nbdkit is killed.
40 The following shell variables are available in the --run argument:
42 $nbd
44 A URL that refers to the nbdkit port or socket.
45 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 $port
51 If ≠ "", the port number that nbdkit is listening on.
52 $unixsocket
54 If ≠ "", the Unix domain socket that nbdkit is listening on.
55 --run implies --foreground. It is not possible, and probably not
57 desirable, to have nbdkit fork into the background when using --run.
58 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 nbdkit -U - plugin [args] --run '...'
65 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 nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
72 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 nbdkit -U - --filter=readahead curl https://example.com/disk.img \
78 --run 'qemu-img convert $nbd disk.img'
79 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 nbdkit -U - tar tar=data.tar file=disk.img \
84 --run 'qemu-img convert -n disk.img $nbd'
85
87 The --exit-with-parent option is almost the opposite of "CAPTIVE
88 NBDKIT" described in the previous section.
89 Running nbdkit with this option, for example from a script:
91 nbdkit --exit-with-parent plugin ... &
93 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 --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 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 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
114 nbdkit(1), prctl(2) (on Linux), procctl(2) (on FreeBSD).
115
117 Eric Blake
118 Richard W.M. Jones
120 Pino Toscano
122
124 Copyright (C) 2013-2018 Red Hat Inc.
125
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 · Redistributions of source code must retain the above copyright
132 notice, this list of conditions and the following disclaimer.
133 · 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 · 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 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.
154nbdkit-1.12.3 2019-05-21 nbdkit-captive(1)