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, 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

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 --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

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       [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

FILES

171       $plugindir/nbdkit-info-plugin.so
172           The plugin.
173
174           Use "nbdkit --dump-config" to find the location of $plugindir.
175

VERSION

177       "nbdkit-info-plugin" first appeared in nbdkit 1.16.
178

SEE ALSO

180       nbdkit(1), nbdkit-plugin(3), nbdkit-cow-filter(1),
181       nbdkit-data-plugin(1).
182

AUTHORS

184       Richard W.M. Jones
185
187       Copyright (C) 2019 Red Hat Inc.
188

LICENSE

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.16.1                     2019-12-03             nbdkit-info-plugin(1)
Impressum