cheatsheet

mdadm Command in Linux: Syntax, Options & Software RAID Examples

mdadm assembles, creates, monitors, and stops Linux MD RAID devices (md arrays) from partitions or whole disks. It writes version 1.2 metadata superblocks, reports array health, and integrates with /etc/mdadm/mdadm.conf for boot-time assembly.

Published

Updated

Read time 7 min read

Reviewed byDeepak Prasad

mdadm Command in Linux: Syntax, Options & Software RAID Examples
About mdadm assembles, creates, monitors, and stops Linux MD RAID devices (md arrays) from partitions or whole disks. It writes version 1.2 metadata superblocks, reports array health, and integrates with /etc/mdadm/mdadm.conf for boot-time assembly.
Tested on Ubuntu 25.04 (Plucky Puffin); mdadm 4.4-7ubuntu1; kernel 7.0.0-27-generic
Package mdadm (apt/deb) · mdadm (dnf/rpm)
Man page mdadm(8)
Privilege root / sudo
Distros

Ubuntu, Debian, RHEL, AlmaLinux, Fedora — install the mdadm package if missing.

Hardware RAID uses vendor tools; mdadm is for software MD arrays in the kernel.
Related guide

mdadm — quick reference

Create arrays

Requires partitioned or whole-disk members with matching role for the chosen level. Use spare loop files under /tmp for practice — never experiment on production RAID volumes.

When to use Command
Create RAID 0 (stripe) with N devices sudo mdadm --create /dev/md0 --level=0 --raid-devices=2 /dev/sdb1 /dev/sdc1
Create RAID 1 (mirror) sudo mdadm --create /dev/md1 --level=1 --raid-devices=2 /dev/sdb1 /dev/sdc1
Create RAID 5 (minimum three devices) sudo mdadm --create /dev/md5 --level=5 --raid-devices=3 /dev/sdb1 /dev/sdc1 /dev/sdd1
Create RAID 10 sudo mdadm --create /dev/md10 --level=10 --raid-devices=4 /dev/sd{b,c,d,e}1
Skip creation prompts in scripts sudo mdadm --create /dev/md0 --level=0 --raid-devices=2 /dev/sdb1 /dev/sdc1 --run
Name the array (metadata tag) sudo mdadm --create /dev/md0 --level=1 --raid-devices=2 --name=backup /dev/sdb1 /dev/sdc1

Inspect arrays and members

When to use Command
Short summary of an MD device sudo mdadm --query /dev/md0
Full array detail sudo mdadm --detail /dev/md0
Examine superblock on a component sudo mdadm --examine /dev/sdb1
Kernel view of active arrays cat /proc/mdstat
Emit ARRAY lines for mdadm.conf sudo mdadm --detail --scan

Stop, zero, and assemble

When to use Command
Stop an array (unmount first) sudo mdadm --stop /dev/md0
Stop every array listed in mdstat sudo mdadm --stop --scan
Erase MD superblock so disk can be reused sudo mdadm --zero-superblock /dev/sdb1
Assemble arrays from mdadm.conf sudo mdadm --assemble --scan
Assemble one known array sudo mdadm --assemble /dev/md0 /dev/sdb1 /dev/sdc1

Manage members

When to use Command
Mark a device failed sudo mdadm /dev/md0 --fail /dev/sdb1
Remove a failed device sudo mdadm /dev/md0 --remove /dev/sdb1
Add a device to an array sudo mdadm /dev/md0 --add /dev/sdd1
Add a hot spare sudo mdadm /dev/md0 --add /dev/sdd1

Help and version

When to use Command
Top-level usage mdadm --help
Mode-specific options mdadm --create --help
Package version mdadm --version

mdadm — command syntax

Synopsis from mdadm --help on Ubuntu 25.04 (mdadm 4.4):

text
mdadm --create device options...
mdadm --assemble device options...
mdadm --build device options...
mdadm --manage device options...
mdadm --misc options... devices
mdadm --grow options device
mdadm --incremental device
mdadm --monitor options...
mdadm device options...    # shorthand for --manage

mdadm writes RAID superblocks to member devices and registers arrays with the md kernel driver. Creating or zeroing superblocks destroys data on those members.

