man/man8/fbdctl.8

   1 .TH FBDCTL 8
   2 .SH NAME
   3 fbdctl \- Faulty Block Device rule management interface
   4 .SH SYNOPSIS
   5 \fBfbdctl\fR \fBadd\fR [\fB-d\fR \fIdevice\fR]
   6 [\fB-a\fR \fIstart\fR[\fB-\fR\fIend\fR]] [\fB-s\fR \fIskip\fR]
   7 [\fB-c\fR \fIcount\fR] [\fB-rw\fR] \fIaction\fR [\fIparams\fR]
   8 .PP
   9 \fBfbdctl\fR \fBdel\fR [\fB-d\fR \fIdevice\fR] \fIrulenum\fR
  10 .PP
  11 \fBfbdctl\fR \fBlist\fR [\fB-d\fR \fIdevice\fR]
  12 .SH DESCRIPTION
  13 The Faulty Block Device (FBD) driver is an interposing block device driver
  14 which can simulate certain disk-level I/O corruption and errors, based on a
  15 user-provided set of rules. The \fBfbdctl\fR tool allows one to add, delete,
  16 and list rules on a running FBD driver instance.
  17 .PP
  18 The \fBadd\fR subcommand adds a new rule, which will perform a predefined
  19 faulty action on a disk transfer when triggered. See the ACTIONS subsection
  20 below. The \fBdel\fR subcommands deletes an existing rule, based on its rule
  21 number. All currently active rules and their corresponding rule numbers can be
  22 viewed with the \fBlist\fR subcommand.
  23 .SH OPTIONS
  24 .TP 10
  25 \fB-d\fR \fIdevice\fR
  26 By default, \fBfbdctl\fR operates on \fB/dev/fbd\fR. With this option, one can
  27 specify a different device node. This is useful when using multiple FBD
  28 instances at the same time. The user would have to create extra device nodes
  29 first in that case.
  30 .TP 10
  31 \fB-a\fR [\fIstart\fR[\fB-\fR\fIend\fR]]
  32 When adding a rule, this option specifies the disk address range for which the
  33 rule triggers. That is, the rule will trigger when an I/O operation overlaps
  34 with the given range. Both \fIstart\fR and \fIend\fR are expected to be
  35 hexadecimal numbers, without a "0x" prefix. The \fIend\fR address is exclusive.
  36 If no \fIend\fR address is given, the rule will affect the disk from the
  37 starting address to the disk end. If this option is not provided at all,
  38 the rule will affect the entire disk.
  39 .TP 10
  40 \fB-s\fR \fIskip\fR
  41 This option makes the new rule refrain from triggering for the given number
  42 of times it matches. The \fIskip\fR value must be a positive decimal number.
  43 If this option is omitted, the value is set to zero, meaning the rule will
  44 start triggering immediately.
  45 .TP 10
  46 \fB-c\fR \fIcount\fR
  47 This option makes the new rule trigger for this many I/O operations when
  48 matched, after which it will be removed automatically. The \fIcount\fR value
  49 must be a positive decimal number. If this option is omitted, or a value of
  50 zero is given, the rule is permanent and will not be removed automatically.
  51 .TP 10
  52 \fB-r\fR, \fB-w\fR
  53 These options allow one to make the new rule trigger on read or write
  54 operations only. By default, or when both are specified, the new rule will
  55 trigger for both read and write I/O operations.
  56 .SH ACTIONS
  57 The following actions are supported. They are executed when the rule matches
  58 for a transfer request, and is triggered as a result. Note that the exact
  59 meaning of the rule's disk address range (as given by the \fB-a\fR option)
  60 depends on the action type.
  61 .TP 10
  62 \fBcorrupt\fR [\fBzero\fR|\fBpersist\fR|\fBrandom\fR]
  63 In the part of the transfer that matches the disk address range given for the
  64 rule (i.e., the intersection of the rule range and the transfer range), the
  65 data will be corrupted. The following corruption policies are supported: the
  66 data is set to \fBzero\fR, it is \fBpersist\fRently set to the same garbage
  67 data for the same disk locations, or it is set to different \fBrandom\fR data
  68 in every transfer.
  69 .TP 10
  70 \fBerror\fR [\fBOK\fR|\fBEIO\fR]
  71 Only the part of the transfer up to the start of the rule's disk address range
  72 will be performed, after which the given error code is returned. The \fBOK\fR
  73 code effectively simulates an end-of-disk condition, whereas the \fBEIO\fR code
  74 simulates generic disk-level I/O failure.
  75 .TP 10
  76 \fBmisdir\fR \fIstart\fR\fB-\fR\fIend\fR \fIalign\fR
  77 Transfer requests that match this rule, will be \fBmisdirected\fR in their
  78 entirety, to a random location in the given address range, and with the given
  79 disk byte alignment within that range. The \fIstart\fR and \fIend\fR parameters
  80 are specified just like the \fB-a\fR option, although the \fIend\fR parameter
  81 is compulsory here (since the driver does not know the disk end). The
  82 \fIalign\fR value must be a positive nonzero decimal number, and should be a
  83 multiple of the medium sector size; a typical value would be 4096.
  84 .TP 10
  85 \fBlost\fR
  86 Transfer requests that match this rule, will be \fBlost\fR in their entirety.
  87 That is, they will not actually be performed, and yet report successful
  88 completion.
  89 .TP 10
  90 \fBtorn\fR \fIlead\fR
  91 Transfer requests that match this rule, will be \fBtorn\fR: only the first
  92 \fIlead\fR bytes of the transfer request will actually be performed, and yet
  93 completion of the full transfer is reported. The \fIlead\fR value must be a
  94 positive nonzero decimal number. A \fBtorn\fR action with a \fIlead\fR value of
  95 zero would be the same as the \fBlost\fR action.
  96 .SH EXAMPLES
  97 .TP 10
  98 .B fbdctl add -a 2000-3000 corrupt zero
  99 # Zero out the 4096 bytes starting from disk address 0x2000 in any transfer
 100 that involves any of those bytes.
 101 .TP 10
 102 .B fbdctl add -s 9 -c 1 -r error EIO
 103 # Fail the tenth read request with an I/O error.
 104 .TP 10
 105 .B fbdctl add -a A0000-B0000 -w misdir D0000-E0000 4096
 106 # Misdirect write requests that overlap with the first range, to fall somewhere
 107 in the second range, at 4K-block-granular alignment.
 108 .SH AUTHOR
 109 David van Moolenbroek <david@minix3.org>