vm: restore stacktrace on SIGSEGV
[minix.git] / man / man8 / fbdctl.8
blobab37458e76912aad9e0237d2e5f8689b949c872a
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>