The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| List active MD arrays | cat /proc/mdstat | View examples |
| Inspect array geometry | sudo mdadm --detail /dev/md/data | View examples |
| Inventory stable identities | lsblk -o \
NAME,PATH,SIZE,MODEL,SERIAL,TYPE,FSTYPE,MOUNTPOINTS | View examples |
| Examine one MD superblock | sudo mdadm --examine /dev/disk/by-id/ATA_MEMBER_A-part1 | View examples |
| Group discovered metadata | sudo mdadm --examine --scan | View examples |
| Create a named RAID1 | sudo mdadm --create /dev/md/data -l1 -n2 -e1.2 -N data \
-b internal /dev/disk/by-id/A-part1 \
/dev/disk/by-id/B-part1 | View examples |
| Create near-layout RAID10 | sudo mdadm --create /dev/md/data -l10 -p n2 -n4 \
/dev/disk/by-id/A-part1 /dev/disk/by-id/B-part1 \
/dev/disk/by-id/C-part1 /dev/disk/by-id/D-part1 | View examples |
| Assemble configured arrays | sudo mdadm --assemble --scan | View examples |
| Assemble explicit members read-only | sudo mdadm --assemble --readonly /dev/md/data \
/dev/disk/by-id/A-part1 /dev/disk/by-id/B-part1 | View examples |
| Stop an unused array | sudo mdadm --stop /dev/md/data | View examples |
| Mark a member faulty | sudo mdadm /dev/md/data --fail \
/dev/disk/by-id/ATA_FAILED-part1 | View examples |
| Detach a failed member | sudo mdadm /dev/md/data --remove \
/dev/disk/by-id/ATA_FAILED-part1 | View examples |
| Add a replacement member | sudo mdadm /dev/md/data --add \
/dev/disk/by-id/ATA_REPLACEMENT-part1 | View examples |
| Replace while the old disk reads | sudo mdadm /dev/md/data --replace \
/dev/disk/by-id/OLD-part1 --with \
/dev/disk/by-id/SPARE-part1 | View examples |
| Watch rebuild progress | watch -n 5 cat /proc/mdstat | View examples |
| Read current sync action | cat /sys/block/md0/md/sync_action | View examples |
| Read precise sync progress | cat /sys/block/md0/md/sync_completed | View examples |
| Inspect per-array speed limits | cat /sys/block/md0/md/sync_speed_min \
/sys/block/md0/md/sync_speed_max | View examples |
| Run one monitoring pass | sudo mdadm --monitor --scan --oneshot | View examples |
| Add an internal bitmap | sudo mdadm --grow /dev/md/data --bitmap=internal | View examples |
| Remove a write-intent bitmap | sudo mdadm --grow /dev/md/data --bitmap=none | View examples |
| Start a consistency check | echo check | sudo tee /sys/block/md0/md/sync_action | View examples |
| Read mismatch count | cat /sys/block/md0/md/mismatch_cnt | View examples |
| Request consistency repair | echo repair | sudo tee /sys/block/md0/md/sync_action | View examples |
| Grow a parity array | sudo mdadm --grow /dev/md/data -n4 \
--backup-file=/mnt/rescue/md-data.reshape | View examples |
| Reassemble with reshape backup | sudo mdadm --assemble --scan \
--backup-file=/mnt/rescue/md-data.reshape | View examples |
| Print array configuration | sudo mdadm --detail --scan | View examples |
| Update Debian-family initramfs | sudo update-initramfs -u | View examples |
| Update dracut initramfs | sudo dracut --force | View examples |
| Read physical-disk SMART data | sudo smartctl -x /dev/disk/by-id/ATA_MEMBER_A | View examples |
Linux MD combines block devices into software RAID arrays, while mdadm writes and interprets their metadata and manages lifecycle operations. RAID can improve availability or throughput, but it does not preserve deleted files, prevent silent corruption, or replace independent tested backups. Before any mutating command, identify every member by stable hardware path, capture current metadata and topology, unmount or quiesce dependent storage where required, verify a restorable backup, and prepare a recovery path. Never infer member order, array geometry, or the correct source of parity from device letters alone.
Step by step
Detailed examples
Choose failure behavior before choosing capacity
RAID0 stripes data and has no redundancy: any member loss can destroy the array. RAID1 stores a full copy on every member, yields the capacity of the smallest member, and can survive all but one member when the remaining copy is sound. RAID5 needs at least three members, yields roughly N minus one members of capacity, and survives one loss; RAID6 needs at least four, yields roughly N minus two, and survives two. Both parity levels impose small-write work and expose every surviving device to heavy reads during recovery. RAID10 distributes replicated blocks, usually yields half of raw capacity with two copies, and has failure tolerance that depends on copy layout and which devices fail. Near, far, and offset RAID10 layouts trade sequential-read behavior against seek and write costs. Chunk size, filesystem geometry, queueing, controllers, workload, and failure domains all matter, so benchmark a representative disposable stack and document the exact level, layout, chunk size, member order, metadata, and kernel compatibility.
cat /proc/mdstat
sudo mdadm --detail /dev/md/data
lsblk -o NAME,PATH,SIZE,MODEL,SERIAL,TYPE,FSTYPE,MOUNTPOINTS /dev/md/dataNote: These commands are read-only. Do not assume RAID10 can survive any two failures; use the reported layout and member roles to determine whether copies overlap.
Identify components from metadata and stable hardware paths
Kernel names such as /dev/sda can change after a reboot or controller event. Correlate /dev/disk/by-id links, serial numbers, physical bays, sizes, partition tables, filesystem signatures, mounts, swap, LVM, and MD superblocks before touching a member. mdadm --examine reads component metadata without assembling it; compare array UUID, metadata version, level, device role, event count, state, and update time across every available member. A member with a lower event count may be stale. Conflicting filesystems or superblocks are a stop condition, not permission to use --force or --zero-superblock. Save command output and, for a high-risk recovery, image questionable drives before allowing writes.
ls -l /dev/disk/by-id/ATA_MEMBER_A /dev/disk/by-id/ATA_MEMBER_A-part1
lsblk -o NAME,PATH,SIZE,MODEL,SERIAL,TYPE,FSTYPE,MOUNTPOINTS /dev/disk/by-id/ATA_MEMBER_A
sudo mdadm --examine /dev/disk/by-id/ATA_MEMBER_A-part1
sudo wipefs --no-act /dev/disk/by-id/ATA_MEMBER_A-part1Note: --no-act makes wipefs report signatures rather than erase them. Replace the illustrative by-id name only after matching inventory records and the physical bay.
Create only on disposable, positively identified members
mdadm --create writes new array superblocks and can make every prior filesystem on the listed devices inaccessible. Stop if any member contains wanted data or is consumed by another MD array, LVM, swap, encryption, or a mounted filesystem. Version 1.2 metadata is stored near the start of the component and is a common native default; version 1.1 is at the start, version 1.0 is near the end, and 0.90 is legacy with important limits. Bootloader, firmware, installer, and old-kernel compatibility can constrain the choice. A name improves stable assembly, but the array UUID is its primary identity. Keep member sizes and sector geometry compatible, align partitions consistently, and let the initial synchronization complete before treating redundancy as established. Do not use --assume-clean merely to save time: wrong assumptions can preserve inconsistent mirrors or parity.
member_a=/dev/disk/by-id/ATA_MEMBER_A-part1
member_b=/dev/disk/by-id/ATA_MEMBER_B-part1
lsblk -o NAME,PATH,SIZE,MODEL,SERIAL,FSTYPE,MOUNTPOINTS "$member_a" "$member_b"
sudo mdadm --examine "$member_a" "$member_b"
sudo mdadm --create /dev/md/data --level=1 --raid-devices=2 --metadata=1.2 --name=data --bitmap=internal "$member_a" "$member_b"Note: The final command is destructive. Run it only during an approved build after both members are proven disposable and the exact geometry and metadata policy are recorded.
Assemble existing metadata instead of recreating it
Assembly associates existing component superblocks with an MD device; creation writes new metadata. Never use --create as a substitute for failed assembly unless a specialist has reconstructed and independently verified the exact original geometry. Normal boot and service workflows should assemble arrays from reviewed mdadm configuration and metadata. During diagnosis, specify known members and start read-only so no recovery or metadata update changes the evidence. --force can select or update metadata in dangerous recovery cases; it is not a generic degraded-start switch, and a dirty degraded RAID5 or RAID6 can contain undetectable corruption. Before stopping an array, unmount filesystems, deactivate swap, and remove LVM, encryption, multipath, container, and other stacked users. Confirm with findmnt, lsblk, and process or device-holder inspection.
member_a=/dev/disk/by-id/ATA_MEMBER_A-part1
member_b=/dev/disk/by-id/ATA_MEMBER_B-part1
sudo mdadm --examine "$member_a" "$member_b"
sudo mdadm --assemble --readonly /dev/md/data "$member_a" "$member_b"
cat /proc/mdstat
sudo mdadm --detail /dev/md/dataNote: Do not add --force or mount read-write after an unexpected failure. First compare event counts, member roles, logs, and backup state, preferably from images of suspect media.
Replace one confirmed member while preserving remaining redundancy
Before failing anything, verify the array, member role, serial number, bay, current degraded count, and health of every survivor. Failing the wrong device can exceed the level's tolerance immediately. A device must normally be marked faulty before removal; then provision a replacement at least as large as the usable component size with matching partition alignment and type. Adding it starts recovery when a role is vacant. If a device is only predicted to fail and remains readable, --replace can keep it as a recovery source until the replacement is synchronized; a device named after --with must already be a spare in that array. Do not power-cycle, repartition, or erase the old member until recovery completes, the array is optimal, application checks pass, and retention policy permits disposal.
failed=/dev/disk/by-id/ATA_FAILED-part1
replacement=/dev/disk/by-id/ATA_REPLACEMENT-part1
sudo mdadm --detail /dev/md/data
lsblk -o NAME,PATH,SIZE,MODEL,SERIAL,FSTYPE,MOUNTPOINTS "$failed" "$replacement"
sudo mdadm /dev/md/data --fail "$failed"
sudo mdadm /dev/md/data --remove "$failed"
sudo mdadm /dev/md/data --add "$replacement"
cat /proc/mdstatNote: The fail, remove, and add steps mutate array state. Execute them one at a time only after a second identity check and never remove another member during recovery.
Monitor state transitions, not just device presence
/proc/mdstat gives a compact view of active arrays and ongoing resync, recovery, check, reshape, or repair. mdadm --detail adds member roles, failure counts, layout, and array identity. Kernel sysfs exposes sync_action, sync_completed, sync_speed, degraded, and per-array sync_speed_min or sync_speed_max. Recovery is a period of reduced fault tolerance and heavy I/O; monitor application latency, device errors, temperatures, and survivor health as well as percent complete. Per-array speed limits are expressed in KiB per second and inherit system values until overridden. Raising them can starve production I/O or overheat devices, while setting them too low extends the vulnerable window. Use tested alert delivery through the distribution's MD monitoring service, and alert on degraded state and stale last-success evidence rather than relying on an interactive watch command.
md_name=$(basename "$(readlink -f /dev/md/data)")
cat /proc/mdstat
sudo mdadm --detail /dev/md/data
cat "/sys/block/$md_name/md/degraded"
cat "/sys/block/$md_name/md/sync_action"
cat "/sys/block/$md_name/md/sync_completed"
cat "/sys/block/$md_name/md/sync_speed"Note: These reads are non-mutating. A completed recovery is not proof of application integrity; run filesystem and application validation from an appropriate maintenance context.
Use a bitmap to limit post-crash resynchronization work
A write-intent bitmap records regions that may differ, allowing an uncleanly stopped redundant array to resynchronize dirty regions instead of scanning the entire address space. An internal bitmap is stored with MD metadata and replicated across members. It improves recovery time but adds metadata writes and may affect small random-write workloads; bitmap chunk size controls the tracking granularity. A bitmap does not validate unchanged regions, repair latent corruption, make RAID0 redundant, or replace scheduled consistency checks. Adding or removing one changes live array metadata, so verify support for the active metadata format, capture array detail, maintain power and monitoring, and benchmark the workload before adopting it broadly.
sudo mdadm --detail /dev/md/data
md_name=$(basename "$(readlink -f /dev/md/data)")
cat "/sys/block/$md_name/md/metadata_version"
cat "/sys/block/$md_name/md/consistency_policy"
sudo mdadm --grow /dev/md/data --bitmap=internal
sudo mdadm --detail /dev/md/dataNote: The grow command mutates metadata. Schedule it, confirm local mdadm and kernel support, and do not confuse a bitmap-assisted resync with a full consistency scrub.
Check redundancy first and interpret mismatches before repair
Writing check to sync_action requests a full consistency pass on redundant levels; kernel documentation notes that check may also perform repair on some RAID levels, so it is not a universal read-only guarantee. mismatch_cnt counts sectors that were, or for a check would be, rewritten; because MD often works in page-sized units, it is not a direct count of corrupt files or bad disks. A count read while sync_action is still check is only an in-progress value, so wait for idle before recording the final result. Concurrent writes, unclean history, device errors, and level-specific behavior affect interpretation. Freeze or quiet the workload when the operating procedure requires comparable results, retain the previous count and logs, and inspect SMART, kernel errors, cabling, power, filesystem health, and application checksums. A repair action explicitly requests rewriting inconsistency, but parity does not inherently reveal whether data or redundancy is correct, and a mirror does not inherently identify which copy is correct. Repair can therefore make the wrong version authoritative. Back up readable data and determine the trusted source before repair. Never schedule blind repair solely because mismatch_cnt is nonzero.
md_name=$(basename "$(readlink -f /dev/md/data)")
test "$(cat "/sys/block/$md_name/md/sync_action")" = idle
echo check | sudo tee "/sys/block/$md_name/md/sync_action"
cat /proc/mdstat
# After sync_action returns to idle, record the final mismatch count.
cat "/sys/block/$md_name/md/sync_action"
cat "/sys/block/$md_name/md/mismatch_cnt"
sudo journalctl -k --since today | grep -E 'md|raid|I/O error|blk_update_request'Note: Starting check consumes substantial I/O. Read mismatch_cnt after completion; do not replace check with repair until evidence and a restorable backup identify a safe recovery decision.
Treat reshape as a recoverability project
Changing member count, level, layout, chunk size, or component size can relocate essentially every block and run for hours or days. Take and test an independent backup, capture mdadm --detail and --examine output, record exact member order and versions, check all devices, provide stable power, and remove avoidable workload first. A member-count grow also requires the new component to be present, normally as a spare. Some RAID5 or RAID6 grows can use spare space for the critical section, but shrink, level, and layout changes require --backup-file. That file must be on a separate device, never the array or a filesystem layered on it. Preserve it unchanged until the reshape and validation finish. If interruption occurs, reassembly may require the same file; guessing, recreating an empty file, or using --invalid-backup can make critical-section data irrecoverable. Grow the block layer first, then resize partition, encryption, LVM, and filesystem layers separately using each layer's rules.
backup_file=/mnt/rescue/md-data.reshape
findmnt -T "$backup_file"
findmnt /dev/md/data
sudo mdadm --detail /dev/md/data
sudo mdadm --examine /dev/disk/by-id/ATA_MEMBER_A-part1
sudo mdadm --grow /dev/md/data --raid-devices=4 --backup-file="$backup_file"
cat /proc/mdstatNote: The grow command is destructive if geometry or backup placement is wrong. Prove /mnt/rescue is independent storage and preserve the file through any interrupted reassembly.
Make array identity and early-boot assembly reproducible
Distributions commonly read /etc/mdadm.conf or /etc/mdadm/mdadm.conf, sometimes plus a conf.d directory. Generate ARRAY records from live verified arrays, review UUID, name, metadata, HOMEHOST, device discovery, monitor destination, and policy instead of blindly appending duplicate scan output. Root, boot, swap, encrypted, or LVM-on-MD layouts may need the md modules, configuration, and discovery tools inside the initramfs. Regenerate it with the distribution-supported tool, inspect the result, keep a known-good boot entry and rescue media, and test a controlled reboot only while console access and backups are available. update-initramfs is typical on Debian-family systems; dracut is common elsewhere. Monitoring unit names and configuration paths vary by package, so use the installed manuals and unit inventory.
sudo mdadm --detail --scan
sudo mdadm --examine --scan
sudo grep -Ev '^[[:space:]]*(#|$)' /etc/mdadm/mdadm.conf
systemctl list-unit-files | grep -E 'mdadm|mdmonitor'
command -v update-initramfs
command -v dracutNote: These commands only inspect current state. Edit the distribution's actual configuration deliberately, then run exactly one supported initramfs generator and verify its output before rebooting.
Monitor physical media and maintain independent backups
MD reports array-level state; SMART, NVMe health, enclosure telemetry, kernel logs, and controller tools report different evidence about physical devices and paths. Query the whole underlying disk, not only its partition or /dev/md device, and trend reallocated or pending sectors, media errors, temperature, error logs, wear, and self-test history according to device type. A healthy SMART summary does not prove a disk or cable is healthy, and an MD member fault does not by itself identify the root cause. RAID only preserves service through a limited set of member failures. It replicates accidental deletion, ransomware, application corruption, and many operator errors; it also shares the host, controller, power, and disaster domain. Keep versioned, access-separated backups on independent storage, monitor completion, and regularly restore and validate them before relying on any fail, repair, forced assembly, or reshape procedure.
sudo mdadm --detail /dev/md/data
sudo smartctl -x /dev/disk/by-id/ATA_MEMBER_A
sudo smartctl -x /dev/disk/by-id/ATA_MEMBER_B
sudo journalctl -k --since today | grep -E 'md|raid|ata|nvme|I/O error'Note: These are diagnostic reads. Use nvme-cli or vendor enclosure tooling where appropriate, and test a restore from storage that does not depend on this array or host.
Sources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
- mdadm project via man7.orgmdadm(8) — manage MD devicesman7.org
- mdadm project via man7.orgmdadm.conf(5) — MD configurationman7.org
- mdadm project via man7.orgmd(4) — Linux Multiple Device driverman7.org
- Linux Kernel documentationRAID arrays — administrator guidekernel.org
- Linux Kernel documentationRAID driver documentationkernel.org
- Debian smartmontools packagesmartctl(8) — SMART disk monitoringmanpages.debian.org
- md-raid-utilities projectmdadm source and project documentationgithub.com
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.