.\" Automatically generated by Podwrapper::Man 1.10.3 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-data-plugin 1"
.TH nbdkit-data-plugin 1 "2019-01-26" "nbdkit-1.10.3" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-data\-plugin \- nbdkit plugin for serving data from the command line
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& nbdkit data data="0 1 2 3 @0x1fe 0x55 0xaa" [size=size]
\&
\& nbdkit data base64="aGVsbG8gbmJka2l0IHVzZXI=" [size=size]
\&
\& nbdkit data raw="binary_data" [size=size]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-data\-plugin\*(C'\fR is a plugin for \fBnbdkit\fR\|(1) which serves a
small amount of data specified directly on the command line.  The
plugin gets its name from the \f(CW\*(C`data:\*(C'\fR \s-1URI\s0 scheme used by web
browsers.  This is mainly useful for testing \s-1NBD\s0 clients.
.PP
You can serve data read-only using the \fI\-r\fR flag, or read-write.  Any
writes are thrown away when nbdkit exits.
.PP
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 \f(CW\*(C`size\*(C'\fR parameter to pad
the image to the full size), or use the \f(CW\*(C`data\*(C'\fR parameter creatively
to make mostly sparse disk images.
.PP
The \f(CW\*(C`size\*(C'\fR parameter can specify any virtual size up to the maximum
supported by nbdkit (2⁶³\-1 bytes).
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.IP "Create a 1 \s-1MB\s0 empty disk:" 4
.IX Item "Create a 1 MB empty disk:"
.Vb 1
\& nbdkit data raw= size=1M
.Ve
.Sp
(This is a contrived example, it is better to use
\&\fBnbdkit\-memory\-plugin\fR\|(1) for real applications.)
.IP "Create a 1 \s-1MB\s0 disk with some nonsense data at the beginning:" 4
.IX Item "Create a 1 MB disk with some nonsense data at the beginning:"
.Vb 1
\& nbdkit data base64=MTIz size=1M
.Ve
.Sp
The above command serves the bytes \f(CW\*(C`0x31 0x32 0x33\*(C'\fR (which is the
base64 decoding of \f(CW\*(C`MTIz\*(C'\fR), followed by 1M \- 3 bytes of zeroes.
.IP "Create a 1 \s-1MB\s0 disk with one empty MBR-formatted partition:" 4
.IX Item "Create a 1 MB disk with one empty MBR-formatted partition:"
.Vb 4
\& nbdkit data 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=1048576
.Ve
.Sp
This example was created by running:
.Sp
.Vb 6
\& $ 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
.Ve
.Sp
The \f(CW\*(C`disk2data.pl\*(C'\fR script is provided in the nbdkit sources
(https://github.com/libguestfs/nbdkit/blob/master/plugins/data/disk2data.pl).
.IP "Create a disk with a partition from another file:" 4
.IX Item "Create a disk with a partition from another file:"
.Vb 5
\& nbdkit data 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
\&   @0x200 <partition\-data
\&   " size=1048576
.Ve
.Sp
The \f(CW\*(C`<FILE\*(C'\fR syntax is used to include a file of binary data.
Note that \fBnbdkit\-partitioning\-plugin\fR\|(1) is easier to use and more
flexible.
.IP "Create a 7 \s-1EB\s0 (exabyte) disk with one empty GPT-formatted partition:" 4
.IX Item "Create a 7 EB (exabyte) disk with one empty GPT-formatted partition:"
The data plugin supports huge sparse virtual disks, up to the maximum
size supported by nbdkit itself (2⁶³\-1 bytes =
8 exabytes \- 1 byte).  These cause all sorts of problems for
software and so make excellent test cases.  To partition such a huge
disk requires the \s-1GPT\s0 (\s-1GUID\s0 Partition Table) format since \s-1MBR\s0 is
limited to just 2 \s-1TB.\s0
.Sp
.Vb 10
\& nbdkit data data="
\&   @0x1c0 2 0 0xee 0xfe 0xff 0xff 0x01 0  0 0 0xff 0xff 0xff 0xff
\&   @0x1fe 0x55 0xaa
\&   @0x200 0x45 0x46 0x49 0x20 0x50 0x41 0x52 0x54
\&                 0 0 1 0 0x5c 0 0 0
\&          0x9b 0xe5 0x6a 0xc5 0 0 0 0  1 0 0 0 0 0 0 0
\&          0xff 0xff 0xff 0xff 0xff 0xff 0x37 0  0x22 0 0 0 0 0 0 0
\&          0xde 0xff 0xff 0xff 0xff 0xff 0x37 0
\&                 0x72 0xb6 0x9e 0x0c 0x6b 0x76 0xb0 0x4f
\&          0xb3 0x94 0xb2 0xf1 0x61 0xec 0xdd 0x3c  2 0 0 0 0 0 0 0
\&          0x80 0 0 0 0x80 0 0 0  0x79 0x8a 0xd0 0x7e 0 0 0 0
\&   @0x400 0xaf 0x3d 0xc6 0x0f 0x83 0x84 0x72 0x47
\&                 0x8e 0x79 0x3d 0x69 0xd8 0x47 0x7d 0xe4
\&          0xd5 0x19 0x46 0x95 0xe3 0x82 0xa8 0x4c
\&                 0x95 0x82 0x7a 0xbe 0x1c 0xfc 0x62 0x90
\&          0x80 0 0 0 0 0 0 0  0x80 0xff 0xff 0xff 0xff 0xff 0x37 0
\&          0 0 0 0 0 0 0 0  0x70 0 0x31 0 0 0 0 0
\&   @0x6fffffffffffbe00
\&          0xaf 0x3d 0xc6 0x0f 0x83 0x84 0x72 0x47
\&                 0x8e 0x79 0x3d 0x69 0xd8 0x47 0x7d 0xe4
\&          0xd5 0x19 0x46 0x95 0xe3 0x82 0xa8 0x4c
\&                 0x95 0x82 0x7a 0xbe 0x1c 0xfc 0x62 0x90
\&          0x80 0 0 0 0 0 0 0  0x80 0xff 0xff 0xff 0xff 0xff 0x37 0
\&          0 0 0 0 0 0 0 0  0x70 0 0x31 0 0 0 0 0
\&   @0x6ffffffffffffe00
\&          0x45 0x46 0x49 0x20 0x50 0x41 0x52 0x54
\&                 0 0 1 0 0x5c 0 0 0
\&          0x6c 0x76 0xa1 0xa0 0 0 0 0
\&                 0xff 0xff 0xff 0xff 0xff 0xff 0x37 0
\&          1 0 0 0 0 0 0 0  0x22 0 0 0 0 0 0 0
\&          0xde 0xff 0xff 0xff 0xff 0xff 0x37 0
\&                 0x72 0xb6 0x9e 0x0c 0x6b 0x76 0xb0 0x4f
\&          0xb3 0x94 0xb2 0xf1 0x61 0xec 0xdd 0x3c
\&                 0xdf 0xff 0xff 0xff 0xff 0xff 0x37 0
\&          0x80 0 0 0 0x80 0 0 0  0x79 0x8a 0xd0 0x7e 0 0 0 0
\&   " size=7E
.Ve
.SH "PARAMETERS"
.IX Header "PARAMETERS"
Exactly one of the \f(CW\*(C`data\*(C'\fR, \f(CW\*(C`base64\*(C'\fR or \f(CW\*(C`raw\*(C'\fR parameters must be
supplied.
.IP "\fBdata=\fR\s-1DATA\s0" 4
.IX Item "data=DATA"
Specify the disk data using a simple compact format.  See
\&\*(L"\s-1DATA FORMAT\*(R"\s0 below.
.IP "\fBbase64=\fR\s-1BASE64\s0" 4
.IX Item "base64=BASE64"
The \f(CW\*(C`base64\*(C'\fR parameter can be used to supply binary data encoded in
base64 on the command line.
.Sp
This is only supported if nbdkit was compiled with GnuTLS ≥ 3.6.0.
You can find out by checking if:
.Sp
.Vb 1
\& $ nbdkit data \-\-dump\-plugin
.Ve
.Sp
contains:
.Sp
.Vb 1
\& data_base64=yes
.Ve
.IP "\fBraw=\fR\s-1BINARY\s0" 4
.IX Item "raw=BINARY"
The \f(CW\*(C`raw\*(C'\fR parameter can be used to supply raw binary data directly on
the command line.
.Sp
It is usually quite difficult to do this unless you are running nbdkit
from another program (see \fBnbdkit\-captive\fR\|(1)).  One particular
problem is that the data must not contain zero bytes (ie. \f(CW\*(C`\e0\*(C'\fR) 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 \f(CW\*(C`data\*(C'\fR
format.
.IP "\fBsize=\fR\s-1SIZE\s0" 4
.IX Item "size=SIZE"
The data is truncated or extended to the size specified.
.Sp
This parameter is optional: If omitted the size is defined by the size
of the \f(CW\*(C`data\*(C'\fR, \f(CW\*(C`raw\*(C'\fR or \f(CW\*(C`base64\*(C'\fR parameter.
.SH "DATA FORMAT"
.IX Header "DATA FORMAT"
The \f(CW\*(C`data\*(C'\fR 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 \f(CW@offset\fR.
.PP
For example:
.PP
.Vb 1
\& nbdkit data data="0 1 2 3 @0x1fe 0x55 0xaa"
.Ve
.PP
creates a 0x200 = 512 byte (1 sector) image containing the four bytes
\&\f(CW\*(C`0 1 2 3\*(C'\fR at the start, and the two bytes \f(CW\*(C`0x55 0xaa\*(C'\fR at the end of
the sector, with the remaining 506 bytes in the middle being all
zeroes.
.PP
Fields in the string can be:
.IP "\fB@\fR\s-1OFFSET\s0" 4
.IX Item "@OFFSET"
Moves the current offset to \f(CW\*(C`OFFSET\*(C'\fR.  The offset may be specified as
either decimal, octal (prefixed by \f(CW0\fR) or hexadecimal (prefixed by
\&\f(CW\*(C`0x\*(C'\fR).
.IP "\fB<\fR\s-1FILE\s0" 4
.IX Item "<FILE"
Read the contents of \fI\s-1FILE\s0\fR 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.
.IP "\s-1BYTE\s0" 4
.IX Item "BYTE"
Write \f(CW\*(C`BYTE\*(C'\fR at the current offset and advance the offset by 1 byte.
The byte may be specified as either decimal, octal (prefixed by \f(CW0\fR)
or hexadecimal (prefixed by \f(CW\*(C`0x\*(C'\fR).
.PP
Whitespace between fields in the string is ignored.
.PP
In the example above the size (512 bytes) is implied by the data.  But
you could additionally use the \f(CW\*(C`size\*(C'\fR parameter to either truncate or
extend (with zeroes) the disk image.
.SS "disk2data.pl script"
.IX Subsection "disk2data.pl script"
This script can convert from small disk images into the data format
described above.
.PP
It is provided in the nbdkit sources.  See
https://github.com/libguestfs/nbdkit/blob/master/plugins/data/disk2data.pl
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-captive\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3),
\&\fBnbdkit\-memory\-plugin\fR\|(1),
\&\fBnbdkit\-null\-plugin\fR\|(1),
\&\fBnbdkit\-partitioning\-plugin\fR\|(1),
\&\fBnbdkit\-pattern\-plugin\fR\|(1),
\&\fBnbdkit\-random\-plugin\fR\|(1),
\&\fBnbdkit\-zero\-plugin\fR\|(1),
https://github.com/libguestfs/nbdkit/blob/master/plugins/data/disk2data.pl,
https://en.wikipedia.org/wiki/Base64.
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2018 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0