1nbdkit-info-plugin(1) NBDKIT nbdkit-info-plugin(1)
2
3
4
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
16 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
23 "mode=address" creates a disk which contains the client's IP address
24 and port number as a string.
25
26 "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
30 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
38 $ 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
46 size = 5
47 buf = b"hello"
48
49 By running the info plugin, you can pass whole bootable VMs on the qemu
50 command line:
51
52 $ 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
69 Another use for the info plugin is to send back the client's IP
70 address:
71
72 $ nbdkit info mode=address
73 $ nbdsh -u 'nbd://localhost' -c 'print(h.pread(h.get_size(), 0))'
74
75 which will print something like:
76
77 b'[::1]:58912'
78
79 This plugin can also return the wallclock time:
80
81 $ 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
89 or the nbdkit server uptime:
90
91 $ 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
96 or the time since the client opened the connection:
97
98 $ 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
109 [mode=]base64exportname
110 Send the export name passed by the client, assuming the client
111 string is base64 encoded.
112
113 This mode is only supported if nbdkit was compiled with GnuTLS ≥
114 3.6.0. You can find out by checking if:
115
116 $ nbdkit info --dump-plugin
117
118 contains:
119
120 info_base64=yes
121
122 [mode=]exportname
123 Send the raw export name passed by the client. Note the export
124 name cannot contain ASCII NUL characters.
125
126 This is the default mode.
127
128 [mode=]time
129 Reflect server wallclock time as seconds and microseconds since the
130 Epoch (see gettimeofday(2)):
131
132 ┌────────┬────────┬────────────┬──────────────────────┐
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
142 To be able to read this atomically you must read the whole 12 bytes
143 in a single request.
144
145 Note that exposing server time may be insecure. It is safer to use
146 "mode=uptime" or "mode=conntime" instead.
147
148 [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
154 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
158 [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
163 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
167 "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
174 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
194 · Redistributions of source code must retain the above copyright
195 notice, this list of conditions and the following disclaimer.
196
197 · 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
202 · 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
206 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.
217
218
219
220nbdkit-1.18.4 2020-04-16 nbdkit-info-plugin(1)