1 dm-dust
2 =======
3
4 This target emulates the behavior of bad sectors at arbitrary
5 locations, and the ability to enable the emulation of the failures
6 at an arbitrary time.
7
8 This target behaves similarly to a linear target. At a given time,
9 the user can send a message to the target to start failing read
10 requests on specific blocks (to emulate the behavior of a hard disk
11 drive with bad sectors).
12
13 When the failure behavior is enabled (i.e.: when the output of
14 "dmsetup status" displays "fail_read_on_bad_block"), reads of blocks
15 in the "bad block list" will fail with EIO ("Input/output error").
16
17 Writes of blocks in the "bad block list will result in the following:
18
19 1. Remove the block from the "bad block list".
20 2. Successfully complete the write.
21
22 This emulates the "remapped sector" behavior of a drive with bad
23 sectors.
24
25 Normally, a drive that is encountering bad sectors will most likely
26 encounter more bad sectors, at an unknown time or location.
27 With dm-dust, the user can use the "addbadblock" and "removebadblock"
28 messages to add arbitrary bad blocks at new locations, and the
29 "enable" and "disable" messages to modulate the state of whether the
30 configured "bad blocks" will be treated as bad, or bypassed.
31 This allows the pre-writing of test data and metadata prior to
32 simulating a "failure" event where bad sectors start to appear.
33
34 Table parameters
35 ----------------
36 <device_path> <offset> <blksz>
37
38 Mandatory parameters:
39 <device_path>:
40 Path to the block device.
41
42 <offset>:
43 Offset to data area from start of device_path
44
45 <blksz>:
46 Block size in bytes
47
48 (minimum 512, maximum 1073741824, must be a power of 2)
49
50 Usage instructions
51 ------------------
52
53 First, find the size (in 512-byte sectors) of the device to be used::
54
55 $ sudo blockdev --getsz /dev/vdb1
56 33552384
57
58 Create the dm-dust device:
59 (For a device with a block size of 512 bytes)
60
61 ::
62
63 $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512'
64
65 (For a device with a block size of 4096 bytes)
66
67 ::
68
69 $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096'
70
71 Check the status of the read behavior ("bypass" indicates that all I/O
72 will be passed through to the underlying device; "verbose" indicates that
73 bad block additions, removals, and remaps will be verbosely logged)::
74
75 $ sudo dmsetup status dust1
76 0 33552384 dust 252:17 bypass verbose
77
78 $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct
79 128+0 records in
80 128+0 records out
81
82 $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
83 128+0 records in
84 128+0 records out
85
86 Adding and removing bad blocks
87 ------------------------------
88
89 At any time (i.e.: whether the device has the "bad block" emulation
90 enabled or disabled), bad blocks may be added or removed from the
91 device via the "addbadblock" and "removebadblock" messages::
92
93 $ sudo dmsetup message dust1 0 addbadblock 60
94 kernel: device-mapper: dust: badblock added at block 60
95
96 $ sudo dmsetup message dust1 0 addbadblock 67
97 kernel: device-mapper: dust: badblock added at block 67
98
99 $ sudo dmsetup message dust1 0 addbadblock 72
100 kernel: device-mapper: dust: badblock added at block 72
101
102 These bad blocks will be stored in the "bad block list".
103 While the device is in "bypass" mode, reads and writes will succeed::
104
105 $ sudo dmsetup status dust1
106 0 33552384 dust 252:17 bypass
107
108 Enabling block read failures
109 ----------------------------
110
111 To enable the "fail read on bad block" behavior, send the "enable" message::
112
113 $ sudo dmsetup message dust1 0 enable
114 kernel: device-mapper: dust: enabling read failures on bad sectors
115
116 $ sudo dmsetup status dust1
117 0 33552384 dust 252:17 fail_read_on_bad_block
118
119 With the device in "fail read on bad block" mode, attempting to read a
120 block will encounter an "Input/output error"::
121
122 $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct
123 dd: error reading '/dev/mapper/dust1': Input/output error
124 0+0 records in
125 0+0 records out
126 0 bytes copied, 0.00040651 s, 0.0 kB/s
127
128 ...and writing to the bad blocks will remove the blocks from the list,
129 therefore emulating the "remap" behavior of hard disk drives::
130
131 $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
132 128+0 records in
133 128+0 records out
134
135 kernel: device-mapper: dust: block 60 removed from badblocklist by write
136 kernel: device-mapper: dust: block 67 removed from badblocklist by write
137 kernel: device-mapper: dust: block 72 removed from badblocklist by write
138 kernel: device-mapper: dust: block 87 removed from badblocklist by write
139
140 Bad block add/remove error handling
141 -----------------------------------
142
143 Attempting to add a bad block that already exists in the list will
144 result in an "Invalid argument" error, as well as a helpful message::
145
146 $ sudo dmsetup message dust1 0 addbadblock 88
147 device-mapper: message ioctl on dust1 failed: Invalid argument
148 kernel: device-mapper: dust: block 88 already in badblocklist
149
150 Attempting to remove a bad block that doesn't exist in the list will
151 result in an "Invalid argument" error, as well as a helpful message::
152
153 $ sudo dmsetup message dust1 0 removebadblock 87
154 device-mapper: message ioctl on dust1 failed: Invalid argument
155 kernel: device-mapper: dust: block 87 not found in badblocklist
156
157 Counting the number of bad blocks in the bad block list
158 -------------------------------------------------------
159
160 To count the number of bad blocks configured in the device, run the
161 following message command::
162
163 $ sudo dmsetup message dust1 0 countbadblocks
164
165 A message will print with the number of bad blocks currently
166 configured on the device::
167
168 countbadblocks: 895 badblock(s) found
169
170 Querying for specific bad blocks
171 --------------------------------
172
173 To find out if a specific block is in the bad block list, run the
174 following message command::
175
176 $ sudo dmsetup message dust1 0 queryblock 72
177
178 The following message will print if the block is in the list::
179
180 dust_query_block: block 72 found in badblocklist
181
182 The following message will print if the block is not in the list::
183
184 dust_query_block: block 72 not found in badblocklist
185
186 The "queryblock" message command will work in both the "enabled"
187 and "disabled" modes, allowing the verification of whether a block
188 will be treated as "bad" without having to issue I/O to the device,
189 or having to "enable" the bad block emulation.
190
191 Clearing the bad block list
192 ---------------------------
193
194 To clear the bad block list (without needing to individually run
195 a "removebadblock" message command for every block), run the
196 following message command::
197
198 $ sudo dmsetup message dust1 0 clearbadblocks
199
200 After clearing the bad block list, the following message will appear::
201
202 dust_clear_badblocks: badblocks cleared
203
204 If there were no bad blocks to clear, the following message will
205 appear::
206
207 dust_clear_badblocks: no badblocks found
208
209 Listing the bad block list
210 --------------------------
211
212 To list all bad blocks in the bad block list (using an example device
213 with blocks 1 and 2 in the bad block list), run the following message
214 command::
215
216 $ sudo dmsetup message dust1 0 listbadblocks
217 1
218 2
219
220 If there are no bad blocks in the bad block list, the command will
221 execute with no output::
222
223 $ sudo dmsetup message dust1 0 listbadblocks
224
225 Message commands list
226 ---------------------
227
228 Below is a list of the messages that can be sent to a dust device:
229
230 Operations on blocks (requires a <blknum> argument)::
231
232 addbadblock <blknum>
233 queryblock <blknum>
234 removebadblock <blknum>
235
236 ...where <blknum> is a block number within range of the device
237 (corresponding to the block size of the device.)
238
239 Single argument message commands::
240
241 countbadblocks
242 clearbadblocks
243 listbadblocks
244 disable
245 enable
246 quiet
247
248 Device removal
249 --------------
250
251 When finished, remove the device via the "dmsetup remove" command::
252
253 $ sudo dmsetup remove dust1
254
255 Quiet mode
256 ----------
257
258 On test runs with many bad blocks, it may be desirable to avoid
259 excessive logging (from bad blocks added, removed, or "remapped").
260 This can be done by enabling "quiet mode" via the following message::
261
262 $ sudo dmsetup message dust1 0 quiet
263
264 This will suppress log messages from add / remove / removed by write
265 operations. Log messages from "countbadblocks" or "queryblock"
266 message commands will still print in quiet mode.
267
268 The status of quiet mode can be seen by running "dmsetup status"::
269
270 $ sudo dmsetup status dust1
271 0 33552384 dust 252:17 fail_read_on_bad_block quiet
272
273 To disable quiet mode, send the "quiet" message again::
274
275 $ sudo dmsetup message dust1 0 quiet
276
277 $ sudo dmsetup status dust1
278 0 33552384 dust 252:17 fail_read_on_bad_block verbose
279
280 (The presence of "verbose" indicates normal logging.)
281
282 "Why not...?"
283 -------------
284
285 scsi_debug has a "medium error" mode that can fail reads on one
286 specified sector (sector 0x1234, hardcoded in the source code), but
287 it uses RAM for the persistent storage, which drastically decreases
288 the potential device size.
289
290 dm-flakey fails all I/O from all block locations at a specified time
291 frequency, and not a given point in time.
292
293 When a bad sector occurs on a hard disk drive, reads to that sector
294 are failed by the device, usually resulting in an error code of EIO
295 ("I/O error") or ENODATA ("No data available"). However, a write to
296 the sector may succeed, and result in the sector becoming readable
297 after the device controller no longer experiences errors reading the
298 sector (or after a reallocation of the sector). However, there may
299 be bad sectors that occur on the device in the future, in a different,
300 unpredictable location.
301
302 This target seeks to provide a device that can exhibit the behavior
303 of a bad sector at a known sector location, at a known time, based
304 on a large storage device (at least tens of gigabytes, not occupying
305 system memory).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.