plugins/pattern/nbdkit-pattern-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-pattern-plugin - plugin to serve a fixed pattern of data for testing
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit pattern [size=]SIZE
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-pattern-plugin> is a plugin for L<nbdkit(1)> which serves a
  12 fixed pattern of data, read only.  This is used for testing nbdkit
  13 filters and NBD clients.
  14
  15 The fixed pattern is the offset, as a 64 bit big endian integer, every
  16 8 bytes.  In hexadecimal this looks like:
  17
  18  offset                         data
  19   0000:   00 00 00 00 00 00 00 00   00 00 00 00 00 00 00 08
  20   0010:   00 00 00 00 00 00 00 10   00 00 00 00 00 00 00 18
  21   0020:   00 00 00 00 00 00 00 20   00 00 00 00 00 00 00 28
  22                                   ↗ └──────────┬──────────┘
  23               byte at offset 0x28              │
  24                                                │
  25                                      64 bit big endian int
  26                                      encoding offset 0x28
  27
  28 The size of the virtual disk must be specified using the C<size>
  29 parameter.  If the size is not a multiple of 8 then the last 8 byte
  30 offset in the pattern is truncated.
  31
  32 =head2 Largest possible size
  33
  34 nbdkit itself limits plugins to S<2⁶³-1> bytes
  35 (S<decimal: 9223372036854775807>,
  36 S<hexadecimal: 0x7fff_ffff_ffff_ffff>).
  37
  38 To test if NBD clients are free of bugs (not to mention nbdkit itself)
  39 you can use:
  40
  41  nbdkit pattern 9223372036854775807
  42
  43 Note this is too large for qemu to open.
  44
  45 =head1 PARAMETERS
  46
  47 =over 4
  48
  49 =item [B<size=>]SIZE
  50
  51 Specify the virtual size of the disk image.
  52
  53 This parameter is required.
  54
  55 C<size=> is a magic config key and may be omitted in most cases.
  56 See L<nbdkit(1)/Magic parameters>.
  57
  58 =back
  59
  60 =head1 FILES
  61
  62 =over 4
  63
  64 =item F<$plugindir/nbdkit-pattern-plugin.so>
  65
  66 The plugin.
  67
  68 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
  69
  70 =back
  71
  72 =head1 VERSION
  73
  74 C<nbdkit-pattern-plugin> first appeared in nbdkit 1.6.
  75
  76 =head1 SEE ALSO
  77
  78 L<nbdkit(1)>,
  79 L<nbdkit-plugin(3)>,
  80 L<nbdkit-data-plugin(1)>,
  81 L<nbdkit-full-plugin(1)>,
  82 L<nbdkit-null-plugin(1)>,
  83 L<nbdkit-offset-filter(1)>,
  84 L<nbdkit-random-plugin(1)>,
  85 L<nbdkit-zero-plugin(1)>.
  86
  87 =head1 AUTHORS
  88
  89 Richard W.M. Jones
  90
  91 =head1 COPYRIGHT
  92
  93 Copyright (C) 2018 Red Hat Inc.