Provided by: nbdkit_1.32.5-1ubuntu2_amd64 bug

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|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) 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 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).  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).

   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.

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

       creates:

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

       In this example the size is implied by the data.  But you could also use the "size"
       parameter to either truncate or extend (with zeroes) the disk image.  Another way to write
       the same disk would be this, where we align the offset to the end of the sector and move
       back 2 bytes to write the signature:

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

       Fields in the string can be:

       BYTE
           Write a byte at the current offset and advance the offset by 1.  The byte may be
           specified as either decimal, octal (prefixed by 0) or hexadecimal (prefixed by "0x").
           To add repeated bytes use the "*" operator (eg. "0xFF*16").

       le16:WORD
       be16:WORD
       le32:WORD
       be32:WORD
       le64:WORD
       be64:WORD
           (nbdkit ≥ 1.28)

           Write a word expressed in little endian (le) or big endian (be) of length 16/32/64
           bits and advance the offset by 2/4/8.  The word may be specified in decimal, octal or
           hexadecimal.  For example:

            nbdkit data ' be32:0x1 '

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

       @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".

       <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; i=$((i+1))
                             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.

           Note that the script is passed to /bin/sh.  On some platforms like Debian this might
           not be a full-featured shell.

       "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 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.

       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://gitlab.com/nbdkit/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://gitlab.com/nbdkit/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.