plugins/info/nbdkit-info-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-info-plugin - serve client and server information
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit info [mode=]exportname|base64exportname|address|
   8                     time|uptime|conntime
   9
  10 =head1 DESCRIPTION
  11
  12 C<nbdkit-info-plugin> is a test plugin which serves information about
  13 the client and server in a disk image back to the client.
  14
  15 In its default mode (C<mode=exportname>) it converts the export name
  16 passed from the client into a disk image.  C<mode=base64exportname> is
  17 similar except the client must base64-encode the data in the export
  18 name, allowing arbitrary binary data to be sent (see L</EXAMPLES>
  19 below to make this clearer).  Export names are limited to 4096 bytes
  20 by the NBD protocol, although some clients have smaller limits.
  21
  22 C<mode=address> creates a disk which contains the client's IP address
  23 and port number as a string.
  24
  25 C<mode=time>, C<mode=uptime> and C<mode=conntime> report server
  26 wallclock time, nbdkit uptime, or time since the connection was opened
  27 respectively and may be used to measure latency.
  28
  29 The plugin only supports read-only access.  To make the disk writable,
  30 add L<nbdkit-cow-filter(1)> on top.
  31
  32 =head1 EXAMPLES
  33
  34 Create a “reflection disk”.  By setting the export name to C<"hello">
  35 when we open it, a virtual disk of only 5 bytes containing these
  36 characters 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 =for paragraph
  47
  48  size = 5
  49  buf = b"hello"
  50
  51 By running the info plugin, you can pass whole bootable VMs on the
  52 qemu command line:
  53
  54  $ nbdkit info mode=base64exportname
  55  $ qemu-system-x86_64 \
  56    -drive 'snapshot=on,file.driver=nbd,file.host=localhost,file.port=10809,file.export=
  57  tACwA80QtBOzCrABuRwAtgCyAL0ZfM0Q9CoqKiBIZWxsbyBmcm9tIG5iZGtp
  58  dCEgKioqDQoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  59  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  60  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  61  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  62  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  63  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  64  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  65  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  66  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  67  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  68  AAAAAAAAAAAAAAAAAAAAVao=
  69  '
  70
  71 Another use for the info plugin is to send back the client's IP
  72 address:
  73
  74  $ nbdkit info mode=address
  75  $ nbdsh -u 'nbd://localhost' -c 'print(h.pread(h.get_size(), 0))'
  76
  77 which will print something like:
  78
  79  b'[::1]:58912'
  80
  81 This plugin can also return the wallclock time:
  82
  83  $ nbdkit info time --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
  84  00000000  00 00 00 00 5d 8f 24 c7  00 04 24 01
  85                       └─────┬─────┘
  86                           ┌─┘
  87                           │
  88  $ date --date="@$(( 0x5d8f24c7 ))"
  89  Sat 28 Sep 10:15:51 BST 2019
  90
  91 or the nbdkit server uptime:
  92
  93  $ nbdkit info uptime --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
  94  00000000  00 00 00 00 00 00 00 00  00 00 60 4b
  95                                          └──┬──┘
  96                                    0x604b is about 25ms
  97
  98 or the time since the client opened the connection:
  99
 100  $ nbdkit info conntime --run 'nbdsh -u "$uri" -c "sys.stdout.buffer.write(h.pread(12,0))" | hexdump -C'
 101  00000000  00 00 00 00 00 00 00 00  00 00 00 e0
 102                                             └─┬─┘
 103                                      0xe0 is about 200μs
 104
 105 =head1 PARAMETERS
 106
 107 =over 4
 108
 109 =item [B<mode=>]B<address>
 110
 111 Send the client's IP address and client port number as a string in the
 112 usual format.  For Unix sockets this sets the disk to the string
 113 C<"unix"> to avoid leaking host paths.
 114
 115 This mode is only supported on some platforms.  You can find out if it
 116 is supported by checking if:
 117
 118  $ nbdkit info --dump-plugin
 119
 120 contains:
 121
 122  info_address=yes
 123
 124 =item [B<mode=>]B<base64exportname>
 125
 126 Send the export name passed by the client, assuming the client string
 127 is base64 encoded.
 128
 129 This mode is only supported if nbdkit was compiled with GnuTLS E<ge>
 130 3.6.0.  You can find out by checking if:
 131
 132  $ nbdkit info --dump-plugin
 133
 134 contains:
 135
 136  info_base64=yes
 137
 138 =item [B<mode=>]B<exportname>
 139
 140 Send the raw export name passed by the client.  Note the export name
 141 cannot contain ASCII NUL characters.
 142
 143 This is the default mode.
 144
 145 =item [B<mode=>]B<time>
 146
 147 Reflect server wallclock time as seconds and microseconds since the
 148 Epoch (see L<gettimeofday(2)>):
 149
 150  ┌────────┬────────┬────────────┬──────────────────────┐
 151  │ offset │ length │ format     │ field                │
 152  ╞════════╪════════╪════════════╪══════════════════════╡
 153  │   0    │    8   │ 64 bit int │ seconds              │
 154  │        │        │ big endian │                      │
 155  ├────────┼────────┼────────────┼──────────────────────┤
 156  │   8    │    4   │ 32 bit int │ microseconds         │
 157  │        │        │ big endian │                      │
 158  └────────┴────────┴────────────┴──────────────────────┘
 159
 160 To be able to read this atomically you must read the whole 12 bytes in
 161 a single request.
 162
 163 Note that exposing server time may be insecure.  It is safer to use
 164 C<mode=uptime> or C<mode=conntime> instead.
 165
 166 =item [B<mode=>]B<uptime>
 167
 168 Reflect nbdkit uptime in seconds and microseconds (ie. both fields are
 169 C<0> immediately after nbdkit starts, although a client would never be
 170 able to observe this).  The format is exactly the same as for
 171 C<mode=time> above.
 172
 173 In the current implementation this can jump forwards or backwards
 174 discontinuously if the server time is adjusted.  In future we may fix
 175 this bug.
 176
 177 =item [B<mode=>]B<conntime>
 178
 179 Reflect time since the NBD client connection was opened in seconds and
 180 microseconds.  The format is exactly the same as for C<mode=time>
 181 above.
 182
 183 In the current implementation this can jump forwards or backwards
 184 discontinuously if the server time is adjusted.  In future we may fix
 185 this bug.
 186
 187 C<mode=> is a magic config key and may be omitted in most cases.
 188 See L<nbdkit(1)/Magic parameters>.
 189
 190 =back
 191
 192 =head1 FILES
 193
 194 =over 4
 195
 196 =item F<$plugindir/nbdkit-info-plugin.so>
 197
 198 The plugin.
 199
 200 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 201
 202 =back
 203
 204 =head1 VERSION
 205
 206 C<nbdkit-info-plugin> first appeared in nbdkit 1.16.
 207
 208 =head1 SEE ALSO
 209
 210 L<nbdkit(1)>,
 211 L<nbdkit-plugin(3)>,
 212 L<nbdkit-cow-filter(1)>,
 213 L<nbdkit-data-plugin(1)>.
 214
 215 =head1 AUTHORS
 216
 217 Richard W.M. Jones
 218
 219 =head1 COPYRIGHT
 220
 221 Copyright Red Hat