nbdkit-data-plugin(1)

📦

version 1.48.1 · 14 versions

💾 nbdkit-data-plugin(1) — NBDKIT 💾

okay bestie, welcome to nbdkit-data-plugin, a page from the NBDKIT manual. this one's a whole vibe: it's the plugin that serves data you literally just type on the command line. no files, no disks, just vibes and bytes. ✨

🌸 NAME 🌸

nbdkit-data-plugin — the nbdkit plugin for serving data straight off the command line, fr fr.

✨ SYNOPSIS ✨

nbdkit data [data=]'0 1 2 3 @0x1fe 0x55 0xaa'
            [size=SIZE] [allocator=sparse|malloc|zstd]

nbdkit data base64='aGVsbG8gbmJka2l0IHVzZXI='
            [size=SIZE] [allocator=sparse|malloc|zstd]

nbdkit data raw='binary_data'
            [size=SIZE] [allocator=sparse|malloc|zstd]

🫶 DESCRIPTION 🫶

nbdkit-data-plugin is a plugin for nbdkit(1) that serves up a small amount of data — and the data is specified right there on the command line. iconic behaviour honestly. it got its name from the data: URI scheme that web browsers use, which is exactly the same energy. it's mainly useful for testing NBD clients, iykyk. 💅

you can serve the data read-only with the -r flag, or read-write. and if you do write to it? any writes are thrown away when nbdkit exits. gone. evaporated. not our problem. 🦋

now, real talk: most operating systems have command line size limits, and those limits are quite a lot smaller than any disk image you'd actually want. so specifying a big, fully populated disk image on the command line? literally not possible, bestie. BUT — and this is the slay part — you can specify a small amount of data at the beginning of the image, possibly followed by zeroes (using the size parameter to pad the image out to the full size), or you can use the data parameter creatively to make mostly sparse disk images. main character energy. 👑

the size parameter can specify any virtual size up to the maximum supported by nbdkit (2⁶³-1 bytes). yes, that many. we love a big number. 🌈

💖 EXAMPLES 💖

🎀 Create small disks filled with test patterns

nbdkit data ' ( 0x55 0xAA )*2048 '
nbdkit data ' ( "Hello" )*2000 ' size=8192

the first command creates a disk containing 4096 bytes filled with the repeating bytes 0x55 0xAA. the second command repeats "HelloHelloHello...", truncating the disk to exactly 8192 bytes. so cute, so consistent. 🍓

🎀 Create a 1 MB disk with MBR-format partition table

nbdkit data '
  @0x1be    # MBR first partition entry
    0           # Partition status
    0 2 0       # CHS start
    0x83        # Partition type (Linux)
    0x20 0x20 0 # CHS last sector
    le32:1      # LBA first sector
    le32:0x7ff  # LBA number of sectors
  @0x1fe    # Boot signature
    0x55 0xaa
  ' size=1M

a more flexible way to create partitions is to use nbdkit-partitioning-plugin(1). and if you want to create a data string from an existing disk, use the disk2data.pl script provided in the nbdkit sources (https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/data/disk2data.pl). periodt. 💅

🎀 Create a disk image with sector-aligned data

nbdkit data ' <file1 @^512 <file2 @^512 <file3 @^512 '

local binary files file1, file2 and file3 get copied into the disk image. and regardless of how big those files are, they will all be aligned to 512-byte sector boundaries. also — because of that final alignment operation (@^512) — the total size of the disk will also get rounded to a whole number of sectors. it's giving tidy. 🧚

🎀 Create a disk with the same random data in each sector

nbdkit data ' </dev/urandom[:512]*16 '

the expression </dev/urandom[:512] reads 512 bytes (one sector) of randomness from the system. then the same random data gets repeated over 16 sectors. chaos, but make it consistent. 🔥

🎀 Create a 1 MB disk with some nonsense data at the beginning

nbdkit data base64=MTIz size=1M

the above command serves the bytes 0x31 0x32 0x33 (which is the base64 decoding of MTIz), followed by 1M - 3 bytes of zeroes. so: a lil snack of data, then a whole lotta nothing. 🙈

🎀 "Hello, world" using this plugin

$ nbdkit data raw='Hello, world!' --run 'nbdcopy "$uri" - | cat'
Hello, world!

this works by creating a disk containing the string Hello, world!. nbdcopy(1) connects to the server using an NBD URI ($uri) and copies the disk to stdout (-). the extra cat(1) is needed because nbdcopy refuses to write raw disk data to a terminal. it's got boundaries. respect them. 😭

