Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
nbdkit-pattern-plugin(1)	    NBDKIT	      nbdkit-pattern-plugin(1)

NAME
       nbdkit-pattern-plugin - plugin to serve a fixed pattern of data for
       testing

SYNOPSIS
	nbdkit pattern [size=]SIZE [stride=BLOCK_SIZE]

DESCRIPTION
       "nbdkit-pattern-plugin" is a plugin for nbdkit(1) which serves a	fixed
       pattern of data,	read only.  This is used for testing nbdkit filters
       and NBD clients.

       To create test disks filled with	other repeated patterns	use
       nbdkit-data-plugin(1) or	nbdkit-ones-plugin(1) instead.	To create
       disks filled with random	data, use nbdkit-random-plugin(1) or
       nbdkit-sparse-random-plugin(1).

       The fixed pattern is the	offset,	as a 64	bit big	endian integer,	every
       8 bytes.	 In hexadecimal	this looks like:

	offset			       data
	 0000:	 00 00 00 00 00	00 00 00   00 00 00 00 00 00 00	08
	 0010:	 00 00 00 00 00	00 00 10   00 00 00 00 00 00 00	18
	 0020:	 00 00 00 00 00	00 00 20   00 00 00 00 00 00 00	28

		     byte at offset 0x28

					    64 bit big endian int
					    encoding offset 0x28

       The size	of the virtual disk must be specified using the	"size"
       parameter.  If the size is not a	multiple of 8 then the last 8 byte
       offset in the pattern is	truncated.

   Upper bits
       The "upper" parameter can be used to set	the top	16 bits	of each	word
       in the pattern.	This can be used to distinguish	between	different
       instances of nbdkit-pattern-plugin, or when testing copies to ensure
       that different data is copied each time.	 For example setting
       "upper=0x1234" changes the pattern to:

	offset			       data
	 0000:	 12 34 00 00 00	00 00 00   12 34 00 00 00 00 00	08
	 0010:	 12 34 00 00 00	00 00 10   12 34 00 00 00 00 00	18
	 0020:	 12 34 00 00 00	00 00 20   12 34 00 00 00 00 00	28

       The upper value is XOR-ed into the top 16 bits, the default is 0.

   Strides
       Using the "stride" parameter you	can create a pattern where each	block
       of data has a unique number.  This is useful for	tracking down disk
       corruption where	blocks of data may be transposed.  For example,	with
       4096 byte block-based storage, using "stride=4k"	will produce a pattern
       like this:

	offset			       data
	 0000:	 00 00 00 00 00	00 00 00   00 00 00 00 00 00 00	00
	 0010:	 00 00 00 00 00	00 00 00   00 00 00 00 00 00 00	00
	 ...
	 ...			      block at offset 0x1000 (4k)
	 ...
	 1000:	 00 00 00 00 00	00 10 00   00 00 00 00 00 00 00	00
	 1010:	 00 00 00 00 00	00 00 00   00 00 00 00 00 00 00	00
	 ...
	 ...			      block at offset 0x2000 (8k)
	 ...
	 2000:	 00 00 00 00 00	00 20 00   00 00 00 00 00 00 00	00
	 2010:	 00 00 00 00 00	00 00 00   00 00 00 00 00 00 00	00

   Writes and testing copying
       Writing to the disk is possible.	 If you	do this	the plugin will	check
       that what you are writing exactly matches what would be read at the
       same offset (if not, it returns EIO error).  You	can use	this to	test
       copying programs	by making the source and destination NBD URIs be the
       same:

	nbdkit pattern size=100M --run 'nbdcopy	"$uri" "$uri"'

       "qemu-img convert" could	be used	in place of nbdcopy.  See also
       nbdkit-checkwrite-filter(1).

   Largest possible size
       nbdkit itself limits plugins to 2-1 bytes
       (decimal: 9223372036854775807, hexadecimal: 0x7fff_ffff_ffff_ffff).

       To test if NBD clients are free of bugs (not to mention nbdkit itself)
       you can use:

	nbdkit pattern 9223372036854775807

       Note this is too	large for qemu to open.

   Little endian pattern
       To get a	little endian pattern instead of big endian apply
       nbdkit-swab-filter(1) on	top of this plugin:

	nbdkit pattern 1G --filter=swab	swab-bits=64

PARAMETERS
       [size=]SIZE
	   Specify the virtual size of the disk	image.

	   This	parameter is required.

	   "size=" prefix may be omitted in most cases.	 See "Magic
	   parameters" in nbdkit(1).

       stride=BLOCK_SIZE
	   Instead of writing the 64 bit integers sequentially,	place them at
	   the beginning of each "BLOCK_SIZE" block.  See "Strides" above.

	   The minimum,	and default, stride is 8 which places the integers
	   sequentially	with no	gaps.  The stride must be a power of two.

       upper=N
	   XOR "N" (N=0..65535)	with the top 16	bits of	the pattern word.  You
	   can prefix the value	with "0x" for hexadecimal.  The	default	is 0.

       upper=random
	   On each run of nbdkit, a random number in the range 1..65535	(not
	   0) is chosen	for the	upper 16 bits of each word.

FILES
       $plugindir/nbdkit-pattern-plugin.so
	   The plugin.

	   Use "nbdkit --dump-config" to find the location of $plugindir.

VERSION
       "nbdkit-pattern-plugin" first appeared in nbdkit	1.6.

SEE ALSO
       nbdkit(1), nbdkit-plugin(3), nbdkit-checkwrite-filter(1),
       nbdkit-data-plugin(1), nbdkit-full-plugin(1), nbdkit-null-plugin(1),
       nbdkit-ones-plugin(1), nbdkit-offset-filter(1),
       nbdkit-random-plugin(1),	nbdkit-sparse-random-plugin(1),
       nbdkit-swab-filter(1), nbdkit-zero-plugin(1).

AUTHORS
       Richard W.M. Jones

COPYRIGHT
       Copyright Red Hat

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.

nbdkit-1.46.0			  2026-03-04	      nbdkit-pattern-plugin(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nbdkit-pattern-plugin&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>

home | help