mdadm — command examples

Essential Create RAID 0 on loop-backed files (lab)

File-backed arrays are safe for learning — use real partitions (/dev/sdb1) in production with the same flags.

bash
dd if=/dev/zero of=/tmp/md1.img bs=1M count=32 status=none
dd if=/dev/zero of=/tmp/md2.img bs=1M count=32 status=none
L1=$(sudo losetup -f --show /tmp/md1.img)
L2=$(sudo losetup -f --show /tmp/md2.img)
sudo mdadm --create /dev/md127 --level=0 --raid-devices=2 $L1 $L2 --run

Sample output:

output
mdadm: Defaulting to version 1.2 metadata
mdadm: array /dev/md127 started.

Verify:

bash
cat /proc/mdstat

Sample output:

output
md127 : active raid0 loop28[1] loop27[0]
      61440 blocks super 1.2 512k chunks

Stop and clean up:

bash
sudo mdadm --stop /dev/md127
sudo mdadm --zero-superblock $L1 $L2
sudo losetup -d $L1 $L2
rm -f /tmp/md1.img /tmp/md2.img
Essential Query and detail an active array
bash
sudo mdadm --query /dev/md127
sudo mdadm --detail /dev/md127

Sample --query line:

text
/dev/md127: 60.00MiB raid0 2 devices, 0 spares. Use mdadm --detail for more detail.

Sample --detail excerpt:

text
Raid Level : raid0
        Array Size : 61440 (60.00 MiB 62.91 MB)
      Raid Devices : 2
             State : clean
    Active Devices : 2

Run these read-only commands on existing production arrays when auditing health — they do not modify metadata.

Common Examine superblock on a member disk

--examine reads metadata on a component even when the array is stopped — useful before reusing a disk.

bash
sudo mdadm --examine /dev/sdb1

Sample fields from a lab member:

text
Magic : a92b4efc
        Version : 1.2
     Raid Level : raid0
   Raid Devices : 2
          State : clean

On Ubuntu, full walkthroughs for RAID 1 and RAID 5 with real disks are in the RAID 1 and RAID 5 guides.

Common Generate mdadm.conf ARRAY lines

Ubuntu stores the config at /etc/mdadm/mdadm.conf. --detail --scan prints ARRAY lines you can merge into that file for boot-time assembly.

bash
sudo mdadm --detail --scan

Sample line:

text
ARRAY /dev/md127 metadata=1.2 UUID=4cf28406:d4c8c78d:33a8821b:c62fbec5

Append only after reviewing — do not overwrite production config in a lab test.

Common Stop an array and clear superblocks

Unmount filesystems before --stop. --zero-superblock lets you repartition members for a new array.

bash
sudo umount /dev/md0
sudo mdadm --stop /dev/md0
sudo mdadm --zero-superblock /dev/sdb1 /dev/sdc1

Sample stop message:

text
mdadm: stopped /dev/md0

Skipping umount leaves the array busy and --stop fails.

Common Watch resync progress in /proc/mdstat

During RAID 1 and RAID 5 rebuilds, /proc/mdstat shows resync progress:

text
md1 : active raid1 sdc1[1] sdb1[0]
      10475520 blocks super 1.2 [2/2] [UU]
      [=====>...............]  resync = 28.4%

When [UU] appears and resync reaches 100%, format the array with mke2fs or mkfs.ext4.

Advanced Assemble arrays at boot

After importing ARRAY lines into /etc/mdadm/mdadm.conf and running update-initramfs -u on Debian/Ubuntu:

bash
sudo mdadm --assemble --scan

Sample success line:

text
mdadm: /dev/md/0 has been started with 2 drives.

On a fresh lab VM with no arrays defined, this command may print nothing — that is normal.

Advanced Creation prompts on mismatched devices

If a member still contains a filesystem signature, mdadm asks for confirmation unless --run or --force is supplied. Always double-check device names — mdadm --create is destructive.

text
mdadm: /dev/sdb1 appears to contain an ext4 filesystem.
       Continue creating array? (y/n)

Answer n unless you intend to wipe the underlying data.

mdadm — when to use / when not

