Provided by: nbdkit_1.24.1-2ubuntu4_amd64 
NAME
nbdkit-data-plugin - nbdkit plugin for serving data from the command line
SYNOPSIS
nbdkit data [data=]'0 1 2 3 @0x1fe 0x55 0xaa'
[size=SIZE] [allocator=sparse|...]
nbdkit data base64='aGVsbG8gbmJka2l0IHVzZXI='
[size=SIZE] [allocator=sparse|...]
nbdkit data raw='binary_data'
[size=SIZE] [allocator=sparse|...]
DESCRIPTION
"nbdkit-data-plugin" is a plugin for nbdkit(1) which serves a small amount of data specified directly on
the command line. The plugin gets its name from the "data:" URI scheme used by web browsers. This is
mainly useful for testing NBD clients.
You can serve data read-only using the -r flag, or read-write. Any writes are thrown away when nbdkit
exits.
Most operating systems have command line size limits which are quite a lot smaller than any desirable
disk image, so specifying a large, fully populated disk image on the command line would not be possible.
However 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 to the full size), or use the "data" parameter creatively to
make mostly sparse disk images.
The "size" parameter can specify any virtual size up to the maximum supported by nbdkit (2⁶³-1 bytes).
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.
See also nbdkit-pattern-plugin(3).
Create a 1 MB disk with one empty MBR-formatted partition
nbdkit data '
@0x1b8 178 190 207 221 0 0 0 0 2 0 131 32 32 0 1 0 0 0 255 7
@0x1fe 85 170
' size=1M
This example was created by running:
$ rm -f disk
$ truncate -s 1M disk
$ echo start=1 | sfdisk disk
Device Boot Start End Sectors Size Id Type
disk1 1 2047 2047 1023.5K 83 Linux
$ ./disk2data.pl disk
The "disk2data.pl" script is provided in the nbdkit sources
(https://github.com/libguestfs/nbdkit/blob/master/plugins/data/disk2data.pl).
See also nbdkit-partitioning-plugin(1).
Create a disk image with sector-aligned data
nbdkit data ' <file1 @^512 <file2 @^512 <file3 @^512 '
Local binary files file1, file2 and file3 are copied into the disk image. Regardless of the size of
these files, they will all be aligned to 512-byte sector boundaries. Furthermore because of the final
alignment operation ("@^512") the total size of the disk will also be rounded to a whole number of
sectors.
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. The
same random data is repeated over 16 sectors.
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.
"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.
PARAMETERS
Exactly one of the "data", "base64" or "raw" parameters must be supplied.
[data=]DATA
Specify the disk data using a simple compact format. See "DATA FORMAT" below.
"data=" is a magic config key and may be omitted in most cases. See "Magic parameters" in nbdkit(1).
base64=BASE64
The "base64" parameter can be used to 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 can be used to supply raw binary data directly on the command line.
It is 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.
DATA FORMAT
The "data" parameter lets you specify small disk images in a simple, compact format. It is a string
containing a list of bytes which are written into the disk image sequentially. You can move the virtual
offset where bytes are written using @offset.
For example:
nbdkit data '0 1 2 3 @0x1fe 0x55 0xaa'
creates a 0x200 = 512 byte (1 sector) image containing the four bytes "0 1 2 3" at the start, and the two
bytes "0x55 0xaa" at the end of the sector, with the remaining 506 bytes in the middle being all zeroes.
In this example the size (512 bytes) is implied by the data. But you could additionally use the "size"
parameter to either truncate or extend (with zeroes) the disk image.
Whitespace between fields in the string is ignored.
Fields in the string can be:
@OFFSET
Moves the current offset to "OFFSET". The offset may be specified as either decimal, octal (prefixed
by 0) or hexadecimal (prefixed by "0x"). Offset @0 is the first byte of the disk.
@+N
@-N (nbdkit ≥ 1.22)
Add or subtract "N" from the current offset.
@^ALIGNMENT
(nbdkit ≥ 1.22)
If the current offset is not a multiple of "ALIGNMENT" then the offset is moved forward to the next
multiple. The next byte written will be aligned to "ALIGNMENT".
BYTE
Write "BYTE" at the current offset and advance the offset by 1 byte. The byte may be specified as
either decimal, octal (prefixed by 0) or hexadecimal (prefixed by "0x"). To add repeated bytes use
"BYTE*N"
<FILE
(nbdkit ≥ 1.8)
Read the contents of binary FILE into the disk image at the current offset. The offset is
incremented by the size of the file. The filename can be a relative or absolute path, but cannot
contain whitespace in the name.
<(SCRIPT)
(nbdkit ≥ 1.24, not Windows)
Substitute the output of the shell script or external program as a binary blob and advance the offset
by the length in bytes of the output. You can use this 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++))
done )[:32768] '
The script may contain "(" and ")" characters, but they must be in matching pairs. A script can
produce a finite amount of output; or (as in the example) an infinite amount which must be truncated
using the "[:len]" slice operator.
Scripts must be idempotent, producing the same output each time they are run. This is because
optimizations might change the order of evaluation or number of times the script is called and you
could get different output in a future version of nbdkit.
"STRING"
(nbdkit ≥ 1.22)
Write a string into the image at the current offset and advance the offset by the length of the
string. To include special characters in the string you can escape them in the same way as C strings
(eg. a double quote character within the string should be written "\""). Be careful with shell
quoting around the whole data parameter.
( ... )
(nbdkit ≥ 1.24)
Group a set of expressions into a single expression.
"( ... )" recursively creates a new data parser so any of the above operators 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.
expression * N
(nbdkit ≥ 1.24)
Repeat the expression "N" times. The offset is 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]
(nbdkit ≥ 1.24)
Take a slice of the expression. Slices are [start:end+1] where start and end are the first and last
byte offsets of the expression desired. Either or both may be omitted. [:len] means to take the
first len bytes. [start:] means to take bytes from offset start to the end of the expression.
expression -> \NAME
\NAME
(nbdkit ≥ 1.24)
Assign an expression to a name which can be used later. Names can be used in the current scope (or
any scopes nested within the current scope), but disappear at the end of the current scope. Names
start with a backslash character followed by one or more alphanumeric, dash and underscore. 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)
Substitute command line parameters or environment variables. The variable is written in the same
language as the "data" parameter, and when substituted it creates a nested scope like "( ... )"
expressions. These are all equivalent:
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.
disk2data.pl script
This script can convert from small disk images into the data format described above.
It is provided in the nbdkit sources. See
https://github.com/libguestfs/nbdkit/blob/master/plugins/data/disk2data.pl
FILES
$plugindir/nbdkit-data-plugin.so
The plugin.
Use "nbdkit --dump-config" to find the location of $plugindir.
VERSION
"nbdkit-data-plugin" first appeared in nbdkit 1.6.
SEE ALSO
nbdkit(1), nbdkit-captive(1), nbdkit-plugin(3), nbdkit-info-plugin(1), nbdkit-memory-plugin(1),
nbdkit-null-plugin(1), nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1), nbdkit-random-plugin(1),
nbdkit-sparse-random-plugin(1), nbdkit-tmpdisk-plugin(1), nbdkit-zero-plugin(1),
https://github.com/libguestfs/nbdkit/blob/master/plugins/data/disk2data.pl,
https://en.wikipedia.org/wiki/Base64.
AUTHORS
Richard W.M. Jones
COPYRIGHT
Copyright (C) 2018-2020 Red Hat Inc.
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.