nbdkit-data-plugin(1)

1nbdkit-data-plugin(1)               NBDKIT               nbdkit-data-plugin(1)
2
3
4

NAME

6       nbdkit-data-plugin - nbdkit plugin for serving data from the command
7       line
8

SYNOPSIS

10        nbdkit data data="0 1 2 3 @0x1fe 0x55 0xaa" [size=size]
11
12        nbdkit data base64="aGVsbG8gbmJka2l0IHVzZXI=" [size=size]
13
14        nbdkit data raw="binary_data" [size=size]
15

DESCRIPTION

17       "nbdkit-data-plugin" is a plugin for nbdkit(1) which serves a small
18       amount of data specified directly on the command line.  The plugin gets
19       its name from the "data:" URI scheme used by web browsers.  This is
20       mainly useful for testing NBD clients.
21
22       You can serve data read-only using the -r flag, or read-write.  Any
23       writes are thrown away when nbdkit exits.
24
25       Most operating systems have command line size limits which are quite a
26       lot smaller than any desirable disk image, so specifying a large, fully
27       populated disk image on the command line would not be possible.
28       However you can specify a small amount of data at the beginning of the
29       image, possibly followed by zeroes (using the "size" parameter to pad
30       the image to the full size), or use the "data" parameter creatively to
31       make mostly sparse disk images.
32
33       The "size" parameter can specify any virtual size up to the maximum
34       supported by nbdkit (2⁶³-1 bytes).
35

EXAMPLES

