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 [...] --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").
19

CAPTIVE NBDKIT

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
25       Some examples should make this clear.
26
27       To run nbdkit captive under qemu:
28
29        nbdkit file disk.img --run 'qemu -drive file=$nbd,if=virtio'
30
31       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
35       Running nbdkit captive under guestfish:
36
37        nbdkit file disk.img --run 'guestfish --format=raw -a $nbd -i'
38
39       When guestfish exits, nbdkit is killed.
40
41       The following shell variables are available in the --run argument:
42
43       $uri
44           A URI that refers to the nbdkit port or socket in the preferred
45           form documented by the NBD project.  If nbdkit was started with the
46           -e option to set the preferred export name, this is included in the
47           URI.
48
49       $nbd
50           An older URL that refers to the nbdkit port or socket in a manner
51           specific to certain tools.  This form does not include an export
52           name, even if -e was used.
53
54           Note there is some magic here, since qemu and guestfish URLs have a
55           different format, so nbdkit tries to guess which you are running.
56           If the magic doesn't work, try using the variables below instead.
57
58       $port
59           If ≠ "", the port number that nbdkit is listening on.
60
61       $unixsocket
62           If ≠ "", the Unix domain socket that nbdkit is listening on.
63
64       $exportname
65           The default export name (which may be "") that nbdkit will
66           advertise in response to NBD_OPT_LIST.  This comes from the -e
67           (--exportname) command line option.
68
69       --run implies --foreground.  It is not possible, and probably not
70       desirable, to have nbdkit fork into the background when using --run.
71
72       Even when running captive, nbdkit still listens on the regular TCP/IP
73       port, unless you specify the -p/-U options.  If you want a truly
74       private captive nbdkit, then you should create a private random Unix
75       socket, like this:
76
77        nbdkit -U - plugin [args] --run '...'
78
79   Copying data in and out of plugins with captive nbdkit
80       Captive nbdkit + qemu-img(1) can be used to copy data into and out of
81       nbdkit plugins.  For example nbdkit-example1-plugin(1) contains an
82       embedded disk image.  To copy it out:
83
84        nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
85
86       If plugin requests have a high overhead (for example making HTTP
87       requests to a remote server), adding nbdkit-readahead-filter(1) may
88       help performance:
89
90        nbdkit -U - --filter=readahead curl https://example.com/disk.img \
91               --run 'qemu-img convert $nbd disk.img'
92
93       If the source suffers from temporary network failures
94       nbdkit-retry-filter(1) may help.
95
96       To overwrite a file inside an uncompressed tar file (the file being
97       overwritten must be the same size), use nbdkit-tar-plugin(1) like this:
98
99        nbdkit -U - tar tar=data.tar file=disk.img \
100          --run 'qemu-img convert -n disk.img $nbd'
101

EXIT WITH PARENT

103       The --exit-with-parent option is almost the opposite of "CAPTIVE
104       NBDKIT" described in the previous section.
105
106       Running nbdkit with this option, for example from a script:
107
108        nbdkit --exit-with-parent plugin ... &
109
110       means that nbdkit will exit automatically if the parent program exits
111       for any reason.  This can be used to avoid complicated cleanups or
112       orphaned nbdkit processes.
113
114       --exit-with-parent is incompatible with forking into the background
115       (because when we fork into the background we lose track of the parent
116       process).  Therefore -f / --foreground is implied.
117
118       This is currently implemented using a non-POSIX feature available in
119       Linux ≥ 2.1.57 and FreeBSD ≥ 11.2, so it won't work on other operating
120       systems (patches welcome to make it work).
121
122       If the parent application is multithreaded, then (in the Linux
123       implementation) if the parent thread exits, that will cause nbdkit to
124       exit.  Thus in multithreaded applications you usually want to run
125       "nbdkit --exit-with-parent" only from the main thread (unless you
126       actually want nbdkit to exit with the thread, but that may not work
127       reliably on all operating systems).
128

AUTHORS

133       Eric Blake
134
135       Richard W.M. Jones
136
137       Pino Toscano
138

COPYRIGHT

140       Copyright (C) 2013-2018 Red Hat Inc.
141

LICENSE

143       Redistribution and use in source and binary forms, with or without
144       modification, are permitted provided that the following conditions are
145       met:
146
147       ·   Redistributions of source code must retain the above copyright
148           notice, this list of conditions and the following disclaimer.
149
150       ·   Redistributions in binary form must reproduce the above copyright
151           notice, this list of conditions and the following disclaimer in the
152           documentation and/or other materials provided with the
153           distribution.
154
155       ·   Neither the name of Red Hat nor the names of its contributors may
156           be used to endorse or promote products derived from this software
157           without specific prior written permission.
158
159       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
160       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
161       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
162       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
163       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
164       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
165       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
166       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
167       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
168       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
169       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
170
171
172
173nbdkit-1.16.1                     2019-12-03                 nbdkit-captive(1)