Use mdadm when Use something else when
  • You are building software RAID0/1/5/10 on Linux with the MD driver
  • You need to inspect failed members, spares, and resync state on md devices
  • You want boot-time assembly via /etc/mdadm/mdadm.conf
  • You are learning RAID on loop files before using real partitions
  • The server has hardware RAID → vendor CLI (PERC, HP SSA, etc.)
  • You need replication across hosts → DRBD, Ceph, or cloud volume mirroring
  • You only need a single-disk filesystem → parted + mke2fs
  • You want ZFS redundancy → ZFS pools, not MD
  • LVM mirroring is enough → lvcreate --mirror (different stack)

mdadm vs hardware RAID

mdadm (software) Hardware RAID
Layer Linux kernel MD driver RAID controller firmware
Cost No controller required Requires RAID HBA
Portability Arrays tied to Linux MD metadata Vendor-specific
Tooling mdadm, /proc/mdstat storcli, ssacli, etc.
Command One line
mdadm Software RAID management (this page)
losetup Loop files for safe RAID practice
cat /proc/mdstat Kernel RAID status

Browse the full index in our Linux commands reference.

mdadm — interview corner

What does mdadm manage?

mdadm controls Linux MD (multiple device) RAID — kernel md devices such as /dev/md0 built from partitions or disks. It creates metadata superblocks, starts and stops arrays, and reports failed members.

A strong answer is:

"mdadm is the userspace tool for Linux software RAID — create, assemble, monitor, and stop md arrays."

How many disks for RAID 0, 1, and 5?

RAID 0 stripes across two or more devices (no redundancy). RAID 1 mirrors two or more copies. RAID 5 needs at least three devices for distributed parity.

A strong answer is:

"RAID 0 minimum two disks, no redundancy; RAID 1 two for mirror; RAID 5 three for parity."

Where do you check RAID sync status?

/proc/mdstat shows active personalities, member states ([UU] = both mirrors up), and resync percentages. mdadm --detail adds UUID, chunk size, and event counters.

A strong answer is:

"I watch /proc/mdstat for resync progress and mdadm --detail for metadata and failed devices."

Why run --zero-superblock?

It removes MD metadata from a disk so you can repartition or join a different array without stale RAID signatures confusing mdadm or blkid.

A strong answer is:

"--zero-superblock wipes RAID metadata so the disk can be reused cleanly — only after stopping the array and backing up data."

What does mdadm --detail --scan output?

ARRAY lines with device path, metadata version, and UUID for /etc/mdadm/mdadm.conf (Ubuntu) so initramfs can assemble arrays at boot.

A strong answer is:

"It prints ARRAY lines for mdadm.conf — device, metadata version, and UUID for boot-time assembly."

Troubleshooting

Symptom Likely cause What to try
mdadm: cannot open /dev/md0: No such file Array not started mdadm --assemble or check /proc/mdstat
mdadm: error opening /dev/sdb1: Device or resource busy Filesystem mounted umount, then --stop or --zero-superblock
Found some drive for an array that is already active Member still in another array mdadm --detail each disk; stop duplicate arrays
Resync stuck Failed member or slow disk mdadm --detail, replace failed drive, check dmesg
Continue creating array? prompt Filesystem signature on member Confirm correct disk; backup before answering y

References

Rohan Timalsina

is a technical writer and Linux enthusiast who writes practical guides on Linux commands and system administration. He focuses on simplifying complex topics through clear explanations.

Related Articles

linux

Post-Quantum Cryptography in Linux: ML-KEM, ML-DSA, TLS, and SSH

Learn how to check ML-KEM support in TLS, create ML-DSA signatures, and verify post-quantum SSH key exchange …

19 min readsecurity

Where Is OpenSSL Config, Certificates, and Libraries? (Linux & Windows)

Find where OpenSSL keeps openssl.cnf, trust-store certificates, libssl libraries, and the openssl binary on …

9 min readcheatsheet

lsblk Command in Linux: Syntax, Options & Practical Examples (Block Devices)

lsblk lists block devices — disks, partitions, LVM volumes, and loop devices — in a tree with sizes and mount …

9 min read