.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" See file COPYING in distribution for details.
+.if n .pl 1000v
.TH MD 4
.SH NAME
md \- Multiple Device driver aka Linux Software RAID
and FAULTY (a layer over a single device into which errors can be injected).
.SS MD METADATA
-Each device in an array may have some
+Each device in an array may have some
.I metadata
stored in the device. This metadata is sometimes called a
.BR superblock .
A RAID0 array (which has zero redundancy) is also known as a
striped array.
A RAID0 array is configured at creation with a
-.B "Chunk Size"
+.B "Chunk Size"
which must be a power of two (prior to Linux 2.6.31), and at least 4
kibibytes.
| - | - | - | - | - | - |
C.
;
-;Device #1;Device #2;Device #3;Device #4;Device #5
+;Dev #1;Dev #2;Dev #3;Dev #4;Dev #5
0x00;0;0;1;1;2
0x01;2;3;3;4;4
\.\.\.;\.\.\.;\.\.\.;\.\.\.;\.\.\.;\.\.\.
| - | - | - | - | - | - |
C.
;
-;Device #1;Device #2;Device #3;Device #4;Device #5
+;Dev #1;Dev #2;Dev #3;Dev #4;Dev #5
;
0x00;0;1;2;3;4;\\
0x01;5;6;7;8;9;> [#]
| - | - | - | - | - | - |
C.
;
-;Device #1;Device #2;Device #3;Device #4;Device #5
+;Dev #1;Dev #2;Dev #3;Dev #4;Dev #5
;
0x00;0;1;2;3;4;) AA
0x01;4;0;1;2;3;) AA~
In 2.6.13, intent bitmaps are only supported with RAID1. Other levels
with redundancy are supported from 2.6.15.
-.SS BAD BLOCK LOG
+.SS BAD BLOCK LIST
From Linux 3.5 each device in an
.I md
When a block cannot be read and cannot be repaired by writing data
recovered from other devices, the address of the block is stored in
-the bad block log. Similarly if an attempt to write a block fails,
+the bad block list. Similarly if an attempt to write a block fails,
the address will be recorded as a bad block. If attempting to record
the bad block fails, the whole device will be marked faulty.
different devices can be faulty without taking the whole array out of
action.
-The log is particularly useful when recovering to a spare. If a few blocks
+The list is particularly useful when recovering to a spare. If a few blocks
cannot be read from the other devices, the bulk of the recovery can
-complete and those few bad blocks will be recorded in the bad block log.
+complete and those few bad blocks will be recorded in the bad block list.
+
+.SS RAID456 WRITE JOURNAL
+
+Due to non-atomicity nature of RAID write operations, interruption of
+write operations (system crash, etc.) to RAID456 array can lead to
+inconsistent parity and data loss (so called RAID-5 write hole).
+
+To plug the write hole, from Linux 4.4 (to be confirmed),
+.I md
+supports write ahead journal for RAID456. When the array is created,
+an additional journal device can be added to the array through
+.IR write-journal
+option. The RAID write journal works similar to file system journals.
+Before writing to the data disks, md persists data AND parity of the
+stripe to the journal device. After crashes, md searches the journal
+device for incomplete write operations, and replay them to the data
+disks.
+
+When the journal device fails, the RAID array is forced to run in
+read-only mode.
.SS WRITE-BEHIND
operations, but the remote system will still have a reasonably
up-to-date copy of all data.
+.SS FAILFAST
+
+From Linux 4.10,
+.I
+md
+supports FAILFAST for RAID1 and RAID10 arrays. This is a flag that
+can be set on individual drives, though it is usually set on all
+drives, or no drives.
+
+When
+.I md
+sends an I/O request to a drive that is marked as FAILFAST, and when
+the array could survive the loss of that drive without losing data,
+.I md
+will request that the underlying device does not perform any retries.
+This means that a failure will be reported to
+.I md
+promptly, and it can mark the device as faulty and continue using the
+other device(s).
+.I md
+cannot control the timeout that the underlying devices use to
+determine failure. Any changes desired to that timeout must be set
+explictly on the underlying device, separately from using
+.IR mdadm .
+
+If a FAILFAST request does fail, and if it is still safe to mark the
+device as faulty without data loss, that will be done and the array
+will continue functioning on a reduced number of devices. If it is not
+possible to safely mark the device as faulty,
+.I md
+will retry the request without disabling retries in the underlying
+device. In any case,
+.I md
+will not attempt to repair read errors on a device marked as FAILFAST
+by writing out the correct. It will just mark the device as faulty.
+
+FAILFAST is appropriate for storage arrays that have a low probability
+of true failure, but will sometimes introduce unacceptable delays to
+I/O requests while performing internal maintenance. The value of
+setting FAILFAST involves a trade-off. The gain is that the chance of
+unacceptable delays is substantially reduced. The cost is that the
+unlikely event of data-loss on one device is slightly more likely to
+result in data-loss for the array.
+
+When a device in an array using FAILFAST is marked as faulty, it will
+usually become usable again in a short while.
+.I mdadm
+makes no attempt to detect that possibility. Some separate
+mechanism, tuned to the specific details of the expected failure modes,
+needs to be created to monitor devices to see when they return to full
+functionality, and to then re-add them to the array. In order of
+this "re-add" functionality to be effective, an array using FAILFAST
+should always have a write-intent bitmap.
+
.SS RESTRIPING
.IR Restriping ,
stripe that requires some "prereading". For fairness this defaults to
1. Valid values are 0 to stripe_cache_size. Setting this to 0
maximizes sequential-write throughput at the cost of fairness to threads
-doing small or random writes.
+doing small or random writes.
.SS KERNEL PARAMETERS