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