=head1 NAME

nbdkit-sparse-random-plugin - make sparse random disks

=head1 SYNOPSIS

 nbdkit sparse-random [size=]SIZE [seed=SEED]
                      [percent=N] [runlength=N]
                      [random-content=true]

=head1 DESCRIPTION

C<nbdkit-sparse-random-plugin> is a plugin for L<nbdkit(1)> which
makes disks containing sparse blocks of random data.  These disks have
a similar shape to virtual machine disks, and this plugin can be used
to benchmark disk copying tools like L<nbdcopy(1)>.  To get a
non-sparse random disk, see L<nbdkit-random-plugin(1)>.

The size of the virtual disk must be specified using the C<size>
parameter.  If you specify the C<seed> parameter then you will get the
same random data over multiple runs with the same seed.

The C<percent> parameter controls the percentage of the disk which
contains random data versus sparse empty space.

The plugin does not generate random data spread evenly over the disk.
Instead to make it look more like a real virtual machine disk, it
tries to create runs of data and runs of empty space.  The
C<runlength> parameter controls the average length of each run of
random data.

The data in each block normally consists of the same random non-zero
byte repeated over the whole block.  If you want fully random content
within each block use C<random-content=true>.  This is not the default
because earlier testing of this plugin showed that a great deal of
time was spent generating random content.  The random content is
generated using a method which is I<not> cryptographically secure.

=head2 Writes and testing copying

Writes to the disk verify that the data written is the same as the
data read (if not, returning EIO).  Thus when testing copies you can
use a single instance of this plugin for both read and write:

 nbdkit sparse-random size=1T --run 'nbdcopy "$uri" "$uri"'

C<qemu-img convert> could be used in place of nbdcopy.
See also L<nbdkit-checkwrite-filter(1)>.

=head1 PARAMETERS

=over 4

=item B<percent=>N

Specify the approximate percentage of the disk which contains random
data versus sparse empty space.  The default is 10 (10%).
C<percent=0> will create a completely empty disk and C<percent=100>
will create a completely full disk.

=item B<random-content=true>

By default a single random non-zero byte is repeated over the whole
block, which is fast to generate and check.  If you want blocks where
each byte is random, use this setting.

=item B<runlength=>N

Specify the average length of runs of random data.  This is expressed
in bytes and the usual modifiers can be used.  The default is 16M,
meaning that (on average) data runs will be 16 megabytes in length.

=item B<seed=>SEED

Specify the random seed to get repeatable data over multiple runs.

If not specified then a random seed is chosen.

=item [B<size=>]SIZE

Specify the virtual size of the disk image.

This parameter is required.

C<size=> is a magic config key and may be omitted in most cases.
See L<nbdkit(1)/Magic parameters>.

=back

=head1 FILES

=over 4

=item F<$plugindir/nbdkit-sparse-random-plugin.so>

The plugin.

Use C<nbdkit --dump-config> to find the location of C<$plugindir>.

=back

=head1 VERSION

C<nbdkit-sparse-random-plugin> first appeared in nbdkit 1.24.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-plugin(3)>,
L<nbdkit-data-plugin(1)>,
L<nbdkit-full-plugin(1)>,
L<nbdkit-null-plugin(1)>,
L<nbdkit-ones-plugin(1)>,
L<nbdkit-pattern-plugin(1)>,
L<nbdkit-random-plugin(1)>,
L<nbdkit-zero-plugin(1)>,
L<nbdcopy(1)>,
L<qemu-img(1)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
