plugins/sparse-random/nbdkit-sparse-random-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-sparse-random-plugin - make sparse random disks
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit sparse-random [size=]SIZE [seed=SEED]
   8                       [percent=N] [runlength=N]
   9                       [random-content=true]
  10
  11 =head1 DESCRIPTION
  12
  13 C<nbdkit-sparse-random-plugin> is a plugin for L<nbdkit(1)> which
  14 makes disks containing sparse blocks of random data.  These disks have
  15 a similar shape to virtual machine disks, and this plugin can be used
  16 to benchmark disk copying tools like L<nbdcopy(1)>.  To get a
  17 non-sparse random disk, see L<nbdkit-random-plugin(1)>.
  18
  19 The size of the virtual disk must be specified using the C<size>
  20 parameter.  If you specify the C<seed> parameter then you will get the
  21 same random data over multiple runs with the same seed.
  22
  23 The C<percent> parameter controls the percentage of the disk which
  24 contains random data versus sparse empty space.
  25
  26 The plugin does not generate random data spread evenly over the disk.
  27 Instead to make it look more like a real virtual machine disk, it
  28 tries to create runs of data and runs of empty space.  The
  29 C<runlength> parameter controls the average length of each run of
  30 random data.
  31
  32 The data in each block normally consists of the same random non-zero
  33 byte repeated over the whole block.  If you want fully random content
  34 within each block use C<random-content=true>.  This is not the default
  35 because earlier testing of this plugin showed that a great deal of
  36 time was spent generating random content.  The random content is
  37 generated using a method which is I<not> cryptographically secure.
  38
  39 =head2 Writes and testing copying
  40
  41 Writes to the disk verify that the data written is the same as the
  42 data read (if not, returning EIO).  Thus when testing copies you can
  43 use a single instance of this plugin for both read and write:
  44
  45  nbdkit -U - sparse-random size=1T --run 'nbdcopy "$uri" "$uri"'
  46
  47 C<qemu-img convert> could be used in place of nbdcopy.
  48 See also L<nbdkit-checkwrite-filter(1)>.
  49
  50 =head1 PARAMETERS
  51
  52 =over 4
  53
  54 =item B<percent=>N
  55
  56 Specify the approximate percentage of the disk which contains random
  57 data versus sparse empty space.  The default is 10 (10%).
  58 C<percent=0> will create a completely empty disk and C<percent=100>
  59 will create a completely full disk.
  60
  61 =item B<random-content=true>
  62
  63 By default a single random non-zero byte is repeated over the whole
  64 block, which is fast to generate and check.  If you want blocks where
  65 each byte is random, use this setting.
  66
  67 =item B<runlength=>N
  68
  69 Specify the average length of runs of random data.  This is expressed
  70 in bytes and the usual modifiers can be used.  The default is 16M,
  71 meaning that (on average) data runs will be 16 megabytes in length.
  72
  73 =item B<seed=>SEED
  74
  75 Specify the random seed to get repeatable data over multiple runs.
  76
  77 If not specified then a random seed is chosen.
  78
  79 =item [B<size=>]SIZE
  80
  81 Specify the virtual size of the disk image.
  82
  83 This parameter is required.
  84
  85 C<size=> is a magic config key and may be omitted in most cases.
  86 See L<nbdkit(1)/Magic parameters>.
  87
  88 =back
  89
  90 =head1 FILES
  91
  92 =over 4
  93
  94 =item F<$plugindir/nbdkit-sparse-random-plugin.so>
  95
  96 The plugin.
  97
  98 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
  99
 100 =back
 101
 102 =head1 VERSION
 103
 104 C<nbdkit-sparse-random-plugin> first appeared in nbdkit 1.24.
 105
 106 =head1 SEE ALSO
 107
 108 L<nbdkit(1)>,
 109 L<nbdkit-plugin(3)>,
 110 L<nbdkit-data-plugin(1)>,
 111 L<nbdkit-full-plugin(1)>,
 112 L<nbdkit-null-plugin(1)>,
 113 L<nbdkit-pattern-plugin(1)>,
 114 L<nbdkit-random-plugin(1)>,
 115 L<nbdkit-zero-plugin(1)>,
 116 L<nbdcopy(1)>,
 117 L<qemu-img(1)>.
 118
 119 =head1 AUTHORS
 120
 121 Richard W.M. Jones
 122
 123 =head1 COPYRIGHT
 124
 125 Copyright Red Hat