Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
nbdkit-info-plugin(1)		    NBDKIT		 nbdkit-info-plugin(1)

NAME
       nbdkit-info-plugin - serve client and server information

SYNOPSIS
	nbdkit info [mode=]exportname|base64exportname|address|
			   time|uptime|conntime

DESCRIPTION
       "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, and nbdkit	limits them to a few bytes smaller than	this.

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

EXAMPLES
       Create a	areflection diska.  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	--connect $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
			     aaaaaaa~aaaaaa
				 aaa
				 a
	$ date --date="@$(( 0x5d8f24c7 ))"
	Sat 28 Sep 10:15:51 BST	2019

       or the nbdkit server uptime:

	$ nbdkit info uptime --run 'nbdsh --connect $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
						aaaa~aaa
					  0x604b is about 25ms

       or the time since the client opened the connection:

	$ nbdkit info conntime --run 'nbdsh --connect $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
						   aaa~aa
					    0xe0 is about 200I1/4s

PARAMETERS
       [mode=]address
	   Send	the client's IP	address	and client port	number as a string in
	   the usual format.  For Unix sockets this sets the disk to the
	   string "unix" to avoid leaking host paths.

       [mode=]base64exportname
	   Send	the export name	passed by the client, assuming the client
	   string is base64 encoded.

	   This	mode is	only supported if nbdkit was compiled with GnuTLS aY
	   3.6.0.  You can find	out by checking	if:

	    $ nbdkit info --dump-plugin

	   contains:

	    info_base64=yes

       [mode=]exportname
	   Send	the raw	export name passed by the client.  Note	the export
	   name	cannot contain ASCII NUL characters.

	   This	is the default mode.

       [mode=]time
	   Reflect server wallclock time as seconds and	microseconds since the
	   Epoch (see gettimeofday(2)):

	    aaaaaaaaaa~aaaaaaaaa~aaaaaaaaaaaaa~aaaaaaaaaaaaaaaaaaaaaaa
	    a offset a length a	format	   a field		  a
	    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!
	    a	0    a	  8   a	64 bit int a seconds		  a
	    a	     a	      a	big endian a			  a
	    aaaaaaaaaa1/4aaaaaaaaa1/4aaaaaaaaaaaaa1/4aaaaaaaaaaaaaaaaaaaaaaax
	    a	8    a	  4   a	32 bit int a microseconds	  a
	    a	     a	      a	big endian a			  a
	    aaaaaaaaaa'aaaaaaaaa'aaaaaaaaaaaaa'aaaaaaaaaaaaaaaaaaaaaaa

	   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.

       [mode=]uptime
	   Reflect nbdkit uptime in seconds and	microseconds (ie. both fields
	   are 0 immediately after nbdkit starts, although a client would
	   never be able to observe this).  The	format is exactly the same as
	   for "mode=time" above.

	   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=]conntime
	   Reflect time	since the NBD client connection	was opened in seconds
	   and microseconds.  The format is exactly the	same as	for
	   "mode=time" above.

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

FILES
       $plugindir/nbdkit-info-plugin.so
	   The plugin.

	   Use "nbdkit --dump-config" to find the location of $plugindir.

VERSION
       "nbdkit-info-plugin" first appeared in nbdkit 1.16.

SEE ALSO
       nbdkit(1), nbdkit-plugin(3), nbdkit-cow-filter(1),
       nbdkit-data-plugin(1).

AUTHORS
       Richard W.M. Jones

COPYRIGHT
       Copyright (C) 2019 Red Hat Inc.

LICENSE
       Redistribution and use in source	and binary forms, with or without
       modification, are permitted provided that the following conditions are
       met:

       o   Redistributions of source code must retain the above	copyright
	   notice, this	list of	conditions and the following disclaimer.

       o   Redistributions in binary form must reproduce the above copyright
	   notice, this	list of	conditions and the following disclaimer	in the
	   documentation and/or	other materials	provided with the
	   distribution.

       o   Neither the name of Red Hat nor the names of	its contributors may
	   be used to endorse or promote products derived from this software
	   without specific prior written permission.

       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.

nbdkit-1.20.4			  2020-08-28		 nbdkit-info-plugin(1)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | PARAMETERS | FILES | VERSION | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nbdkit-info-plugin&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help