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

FreeBSD Manual Pages

  
 
  

home | help
nbdkit-blocksize-filter(1)	    NBDKIT	    nbdkit-blocksize-filter(1)

NAME
       nbdkit-blocksize-filter - nbdkit	blocksize filter

SYNOPSIS
	nbdkit --filter=blocksize plugin [minblock=SIZE] [maxdata=SIZE]	\
	    [maxlen=SIZE] [plugin-args...]

DESCRIPTION
       "nbdkit-blocksize-filter" is a filter that ensures various block	size
       limits are met on transactions presented	to the plugin.	The NBD
       protocol	permits	clients	to send	requests with a	granularity as small
       as 1 byte or as large as	nearly 4 gigabytes, although it	suggests that
       portable	clients	should align requests to 512 bytes and not exceed 32
       megabytes without prior coordination with the server.

       Meanwhile, some plugins require requests	to be aligned to 512-byte
       multiples, or may enforce a maximum transaction size to bound the time
       or memory resources spent by any	one command (note that nbdkit itself
       refuses a read or write larger than 64 megabytes, while many other NBD
       servers limit things to 32 megabytes).  The blocksize filter can	be
       used to modify the client requests to meet the plugin restrictions.

PARAMETERS
       The nbdkit-blocksize-filter accepts the following parameters.

       minblock=SIZE
	   The minimum block size and alignment	to pass	to the plugin.	This
	   must	be a power of two, and no larger than 64k.  If omitted,	this
	   defaults to 1 (that is, no minimum size restrictions).  The filter
	   rounds up read requests to alignment	boundaries, performs read-
	   modify-write	cycles for any unaligned head or tail of a write or
	   zero	request, and silently ignores any unaligned head or tail of a
	   trim	request.  The filter also truncates the	plugin size down to an
	   aligned value (as it	cannot safely operate on the unaligned tail).
	   If you need to round	the image size up instead to access the	last
	   few bytes, combine this filter with nbdkit-truncate-filter(1).

	   This	parameter understands the suffix 'k' for 1024.

       maxdata=SIZE
	   The maximum block size for any single transaction with data (read
	   and write).	If omitted, this defaults to 64	megabytes (that	is,
	   the nbdkit maximum).	 This need not be a power of two, but must be
	   an integer multiple of "minblock".  The filter fragments any	larger
	   client request into multiple	plugin requests.

	   This	parameter understands the suffixes 'k',	'M', and 'G' for
	   powers of 1024.

       maxlen=SIZE
	   The maximum length for any single transaction without data (trim,
	   zero	or extents).  If omitted, this defaults	to 0xffffffff rounded
	   down	to "minsize" alignment (that is, the inherent 32-bit limit of
	   the NBD protocol).  This need not be	a power	of two,	but must be an
	   integer multiple of "minblock", and should be at least as large as
	   "maxdata".  The filter fragments any	larger client request into
	   multiple plugin requests.

	   This	parameter understands the suffixes 'k',	'M', and 'G' for
	   powers of 1024.

EXAMPLES
       Allow an	arbitrary client to use	the VDDK plugin	(which is limited to
       512-byte	blocks), without having	to fix the client to avoid sending
       unaligned requests:

	nbdkit --filter=blocksize vddk minblock=512 file=/absolute/path/to/file.vmdk

       Allow an	arbitrary client tuned to nbdkit's 64 megabyte sizing to
       connect to a remote server that insists on 32 megabyte sizing, via the
       nbd plugin:

	nbdkit --filter=blocksize nbd maxdata=32M socket=/path/to/socket

       Serve a file as if it were a block device that insists on 4k alignment,
       while still allowing access to any unaligned bytes at the end of	the
       file:

	nbdkit --filter=blocksize --filter=truncate file /path/to/file \
	minblock=4k round-up=4k

FILES
       $filterdir/nbdkit-blocksize-filter.so
	   The filter.

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

VERSION
       "nbdkit-blocksize-filter" first appeared	in nbdkit 1.4.

SEE ALSO
       nbdkit(1), nbdkit-nbd-plugin(1),	nbdkit-vddk-plugin(1),
       nbdkit-filter(3), nbdkit-truncate-filter(1).

AUTHORS
       Eric Blake

COPYRIGHT
       Copyright (C) 2018 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:

       o   Redistributions of source code must retain the above	copyright
	   notice, this	list of	conditions and the following disclaimer.

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

       o   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.20.4			  2021-09-21	    nbdkit-blocksize-filter(1)

NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | EXAMPLES | FILES | VERSION | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nbdkit-blocksize-filter&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help