1nbdkit-sparse-random-plugin(1)      NBDKIT      nbdkit-sparse-random-plugin(1)
2
3
4

NAME

6       nbdkit-sparse-random-plugin - make sparse random disks
7

SYNOPSIS

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

DESCRIPTION

14       "nbdkit-sparse-random-plugin" is a plugin for nbdkit(1) which makes
15       disks containing sparse blocks of random data.  These disks have a
16       similar shape to virtual machine disks, and this plugin can be used to
17       benchmark disk copying tools like nbdcopy(1).  To get a non-sparse
18       random disk, see nbdkit-random-plugin(1).
19
20       The size of the virtual disk must be specified using the "size"
21       parameter.  If you specify the "seed" parameter then you will get the
22       same random data over multiple runs with the same seed.
23
24       The "percent" parameter controls the percentage of the disk which
25       contains random data versus sparse empty space.
26
27       The plugin does not generate random data spread evenly over the disk.
28       Instead to make it look more like a real virtual machine disk, it tries
29       to create runs of data and runs of empty space.  The "runlength"
30       parameter controls the average length of each run of 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 "random-content=true".  This is not the default
35       because earlier testing of this plugin showed that a great deal of time
36       was spent generating random content.  The random content is generated
37       using a method which is not cryptographically secure.
38
39   Writes and testing copying
40       Writes to the disk verify that the data written is the same as the data
41       read (if not, returning EIO).  Thus when testing copies you can use a
42       single instance of this plugin for both read and write:
43
44        nbdkit -U - sparse-random size=1T --run 'nbdcopy "$uri" "$uri"'
45
46       "qemu-img convert" could be used in place of nbdcopy.  See also
47       nbdkit-checkwrite-filter(1).
48

PARAMETERS

50       percent=N
51           Specify the approximate percentage of the disk which contains
52           random data versus sparse empty space.  The default is 10 (10%).
53           "percent=0" will create a completely empty disk and "percent=100"
54           will create a completely full disk.
55
56       random-content=true
57           By default a single random non-zero byte is repeated over the whole
58           block, which is fast to generate and check.  If you want blocks
59           where each byte is random, use this setting.
60
61       runlength=N
62           Specify the average length of runs of random data.  This is
63           expressed in bytes and the usual modifiers can be used.  The
64           default is 16M, meaning that (on average) data runs will be 16
65           megabytes in length.
66
67       seed=SEED
68           Specify the random seed to get repeatable data over multiple runs.
69
70           If not specified then a random seed is chosen.
71
72       [size=]SIZE
73           Specify the virtual size of the disk image.
74
75           This parameter is required.
76
77           "size=" is a magic config key and may be omitted in most cases.
78           See "Magic parameters" in nbdkit(1).
79

FILES

81       $plugindir/nbdkit-sparse-random-plugin.so
82           The plugin.
83
84           Use "nbdkit --dump-config" to find the location of $plugindir.
85

VERSION

87       "nbdkit-sparse-random-plugin" first appeared in nbdkit 1.24.
88

SEE ALSO

90       nbdkit(1), nbdkit-plugin(3), nbdkit-data-plugin(1),
91       nbdkit-full-plugin(1), nbdkit-null-plugin(1), nbdkit-pattern-plugin(1),
92       nbdkit-random-plugin(1), nbdkit-zero-plugin(1), nbdcopy(1),
93       qemu-img(1).
94

AUTHORS

96       Richard W.M. Jones
97

COPYRIGHT

99       Copyright Red Hat
100

LICENSE

102       Redistribution and use in source and binary forms, with or without
103       modification, are permitted provided that the following conditions are
104       met:
105
106       •   Redistributions of source code must retain the above copyright
107           notice, this list of conditions and the following disclaimer.
108
109       •   Redistributions in binary form must reproduce the above copyright
110           notice, this list of conditions and the following disclaimer in the
111           documentation and/or other materials provided with the
112           distribution.
113
114       •   Neither the name of Red Hat nor the names of its contributors may
115           be used to endorse or promote products derived from this software
116           without specific prior written permission.
117
118       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
119       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
120       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
121       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
122       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
123       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
124       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
125       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
126       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
127       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
128       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
129
130
131
132nbdkit-1.34.4                     2023-09-26    nbdkit-sparse-random-plugin(1)