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