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

FreeBSD Manual Pages

  
 
  

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

NAME
       nbdkit-retry-filter - reopen connection on error

SYNOPSIS
	nbdkit --filter=retry PLUGIN [retries=N] [retry-delay=N]
				     [retry-exponential=yes|no]
				     [retry-readonly=yes|no]

DESCRIPTION
       "nbdkit-retry-filter" is	a filter that transparently reopens the	plugin
       connection when an error	is encountered.	 It can	be used	to make	long-
       running copy operations reliable	in the presence	of temporary network
       failures, without requiring any changes to the plugin or	the NBD
       client.

       Several optional	parameters are available to control:

       o   how many times we retry,

       o   the delay between retries, and whether we wait longer each time
	   (known as aexponential back-offa),

       o   if we reopen	the plugin in read-only	mode after the first failure.

       The default (with no parameters)	is designed to offer a happy medium
       between recovering from short temporary failures	but not	doing anything
       too bad when permanent or unrecoverable failures	happen.	 The default
       behaviour is: we	retry 5	times with exponential back-off, waiting in
       total about 1 minute before we give up.

EXAMPLE
       In this example we copy and convert a large file	using
       nbdkit-ssh-plugin(1), qemu-img(1) and nbdkit-captive(1).

	nbdkit -U - \
	  ssh host=remote.example.com /var/tmp/test.iso	\
	  --filter=retry \
	  --run	'qemu-img convert -p -f	raw $nbd -O qcow2 test.qcow2'

       Without --filter=retry a	temporary failure would	cause the copy to fail
       (for example, the remote	hostas firewall	is restarted causing the SSH
       connection to be	dropped).  Adding this filter means that it may	be
       possible	to transparently recover.

PARAMETERS
       retries=N
	   The number of times any single operation will be retried before we
	   give	up and fail the	operation.  The	default	is 5.

       retry-delay=N
	   The number of seconds to wait before	retrying.  The default is 2
	   seconds.

       retry-exponential=yes
	   Use exponential back-off.  The retry	delay is doubled between each
	   retry.  This	is the default.

       retry-exponential=no
	   Do not use exponential back-off.  The retry delay is	the same
	   between each	retry.

       retry-readonly=yes
	   As soon as a	failure	occurs,	switch the underlying plugin to	read-
	   only	mode for the rest of this connection.  (A new NBD client
	   connection will still open the plugin in the	original mode.)

       retry-readonly=no
	   Do not change the read-write/read-only mode of the plugin when
	   retrying.  This is the default.

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

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

VERSION
       "nbdkit-retry-filter" first appeared in nbdkit 1.16.

SEE ALSO
       nbdkit(1), nbdkit-filter(3), nbdkit-readahead-filter(1).

AUTHORS
       Richard W.M. Jones

COPYRIGHT
       Copyright (C) 2019 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			  2020-08-28		nbdkit-retry-filter(1)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | PARAMETERS | 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-retry-filter&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help