plugins/data/nbdkit-data-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-data-plugin - nbdkit plugin for serving data from the command line
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit data [data=]'0 1 2 3 @0x1fe 0x55 0xaa'
   8              [size=SIZE] [allocator=sparse|malloc|zstd]
   9
  10 =for paragraph
  11
  12  nbdkit data base64='aGVsbG8gbmJka2l0IHVzZXI='
  13              [size=SIZE] [allocator=sparse|malloc|zstd]
  14
  15 =for paragraph
  16
  17  nbdkit data raw='binary_data'
  18              [size=SIZE] [allocator=sparse|malloc|zstd]
  19
  20 =head1 DESCRIPTION
  21
  22 C<nbdkit-data-plugin> is a plugin for L<nbdkit(1)> which serves a
  23 small amount of data specified directly on the command line.  The
  24 plugin gets its name from the C<data:> URI scheme used by web
  25 browsers.  This is mainly useful for testing NBD clients.
  26
  27 You can serve data read-only using the I<-r> flag, or read-write.  Any
  28 writes are thrown away when nbdkit exits.
  29
  30 Most operating systems have command line size limits which are quite a
  31 lot smaller than any desirable disk image, so specifying a large,
  32 fully populated disk image on the command line would not be possible.
  33 However you can specify a small amount of data at the beginning of the
  34 image, possibly followed by zeroes (using the C<size> parameter to pad
  35 the image to the full size), or use the C<data> parameter creatively
  36 to make mostly sparse disk images.
  37
  38 The C<size> parameter can specify any virtual size up to the maximum
  39 supported by nbdkit (S<2⁶³-1 bytes>).
  40
  41 =head1 EXAMPLES
  42
  43 =head2 Create small disks filled with test patterns
  44
  45  nbdkit data ' ( 0x55 0xAA )*2048 '
  46  nbdkit data ' ( "Hello" )*2000 ' size=8192
  47
  48 The first command creates a disk containing 4096 bytes filled with the
  49 repeating bytes 0x55 0xAA.  The second command repeats
  50 C<HelloHelloHello...>, truncating the disk to exactly 8192 bytes.
  51
  52 See also L<nbdkit-pattern-plugin(3)>.
  53
  54 =head2 Create a 1 MB disk with MBR-format partition table
  55
  56  nbdkit data '
  57    @0x1be    # MBR first partition entry
  58      0           # Partition status
  59      0 2 0       # CHS start
  60      0x83        # Partition type (Linux)
  61      0x20 0x20 0 # CHS last sector
  62      le32:1      # LBA first sector
  63      le32:0x7ff  # LBA number of sectors
  64    @0x1fe    # Boot signature
  65      0x55 0xaa
  66    ' size=1M
  67
  68 A more flexible way to create partitions is to use
  69 L<nbdkit-partitioning-plugin(1)>.  To create a data string from an
  70 existing disk use the C<disk2data.pl> script provided in the nbdkit
  71 sources
  72 (L<https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/data/disk2data.pl>).
  73
  74 =head2 Create a disk image with sector-aligned data
  75
  76  nbdkit data ' <file1 @^512 <file2 @^512 <file3 @^512 '
  77
  78 Local binary files F<file1>, F<file2> and F<file3> are copied into the
  79 disk image.  Regardless of the size of these files, they will all be
  80 aligned to 512-byte sector boundaries.  Furthermore because of the
  81 final alignment operation (C<@^512>) the total size of the disk will
  82 also be rounded to a whole number of sectors.
  83
  84 =head2 Create a disk with the same random data in each sector
  85
  86  nbdkit data ' </dev/urandom[:512]*16 '
  87
  88 The expression C<E<lt>/dev/urandom[:512]> reads 512 bytes (one sector)
  89 of randomness from the system.  The same random data is repeated over
  90 16 sectors.
  91
  92 =head2 Create a 1 MB disk with some nonsense data at the beginning
  93
  94  nbdkit data base64=MTIz size=1M
  95
  96 The above command serves the bytes C<0x31 0x32 0x33> (which is the
  97 base64 decoding of C<MTIz>), followed by S<1M - 3 bytes> of zeroes.
  98
  99 =head2 "Hello, world" using this plugin
 100
 101  $ nbdkit data raw='Hello, world!' --run 'nbdcopy "$uri" - | cat'
 102  Hello, world!
 103
 104 This works by creating a disk containing the string
 105 C<"Hello, world!">.  L<nbdcopy(1)> connects to the server using an NBD
 106 URI (C<"$uri">) and copies the disk to stdout (C<->).  The extra
 107 L<cat(1)> is needed because nbdcopy refuses to write raw disk data to
 108 a terminal.
 109
 110 =head1 PARAMETERS
 111
 112 Exactly one of the C<data>, C<base64> or C<raw> parameters must be
 113 supplied.
 114
 115 =over 4
 116
 117 =item [B<data=>]DATA
 118
 119 Specify the disk data using a simple compact format.  See
 120 L</DATA FORMAT> below.
 121
 122 C<data=> is a magic config key and may be omitted in most cases.
 123 See L<nbdkit(1)/Magic parameters>.
 124
 125 =item B<base64=>BASE64
 126
 127 The C<base64> parameter can be used to supply binary data encoded in
 128 base64 on the command line.
 129
 130 This is only supported if nbdkit was compiled with GnuTLS E<ge> 3.6.0.
 131 You can find out by checking if:
 132
 133  $ nbdkit data --dump-plugin
 134
 135 contains:
 136
 137  data_base64=yes
 138
 139 =item B<raw=>BINARY
 140
 141 The C<raw> parameter can be used to supply raw binary data directly on
 142 the command line.
 143
 144 It is usually quite difficult to do this unless you are running nbdkit
 145 from another program (see L<nbdkit-captive(1)>).  One particular
 146 problem is that the data must not contain zero bytes (ie. C<\0>) since
 147 those will be processed in C to mean the end of the string.  In almost
 148 all cases it is better to use base64 encoding or the custom C<data>
 149 format.
 150
 151 =item B<size=>SIZE
 152
 153 The data is truncated or extended to the size specified.
 154
 155 This parameter is optional: If omitted the size is defined by the size
 156 of the C<data>, C<raw> or C<base64> parameter.
 157
 158 =item B<allocator=sparse>
 159
 160 =item B<allocator=malloc>[,B<mlock=true>]
 161
 162 =item B<allocator=zstd>
 163
 164 (nbdkit E<ge> 1.22)
 165
 166 Select the backend allocation strategy.  See
 167 L<nbdkit-memory-plugin(1)/ALLOCATORS>.  The default is sparse.
 168
 169 =back
 170
 171 =head1 DATA FORMAT
 172
 173 The C<data> parameter lets you specify small disk images in a simple,
 174 compact format.  It is a string containing a list of bytes which are
 175 written into the disk image sequentially.  You can move the virtual
 176 offset where bytes are written using C<@offset>.
 177
 178  nbdkit data '0 1 2 3 @0x1fe 0x55 0xaa'
 179
 180 creates:
 181
 182              total size 0x200 = 512 bytes (1 sector)
 183 ┌──────┬──────┬──────┬──────┬───────── ── ── ───┬──────┬──────┐
 184 │   0  │   1  │   2  │   3  │  0     0  ...  0  │ 0x55 │ 0xaa │
 185 └──────┴──────┴──────┴──────┴───────── ── ── ───┴──────┴──────┘
 186                                                   ↑
 187                                             offset 0x1fe
 188
 189 In this example the size is implied by the data.  But you could also
 190 use the C<size> parameter to either truncate or extend (with zeroes)
 191 the disk image.  Another way to write the same disk would be this,
 192 where we align the offset to the end of the sector and move back 2
 193 bytes to write the signature:
 194
 195  nbdkit data '0 1 2 3 @^0x200 @-2 le16:0xaa55'
 196
 197 Fields in the string can be:
 198
 199 =over 4
 200
 201 =item BYTE
 202
 203 Write a byte at the current offset and advance the offset by 1.  The
 204 byte may be specified as either decimal, octal (prefixed by C<0>) or
 205 hexadecimal (prefixed by C<0x>).  To add repeated bytes use the C<*>
 206 operator (eg. C<0xFF*16>).
 207
 208 =item B<le16:>WORD
 209
 210 =item B<be16:>WORD
 211
 212 =item B<le32:>WORD
 213
 214 =item B<be32:>WORD
 215
 216 =item B<le64:>WORD
 217
 218 =item B<be64:>WORD
 219
 220 (nbdkit E<ge> 1.28)
 221
 222 Write a word expressed in little endian (le) or big endian (be) of
 223 length 16/32/64 bits and advance the offset by 2/4/8.  The word may be
 224 specified in decimal, octal or hexadecimal.  For example:
 225
 226  nbdkit data ' be32:0x1 '
 227
 228 generates the 4 byte sequence C<0 0 0 1>.
 229
 230 =item B<@>OFFSET
 231
 232 Moves the current offset to C<OFFSET>.  The offset may be specified as
 233 either decimal, octal (prefixed by C<0>) or hexadecimal (prefixed by
 234 C<0x>).  Offset C<@0> is the first byte of the disk.
 235
 236 =item B<@+>N
 237
 238 =item B<@->N
 239
 240 (nbdkit E<ge> 1.22)
 241
 242 Add or subtract C<N> from the current offset.
 243
 244 =item B<@^>ALIGNMENT
 245
 246 (nbdkit E<ge> 1.22)
 247
 248 If the current offset is not a multiple of C<ALIGNMENT> then the
 249 offset is moved forward to the next multiple.  The next byte written
 250 will be aligned to C<ALIGNMENT>.
 251
 252 =item B<E<lt>>FILE
 253
 254 (nbdkit E<ge> 1.8)
 255
 256 Read the contents of binary F<FILE> into the disk image at the current
 257 offset.  The offset is incremented by the size of the file.  The
 258 filename can be a relative or absolute path, but cannot contain
 259 whitespace in the name.
 260
 261 =item B<E<lt>(>SCRIPTB<)>
 262
 263 (nbdkit E<ge> 1.24, not Windows)
 264
 265 Substitute the output of the shell script or external program as a
 266 binary blob and advance the offset by the length in bytes of the
 267 output.  You can use this to create more complex test patterns.  For
 268 example this produces a 32K disk image with an incrementing test
 269 pattern in groups of 4 bytes:
 270
 271  nbdkit data ' <( i=0
 272                   while :; do
 273                       printf "%04d" $i; i=$((i+1))
 274                   done )[:32768] '
 275
 276 The script may contain C<(> and C<)> characters, but they must be in
 277 matching pairs.  A script can produce a finite amount of output; or
 278 (as in the example) an infinite amount which must be truncated using
 279 the C<[:len]> slice operator.
 280
 281 Scripts must be idempotent, producing the same output each time they
 282 are run.  This is because optimizations might change the order of
 283 evaluation or number of times the script is called and you could get
 284 different output in a future version of nbdkit.
 285
 286 Note that the script is passed to F</bin/sh>.  On some platforms like
 287 Debian this might not be a full-featured shell.
 288
 289 =item B<">STRINGB<">
 290
 291 (nbdkit E<ge> 1.22)
 292
 293 Write a string into the image at the current offset and advance the
 294 offset by the length of the string.  To include special characters in
 295 the string you can escape them in the same way as C strings (eg. a
 296 double quote character within the string should be written C<\">).  Be
 297 careful with shell quoting around the whole data parameter.
 298
 299 =item B<(> ... B<)>
 300
 301 (nbdkit E<ge> 1.24)
 302
 303 Group a set of expressions into a single expression.
 304
 305 S<C<( ... )>> recursively creates a new data parser so any expression
 306 can appear inside, including nested S<C<( ... )>>.  Note that offsets
 307 and alignments within the subpattern are relative to the start of the
 308 subpattern, not relative to the final disk image.
 309
 310 =item expression B<*> N
 311
 312 (nbdkit E<ge> 1.24)
 313
 314 Repeat the expression C<N> times.  The offset is incremented by the
 315 length of the expression × N.  For example to create a repeating
 316 pattern of 0x55, 0xAA for 512 (2×256) bytes do:
 317
 318  nbdkit data '( 0x55 0xAA ) * 256'
 319
 320 =item expression B<[>NB<:>MB<]>
 321
 322 (nbdkit E<ge> 1.24)
 323
 324 Take a slice of the expression.  Slices are S<B<[>startB<:>end+1B<]>>
 325 where I<start> and I<end> are the first and last byte offsets of the
 326 expression desired.  Either or both may be omitted.  S<B<[:>lenB<]>>
 327 means to take the first I<len> bytes.  S<B<[>startB<:]>> means to take
 328 bytes from offset I<start> to the end of the expression.
 329
 330 =item expression B<-E<gt> \>NAME
 331
 332 =item B<\>NAME
 333
 334 (nbdkit E<ge> 1.24)
 335
 336 Assign an expression to a name which can be used later.  Names can be
 337 used in the current scope (or any scopes nested within the current
 338 scope), but disappear at the end of the current scope.  Names start
 339 with a backslash character followed by one or more alphanumeric, dash
 340 and underscore.  For example this makes two identical sectors both
 341 containing a boot signature at the end:
 342
 343  nbdkit data ' ( 0x55 0xAA ) -> \boot-signature
 344                ( @0x1fe \boot-signature ) -> \sector
 345                \sector \sector '
 346
 347 =item B<$>VAR
 348
 349 (nbdkit E<ge> 1.24)
 350
 351 Substitute command line parameters or environment variables.  The
 352 variable is written in the same language as the C<data> parameter, and
 353 when substituted it creates a nested scope like S<C<( ... )>>
 354 expressions.  These are all equivalent:
 355
 356  nbdkit data '$pattern*16' pattern='0x55 0xAA'
 357
 358 =for paragraph
 359
 360  export pattern='0x55 0xAA'
 361  nbdkit data '$pattern*16'
 362
 363 =for paragraph
 364
 365  nbdkit data '( 0x55 0xAA )*16'
 366
 367 =item B<#> COMMENT
 368
 369 (nbdkit E<ge> 1.24)
 370
 371 C<#> begins a comment stretching to the end of the current line.
 372
 373 =back
 374
 375 =head2 disk2data.pl script
 376
 377 This script can convert from small disk images into the data format
 378 described above.
 379
 380 It is provided in the nbdkit sources.  See
 381 L<https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/data/disk2data.pl>
 382
 383 =head1 FILES
 384
 385 =over 4
 386
 387 =item F<$plugindir/nbdkit-data-plugin.so>
 388
 389 The plugin.
 390
 391 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 392
 393 =back
 394
 395 =head1 VERSION
 396
 397 C<nbdkit-data-plugin> first appeared in nbdkit 1.6.
 398
 399 =head1 SEE ALSO
 400
 401 L<nbdkit(1)>,
 402 L<nbdkit-captive(1)>,
 403 L<nbdkit-plugin(3)>,
 404 L<nbdkit-info-plugin(1)>,
 405 L<nbdkit-memory-plugin(1)>,
 406 L<nbdkit-null-plugin(1)>,
 407 L<nbdkit-partitioning-plugin(1)>,
 408 L<nbdkit-pattern-plugin(1)>,
 409 L<nbdkit-random-plugin(1)>,
 410 L<nbdkit-sparse-random-plugin(1)>,
 411 L<nbdkit-tmpdisk-plugin(1)>,
 412 L<nbdkit-zero-plugin(1)>,
 413 L<https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/data/disk2data.pl>,
 414 L<https://en.wikipedia.org/wiki/Base64>.
 415
 416 =head1 AUTHORS
 417
 418 Richard W.M. Jones
 419
 420 =head1 COPYRIGHT
 421
 422 Copyright Red Hat