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, and nbdkit limits them to a few bytes smaller than this.
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 --connect $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 --connect $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 --connect $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 [mode=]base64exportname
110 Send the export name passed by the client, assuming the client
111 string is base64 encoded.
112 This mode is only supported if nbdkit was compiled with GnuTLS ≥
114 3.6.0. You can find out by checking if:
115 $ nbdkit info --dump-plugin
117 contains:
119 info_base64=yes
121 [mode=]exportname
123 Send the raw export name passed by the client. Note the export
124 name cannot contain ASCII NUL characters.
125 This is the default mode.
127 [mode=]time
129 Reflect server wallclock time as seconds and microseconds since the
130 Epoch (see gettimeofday(2)):
131 ┌────────┬────────┬────────────┬──────────────────────┐
133 │ offset │ length │ format │ field │
134 ╞════════╪════════╪════════════╪══════════════════════╡
135 │ 0 │ 8 │ 64 bit int │ seconds │
136 │ │ │ big endian │ │
137 ├────────┼────────┼────────────┼──────────────────────┤
138 │ 8 │ 4 │ 32 bit int │ microseconds │
139 │ │ │ big endian │ │
140 └────────┴────────┴────────────┴──────────────────────┘
141 To be able to read this atomically you must read the whole 12 bytes
143 in a single request.
144 Note that exposing server time may be insecure. It is safer to use
146 "mode=uptime" or "mode=conntime" instead.
147 [mode=]uptime
149 Reflect nbdkit uptime in seconds and microseconds (ie. both fields
150 are 0 immediately after nbdkit starts, although a client would
151 never be able to observe this). The format is exactly the same as
152 for "mode=time" above.
153 In the current implementation this can jump forwards or backwards
155 discontinuously if the server time is adjusted. In future we may
156 fix this bug.
157 [mode=]conntime
159 Reflect time since the NBD client connection was opened in seconds
160 and microseconds. The format is exactly the same as for
161 "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=" is a magic config key and may be omitted in most cases.
168 See "Magic parameters" in nbdkit(1).
169
171 $plugindir/nbdkit-info-plugin.so
172 The plugin.
173 Use "nbdkit --dump-config" to find the location of $plugindir.
175
177 "nbdkit-info-plugin" first appeared in nbdkit 1.16.
178
180 nbdkit(1), nbdkit-plugin(3), nbdkit-cow-filter(1),
181 nbdkit-data-plugin(1).
182
184 Richard W.M. Jones
185
187 Copyright (C) 2019 Red Hat Inc.
188
190 Redistribution and use in source and binary forms, with or without
191 modification, are permitted provided that the following conditions are
192 met:
193 · Redistributions of source code must retain the above copyright
195 notice, this list of conditions and the following disclaimer.
196 · Redistributions in binary form must reproduce the above copyright
198 notice, this list of conditions and the following disclaimer in the
199 documentation and/or other materials provided with the
200 distribution.
201 · Neither the name of Red Hat nor the names of its contributors may
203 be used to endorse or promote products derived from this software
204 without specific prior written permission.
205 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
207 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
208 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
209 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
210 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
211 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
212 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
213 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
214 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
215 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
216 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
217nbdkit-1.16.1 2019-12-03 nbdkit-info-plugin(1)