1nbdkit-info-plugin(1) NBDKIT nbdkit-info-plugin(1)
2
6 nbdkit-info-plugin - serve client and server information
7
9 nbdkit info [mode=]exportname|base64exportname|address|
10 time|uptime|conntime
11
13 "nbdkit-info-plugin" is a test plugin which serves information about
14 the client and server in a disk image back to the client.
15 In its default mode ("mode=exportname") it converts the export name
17 passed from the client into a disk image. "mode=base64exportname" is
18 similar except the client must base64-encode the data in the export
19 name, allowing arbitrary binary data to be sent (see "EXAMPLES" below
20 to make this clearer). Export names are limited to 4096 bytes by the
21 NBD protocol, although some clients have smaller limits.
22 "mode=address" creates a disk which contains the client's IP address
24 and port number as a string.
25 "mode=time", "mode=uptime" and "mode=conntime" report server wallclock
27 time, nbdkit uptime, or time since the connection was opened
28 respectively and may be used to measure latency.
29 The plugin only supports read-only access. To make the disk writable,
31 add nbdkit-cow-filter(1) on top.
32
34 Create a “reflection disk”. By setting the export name to "hello" when
35 we open it, a virtual disk of only 5 bytes containing these characters
36 is created. We then display the contents:
37 $ nbdkit --exit-with-parent info mode=exportname &
39 $ nbdsh -u 'nbd://localhost/hello' -c - <<'EOF'
40 size = h.get_size()
41 print("size = %d" % size)
42 buf = h.pread(size, 0)
43 print("buf = %r" % buf)
44 EOF
45 size = 5
47 buf = b"hello"
48 By running the info plugin, you can pass whole bootable VMs on the qemu
50 command line:
51 $ nbdkit info mode=base64exportname
53 $ qemu-system-x86_64 \
54 -drive 'snapshot=on,file.driver=nbd,file.host=localhost,file.port=10809,file.export=
55 tACwA80QtBOzCrABuRwAtgCyAL0ZfM0Q9CoqKiBIZWxsbyBmcm9tIG5iZGtp
56 dCEgKioqDQoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
57 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
58 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
59 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
60 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
61 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
62 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
63 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
64 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
65 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
66 AAAAAAAAAAAAAAAAAAAAVao=
67 '
68 Another use for the info plugin is to send back the client's IP
70 address:
71 $ nbdkit info mode=address
73 $ nbdsh -u 'nbd://localhost' -c 'print(h.pread(h.get_size(), 0))'
74 which will print something like:
76 b'[::1]:58912'
78 This plugin can also return the wallclock time:
80 $ nbdkit info time --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
82 00000000 00 00 00 00 5d 8f 24 c7 00 04 24 01
83 └─────┬─────┘
84 ┌─┘
85 │
86 $ date --date="@$(( 0x5d8f24c7 ))"
87 Sat 28 Sep 10:15:51 BST 2019
88 or the nbdkit server uptime:
90 $ nbdkit info uptime --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
92 00000000 00 00 00 00 00 00 00 00 00 00 60 4b
93 └──┬──┘
94 0x604b is about 25ms
95 or the time since the client opened the connection:
97 $ nbdkit info conntime --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
99 00000000 00 00 00 00 00 00 00 00 00 00 00 e0
100 └─┬─┘
101 0xe0 is about 200μs
102
104 [mode=]address
105 Send the client's IP address and client port number as a string in
106 the usual format. For Unix sockets this sets the disk to the
107 string "unix" to avoid leaking host paths.
108 This mode is only supported on some platforms. You can find out if
110 it is supported by checking if:
111 $ nbdkit info --dump-plugin
113 contains:
115 info_address=yes
117 [mode=]base64exportname
119 Send the export name passed by the client, assuming the client
120 string is base64 encoded.
121 This mode is only supported if nbdkit was compiled with GnuTLS ≥
123 3.6.0. You can find out by checking if:
124 $ nbdkit info --dump-plugin
126 contains:
128 info_base64=yes
130 [mode=]exportname
132 Send the raw export name passed by the client. Note the export
133 name cannot contain ASCII NUL characters.
134 This is the default mode.
136 [mode=]time
138 Reflect server wallclock time as seconds and microseconds since the
139 Epoch (see gettimeofday(2)):
140 ┌────────┬────────┬────────────┬──────────────────────┐
142 │ offset │ length │ format │ field │
143 ╞════════╪════════╪════════════╪══════════════════════╡
144 │ 0 │ 8 │ 64 bit int │ seconds │
145 │ │ │ big endian │ │
146 ├────────┼────────┼────────────┼──────────────────────┤
147 │ 8 │ 4 │ 32 bit int │ microseconds │
148 │ │ │ big endian │ │
149 └────────┴────────┴────────────┴──────────────────────┘
150 To be able to read this atomically you must read the whole 12 bytes
152 in a single request.
153 Note that exposing server time may be insecure. It is safer to use
155 "mode=uptime" or "mode=conntime" instead.
156 [mode=]uptime
158 Reflect nbdkit uptime in seconds and microseconds (ie. both fields
159 are 0 immediately after nbdkit starts, although a client would
160 never be able to observe this). The format is exactly the same as
161 for "mode=time" above.
162 In the current implementation this can jump forwards or backwards
164 discontinuously if the server time is adjusted. In future we may
165 fix this bug.
166 [mode=]conntime
168 Reflect time since the NBD client connection was opened in seconds
169 and microseconds. The format is exactly the same as for
170 "mode=time" above.
171 In the current implementation this can jump forwards or backwards
173 discontinuously if the server time is adjusted. In future we may
174 fix this bug.
175 "mode=" is a magic config key and may be omitted in most cases.
177 See "Magic parameters" in nbdkit(1).
178
180 $plugindir/nbdkit-info-plugin.so
181 The plugin.
182 Use "nbdkit --dump-config" to find the location of $plugindir.
184
186 "nbdkit-info-plugin" first appeared in nbdkit 1.16.
187
189 nbdkit(1), nbdkit-plugin(3), nbdkit-cow-filter(1),
190 nbdkit-data-plugin(1).
191
193 Richard W.M. Jones
194
196 Copyright (C) 2019 Red Hat Inc.
197
199 Redistribution and use in source and binary forms, with or without
200 modification, are permitted provided that the following conditions are
201 met:
202 • Redistributions of source code must retain the above copyright
204 notice, this list of conditions and the following disclaimer.
205 • Redistributions in binary form must reproduce the above copyright
207 notice, this list of conditions and the following disclaimer in the
208 documentation and/or other materials provided with the
209 distribution.
210 • Neither the name of Red Hat nor the names of its contributors may
212 be used to endorse or promote products derived from this software
213 without specific prior written permission.
214 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
216 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
217 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
218 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
219 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
220 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
221 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
222 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
223 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
224 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
225 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
226nbdkit-1.32.5 2023-01-03 nbdkit-info-plugin(1)