=head1 NAME

nbdkit-random-plugin - plugin to serve random data

=head1 SYNOPSIS

 nbdkit random [size=]SIZE [seed=SEED] [fast=true]

=head1 DESCRIPTION

C<nbdkit-random-plugin> is a plugin for L<nbdkit(1)> which serves
random data.  This plugin is mainly good for testing NBD clients.
This plugin creates a non-sparse random disk, for a sparse random disk
see L<nbdkit-sparse-random-plugin(1)>.  For a plugin containing a
predictable test pattern see L<nbdkit-pattern-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.

In C<fast=true> mode, the same sector of random data is repeated
across the disk with small variations.  As the name suggests, this is
much faster, and is usually sufficient for testing.

The random data is generated using an I<insecure> method.

=head2 Writes and testing copying

Writing to the disk is possible.  If you do this the plugin will check
that what you are writing exactly matches what would be read at the
same offset (if not, it returns EIO error).  You can use this to test
copying programs by making the source and destination NBD URIs be the
same:

 nbdkit random size=100M --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<fast=true>

Instead of generating completely random data, a single sector of
random data is generated when the plugin starts up, which is
duplicated across the disk with variations.

=item [B<size=>]SIZE

Specify the virtual size of the disk image.

This parameter is required.

C<size=> __IS_MAGIC__

=item B<seed=>SEED

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

If not specified then a random seed is chosen.

=back

=head1 FILES

=over 4

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

The plugin.

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

=back

=head1 VERSION

C<nbdkit-random-plugin> first appeared in nbdkit 1.4.

=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-sparse-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
