1nbdkit-error-filter(1) NBDKIT nbdkit-error-filter(1)
2
6 nbdkit-error-filter - inject errors for testing clients
7
9 nbdkit --filter=error PLUGIN
10 [error=EPERM|EIO|ENOMEM|EINVAL|ENOSPC|ESHUTDOWN]
11 [error-rate=10%|0.1|1:10]
12 [error-file=/tmp/inject]
13 [error-pread=...] [error-pread-rate=...] [error-pread-file=...]
14 [error-pwrite=...] [error-pwrite-rate=...] [error-pwrite-file=...]
15 [error-trim=...] [error-trim-rate=...] [error-trim-file=...]
16 [error-zero=...] [error-zero-rate=...] [error-zero-file=...]
17 [error-extents=...] [error-extents-rate=...] [error-extents-file=...]
18 [error-cache=...] [error-cache-rate=...] [error-cache-file=...]
19
21 "nbdkit-error-filter" is an nbdkit filter that injects random errors
22 into replies from the server. This is used for testing that NBD
23 clients can handle errors.
24 All parameters are optional, but you should usually specify one of the
26 "error-rate" or "error-*-rate" parameters, otherwise this filter will
27 do nothing.
28 nbdkit-evil-filter(1) is a related filter that injects data corruption
30 instead of errors.
31
33 Inject a low rate of errors randomly into the connection:
34 nbdkit --filter=error file disk.img error-rate=1%
36 Reading, trimming, cache and extents (block status) requests will be
38 successful, but all writes and zeroing will return "No space left on
39 device":
40 nbdkit --filter=error file disk.img \
42 error=ENOSPC \
43 error-pwrite-rate=100% \
44 error-zero-rate=100%
45 To make all connections fail hard 60 seconds after the server is
47 started, use:
48 rm -f /tmp/inject
50 nbdkit --filter=error file disk.img \
51 error-rate=100% \
52 error-file=/tmp/inject
53 sleep 60; touch /tmp/inject
54
56 error=EPERM|EIO|ENOMEM|EINVAL|ENOSPC|ESHUTDOWN
57 When a random error is injected, you can select which one from the
58 range of possible NBD errors (the NBD protocol only supports a
59 limited range of error codes).
60 This parameter is optional and the default is "EIO" ("Input/output
62 error").
63 error-rate=N%
65 error-rate=0..1
66 error-rate=N:M
67 The rate of injected errors per NBD request. This can be expressed
68 as a percentage between "0%" and "100%", or as a probability
69 between 0 and 1, or as a ratio like "1:10". If "0%" or 0 is used
70 then no errors are ever injected, and if "100%" or 1 is used then
71 all requests return errors.
72 This parameter is optional and the default is "0%". Unless you set
74 this, the filter will do nothing.
75 error-file=FILENAME
77 Errors will only be injected when FILENAME exists. (Note you must
78 also specify the "error-rate").
79 You can use this for fine-grained control over when to inject
81 errors, for example if you want to trigger an error at an exact
82 moment during a test, arrange for this file to be created at the
83 appropriate time. Or conversely to test error recovery in a
84 client, create the file initially, and then delete it to check the
85 client can recover.
86 This parameter is optional.
88 error-pread, error-pread-rate, error-pread-file.
90 Same as "error", "error-rate" and "error-file" but only apply the
91 settings to NBD pread requests.
92 error-pwrite, error-pwrite-rate, error-pwrite-file.
94 Same as "error", "error-rate" and "error-file" but only apply the
95 settings to NBD pwrite requests.
96 error-trim, error-trim-rate, error-trim-file.
98 Same as "error", "error-rate" and "error-file" but only apply the
99 settings to NBD trim requests.
100 error-zero, error-zero-rate, error-zero-file.
102 Same as "error", "error-rate" and "error-file" but only apply the
103 settings to NBD zero requests.
104 error-extents, error-extents-rate, error-extents-file.
106 (nbdkit ≥ 1.12)
107 Same as "error", "error-rate" and "error-file" but only apply the
109 settings to NBD block status requests to read extents.
110 error-cache, error-cache-rate, error-cache-file.
112 (nbdkit ≥ 1.14)
113 Same as "error", "error-rate" and "error-file" but only apply the
115 settings to NBD cache requests.
116
118 Peculiar debug output
119 If you are looking at the debugging output (using "nbdkit -f -v")
120 references to the name of this filter show up as "error-inject:", and
121 such lines indicate that the filter is not altering output, for
122 example:
123 nbdkit: file.9: debug: error-inject: pread count=1024 offset=0 flags=0x0
125 Conversely, references to the string "error:" occur when the
127 nbdkit_error(3) API was used, including when this filter injects an
128 error, as in:
129 nbdkit: file.4: error: injecting ENOSPC error into pwrite
131
133 $filterdir/nbdkit-error-filter.so
134 The filter.
135 Use "nbdkit --dump-config" to find the location of $filterdir.
137
139 "nbdkit-error-filter" first appeared in nbdkit 1.6.
140
142 nbdkit(1), nbdkit-evil-filter(1), nbdkit-file-plugin(1),
143 nbdkit-full-plugin(1), nbdkit-retry-filter(1),
144 nbdkit-retry-request-filter(1), nbdkit-filter(3).
145
147 Richard W.M. Jones
148
150 Copyright Red Hat
151
153 Redistribution and use in source and binary forms, with or without
154 modification, are permitted provided that the following conditions are
155 met:
156 • Redistributions of source code must retain the above copyright
158 notice, this list of conditions and the following disclaimer.
159 • Redistributions in binary form must reproduce the above copyright
161 notice, this list of conditions and the following disclaimer in the
162 documentation and/or other materials provided with the
163 distribution.
164 • Neither the name of Red Hat nor the names of its contributors may
166 be used to endorse or promote products derived from this software
167 without specific prior written permission.
168 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
170 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
171 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
172 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
173 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
174 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
175 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
176 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
177 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
178 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
179 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
180nbdkit-1.36.2 2023-11-26 nbdkit-error-filter(1)