FBDCTL(8)FBDCTL(8)NAMEfbdctl - Faulty Block Device rule management interface
SYNOPSISfbdctl add [-d device] [-a start[-end]] [-s skip] [-c count] [-rw]
action [params]
fbdctl del [-d device] rulenum
fbdctl list [-d device]
DESCRIPTION
The Faulty Block Device (FBD) driver is an interposing block device
driver which can simulate certain disk-level I/O corruption and errors,
based on a user-provided set of rules. The fbdctl tool allows one to
add, delete, and list rules on a running FBD driver instance.
The add subcommand adds a new rule, which will perform a predefined
faulty action on a disk transfer when triggered. See the ACTIONS sub‐
section below. The del subcommands deletes an existing rule, based on
its rule number. All currently active rules and their corresponding
rule numbers can be viewed with the list subcommand.
OPTIONS-d device By default, fbdctl operates on /dev/fbd. With this option,
one can specify a different device node. This is useful when
using multiple FBD instances at the same time. The user would
have to create extra device nodes first in that case.
-a [start[-end]]
When adding a rule, this option specifies the disk address
range for which the rule triggers. That is, the rule will
trigger when an I/O operation overlaps with the given range.
Both start and end are expected to be hexadecimal numbers,
without a "0x" prefix. The end address is exclusive. If no
end address is given, the rule will affect the disk from the
starting address to the disk end. If this option is not pro‐
vided at all, the rule will affect the entire disk.
-s skip This option makes the new rule refrain from triggering for
the given number of times it matches. The skip value must be
a positive decimal number. If this option is omitted, the
value is set to zero, meaning the rule will start triggering
immediately.
-c count This option makes the new rule trigger for this many I/O
operations when matched, after which it will be removed auto‐
matically. The count value must be a positive decimal number.
If this option is omitted, or a value of zero is given, the
rule is permanent and will not be removed automatically.
-r, -w These options allow one to make the new rule trigger on read
or write operations only. By default, or when both are speci‐
fied, the new rule will trigger for both read and write I/O
operations.
ACTIONS
The following actions are supported. They are executed when the rule
matches for a transfer request, and is triggered as a result. Note that
the exact meaning of the rule's disk address range (as given by the -a
option) depends on the action type.
corrupt [zero|persist|random]
In the part of the transfer that matches the disk address
range given for the rule (i.e., the intersection of the rule
range and the transfer range), the data will be corrupted.
The following corruption policies are supported: the data is
set to zero, it is persistently set to the same garbage data
for the same disk locations, or it is set to different random
data in every transfer.
error [OK|EIO]
Only the part of the transfer up to the start of the rule's
disk address range will be performed, after which the given
error code is returned. The OK code effectively simulates an
end-of-disk condition, whereas the EIO code simulates generic
disk-level I/O failure.
misdir start-end align
Transfer requests that match this rule, will be misdirected
in their entirety, to a random location in the given address
range, and with the given disk byte alignment within that
range. The start and end parameters are specified just like
the -a option, although the end parameter is compulsory here
(since the driver does not know the disk end). The align
value must be a positive nonzero decimal number, and should
be a multiple of the medium sector size; a typical value
would be 4096.
lost Transfer requests that match this rule, will be lost in their
entirety. That is, they will not actually be performed, and
yet report successful completion.
torn lead Transfer requests that match this rule, will be torn: only
the first lead bytes of the transfer request will actually be
performed, and yet completion of the full transfer is
reported. The lead value must be a positive nonzero decimal
number. A torn action with a lead value of zero would be the
same as the lost action.
EXAMPLESfbdctl add -a 2000-3000 corrupt zero
# Zero out the 4096 bytes starting from disk address 0x2000
in any transfer that involves any of those bytes.
fbdctl add -s 9 -c 1 -r error EIO
# Fail the tenth read request with an I/O error.
fbdctl add -a A0000-B0000 -w misdir D0000-E0000 4096
# Misdirect write requests that overlap with the first range,
to fall somewhere in the second range, at 4K-block-granular
alignment.
AUTHOR
David van Moolenbroek <david@minix3.org>
FBDCTL(8)
