nbdkit-sparse-random-plugin(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

💖 nbdkit-sparse-random-plugin(1) 💖

okay bestie, sit down, hydrate, because we're about to talk about making sparse random disks and honestly? it's giving main character energy. this is the nbdkit-sparse-random-plugin page from the nbdkit manual, and i'm gonna walk you through every single crumb of it. no skips. 🍓

✨ NAME ✨

nbdkit-sparse-random-plugin — make sparse random disks 🦋

✨ SYNOPSIS ✨

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

look at her. iconic. 💅

✨ DESCRIPTION ✨

so nbdkit-sparse-random-plugin is a plugin for nbdkit(1) and what it does is make disks that contain sparse blocks of random data. these disks have a similar shape to virtual machine disks, and you can use this plugin to benchmark disk copying tools like nbdcopy(1). 💖

want a non-sparse random disk instead? that's a whole different girl, go see nbdkit-random-plugin(1). and if what you actually want is a plugin with a predictable test pattern, that's nbdkit-pattern-plugin(1). 🎀

you must specify the size of the virtual disk using the size parameter. and if you specify the seed parameter, then you'll get the same random data over multiple runs with that same seed. repeatable queen. ✨

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

here's the thing tho — 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 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 random-content=true. it's not the default because earlier testing of this plugin showed that a great deal of time was spent generating random content. 😭 and also, the random content is generated using a method which is not cryptographically secure. so don't be using this for your secrets, babe. 💀

🌸 Writes and testing copying 🌸

writes to the disk verify that the data written is the same as the data read (if not, returning EIO). so when you're 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"'

qemu-img convert could be used in place of nbdcopy. see also nbdkit-checkwrite-filter(1). 👑

✨ PARAMETERS ✨

  • blocksize=N — set the block size. this is the granularity that this plugin operates at, and sparse extents will be aligned to the block size. it must be a power of 2 and ≥ 1024. the default is 4096. 🧚
  • percent=N — specify the approximate percentage of the disk which contains random data versus sparse empty space. the default is 10 (10%). percent=0 will create a completely empty disk and percent=100 will create a completely full disk. full send or nothing at all, no in between. 💅
  • 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. 🎀
  • 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. 🌈
  • seed=SEED — specify the random seed to get repeatable data over multiple runs. if not specified then a random seed is chosen. 🙈
  • [size=]SIZE — specify the virtual size of the disk image. this parameter is required. the size= prefix may be omitted in most cases. see "Magic parameters" in nbdkit(1). ⭐

✨ FILES ✨

  • $plugindir/nbdkit-sparse-random-plugin.so — the plugin. use nbdkit --dump-config to find the location of $plugindir. 🦋

✨ VERSION ✨

nbdkit-sparse-random-plugin first appeared in nbdkit 1.24. a classic, a legend, an era. 👑

✨ SEE ALSO ✨

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

the whole friend group, fr fr. 🫶

✨ AUTHORS ✨

Richard W.M. Jones 💜

Copyright Red Hat

✨ LICENSE ✨

redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 💖
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. ✨
  • Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. 🎀
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

and that's the whole page, bestie!! this was nbdkit-1.48.1, dated 2026-08-29, straight from the nbdkit-sparse-random-plugin(1) manual. you ate that 💖✨🎀🦋 go benchmark something and slay. 😭💅

📦 where this page comes from