1nbdkit-info-plugin(1)               NBDKIT               nbdkit-info-plugin(1)
2
3
4

NAME

6       nbdkit-info-plugin - serve client and server information
7

SYNOPSIS

9        nbdkit info [mode=]exportname|base64exportname|address|
10                           time|uptime|conntime
11

DESCRIPTION

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, although some clients have smaller limits.
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

EXAMPLES

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 -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
89       or the nbdkit server uptime:
90
91        $ 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
96       or the time since the client opened the connection:
97
98        $ 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

PARAMETERS

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           This mode is only supported on some platforms.  You can find out if
110           it is supported by checking if:
111
112            $ nbdkit info --dump-plugin
113
114           contains:
115
116            info_address=yes
117
118       [mode=]base64exportname
119           Send the export name passed by the client, assuming the client
120           string is base64 encoded.
121
122           This mode is only supported if nbdkit was compiled with GnuTLS ≥
123           3.6.0.  You can find out by checking if:
124
125            $ nbdkit info --dump-plugin
126
127           contains:
128
129            info_base64=yes
130
131       [mode=]exportname
132           Send the raw export name passed by the client.  Note the export
133           name cannot contain ASCII NUL characters.
134
135           This is the default mode.
136
137       [mode=]time
138           Reflect server wallclock time as seconds and microseconds since the
139           Epoch (see gettimeofday(2)):
140
141            ┌────────┬────────┬────────────┬──────────────────────┐
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
151           To be able to read this atomically you must read the whole 12 bytes
152           in a single request.
153
154           Note that exposing server time may be insecure.  It is safer to use
155           "mode=uptime" or "mode=conntime" instead.
156
157       [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
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=]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
172           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
176           "mode=" is a magic config key and may be omitted in most cases.
177           See "Magic parameters" in nbdkit(1).
178

FILES

180       $plugindir/nbdkit-info-plugin.so
181           The plugin.
182
183           Use "nbdkit --dump-config" to find the location of $plugindir.
184

VERSION

186       "nbdkit-info-plugin" first appeared in nbdkit 1.16.
187

SEE ALSO

189       nbdkit(1), nbdkit-plugin(3), nbdkit-cow-filter(1),
190       nbdkit-data-plugin(1).
191

AUTHORS

193       Richard W.M. Jones
194
196       Copyright Red Hat
197

LICENSE

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
203       •   Redistributions of source code must retain the above copyright
204           notice, this list of conditions and the following disclaimer.
205
206       •   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
211       •   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
215       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.
226
227
228
229nbdkit-1.34.4                     2023-09-26             nbdkit-info-plugin(1)
Impressum