[linux-block.git] / Documentation / admin-guide / device-mapper / dm-flakey.rst

=========
dm-flakey
=========

This target is the same as the linear target except that it exhibits
unreliable behaviour periodically.  It's been found useful in simulating
failing devices for testing purposes.

Starting from the time the table is loaded, the device is available for
<up interval> seconds, then exhibits unreliable behaviour for <down
interval> seconds, and then this cycle repeats.

Also, consider using this in combination with the dm-delay target too,
which can delay reads and writes and/or send them to different
underlying devices.

Table parameters
----------------

::

  <dev path> <offset> <up interval> <down interval> \
    [<num_features> [<feature arguments>]]

Mandatory parameters:

    <dev path>:
        Full pathname to the underlying block-device, or a
        "major:minor" device-number.
    <offset>:
        Starting sector within the device.
    <up interval>:
        Number of seconds device is available.
    <down interval>:
        Number of seconds device returns errors.

Optional feature parameters:

  If no feature parameters are present, during the periods of
  unreliability, all I/O returns errors.

  drop_writes:
	All write I/O is silently ignored.
	Read I/O is handled correctly.

  error_writes:
	All write I/O is failed with an error signalled.
	Read I/O is handled correctly.

  corrupt_bio_byte <Nth_byte> <direction> <value> <flags>:
	During <down interval>, replace <Nth_byte> of the data of
	each matching bio with <value>.

    <Nth_byte>:
	The offset of the byte to replace.
	Counting starts at 1, to replace the first byte.
    <direction>:
	Either 'r' to corrupt reads or 'w' to corrupt writes.
	'w' is incompatible with drop_writes.
    <value>:
	The value (from 0-255) to write.
    <flags>:
	Perform the replacement only if bio->bi_opf has all the
	selected flags set.

Examples:

Replaces the 32nd byte of READ bios with the value 1::

  corrupt_bio_byte 32 r 1 0

Replaces the 224th byte of REQ_META (=32) bios with the value 0::

  corrupt_bio_byte 224 w 0 32
Commit	Line	Data
f0ba4377	1	=========
3407ef52 JB	2	dm-flakey
	3	=========
	4
b26f5e3d MS	5	This target is the same as the linear target except that it exhibits
	6	unreliable behaviour periodically. It's been found useful in simulating
	7	failing devices for testing purposes.
3407ef52 JB	8
3407ef52 JB	9	Starting from the time the table is loaded, the device is available for
b26f5e3d MS	10	<up interval> seconds, then exhibits unreliable behaviour for <down
b26f5e3d MS	11	interval> seconds, and then this cycle repeats.
3407ef52	12
b26f5e3d MS	13	Also, consider using this in combination with the dm-delay target too,
	14	which can delay reads and writes and/or send them to different
	15	underlying devices.
	16
	17	Table parameters
	18	----------------
f0ba4377 MCC	19
	20	::
	21
b26f5e3d MS	22	<dev path> <offset> <up interval> <down interval> \
	23	[<num_features> [<feature arguments>]]
	24
	25	Mandatory parameters:
f0ba4377 MCC	26
	27	<dev path>:
	28	Full pathname to the underlying block-device, or a
	29	"major:minor" device-number.
	30	<offset>:
	31	Starting sector within the device.
	32	<up interval>:
	33	Number of seconds device is available.
	34	<down interval>:
	35	Number of seconds device returns errors.
b26f5e3d MS	36
b26f5e3d MS	37	Optional feature parameters:
f0ba4377	38
b26f5e3d MS	39	If no feature parameters are present, during the periods of
	40	unreliability, all I/O returns errors.
	41
	42	drop_writes:
	43	All write I/O is silently ignored.
	44	Read I/O is handled correctly.
a3998799	45
0c6c987f NB	46	error_writes:
	47	All write I/O is failed with an error signalled.
	48	Read I/O is handled correctly.
	49
a3998799 MS	50	corrupt_bio_byte <Nth_byte> <direction> <value> <flags>:
	51	During <down interval>, replace <Nth_byte> of the data of
	52	each matching bio with <value>.
	53
f0ba4377 MCC	54	<Nth_byte>:
	55	The offset of the byte to replace.
	56	Counting starts at 1, to replace the first byte.
	57	<direction>:
	58	Either 'r' to corrupt reads or 'w' to corrupt writes.
	59	'w' is incompatible with drop_writes.
	60	<value>:
	61	The value (from 0-255) to write.
	62	<flags>:
	63	Perform the replacement only if bio->bi_opf has all the
	64	selected flags set.
a3998799 MS	65
a3998799 MS	66	Examples:
f0ba4377 MCC	67
	68	Replaces the 32nd byte of READ bios with the value 1::
	69
a3998799	70	corrupt_bio_byte 32 r 1 0
f0ba4377 MCC	71
f0ba4377 MCC	72	Replaces the 224th byte of REQ_META (=32) bios with the value 0::
a3998799 MS	73
a3998799 MS	74	corrupt_bio_byte 224 w 0 32