+++ /dev/null
-=======
-dm-raid
-=======
-
-The device-mapper RAID (dm-raid) target provides a bridge from DM to MD.
-It allows the MD RAID drivers to be accessed using a device-mapper
-interface.
-
-
-Mapping Table Interface
------------------------
-The target is named "raid" and it accepts the following parameters::
-
- <raid_type> <#raid_params> <raid_params> \
- <#raid_devs> <metadata_dev0> <dev0> [.. <metadata_devN> <devN>]
-
-<raid_type>:
-
- ============= ===============================================================
- raid0 RAID0 striping (no resilience)
- raid1 RAID1 mirroring
- raid4 RAID4 with dedicated last parity disk
- raid5_n RAID5 with dedicated last parity disk supporting takeover
- Same as raid4
-
- - Transitory layout
- raid5_la RAID5 left asymmetric
-
- - rotating parity 0 with data continuation
- raid5_ra RAID5 right asymmetric
-
- - rotating parity N with data continuation
- raid5_ls RAID5 left symmetric
-
- - rotating parity 0 with data restart
- raid5_rs RAID5 right symmetric
-
- - rotating parity N with data restart
- raid6_zr RAID6 zero restart
-
- - rotating parity zero (left-to-right) with data restart
- raid6_nr RAID6 N restart
-
- - rotating parity N (right-to-left) with data restart
- raid6_nc RAID6 N continue
-
- - rotating parity N (right-to-left) with data continuation
- raid6_n_6 RAID6 with dedicate parity disks
-
- - parity and Q-syndrome on the last 2 disks;
- layout for takeover from/to raid4/raid5_n
- raid6_la_6 Same as "raid_la" plus dedicated last Q-syndrome disk
-
- - layout for takeover from raid5_la from/to raid6
- raid6_ra_6 Same as "raid5_ra" dedicated last Q-syndrome disk
-
- - layout for takeover from raid5_ra from/to raid6
- raid6_ls_6 Same as "raid5_ls" dedicated last Q-syndrome disk
-
- - layout for takeover from raid5_ls from/to raid6
- raid6_rs_6 Same as "raid5_rs" dedicated last Q-syndrome disk
-
- - layout for takeover from raid5_rs from/to raid6
- raid10 Various RAID10 inspired algorithms chosen by additional params
- (see raid10_format and raid10_copies below)
-
- - RAID10: Striped Mirrors (aka 'Striping on top of mirrors')
- - RAID1E: Integrated Adjacent Stripe Mirroring
- - RAID1E: Integrated Offset Stripe Mirroring
- - and other similar RAID10 variants
- ============= ===============================================================
-
- Reference: Chapter 4 of
- http://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf
-
-<#raid_params>: The number of parameters that follow.
-
-<raid_params> consists of
-
- Mandatory parameters:
- <chunk_size>:
- Chunk size in sectors. This parameter is often known as
- "stripe size". It is the only mandatory parameter and
- is placed first.
-
- followed by optional parameters (in any order):
- [sync|nosync]
- Force or prevent RAID initialization.
-
- [rebuild <idx>]
- Rebuild drive number 'idx' (first drive is 0).
-
- [daemon_sleep <ms>]
- Interval between runs of the bitmap daemon that
- clear bits. A longer interval means less bitmap I/O but
- resyncing after a failure is likely to take longer.
-
- [min_recovery_rate <kB/sec/disk>]
- Throttle RAID initialization
- [max_recovery_rate <kB/sec/disk>]
- Throttle RAID initialization
- [write_mostly <idx>]
- Mark drive index 'idx' write-mostly.
- [max_write_behind <sectors>]
- See '--write-behind=' (man mdadm)
- [stripe_cache <sectors>]
- Stripe cache size (RAID 4/5/6 only)
- [region_size <sectors>]
- The region_size multiplied by the number of regions is the
- logical size of the array. The bitmap records the device
- synchronisation state for each region.
-
- [raid10_copies <# copies>], [raid10_format <near|far|offset>]
- These two options are used to alter the default layout of
- a RAID10 configuration. The number of copies is can be
- specified, but the default is 2. There are also three
- variations to how the copies are laid down - the default
- is "near". Near copies are what most people think of with
- respect to mirroring. If these options are left unspecified,
- or 'raid10_copies 2' and/or 'raid10_format near' are given,
- then the layouts for 2, 3 and 4 devices are:
-
- ======== ========== ==============
- 2 drives 3 drives 4 drives
- ======== ========== ==============
- A1 A1 A1 A1 A2 A1 A1 A2 A2
- A2 A2 A2 A3 A3 A3 A3 A4 A4
- A3 A3 A4 A4 A5 A5 A5 A6 A6
- A4 A4 A5 A6 A6 A7 A7 A8 A8
- .. .. .. .. .. .. .. .. ..
- ======== ========== ==============
-
- The 2-device layout is equivalent 2-way RAID1. The 4-device
- layout is what a traditional RAID10 would look like. The
- 3-device layout is what might be called a 'RAID1E - Integrated
- Adjacent Stripe Mirroring'.
-
- If 'raid10_copies 2' and 'raid10_format far', then the layouts
- for 2, 3 and 4 devices are:
-
- ======== ============ ===================
- 2 drives 3 drives 4 drives
- ======== ============ ===================
- A1 A2 A1 A2 A3 A1 A2 A3 A4
- A3 A4 A4 A5 A6 A5 A6 A7 A8
- A5 A6 A7 A8 A9 A9 A10 A11 A12
- .. .. .. .. .. .. .. .. ..
- A2 A1 A3 A1 A2 A2 A1 A4 A3
- A4 A3 A6 A4 A5 A6 A5 A8 A7
- A6 A5 A9 A7 A8 A10 A9 A12 A11
- .. .. .. .. .. .. .. .. ..
- ======== ============ ===================
-
- If 'raid10_copies 2' and 'raid10_format offset', then the
- layouts for 2, 3 and 4 devices are:
-
- ======== ========== ================
- 2 drives 3 drives 4 drives
- ======== ========== ================
- A1 A2 A1 A2 A3 A1 A2 A3 A4
- A2 A1 A3 A1 A2 A2 A1 A4 A3
- A3 A4 A4 A5 A6 A5 A6 A7 A8
- A4 A3 A6 A4 A5 A6 A5 A8 A7
- A5 A6 A7 A8 A9 A9 A10 A11 A12
- A6 A5 A9 A7 A8 A10 A9 A12 A11
- .. .. .. .. .. .. .. .. ..
- ======== ========== ================
-
- Here we see layouts closely akin to 'RAID1E - Integrated
- Offset Stripe Mirroring'.
-
- [delta_disks <N>]
- The delta_disks option value (-251 < N < +251) triggers
- device removal (negative value) or device addition (positive
- value) to any reshape supporting raid levels 4/5/6 and 10.
- RAID levels 4/5/6 allow for addition of devices (metadata
- and data device tuple), raid10_near and raid10_offset only
- allow for device addition. raid10_far does not support any
- reshaping at all.
- A minimum of devices have to be kept to enforce resilience,
- which is 3 devices for raid4/5 and 4 devices for raid6.
-
- [data_offset <sectors>]
- This option value defines the offset into each data device
- where the data starts. This is used to provide out-of-place
- reshaping space to avoid writing over data while
- changing the layout of stripes, hence an interruption/crash
- may happen at any time without the risk of losing data.
- E.g. when adding devices to an existing raid set during
- forward reshaping, the out-of-place space will be allocated
- at the beginning of each raid device. The kernel raid4/5/6/10
- MD personalities supporting such device addition will read the data from
- the existing first stripes (those with smaller number of stripes)
- starting at data_offset to fill up a new stripe with the larger
- number of stripes, calculate the redundancy blocks (CRC/Q-syndrome)
- and write that new stripe to offset 0. Same will be applied to all
- N-1 other new stripes. This out-of-place scheme is used to change
- the RAID type (i.e. the allocation algorithm) as well, e.g.
- changing from raid5_ls to raid5_n.
-
- [journal_dev <dev>]
- This option adds a journal device to raid4/5/6 raid sets and
- uses it to close the 'write hole' caused by the non-atomic updates
- to the component devices which can cause data loss during recovery.
- The journal device is used as writethrough thus causing writes to
- be throttled versus non-journaled raid4/5/6 sets.
- Takeover/reshape is not possible with a raid4/5/6 journal device;
- it has to be deconfigured before requesting these.
-
- [journal_mode <mode>]
- This option sets the caching mode on journaled raid4/5/6 raid sets
- (see 'journal_dev <dev>' above) to 'writethrough' or 'writeback'.
- If 'writeback' is selected the journal device has to be resilient
- and must not suffer from the 'write hole' problem itself (e.g. use
- raid1 or raid10) to avoid a single point of failure.
-
-<#raid_devs>: The number of devices composing the array.
- Each device consists of two entries. The first is the device
- containing the metadata (if any); the second is the one containing the
- data. A Maximum of 64 metadata/data device entries are supported
- up to target version 1.8.0.
- 1.9.0 supports up to 253 which is enforced by the used MD kernel runtime.
-
- If a drive has failed or is missing at creation time, a '-' can be
- given for both the metadata and data drives for a given position.
-
-
-Example Tables
---------------
-
-::
-
- # RAID4 - 4 data drives, 1 parity (no metadata devices)
- # No metadata devices specified to hold superblock/bitmap info
- # Chunk size of 1MiB
- # (Lines separated for easy reading)
-
- 0 1960893648 raid \
- raid4 1 2048 \
- 5 - 8:17 - 8:33 - 8:49 - 8:65 - 8:81
-
- # RAID4 - 4 data drives, 1 parity (with metadata devices)
- # Chunk size of 1MiB, force RAID initialization,
- # min recovery rate at 20 kiB/sec/disk
-
- 0 1960893648 raid \
- raid4 4 2048 sync min_recovery_rate 20 \
- 5 8:17 8:18 8:33 8:34 8:49 8:50 8:65 8:66 8:81 8:82
-
-
-Status Output
--------------
-'dmsetup table' displays the table used to construct the mapping.
-The optional parameters are always printed in the order listed
-above with "sync" or "nosync" always output ahead of the other
-arguments, regardless of the order used when originally loading the table.
-Arguments that can be repeated are ordered by value.
-
-
-'dmsetup status' yields information on the state and health of the array.
-The output is as follows (normally a single line, but expanded here for
-clarity)::
-
- 1: <s> <l> raid \
- 2: <raid_type> <#devices> <health_chars> \
- 3: <sync_ratio> <sync_action> <mismatch_cnt>
-
-Line 1 is the standard output produced by device-mapper.
-
-Line 2 & 3 are produced by the raid target and are best explained by example::
-
- 0 1960893648 raid raid4 5 AAAAA 2/490221568 init 0
-
-Here we can see the RAID type is raid4, there are 5 devices - all of
-which are 'A'live, and the array is 2/490221568 complete with its initial
-recovery. Here is a fuller description of the individual fields:
-
- =============== =========================================================
- <raid_type> Same as the <raid_type> used to create the array.
- <health_chars> One char for each device, indicating:
-
- - 'A' = alive and in-sync
- - 'a' = alive but not in-sync
- - 'D' = dead/failed.
- <sync_ratio> The ratio indicating how much of the array has undergone
- the process described by 'sync_action'. If the
- 'sync_action' is "check" or "repair", then the process
- of "resync" or "recover" can be considered complete.
- <sync_action> One of the following possible states:
-
- idle
- - No synchronization action is being performed.
- frozen
- - The current action has been halted.
- resync
- - Array is undergoing its initial synchronization
- or is resynchronizing after an unclean shutdown
- (possibly aided by a bitmap).
- recover
- - A device in the array is being rebuilt or
- replaced.
- check
- - A user-initiated full check of the array is
- being performed. All blocks are read and
- checked for consistency. The number of
- discrepancies found are recorded in
- <mismatch_cnt>. No changes are made to the
- array by this action.
- repair
- - The same as "check", but discrepancies are
- corrected.
- reshape
- - The array is undergoing a reshape.
- <mismatch_cnt> The number of discrepancies found between mirror copies
- in RAID1/10 or wrong parity values found in RAID4/5/6.
- This value is valid only after a "check" of the array
- is performed. A healthy array has a 'mismatch_cnt' of 0.
- <data_offset> The current data offset to the start of the user data on
- each component device of a raid set (see the respective
- raid parameter to support out-of-place reshaping).
- <journal_char> - 'A' - active write-through journal device.
- - 'a' - active write-back journal device.
- - 'D' - dead journal device.
- - '-' - no journal device.
- =============== =========================================================
-
-
-Message Interface
------------------
-The dm-raid target will accept certain actions through the 'message' interface.
-('man dmsetup' for more information on the message interface.) These actions
-include:
-
- ========= ================================================
- "idle" Halt the current sync action.
- "frozen" Freeze the current sync action.
- "resync" Initiate/continue a resync.
- "recover" Initiate/continue a recover process.
- "check" Initiate a check (i.e. a "scrub") of the array.
- "repair" Initiate a repair of the array.
- ========= ================================================
-
-
-Discard Support
----------------
-The implementation of discard support among hardware vendors varies.
-When a block is discarded, some storage devices will return zeroes when
-the block is read. These devices set the 'discard_zeroes_data'
-attribute. Other devices will return random data. Confusingly, some
-devices that advertise 'discard_zeroes_data' will not reliably return
-zeroes when discarded blocks are read! Since RAID 4/5/6 uses blocks
-from a number of devices to calculate parity blocks and (for performance
-reasons) relies on 'discard_zeroes_data' being reliable, it is important
-that the devices be consistent. Blocks may be discarded in the middle
-of a RAID 4/5/6 stripe and if subsequent read results are not
-consistent, the parity blocks may be calculated differently at any time;
-making the parity blocks useless for redundancy. It is important to
-understand how your hardware behaves with discards if you are going to
-enable discards with RAID 4/5/6.
-
-Since the behavior of storage devices is unreliable in this respect,
-even when reporting 'discard_zeroes_data', by default RAID 4/5/6
-discard support is disabled -- this ensures data integrity at the
-expense of losing some performance.
-
-Storage devices that properly support 'discard_zeroes_data' are
-increasingly whitelisted in the kernel and can thus be trusted.
-
-For trusted devices, the following dm-raid module parameter can be set
-to safely enable discard support for RAID 4/5/6:
-
- 'devices_handle_discards_safely'
-
-
-Version History
----------------
-
-::
-
- 1.0.0 Initial version. Support for RAID 4/5/6
- 1.1.0 Added support for RAID 1
- 1.2.0 Handle creation of arrays that contain failed devices.
- 1.3.0 Added support for RAID 10
- 1.3.1 Allow device replacement/rebuild for RAID 10
- 1.3.2 Fix/improve redundancy checking for RAID10
- 1.4.0 Non-functional change. Removes arg from mapping function.
- 1.4.1 RAID10 fix redundancy validation checks (commit 55ebbb5).
- 1.4.2 Add RAID10 "far" and "offset" algorithm support.
- 1.5.0 Add message interface to allow manipulation of the sync_action.
- New status (STATUSTYPE_INFO) fields: sync_action and mismatch_cnt.
- 1.5.1 Add ability to restore transiently failed devices on resume.
- 1.5.2 'mismatch_cnt' is zero unless [last_]sync_action is "check".
- 1.6.0 Add discard support (and devices_handle_discard_safely module param).
- 1.7.0 Add support for MD RAID0 mappings.
- 1.8.0 Explicitly check for compatible flags in the superblock metadata
- and reject to start the raid set if any are set by a newer
- target version, thus avoiding data corruption on a raid set
- with a reshape in progress.
- 1.9.0 Add support for RAID level takeover/reshape/region size
- and set size reduction.
- 1.9.1 Fix activation of existing RAID 4/10 mapped devices
- 1.9.2 Don't emit '- -' on the status table line in case the constructor
- fails reading a superblock. Correctly emit 'maj:min1 maj:min2' and
- 'D' on the status line. If '- -' is passed into the constructor, emit
- '- -' on the table line and '-' as the status line health character.
- 1.10.0 Add support for raid4/5/6 journal device
- 1.10.1 Fix data corruption on reshape request
- 1.11.0 Fix table line argument order
- (wrong raid10_copies/raid10_format sequence)
- 1.11.1 Add raid4/5/6 journal write-back support via journal_mode option
- 1.12.1 Fix for MD deadlock between mddev_suspend() and md_write_start() available
- 1.13.0 Fix dev_health status at end of "recover" (was 'a', now 'A')
- 1.13.1 Fix deadlock caused by early md_stop_writes(). Also fix size an
- state races.
- 1.13.2 Fix raid redundancy validation and avoid keeping raid set frozen
- 1.14.0 Fix reshape race on small devices. Fix stripe adding reshape
- deadlock/potential data corruption. Update superblock when
- specific devices are requested via rebuild. Fix RAID leg
- rebuild errors.
projects / linux-2.6-microblaze.git / blobdiff