.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.48.0 (Pod::Simple 3.47)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "nbdkit-retry-filter 1"
.TH nbdkit-retry-filter 1 2026-07-14 nbdkit-1.48.0 NBDKIT
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdkit\-retry\-filter \- reopen connection on error
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\& nbdkit \-\-filter=retry PLUGIN [retries=N] [retry\-delay=N]
\&                              [retry\-exponential=yes|no]
\&                              [retry\-readonly=yes|no]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-retry\-filter\*(C'\fR 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.
.PP
An alternative and more fine\-grained filter is
\&\fBnbdkit\-retry\-request\-filter\fR\|(1) which will retry only single
requests that fail.
.PP
Several optional parameters are available to control:
.IP \(bu 4
how many times we retry,
.IP \(bu 4
the delay between retries, and whether we wait longer each time (known
as “exponential back\-off”),
.IP \(bu 4
if we reopen the plugin in read\-only mode after the first failure.
.PP
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.
.SH EXAMPLE
.IX Header "EXAMPLE"
In this example we copy and convert a large file using
\&\fBnbdkit\-ssh\-plugin\fR\|(1), \fBqemu\-img\fR\|(1) and \fBnbdkit\-captive\fR\|(1).
.PP
.Vb 4
\& nbdkit \e
\&   ssh host=remote.example.com /var/tmp/test.iso \e
\&   \-\-filter=retry \e
\&   \-\-run \*(Aqqemu\-img convert \-p \-f raw "$uri" \-O qcow2 test.qcow2\*(Aq
.Ve
.PP
Without \fI\-\-filter=retry\fR a temporary failure would cause the copy to
fail (for example, the remote host’s firewall is restarted causing the
SSH connection to be dropped).  Adding this filter means that it may
be possible to transparently recover.
.SH PARAMETERS
.IX Header "PARAMETERS"
.IP \fBretries=\fRN 4
.IX Item "retries=N"
The number of times any single operation will be retried before we
give up and fail the operation.  The default is 5.
.IP \fBretry\-delay=\fRN 4
.IX Item "retry-delay=N"
The number of seconds to wait before retrying.  The default is 2
seconds.  Any format supported by \fBnbdkit_parse_delay\fR\|(3) is allowed
here.
.IP \fBretry\-exponential=yes\fR 4
.IX Item "retry-exponential=yes"
Use exponential back\-off.  The retry delay is doubled between each
retry.  This is the default.
.IP \fBretry\-exponential=no\fR 4
.IX Item "retry-exponential=no"
Do not use exponential back\-off.  The retry delay is the same between
each retry.
.IP \fBretry\-readonly=yes\fR 4
.IX Item "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.)
.IP \fBretry\-readonly=no\fR 4
.IX Item "retry-readonly=no"
Do not change the read\-write/read\-only mode of the plugin when
retrying.  This is the default.
.SH FILES
.IX Header "FILES"
.ie n .IP \fR\fI$filterdir\fR\fI/nbdkit\-retry\-filter.so\fR 4
.el .IP \fR\f(CI$filterdir\fR\fI/nbdkit\-retry\-filter.so\fR 4
.IX Item "$filterdir/nbdkit-retry-filter.so"
The filter.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$filterdir\fR.
.SH VERSION
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-retry\-filter\*(C'\fR first appeared in nbdkit 1.16.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-filter\fR\|(3),
\&\fBnbdkit\-openonce\-filter\fR\|(1),
\&\fBnbdkit\-readahead\-filter\fR\|(1),
\&\fBnbdkit\-retry\-request\-filter\fR\|(1),
\&\fBnbdkit_parse_delay\fR\|(3).
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP \(bu 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP \(bu 4
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.
.IP \(bu 4
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.
.PP
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS \*(Aq\*(AqAS IS\*(Aq\*(Aq 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.
