filters/error/nbdkit-error-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-error-filter - inject errors for testing clients
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=error PLUGIN
   8      [error=EPERM|EIO|ENOMEM|EINVAL|ENOSPC|ESHUTDOWN]
   9      [error-rate=10%|0.1]
  10      [error-file=/tmp/inject]
  11      [error-pread=...] [error-pread-rate=...] [error-pread-file=...]
  12      [error-pwrite=...] [error-pwrite-rate=...] [error-pwrite-file=...]
  13      [error-trim=...] [error-trim-rate=...] [error-trim-file=...]
  14      [error-zero=...] [error-zero-rate=...] [error-zero-file=...]
  15      [error-extents=...] [error-extents-rate=...] [error-extents-file=...]
  16      [error-cache=...] [error-cache-rate=...] [error-cache-file=...]
  17
  18 =head1 DESCRIPTION
  19
  20 C<nbdkit-error-filter> is an nbdkit filter that injects random errors
  21 into replies from the server.  This is used for testing that NBD
  22 clients can handle errors.
  23
  24 All parameters are optional, but you should usually specify one of the
  25 C<error-rate> or C<error-*-rate> parameters,
  26 B<otherwise this filter will do nothing>.
  27
  28 =head1 EXAMPLES
  29
  30 Inject a low rate of errors randomly into the connection:
  31
  32  nbdkit --filter=error file disk.img error-rate=1%
  33
  34 Reading, trimming, cache and extents (block status) requests will be
  35 successful, but all writes and zeroing will return "No space left on
  36 device":
  37
  38  nbdkit --filter=error file disk.img \
  39                             error=ENOSPC \
  40                             error-pwrite-rate=100% \
  41                             error-zero-rate=100%
  42
  43 To make all connections fail hard 60 seconds after the server is
  44 started, use:
  45
  46  rm -f /tmp/inject
  47  nbdkit --filter=error file disk.img \
  48                             error-rate=100% \
  49                             error-file=/tmp/inject
  50  sleep 60; touch /tmp/inject
  51
  52 =head1 PARAMETERS
  53
  54 =over 4
  55
  56 =item B<error=EPERM|EIO|ENOMEM|EINVAL|ENOSPC|ESHUTDOWN>
  57
  58 When a random error is injected, you can select which one from the
  59 range of possible NBD errors (the NBD protocol only supports a limited
  60 range of error codes).
  61
  62 This parameter is optional and the default is C<EIO>
  63 ("Input/output error").
  64
  65 =item B<error-rate=>NB<%>
  66
  67 =item B<error-rate=>0..1
  68
  69 The rate of injected errors per NBD request.  This can be expressed as
  70 either a percentage between C<0%> and C<100%> or as a probability
  71 between C<0> and C<1>.  If C<0%> or C<0> is used then no errors are
  72 ever injected, and if C<100%> or C<1> is used then all requests return
  73 errors.
  74
  75 This parameter is optional and the default is C<0%>.
  76 B<Unless you set this, the filter will do nothing.>
  77
  78 =item B<error-file=>FILENAME
  79
  80 Errors will only be injected when F<FILENAME> exists.  (Note you must
  81 also specify the C<error-rate>).
  82
  83 You can use this for fine-grained control over when to inject errors,
  84 for example if you want to trigger an error at an exact moment during
  85 a test, arrange for this file to be created at the appropriate time.
  86 Or conversely to test error recovery in a client, create the file
  87 initially, and then delete it to check the client can recover.
  88
  89 This parameter is optional.
  90
  91 =item B<error-pread>, B<error-pread-rate>, B<error-pread-file>.
  92
  93 Same as C<error>, C<error-rate> and C<error-file> but only apply the
  94 settings to NBD pread requests.
  95
  96 =item B<error-pwrite>, B<error-pwrite-rate>, B<error-pwrite-file>.
  97
  98 Same as C<error>, C<error-rate> and C<error-file> but only apply the
  99 settings to NBD pwrite requests.
 100
 101 =item B<error-trim>, B<error-trim-rate>, B<error-trim-file>.
 102
 103 Same as C<error>, C<error-rate> and C<error-file> but only apply the
 104 settings to NBD trim requests.
 105
 106 =item B<error-zero>, B<error-zero-rate>, B<error-zero-file>.
 107
 108 Same as C<error>, C<error-rate> and C<error-file> but only apply the
 109 settings to NBD zero requests.
 110
 111 =item B<error-extents>, B<error-extents-rate>, B<error-extents-file>.
 112
 113 (nbdkit E<ge> 1.12)
 114
 115 Same as C<error>, C<error-rate> and C<error-file> but only apply the
 116 settings to NBD block status requests to read extents.
 117
 118 =item B<error-cache>, B<error-cache-rate>, B<error-cache-file>.
 119
 120 (nbdkit E<ge> 1.14)
 121
 122 Same as C<error>, C<error-rate> and C<error-file> but only apply the
 123 settings to NBD cache requests.
 124
 125 =back
 126
 127 =head1 NOTES
 128
 129 =head2 Peculiar debug output
 130
 131 If you are looking at the debugging output (using C<nbdkit -f -v>)
 132 references to the name of this filter show up as C<"error-inject:">,
 133 and such lines indicate that the filter is not altering output, for
 134 example:
 135
 136  nbdkit: file.9: debug: error-inject: pread count=1024 offset=0 flags=0x0
 137
 138 Conversely, references to the string C<"error:"> occur when the
 139 L<nbdkit_error(3)> API was used, including when this filter injects an
 140 error, as in:
 141
 142  nbdkit: file.4: error: injecting ENOSPC error into pwrite
 143
 144 =head1 FILES
 145
 146 =over 4
 147
 148 =item F<$filterdir/nbdkit-error-filter.so>
 149
 150 The filter.
 151
 152 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 153
 154 =back
 155
 156 =head1 VERSION
 157
 158 C<nbdkit-error-filter> first appeared in nbdkit 1.6.
 159
 160 =head1 SEE ALSO
 161
 162 L<nbdkit(1)>,
 163 L<nbdkit-file-plugin(1)>,
 164 L<nbdkit-full-plugin(1)>,
 165 L<nbdkit-retry-filter(1)>,
 166 L<nbdkit-retry-request-filter(1)>,
 167 L<nbdkit-filter(3)>.
 168
 169 =head1 AUTHORS
 170
 171 Richard W.M. Jones
 172
 173 =head1 COPYRIGHT
 174
 175 Copyright Red Hat