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

FreeBSD Manual Pages

  
 
  

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

NAME
       nbdkit-nozero-filter - nbdkit nozero filter

SYNOPSIS
	nbdkit --filter=nozero plugin [plugin-args...] \
	  [zeromode=MODE] [fastzeromode=MODE]

DESCRIPTION
       "nbdkit-nozero-filter" is a filter that intentionally disables
       efficient handling of sparse file holes (ranges of all-zero bytes)
       across the NBD protocol.	 It is mainly useful for evaluating timing
       differences between naive vs. sparse-aware connections, and for testing
       client or server	fallbacks.

PARAMETERS
       zeromode=none
       zeromode=emulate
       zeromode=notrim
       zeromode=plugin
	   Optional, controls which mode the filter will use.  Mode none
	   (default) means that	zero support is	not advertised to the client.
	   Mode	emulate	means that zero	support	is emulated by the filter
	   using the plugin's "pwrite" callback, regardless of whether the
	   plugin itself implemented the "zero"	callback with a	more efficient
	   way to write	zeros. Since nbdkit aY 1.13.4, mode notrim means that
	   zero	requests are forwarded on to the plugin, except	that the
	   plugin will never see the NBDKIT_MAY_TRIM flag, to determine	if the
	   client permitting trimming during zero operations makes a
	   difference.	Since nbdkit aY	1.15.0,	mode plugin leaves normal zero
	   requests up to the plugin, useful when combined with	"fastzeromode"
	   for experimenting with the effects of fast zero requests.  It is an
	   error to request notrim or plugin if	the plugin does	not support
	   the "zero" callback.

       fastzeromode=none
       fastzeromode=slow
       fastzeromode=ignore
       fastzeromode=default
	   Optional since nbdkit aY 1.15.0, controls whether fast zeroes are
	   advertised to the client, and if so,	how the	filter will react to a
	   client fast zero request.  Mode none	avoids advertising fast	zero
	   support.  Mode slow advertises fast zero support unconditionally,
	   but treats all fast zero requests as	an immediate "ENOTSUP" failure
	   rather than performing a fallback.  Mode ignore advertises fast
	   zero	support, but treats all	client fast zero requests as if	the
	   flag	had not	been used (this	behavior is typically contrary to the
	   NBD specification, but can be useful	for comparison against the
	   actual fast zero implementation to see if fast zeroes make a
	   difference).	 Mode default is selected by default; when paired with
	   "zeromode=emulate", fast zeroes are advertised but fast zero
	   requests always fail	(similar to "slow"); when paired with
	   "zeromode=notrim" or	"zeromode=plugin", fast	zero support is	left
	   to the plugin (although in the latter case, the nozero filter could
	   be omitted for the same behavior).

EXAMPLES
       Serve the file disk.img,	but force the client to	write zeroes
       explicitly rather than with "NBD_CMD_WRITE_ZEROES":

	nbdkit --filter=nozero file disk.img

       Serve the file disk.img,	allowing the client to take advantage of less
       network traffic via "NBD_CMD_WRITE_ZEROES", but fail any	fast zero
       requests	up front and force all other zero requests to write data
       explicitly rather than punching any holes:

	nbdkit --filter=nozero file zeromode=emulate disk.img

       Serve the file disk.img,	but do not advertise fast zero support to the
       client even if the plugin supports it:

	nbdkit --filter=nozero file zeromode=plugin fastzeromode=none disk.img

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

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

VERSION
       "nbdkit-nozero-filter" first appeared in	nbdkit 1.2.

SEE ALSO
       nbdkit(1), nbdkit-file-plugin(1), nbdkit-filter(3),
       nbdkit-fua-filter(1), nbdkit-nocache-filter(1),
       nbdkit-noparallel-filter(1), nbdkit-noextents-filter(1).

AUTHORS
       Eric Blake

COPYRIGHT
       Copyright (C) 2018-2020 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-nozero-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-nozero-filter&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help