Documentation/admin-guide/device-mapper/dm-dust.rst

   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).