👑 PARAMETERS 👑

exactly one of the data, base64 or raw parameters must be supplied. not two. not zero. one. 💀

[data=]DATA — specify the disk data using a simple compact format. see DATA FORMAT below. the data= prefix may be omitted in most cases. see "Magic parameters" in nbdkit(1).
base64=BASE64 — the base64 parameter lets you supply binary data encoded in base64 on the command line. this is only supported if nbdkit was compiled with GnuTLS ≥ 3.6.0. you can find out by checking if:

$ nbdkit data --dump-plugin

contains:

data_base64=yes

raw=BINARY — the raw parameter lets you supply raw binary data directly on the command line. it's usually quite difficult to do this unless you are running nbdkit from another program (see nbdkit-captive(1)). one particular problem is that the data must not contain zero bytes (ie. \0), since those will be processed in C to mean the end of the string. in almost all cases it is better to use base64 encoding or the custom data format.
size=SIZE — the data is truncated or extended to the size specified. this parameter is optional: if omitted, the size is defined by the size of the data, raw or base64 parameter.
allocator=sparse
allocator=malloc[,mlock=true]
allocator=zstd — (nbdkit ≥ 1.22) select the backend allocation strategy. see "ALLOCATORS" in nbdkit-memory-plugin(1). the default is sparse.

to be continued, bestie… 💜

ok bestie, this is the part where it gets ✨spicy✨ — the actual data mini-language. buckle up 💖

🧬 DATA FORMAT 🧬

so the data parameter is how you hand nbdkit a whole little disk image in one cute compact string. it's literally just a list of bytes, written into the disk image one after another, in order. and whenever you want to jump somewhere else, you use @offset to move the virtual offset where the next byte gets written. slay.

 nbdkit data '0 1 2 3 @0x1fe 0x55 0xaa'

and that creates:

             total size 0x200 = 512 bytes (1 sector)
┌──────┬──────┬──────┬──────┬───────── ── ── ───┬──────┬──────┐
│   0  │   1  │   2  │   3  │  0     0  ...  0  │ 0x55 │ 0xaa │
└──────┴──────┴──────┴──────┴───────── ── ── ───┴──────┴──────┘
                                                  ↑
                                            offset 0x1fe

see how in that example the size is just implied by the data? yeah. but you can also use the size parameter to either truncate the disk image or extend it (with zeroes). and here's another way to write the exact same disk — we align the offset to the end of the sector, then move back 2 bytes to drop the signature in:

 nbdkit data '0 1 2 3 @^0x200 @-2 le16:0xaa55'

ok so here are all the fields you can put in the string, one by one, no skips, we are NOT skipping any 💅

BYTE

writes a single byte at the current offset and advances the offset by 1. the byte can be decimal, octal (prefixed with 0), or hexadecimal (prefixed with 0x). and if you want a bunch of the same byte, use the * operator, like 0xFF*16.

`le16:WORD`, `be16:WORD`, `le32:WORD`, `be32:WORD`, `le64:WORD`, `be64:WORD`

(nbdkit ≥ 1.28)

writes a word in little endian (le) or big endian (be), 16/32/64 bits long, and advances the offset by 2/4/8. the word can be decimal, octal or hexadecimal. for example:

 nbdkit data ' be32:0x1 '

generates the 4 byte sequence 0 0 0 1. iconic.

`base64:BASE64`

(nbdkit ≥ 1.46)

decodes the BASE64 string into bytes and writes them into the image. the offset advances by however many bytes got decoded. and bestie, the BASE64 string cannot contain any whitespace, not even one.

this is only supported if nbdkit was compiled with GnuTLS ≥ 3.6.0. the output of nbdkit data --dump-plugin will contain data_base64=yes.

`@OFFSET`

moves the current offset to OFFSET. the offset can be decimal, octal (prefixed with 0) or hexadecimal (prefixed with 0x); and if you're using decimal you can also slap a scaling suffix on it like k or M. @0 is the first byte of the disk.

`@+N`, `@-N`

(nbdkit ≥ 1.22)

adds or subtracts N from the current offset. simple as.

`@^ALIGNMENT`

(nbdkit ≥ 1.22)

if the current offset isn't a multiple of ALIGNMENT, the offset gets moved forward to the next multiple. so the next byte you write will be aligned to ALIGNMENT. very satisfying fr.

`<FILE`

(nbdkit ≥ 1.8)

reads the contents of binary FILE into the disk image at the current offset. the offset gets incremented by the size of the file. the filename can be a relative or absolute path, but it cannot contain whitespace. nope.