37       Create a 1 MB empty disk:
38            nbdkit data raw= size=1M
39
40           (This is a contrived example, it is better to use
41           nbdkit-memory-plugin(1) for real applications.)
42
43       Create a 1 MB disk with some nonsense data at the beginning:
44            nbdkit data base64=MTIz size=1M
45
46           The above command serves the bytes "0x31 0x32 0x33" (which is the
47           base64 decoding of "MTIz"), followed by 1M - 3 bytes of zeroes.
48
49       Create a 1 MB disk with one empty MBR-formatted partition:
50            nbdkit data data="
51              @0x1b8 178 190 207 221 0 0 0 0 2 0 131 32 32 0 1 0 0 0 255 7
52              @0x1fe 85 170
53              " size=1048576
54
55           This example was created by running:
56
57            $ rm -f disk
58            $ truncate -s 1M disk
59            $ echo start=1 | sfdisk disk
60            Device Boot Start   End Sectors    Size Id Type
61            disk1           1  2047    2047 1023.5K 83 Linux
62            $ ./disk2data.pl disk
63
64           The "disk2data.pl" script is provided in the nbdkit sources
65           (https://github.com/libguestfs/nbdkit/blob/master/plugins/data/disk2data.pl).
66
67       Create a disk with a partition from another file:
68            nbdkit data data="
69              @0x1b8 178 190 207 221 0 0 0 0 2 0 131 32 32 0 1 0 0 0 255 7
70              @0x1fe 85 170
71              @0x200 <partition-data
72              " size=1048576
73
74           The "<FILE" syntax is used to include a file of binary data.  Note
75           that nbdkit-partitioning-plugin(1) is easier to use and more
76           flexible.
77
78       Create a 7 EB (exabyte) disk with one empty GPT-formatted partition:
79           The data plugin supports huge sparse virtual disks, up to the
80           maximum size supported by nbdkit itself (2⁶³-1 bytes =
81           8 exabytes - 1 byte).  These cause all sorts of problems for
82           software and so make excellent test cases.  To partition such a
83           huge disk requires the GPT (GUID Partition Table) format since MBR
84           is limited to just 2 TB.
85
86            nbdkit data data="
87              @0x1c0 2 0 0xee 0xfe 0xff 0xff 0x01 0  0 0 0xff 0xff 0xff 0xff
88              @0x1fe 0x55 0xaa
89              @0x200 0x45 0x46 0x49 0x20 0x50 0x41 0x52 0x54
90                            0 0 1 0 0x5c 0 0 0
91                     0x9b 0xe5 0x6a 0xc5 0 0 0 0  1 0 0 0 0 0 0 0
92                     0xff 0xff 0xff 0xff 0xff 0xff 0x37 0  0x22 0 0 0 0 0 0 0
93                     0xde 0xff 0xff 0xff 0xff 0xff 0x37 0
94                            0x72 0xb6 0x9e 0x0c 0x6b 0x76 0xb0 0x4f
95                     0xb3 0x94 0xb2 0xf1 0x61 0xec 0xdd 0x3c  2 0 0 0 0 0 0 0
96                     0x80 0 0 0 0x80 0 0 0  0x79 0x8a 0xd0 0x7e 0 0 0 0
97              @0x400 0xaf 0x3d 0xc6 0x0f 0x83 0x84 0x72 0x47
98                            0x8e 0x79 0x3d 0x69 0xd8 0x47 0x7d 0xe4
99                     0xd5 0x19 0x46 0x95 0xe3 0x82 0xa8 0x4c
100                            0x95 0x82 0x7a 0xbe 0x1c 0xfc 0x62 0x90
101                     0x80 0 0 0 0 0 0 0  0x80 0xff 0xff 0xff 0xff 0xff 0x37 0
102                     0 0 0 0 0 0 0 0  0x70 0 0x31 0 0 0 0 0
103              @0x6fffffffffffbe00
104                     0xaf 0x3d 0xc6 0x0f 0x83 0x84 0x72 0x47
105                            0x8e 0x79 0x3d 0x69 0xd8 0x47 0x7d 0xe4
106                     0xd5 0x19 0x46 0x95 0xe3 0x82 0xa8 0x4c
107                            0x95 0x82 0x7a 0xbe 0x1c 0xfc 0x62 0x90
108                     0x80 0 0 0 0 0 0 0  0x80 0xff 0xff 0xff 0xff 0xff 0x37 0
109                     0 0 0 0 0 0 0 0  0x70 0 0x31 0 0 0 0 0
110              @0x6ffffffffffffe00
111                     0x45 0x46 0x49 0x20 0x50 0x41 0x52 0x54
112                            0 0 1 0 0x5c 0 0 0
113                     0x6c 0x76 0xa1 0xa0 0 0 0 0
114                            0xff 0xff 0xff 0xff 0xff 0xff 0x37 0
115                     1 0 0 0 0 0 0 0  0x22 0 0 0 0 0 0 0
116                     0xde 0xff 0xff 0xff 0xff 0xff 0x37 0
117                            0x72 0xb6 0x9e 0x0c 0x6b 0x76 0xb0 0x4f
118                     0xb3 0x94 0xb2 0xf1 0x61 0xec 0xdd 0x3c
119                            0xdf 0xff 0xff 0xff 0xff 0xff 0x37 0
120                     0x80 0 0 0 0x80 0 0 0  0x79 0x8a 0xd0 0x7e 0 0 0 0
121              " size=7E
122

PARAMETERS

124       Exactly one of the "data", "base64" or "raw" parameters must be
125       supplied.
126
127       data=DATA
128           Specify the disk data using a simple compact format.  See "DATA
129           FORMAT" below.
130
131       base64=BASE64
132           The "base64" parameter can be used to supply binary data encoded in
133           base64 on the command line.
134
135           This is only supported if nbdkit was compiled with GnuTLS ≥ 3.6.0.
136           You can find out by checking if:
137
138            $ nbdkit data --dump-plugin
139
140           contains:
141
142            data_base64=yes
143
144       raw=BINARY
145           The "raw" parameter can be used to supply raw binary data directly
146           on the command line.
147
148           It is usually quite difficult to do this unless you are running
149           nbdkit from another program (see nbdkit-captive(1)).  One
150           particular problem is that the data must not contain zero bytes
151           (ie. "\0") since those will be processed in C to mean the end of
152           the string.  In almost all cases it is better to use base64
153           encoding or the custom "data" format.
154
155       size=SIZE
156           The data is truncated or extended to the size specified.
157
158           This parameter is optional: If omitted the size is defined by the
159           size of the "data", "raw" or "base64" parameter.
160

DATA FORMAT

162       The "data" parameter lets you specify small disk images in a simple,
163       compact format.  It is a string containing a list of bytes which are
164       written into the disk image sequentially.  You can move the virtual
165       offset where bytes are written using @offset.
166
167       For example:
168
169        nbdkit data data="0 1 2 3 @0x1fe 0x55 0xaa"
170
171       creates a 0x200 = 512 byte (1 sector) image containing the four bytes
172       "0 1 2 3" at the start, and the two bytes "0x55 0xaa" at the end of the
173       sector, with the remaining 506 bytes in the middle being all zeroes.
174
175       Fields in the string can be:
176
177       @OFFSET
178           Moves the current offset to "OFFSET".  The offset may be specified
179           as either decimal, octal (prefixed by 0) or hexadecimal (prefixed
180           by "0x").
181
182       <FILE
183           Read the contents of FILE into the disk image at the current
184           offset.  The offset is incremented by the size of the file.  The
185           filename can be a relative or absolute path, but cannot contain
186           whitespace in the name.
187
188       BYTE
189           Write "BYTE" at the current offset and advance the offset by 1
190           byte.  The byte may be specified as either decimal, octal (prefixed
191           by 0) or hexadecimal (prefixed by "0x").
192
193       Whitespace between fields in the string is ignored.
194
195       In the example above the size (512 bytes) is implied by the data.  But
196       you could additionally use the "size" parameter to either truncate or
197       extend (with zeroes) the disk image.
198
199   disk2data.pl script
200       This script can convert from small disk images into the data format
201       described above.
202
203       It is provided in the nbdkit sources.  See
204       https://github.com/libguestfs/nbdkit/blob/master/plugins/data/disk2data.pl
205

AUTHORS

215       Richard W.M. Jones
216

COPYRIGHT

218       Copyright (C) 2018 Red Hat Inc.
219

LICENSE

221       Redistribution and use in source and binary forms, with or without
222       modification, are permitted provided that the following conditions are
223       met:
224
225       ·   Redistributions of source code must retain the above copyright
226           notice, this list of conditions and the following disclaimer.
227
228       ·   Redistributions in binary form must reproduce the above copyright
229           notice, this list of conditions and the following disclaimer in the
230           documentation and/or other materials provided with the
231           distribution.
232
233       ·   Neither the name of Red Hat nor the names of its contributors may
234           be used to endorse or promote products derived from this software
235           without specific prior written permission.
236
237       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
238       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
239       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
240       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
241       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
242       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
243       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
244       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
245       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
246       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
247       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
248
249
250
251nbdkit-1.12.3                     2019-05-21             nbdkit-data-plugin(1)