0001 dm-dust
0002 =======
0003
0004 This target emulates the behavior of bad sectors at arbitrary
0005 locations, and the ability to enable the emulation of the failures
0006 at an arbitrary time.
0007
0008 This target behaves similarly to a linear target. At a given time,
0009 the user can send a message to the target to start failing read
0010 requests on specific blocks (to emulate the behavior of a hard disk
0011 drive with bad sectors).
0012
0013 When the failure behavior is enabled (i.e.: when the output of
0014 "dmsetup status" displays "fail_read_on_bad_block"), reads of blocks
0015 in the "bad block list" will fail with EIO ("Input/output error").
0016
0017 Writes of blocks in the "bad block list will result in the following:
0018
0019 1. Remove the block from the "bad block list".
0020 2. Successfully complete the write.
0021
0022 This emulates the "remapped sector" behavior of a drive with bad
0023 sectors.
0024
0025 Normally, a drive that is encountering bad sectors will most likely
0026 encounter more bad sectors, at an unknown time or location.
0027 With dm-dust, the user can use the "addbadblock" and "removebadblock"
0028 messages to add arbitrary bad blocks at new locations, and the
0029 "enable" and "disable" messages to modulate the state of whether the
0030 configured "bad blocks" will be treated as bad, or bypassed.
0031 This allows the pre-writing of test data and metadata prior to
0032 simulating a "failure" event where bad sectors start to appear.
0033
0034 Table parameters
0035 ----------------
0036 <device_path> <offset> <blksz>
0037
0038 Mandatory parameters:
0039 <device_path>:
0040 Path to the block device.
0041
0042 <offset>:
0043 Offset to data area from start of device_path
0044
0045 <blksz>:
0046 Block size in bytes
0047
0048 (minimum 512, maximum 1073741824, must be a power of 2)
0049
0050 Usage instructions
0051 ------------------
0052
0053 First, find the size (in 512-byte sectors) of the device to be used::
0054
0055 $ sudo blockdev --getsz /dev/vdb1
0056 33552384
0057
0058 Create the dm-dust device:
0059 (For a device with a block size of 512 bytes)
0060
0061 ::
0062
0063 $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512'
0064
0065 (For a device with a block size of 4096 bytes)
0066
0067 ::
0068
0069 $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096'
0070
0071 Check the status of the read behavior ("bypass" indicates that all I/O
0072 will be passed through to the underlying device; "verbose" indicates that
0073 bad block additions, removals, and remaps will be verbosely logged)::
0074
0075 $ sudo dmsetup status dust1
0076 0 33552384 dust 252:17 bypass verbose
0077
0078 $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct
0079 128+0 records in
0080 128+0 records out
0081
0082 $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
0083 128+0 records in
0084 128+0 records out
0085
0086 Adding and removing bad blocks
0087 ------------------------------
0088
0089 At any time (i.e.: whether the device has the "bad block" emulation
0090 enabled or disabled), bad blocks may be added or removed from the
0091 device via the "addbadblock" and "removebadblock" messages::
0092
0093 $ sudo dmsetup message dust1 0 addbadblock 60
0094 kernel: device-mapper: dust: badblock added at block 60
0095
0096 $ sudo dmsetup message dust1 0 addbadblock 67
0097 kernel: device-mapper: dust: badblock added at block 67
0098
0099 $ sudo dmsetup message dust1 0 addbadblock 72
0100 kernel: device-mapper: dust: badblock added at block 72
0101
0102 These bad blocks will be stored in the "bad block list".
0103 While the device is in "bypass" mode, reads and writes will succeed::
0104
0105 $ sudo dmsetup status dust1
0106 0 33552384 dust 252:17 bypass
0107
0108 Enabling block read failures
0109 ----------------------------
0110
0111 To enable the "fail read on bad block" behavior, send the "enable" message::
0112
0113 $ sudo dmsetup message dust1 0 enable
0114 kernel: device-mapper: dust: enabling read failures on bad sectors
0115
0116 $ sudo dmsetup status dust1
0117 0 33552384 dust 252:17 fail_read_on_bad_block
0118
0119 With the device in "fail read on bad block" mode, attempting to read a
0120 block will encounter an "Input/output error"::
0121
0122 $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct
0123 dd: error reading '/dev/mapper/dust1': Input/output error
0124 0+0 records in
0125 0+0 records out
0126 0 bytes copied, 0.00040651 s, 0.0 kB/s
0127
0128 ...and writing to the bad blocks will remove the blocks from the list,
0129 therefore emulating the "remap" behavior of hard disk drives::
0130
0131 $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
0132 128+0 records in
0133 128+0 records out
0134
0135 kernel: device-mapper: dust: block 60 removed from badblocklist by write
0136 kernel: device-mapper: dust: block 67 removed from badblocklist by write
0137 kernel: device-mapper: dust: block 72 removed from badblocklist by write
0138 kernel: device-mapper: dust: block 87 removed from badblocklist by write
0139
0140 Bad block add/remove error handling
0141 -----------------------------------
0142
0143 Attempting to add a bad block that already exists in the list will
0144 result in an "Invalid argument" error, as well as a helpful message::
0145
0146 $ sudo dmsetup message dust1 0 addbadblock 88
0147 device-mapper: message ioctl on dust1 failed: Invalid argument
0148 kernel: device-mapper: dust: block 88 already in badblocklist
0149
0150 Attempting to remove a bad block that doesn't exist in the list will
0151 result in an "Invalid argument" error, as well as a helpful message::
0152
0153 $ sudo dmsetup message dust1 0 removebadblock 87
0154 device-mapper: message ioctl on dust1 failed: Invalid argument
0155 kernel: device-mapper: dust: block 87 not found in badblocklist
0156
0157 Counting the number of bad blocks in the bad block list
0158 -------------------------------------------------------
0159
0160 To count the number of bad blocks configured in the device, run the
0161 following message command::
0162
0163 $ sudo dmsetup message dust1 0 countbadblocks
0164
0165 A message will print with the number of bad blocks currently
0166 configured on the device::
0167
0168 countbadblocks: 895 badblock(s) found
0169
0170 Querying for specific bad blocks
0171 --------------------------------
0172
0173 To find out if a specific block is in the bad block list, run the
0174 following message command::
0175
0176 $ sudo dmsetup message dust1 0 queryblock 72
0177
0178 The following message will print if the block is in the list::
0179
0180 dust_query_block: block 72 found in badblocklist
0181
0182 The following message will print if the block is not in the list::
0183
0184 dust_query_block: block 72 not found in badblocklist
0185
0186 The "queryblock" message command will work in both the "enabled"
0187 and "disabled" modes, allowing the verification of whether a block
0188 will be treated as "bad" without having to issue I/O to the device,
0189 or having to "enable" the bad block emulation.
0190
0191 Clearing the bad block list
0192 ---------------------------
0193
0194 To clear the bad block list (without needing to individually run
0195 a "removebadblock" message command for every block), run the
0196 following message command::
0197
0198 $ sudo dmsetup message dust1 0 clearbadblocks
0199
0200 After clearing the bad block list, the following message will appear::
0201
0202 dust_clear_badblocks: badblocks cleared
0203
0204 If there were no bad blocks to clear, the following message will
0205 appear::
0206
0207 dust_clear_badblocks: no badblocks found
0208
0209 Listing the bad block list
0210 --------------------------
0211
0212 To list all bad blocks in the bad block list (using an example device
0213 with blocks 1 and 2 in the bad block list), run the following message
0214 command::
0215
0216 $ sudo dmsetup message dust1 0 listbadblocks
0217 1
0218 2
0219
0220 If there are no bad blocks in the bad block list, the command will
0221 execute with no output::
0222
0223 $ sudo dmsetup message dust1 0 listbadblocks
0224
0225 Message commands list
0226 ---------------------
0227
0228 Below is a list of the messages that can be sent to a dust device:
0229
0230 Operations on blocks (requires a <blknum> argument)::
0231
0232 addbadblock <blknum>
0233 queryblock <blknum>
0234 removebadblock <blknum>
0235
0236 ...where <blknum> is a block number within range of the device
0237 (corresponding to the block size of the device.)
0238
0239 Single argument message commands::
0240
0241 countbadblocks
0242 clearbadblocks
0243 listbadblocks
0244 disable
0245 enable
0246 quiet
0247
0248 Device removal
0249 --------------
0250
0251 When finished, remove the device via the "dmsetup remove" command::
0252
0253 $ sudo dmsetup remove dust1
0254
0255 Quiet mode
0256 ----------
0257
0258 On test runs with many bad blocks, it may be desirable to avoid
0259 excessive logging (from bad blocks added, removed, or "remapped").
0260 This can be done by enabling "quiet mode" via the following message::
0261
0262 $ sudo dmsetup message dust1 0 quiet
0263
0264 This will suppress log messages from add / remove / removed by write
0265 operations. Log messages from "countbadblocks" or "queryblock"
0266 message commands will still print in quiet mode.
0267
0268 The status of quiet mode can be seen by running "dmsetup status"::
0269
0270 $ sudo dmsetup status dust1
0271 0 33552384 dust 252:17 fail_read_on_bad_block quiet
0272
0273 To disable quiet mode, send the "quiet" message again::
0274
0275 $ sudo dmsetup message dust1 0 quiet
0276
0277 $ sudo dmsetup status dust1
0278 0 33552384 dust 252:17 fail_read_on_bad_block verbose
0279
0280 (The presence of "verbose" indicates normal logging.)
0281
0282 "Why not...?"
0283 -------------
0284
0285 scsi_debug has a "medium error" mode that can fail reads on one
0286 specified sector (sector 0x1234, hardcoded in the source code), but
0287 it uses RAM for the persistent storage, which drastically decreases
0288 the potential device size.
0289
0290 dm-flakey fails all I/O from all block locations at a specified time
0291 frequency, and not a given point in time.
0292
0293 When a bad sector occurs on a hard disk drive, reads to that sector
0294 are failed by the device, usually resulting in an error code of EIO
0295 ("I/O error") or ENODATA ("No data available"). However, a write to
0296 the sector may succeed, and result in the sector becoming readable
0297 after the device controller no longer experiences errors reading the
0298 sector (or after a reallocation of the sector). However, there may
0299 be bad sectors that occur on the device in the future, in a different,
0300 unpredictable location.
0301
0302 This target seeks to provide a device that can exhibit the behavior
0303 of a bad sector at a known sector location, at a known time, based
0304 on a large storage device (at least tens of gigabytes, not occupying
0305 system memory).
