plugins/reflection/nbdkit-reflection-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-reflection-plugin - reflect client info back to the client
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit reflection [mode=]exportname|base64exportname|address
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-reflection-plugin> is a test plugin which reflects
  12 information sent by the client back to the client.
  13
  14 In its default mode (C<mode=exportname>) it converts the export name
  15 passed from the client into a disk image.  C<mode=base64exportname> is
  16 similar except the client must base64-encode the data in the export
  17 name, allowing arbitrary binary data to be sent (see L</EXAMPLES>
  18 below to make this clearer).  Export names are limited to 4096 bytes
  19 by the NBD protocol, and nbdkit limits them to a few bytes smaller
  20 than this.
  21
  22 C<mode=address> creates a disk which contains the client's IP address
  23 and port number as a string.
  24
  25 The plugin only supports read-only access.  To make the disk writable,
  26 add L<nbdkit-cow-filter(1)> on top.
  27
  28 =head1 EXAMPLES
  29
  30 Create a reflection disk.  By setting the export name to C<"hello">
  31 when we open it, a virtual disk of only 5 bytes containing these
  32 characters is created.  We then display the contents:
  33
  34  $ nbdkit --exit-with-parent reflection mode=exportname &
  35  $ nbdsh -u 'nbd://localhost/hello' -c - <<'EOF'
  36  size = h.get_size()
  37  print("size = %d" % size)
  38  buf = h.pread(size, 0)
  39  print("buf = %r" % buf)
  40  EOF
  41
  42  size = 5
  43  buf = b"hello"
  44
  45 By running a reflection plugin, you can pass whole bootable VMs on the
  46 qemu command line:
  47
  48  $ nbdkit reflection mode=base64exportname
  49  $ qemu-system-x86_64 \
  50    -drive 'snapshot=on,file.driver=nbd,file.host=localhost,file.port=10809,file.export=
  51  tACwA80QtBOzCrABuRwAtgCyAL0ZfM0Q9CoqKiBIZWxsbyBmcm9tIG5iZGtp
  52  dCEgKioqDQoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  53  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  54  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  55  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  56  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  57  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  58  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  59  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  60  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  61  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  62  AAAAAAAAAAAAAAAAAAAAVao=
  63  '
  64
  65 Another use for the reflection plugin is to send back the client's IP
  66 address:
  67
  68  $ nbdkit reflection mode=address
  69  $ nbdsh -u 'nbd://localhost' -c 'print(h.pread(h.get_size(), 0))'
  70
  71 which will print something like:
  72
  73  b'[::1]:58912'
  74
  75 =head1 PARAMETERS
  76
  77 =over 4
  78
  79 =item [B<mode=>]B<address>
  80
  81 Reflect the client's IP address and client port number as a string in
  82 the usual format.  For Unix sockets this sets the disk to the string
  83 C<"unix"> to avoid leaking host paths.
  84
  85 =item [B<mode=>]B<base64exportname>
  86
  87 Reflect the export name passed by the client, assuming the client
  88 string is base64 encoded.
  89
  90 This mode is only supported if nbdkit was compiled with GnuTLS E<ge>
  91 3.6.0.  You can find out by checking if:
  92
  93  $ nbdkit reflection --dump-plugin
  94
  95 contains:
  96
  97  reflection_base64=yes
  98
  99 =item [B<mode=>]B<exportname>
 100
 101 Reflect the raw export name passed by the client.  Note the export
 102 name cannot contain ASCII NUL characters.
 103
 104 This is the default mode.
 105
 106 C<mode=> is a magic config key and may be omitted in most cases.
 107 See L<nbdkit(1)/Magic parameters>.
 108
 109 =back
 110
 111 =head1 FILES
 112
 113 =over 4
 114
 115 =item F<$plugindir/nbdkit-reflection-plugin.so>
 116
 117 The plugin.
 118
 119 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 120
 121 =back
 122
 123 =head1 VERSION
 124
 125 C<nbdkit-reflection-plugin> first appeared in nbdkit 1.16.
 126
 127 =head1 SEE ALSO
 128
 129 L<nbdkit(1)>,
 130 L<nbdkit-plugin(3)>,
 131 L<nbdkit-cow-filter(1)>,
 132 L<nbdkit-data-plugin(1)>.
 133
 134 =head1 AUTHORS
 135
 136 Richard W.M. Jones
 137
 138 =head1 COPYRIGHT
 139
 140 Copyright (C) 2019 Red Hat Inc.