`<(SCRIPT)`

(nbdkit ≥ 1.24, not Windows)

substitutes the output of the shell script or external program as a binary blob, and advances the offset by the length in bytes of that output. this is your moment if you want to create more complex test patterns. for example, this produces a 32K disk image with an incrementing test pattern in groups of 4 bytes:

 nbdkit data ' <( i=0
                  while :; do
                      printf "%04d" $i; i=$((i+1))
                  done )[:32768] '

the script may contain ( and ) characters, but they have to be in matching pairs. a script can produce a finite amount of output; or (like in that example) an infinite amount, which you then have to truncate with the [:len] slice operator.

🚨 scripts must be idempotent — they have to produce the same output every single time they run. this is because optimizations might change the order of evaluation or the number of times the script gets called, and you could get different output in a future version of nbdkit. no cap, just make them deterministic.

also note that the script gets passed to /bin/sh. on some platforms like Debian this might not be a full-featured shell. so don't assume fancy bash stuff is there 🙈

`"STRING"`

(nbdkit ≥ 1.22)

writes a string into the image at the current offset and advances the offset by the length of the string. to include special characters in the string you can escape them the same way as C strings (eg. a double quote character inside the string should be written "\""). and be careful with your shell quoting around the whole data parameter, it's giving delicate 💅

`( ... )`

(nbdkit ≥ 1.24)

groups a set of expressions into a single expression.

( ... ) recursively creates a new data parser, so any expression can appear inside, including nested ( ... ). note that offsets and alignments within the subpattern are relative to the start of the subpattern, not relative to the final disk image. sneaky but important.

`expression * N`

(nbdkit ≥ 1.24)

repeats the expression N times. the offset gets incremented by the length of the expression × N. for example, to create a repeating pattern of 0x55, 0xAA for 512 (2×256) bytes, do:

 nbdkit data '( 0x55 0xAA ) * 256'

`expression [N:M]`, `expression [start:]`, `expression [:len]`

(nbdkit ≥ 1.24)

takes a slice of the expression. slices are [start:end+1] where start and end are the first and last byte offsets of the expression you want. either or both may be omitted.

[start:] means take bytes from offset start all the way to the end of the expression. [:len] means truncate the expression to len bytes.

`expression -> \NAME`, `\NAME`

(nbdkit ≥ 1.24)

assigns an expression to a name you can use later. names can be used in the current scope (or any scopes nested inside the current scope), but they disappear at the end of the current scope. names start with a backslash character followed by one or more alphanumeric characters, dashes and underscores. for example, this makes two identical sectors both containing a boot signature at the end:

 nbdkit data ' ( 0x55 0xAA ) -> \boot-signature
               ( @0x1fe \boot-signature ) -> \sector
               \sector \sector '

`$VAR`

(nbdkit ≥ 1.24)

substitutes command line parameters or environment variables. the variable is written in the same language as the data parameter, and when it gets substituted it creates a nested scope like ( ... ) expressions do. these three commands all do the same thing:

 nbdkit data '$pattern*16' pattern='0x55 0xAA'

 export pattern='0x55 0xAA' ; nbdkit data '$pattern*16'

 nbdkit data '( 0x55 0xAA )*16'

`# COMMENT`

(nbdkit ≥ 1.24)

# begins a comment stretching to the end of the current line. go off, annotate your disk images 🫶

🪄 disk2data.pl script

this script can convert from small disk images into the data format described above. yes, the reverse direction. queen behavior.

it's provided in the nbdkit sources. see https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/data/disk2data.pl

📁 FILES 📁

$plugindir/nbdkit-data-plugin.so — the plugin itself.

use nbdkit --dump-config to find the location of $plugindir. 🔍

🕰️ VERSION 🕰️

nbdkit-data-plugin first appeared in nbdkit 1.6. a classic, an OG, a legend.

(the last two are links, bestie, go click them, they're the good stuff 🌈)

👑 AUTHORS 👑

Richard W.M. Jones

⚖️ LICENSE ⚖️

ok so here's the legal bit, and no we are not skipping it, we are reading the whole thing like the responsible main characters we are ✨

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.

aaaand that's the whole page bestie 💖 this one's from nbdkit-1.48.1, dated 2026-08-29, and it's the nbdkit-data-plugin(1) manual. go forth and build your tiny cursed disk images, you absolute icon 🎀✨

📦 where this page comes from

fedora 44: nbdkit-basic-plugins 1.48.1-1.fc44 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms

nbdkit-data-plugin(1)