filters/retry/nbdkit-retry-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-retry-filter - reopen connection on error
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=retry PLUGIN [retries=N] [retry-delay=N]
   8                               [retry-exponential=yes|no]
   9                               [retry-readonly=yes|no]
  10
  11 =head1 DESCRIPTION
  12
  13 C<nbdkit-retry-filter> is a filter that transparently reopens the
  14 plugin connection when an error is encountered.  It can be used to
  15 make long-running copy operations reliable in the presence of
  16 temporary network failures, without requiring any changes to the
  17 plugin or the NBD client.
  18
  19 An alternative and more fine-grained filter is
  20 L<nbdkit-retry-request-filter(1)> which will retry only single
  21 requests that fail.
  22
  23 Several optional parameters are available to control:
  24
  25 =over 4
  26
  27 =item *
  28
  29 how many times we retry,
  30
  31 =item *
  32
  33 the delay between retries, and whether we wait longer each time (known
  34 as “exponential back-off”),
  35
  36 =item *
  37
  38 if we reopen the plugin in read-only mode after the first failure.
  39
  40 =back
  41
  42 The default (with no parameters) is designed to offer a happy medium
  43 between recovering from short temporary failures but not doing
  44 anything too bad when permanent or unrecoverable failures happen.  The
  45 default behaviour is: we retry 5 times with exponential back-off,
  46 waiting in total about 1 minute before we give up.
  47
  48 =head1 EXAMPLE
  49
  50 In this example we copy and convert a large file using
  51 L<nbdkit-ssh-plugin(1)>, L<qemu-img(1)> and L<nbdkit-captive(1)>.
  52
  53  nbdkit -U - \
  54    ssh host=remote.example.com /var/tmp/test.iso \
  55    --filter=retry \
  56    --run 'qemu-img convert -p -f raw $nbd -O qcow2 test.qcow2'
  57
  58 Without I<--filter=retry> a temporary failure would cause the copy to
  59 fail (for example, the remote host’s firewall is restarted causing the
  60 SSH connection to be dropped).  Adding this filter means that it may
  61 be possible to transparently recover.
  62
  63 =head1 PARAMETERS
  64
  65 =over 4
  66
  67 =item B<retries=>N
  68
  69 The number of times any single operation will be retried before we
  70 give up and fail the operation.  The default is 5.
  71
  72 =item B<retry-delay=>N
  73
  74 The number of seconds to wait before retrying.  The default is 2
  75 seconds.
  76
  77 =item B<retry-exponential=yes>
  78
  79 Use exponential back-off.  The retry delay is doubled between each
  80 retry.  This is the default.
  81
  82 =item B<retry-exponential=no>
  83
  84 Do not use exponential back-off.  The retry delay is the same between
  85 each retry.
  86
  87 =item B<retry-readonly=yes>
  88
  89 As soon as a failure occurs, switch the underlying plugin to read-only
  90 mode for the rest of this connection.  (A new NBD client connection
  91 will still open the plugin in the original mode.)
  92
  93 =item B<retry-readonly=no>
  94
  95 Do not change the read-write/read-only mode of the plugin when
  96 retrying.  This is the default.
  97
  98 =back
  99
 100 =head1 FILES
 101
 102 =over 4
 103
 104 =item F<$filterdir/nbdkit-retry-filter.so>
 105
 106 The filter.
 107
 108 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 109
 110 =back
 111
 112 =head1 VERSION
 113
 114 C<nbdkit-retry-filter> first appeared in nbdkit 1.16.
 115
 116 =head1 SEE ALSO
 117
 118 L<nbdkit(1)>,
 119 L<nbdkit-filter(3)>,
 120 L<nbdkit-readahead-filter(1)>,
 121 L<nbdkit-retry-request-filter(1)>.
 122
 123 =head1 AUTHORS
 124
 125 Richard W.M. Jones
 126
 127 =head1 COPYRIGHT
 128
 129 Copyright Red Hat