| nbdkit-info-plugin(1) | NBDKIT | nbdkit-info-plugin(1) |
nbdkit-info-plugin - serve client and server information
nbdkit info [mode=]exportname|base64exportname|address|
time|uptime|conntime
"nbdkit-info-plugin" is a test plugin which serves information about the client and server in a disk image back to the client.
In its default mode ("mode=exportname") it converts the export name passed from the client into a disk image. "mode=base64exportname" is similar except the client must base64-encode the data in the export name, allowing arbitrary binary data to be sent (see "EXAMPLES" below to make this clearer). Export names are limited to 4096 bytes by the NBD protocol, although some clients have smaller limits.
"mode=address" creates a disk which contains the client's IP address and port number as a string.
"mode=time", "mode=uptime" and "mode=conntime" report server wallclock time, nbdkit uptime, or time since the connection was opened respectively and may be used to measure latency.
The plugin only supports read-only access. To make the disk writable, add nbdkit-cow-filter(1) on top.
Create a “reflection disk”. By setting the export name to "hello" when we open it, a virtual disk of only 5 bytes containing these characters is created. We then display the contents:
$ nbdkit --exit-with-parent info mode=exportname &
$ nbdsh -u 'nbd://localhost/hello' -c - <<'EOF'
size = h.get_size()
print("size = %d" % size)
buf = h.pread(size, 0)
print("buf = %r" % buf)
EOF
size = 5
buf = b"hello"
By running the info plugin, you can pass whole bootable VMs on the qemu command line:
$ nbdkit info mode=base64exportname $ qemu-system-x86_64 \ -drive 'snapshot=on,file.driver=nbd,file.host=localhost,file.port=10809,file.export= tACwA80QtBOzCrABuRwAtgCyAL0ZfM0Q9CoqKiBIZWxsbyBmcm9tIG5iZGtp dCEgKioqDQoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAVao= '
Another use for the info plugin is to send back the client's IP address:
$ nbdkit info mode=address $ nbdsh -u 'nbd://localhost' -c 'print(h.pread(h.get_size(), 0))'
which will print something like:
b'[::1]:58912'
This plugin can also return the wallclock time:
$ nbdkit info time --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
00000000 00 00 00 00 5d 8f 24 c7 00 04 24 01
└─────┬─────┘
┌─┘
│
$ date --date="@$(( 0x5d8f24c7 ))"
Sat 28 Sep 10:15:51 BST 2019
or the nbdkit server uptime:
$ nbdkit info uptime --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
00000000 00 00 00 00 00 00 00 00 00 00 60 4b
└──┬──┘
0x604b is about 25ms
or the time since the client opened the connection:
$ nbdkit info conntime --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
00000000 00 00 00 00 00 00 00 00 00 00 00 e0
└─┬─┘
0xe0 is about 200μs
This mode is only supported if nbdkit was compiled with GnuTLS ≥ 3.6.0. You can find out by checking if:
$ nbdkit info --dump-plugin
contains:
info_base64=yes
This is the default mode.
┌────────┬────────┬────────────┬──────────────────────┐
│ offset │ length │ format │ field │
╞════════╪════════╪════════════╪══════════════════════╡
│ 0 │ 8 │ 64 bit int │ seconds │
│ │ │ big endian │ │
├────────┼────────┼────────────┼──────────────────────┤
│ 8 │ 4 │ 32 bit int │ microseconds │
│ │ │ big endian │ │
└────────┴────────┴────────────┴──────────────────────┘
To be able to read this atomically you must read the whole 12 bytes in a single request.
Note that exposing server time may be insecure. It is safer to use "mode=uptime" or "mode=conntime" instead.
In the current implementation this can jump forwards or backwards discontinuously if the server time is adjusted. In future we may fix this bug.
In the current implementation this can jump forwards or backwards discontinuously if the server time is adjusted. In future we may fix this bug.
"mode=" is a magic config key and may be omitted in most cases. See "Magic parameters" in nbdkit(1).
Use "nbdkit --dump-config" to find the location of $plugindir.
"nbdkit-info-plugin" first appeared in nbdkit 1.16.
nbdkit(1), nbdkit-plugin(3), nbdkit-cow-filter(1), nbdkit-data-plugin(1).
Richard W.M. Jones
Copyright (C) 2019 Red Hat Inc.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
| 2021-01-20 | nbdkit-1.24.1 |