dm-dust.rst 10 KB

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