FBDCTL(8)

NAME
fbdctl - Faulty Block Device rule management interface

SYNOPSIS
fbdctl 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 subsection 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 provided 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 automatically. 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 specified, 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.

EXAMPLES

fbdctl 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>