1nbdkit-evil-filter(1) NBDKIT nbdkit-evil-filter(1)
2
6 nbdkit-evil-filter - add random data corruption to reads
7
9 nbdkit --filter=evil PLUGIN [PLUGIN-ARGS...]
10 evil=[cosmic-rays|stuck-bits|stuck-wires]
11 [evil-probability=PROB] [evil-stuck-probability=PROB]
12 [evil-seed=SEED]
13
15 nbdkit-evil-filter is a Byzantine filter for nbdkit(1) that randomly
16 corrupts data when reading from the underlying plugin. This can be
17 used for testing filesystem checksums. Note that it does not change
18 write operations, so the underlying plugin contains the correct data.
19 nbdkit-error-filter(1) is a related filter that injects hard errors
21 into the NBD protocol.
22 This filter has several modes, controlled using the "evil=..."
24 parameter. These are:
25 "evil=cosmic-rays"
27 Bits are flipped at random when reading data. The probability that
28 a bit is flipped is controlled using the "evil-probability"
29 parameter, defaulting to 1e-8 (on average 1 in every 100 million
30 bits read is flipped).
31 "evil=stuck-bits"
33 This is the default mode.
34 Fixed bits in the backing file are stuck randomly high or low. The
36 "evil-probability" parameter controls the expected probability that
37 a particular bit is stuck, defaulting in this mode to 1e-8 (1 in
38 100 million). "evil-stuck-probability" controls the probability
39 that a stuck bit is read as its stuck value or its correct value,
40 defaulting to 100% (always read as a stuck bit).
41 "evil=stuck-wires"
43 This is similar to "stuck-bits" but instead of simulating bad
44 backing data, it simulates stuck wires along the data path (eg. in
45 a register). The difference is that when reading, the stuck bit
46 always happens at the same position in the packet of data being
47 read, regardless of where on the underlying disk it is being read
48 from. "evil-probability" controls the probability of a stuck wire,
49 defaulting in this mode to 1e-6 (1 in 1 million).
50 "evil-stuck-probability" controls the probability that a stuck bit
51 is read as its stuck value or its correct value, defaulting to 100%
52 (always read as a stuck bit).
53
55 Add some stuck bits to the backing file at random:
56 nbdkit --filter=evil file disk.img
58 Cosmic rays will flip (on average) one in every 100 million bits copied
60 from the backing file over NBD:
61 nbdkit --filter=evil file disk.img evil=cosmic-rays \
63 --run 'nbdcopy $uri output.img'
64
66 Extents
67 Plugins can be sparse. This filter only corrupts bits in non-sparse
68 parts of the backing disk and it leaves sparse regions unchanged (which
69 is realistic behaviour). If you wish to use this filter to corrupt
70 sparse regions, then combine this filter with
71 nbdkit-noextents-filter(1). For example:
72 nbdkit --filter=evil --filter=noextents memory 1G
74 Probability limited to [ 1e-12 .. 1/8 ]
76 The current implementation limits probabilities to the range
77 [ 1e-12 .. 1/8 ]. Values below this range are treated the same as 0%.
78 Values above this range are treated the same as 100%.
79
81 evil=cosmic-rays
82 evil=stuck-bits
83 evil=stuck-wires
84 Select the mode of evil. See the "DESCRIPTION" above. The default
85 is "stuck-bits".
86 evil-probability=N
88 evil-probability=N:M
89 evil-probability=N%
90 Set the probability for the mode. You can either use a floating
91 point number between 0 and 1, eg. "evil-probability=0.001" or
92 "evil-probability=1e-6". Or you can write it as N in M, eg.
93 "evil-probability=1:1000000" or "evil-probability=3.33:100000". Or
94 you can write this as a percentage, eg. "evil-probability=1%".
95 The default probability depends on the mode.
97 evil-seed=SEED
99 To make runs repeatable, use this to set a seed for the random
100 number generator. Note that runs are repeatable only if you use
101 the same version of nbdkit, since in future we may change the
102 algorithm.
103 The default is to choose a seed at random.
105 evil-stuck-probability=N
107 evil-stuck-probability=N:M
108 evil-stuck-probability=N%
109 For the "stuck-*" modes, the probability that when reading a stuck
110 bit you will read the stuck bit or the correct value. This
111 defaults to 1 (ie. 100%) which means the bit is always stuck.
112 Setting it to 0.5 for example will mean that half the time the bit
113 appears stuck and half the time you see the correct value.
114
116 $filterdir/nbdkit-evil-filter.so
117 The filter.
118 Use "nbdkit --dump-config" to find the location of $filterdir.
120
122 "nbdkit-evil-filter" first appeared in nbdkit 1.36.
123
125 nbdkit(1), nbdkit-filter(3), nbdkit-delay-filter(1),
126 nbdkit-noextents-filter(1), nbdkit-error-filter(1).
127
129 Richard W.M. Jones
130
132 Copyright Red Hat
133
135 Redistribution and use in source and binary forms, with or without
136 modification, are permitted provided that the following conditions are
137 met:
138 • Redistributions of source code must retain the above copyright
140 notice, this list of conditions and the following disclaimer.
141 • Redistributions in binary form must reproduce the above copyright
143 notice, this list of conditions and the following disclaimer in the
144 documentation and/or other materials provided with the
145 distribution.
146 • Neither the name of Red Hat nor the names of its contributors may
148 be used to endorse or promote products derived from this software
149 without specific prior written permission.
150 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
152 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
153 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
154 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
155 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
156 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
157 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
158 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
159 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
160 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
161 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
162nbdkit-1.36.2 2023-11-26 nbdkit-evil-filter(1)