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

FreeBSD Manual Pages

  
 
  

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

NAME
       nbdkit-error-filter - inject errors for testing clients

SYNOPSIS
	nbdkit --filter=error PLUGIN
	    [error=EPERM|EIO|ENOMEM|EINVAL|ENOSPC|ESHUTDOWN]
	    [error-rate=10%|0.1]
	    [error-file=/tmp/inject]
	    [error-pread=...] [error-pread-rate=...] [error-pread-file=...]
	    [error-pwrite=...] [error-pwrite-rate=...] [error-pwrite-file=...]
	    [error-trim=...] [error-trim-rate=...] [error-trim-file=...]
	    [error-zero=...] [error-zero-rate=...] [error-zero-file=...]
	    [error-extents=...]	[error-extents-rate=...] [error-extents-file=...]
	    [error-cache=...] [error-cache-rate=...] [error-cache-file=...]

DESCRIPTION
       "nbdkit-error-filter" is	an nbdkit filter that injects random errors
       into replies from the server.  This is used for testing that NBD
       clients can handle errors.

       All parameters are optional, but	you should usually specify one of the
       "error-rate" or "error-*-rate" parameters, otherwise this filter	will
       do nothing.

EXAMPLES
       Inject a	low rate of errors randomly into the connection:

	nbdkit --filter=error file disk.img error-rate=1%

       Reading,	trimming, cache	and extents (block status) requests will be
       successful, but all writes and zeroing will return "No space left on
       device":

	nbdkit --filter=error file disk.img \
				   error=ENOSPC	\
				   error-pwrite-rate=100% \
				   error-zero-rate=100%

       To make all connections fail hard 60 seconds after the server is
       started,	use:

	rm -f /tmp/inject
	nbdkit --filter=error file disk.img \
				   error-rate=100% \
				   error-file=/tmp/inject
	sleep 60; touch	/tmp/inject

PARAMETERS
       error=EPERM|EIO|ENOMEM|EINVAL|ENOSPC|ESHUTDOWN
	   When	a random error is injected, you	can select which one from the
	   range of possible NBD errors	(the NBD protocol only supports	a
	   limited range of error codes).

	   This	parameter is optional and the default is "EIO" ("Input/output
	   error").

       error-rate=N%
       error-rate=0..1
	   The rate of injected	errors per NBD request.	 This can be expressed
	   as either a percentage between "0%" and "100%" or as	a probability
	   between 0 and 1.  If	"0%" or	0 is used then no errors are ever
	   injected, and if "100%" or 1	is used	then all requests return
	   errors.

	   This	parameter is optional and the default is "0%".	Unless you set
	   this, the filter will do nothing.

       error-file=FILENAME
	   Errors will only be injected	when FILENAME exists.  (Note you must
	   also	specify	the "error-rate").

	   You can use this for	fine-grained control over when to inject
	   errors, for example if you want to trigger an error at an exact
	   moment during a test, arrange for this file to be created at	the
	   appropriate time.  Or conversely to test error recovery in a
	   client, create the file initially, and then delete it to check the
	   client can recover.

	   This	parameter is optional.

       error-pread, error-pread-rate, error-pread-file.
	   Same	as "error", "error-rate" and "error-file" but only apply the
	   settings to NBD pread requests.

       error-pwrite, error-pwrite-rate,	error-pwrite-file.
	   Same	as "error", "error-rate" and "error-file" but only apply the
	   settings to NBD pwrite requests.

       error-trim, error-trim-rate, error-trim-file.
	   Same	as "error", "error-rate" and "error-file" but only apply the
	   settings to NBD trim	requests.

       error-zero, error-zero-rate, error-zero-file.
	   Same	as "error", "error-rate" and "error-file" but only apply the
	   settings to NBD zero	requests.

       error-extents, error-extents-rate, error-extents-file.
	   Same	as "error", "error-rate" and "error-file" but only apply the
	   settings to NBD block status	requests to read extents.

       error-cache, error-cache-rate, error-cache-file.
	   Same	as "error", "error-rate" and "error-file" but only apply the
	   settings to NBD cache requests.

NOTES
   Peculiar debug output
       If you are looking at the debugging output (using "nbdkit -f -v") then
       you may see peculiar "errors" appearing when using this filter, for
       example:

	nbdkit:	file.9:	debug: error: pread count=1024 offset=0	flags=0x0

       In fact these are not errors, nbdkit core is simply printing the	name
       of the filter which happens to be "error".  When	this filter injects an
       error you will see something like:

	nbdkit:	file.4:	error: injecting ENOSPC	error into pwrite

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

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

VERSION
       "nbdkit-error-filter" first appeared in nbdkit 1.6.

SEE ALSO
       nbdkit(1), nbdkit-file-plugin(1), nbdkit-full-plugin(1),
       nbdkit-filter(3).

AUTHORS
       Richard W.M. Jones

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-error-filter(1)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | PARAMETERS | NOTES | 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-error-filter&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help