The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| Resolve a mount source | findmnt --target /srv/data -o \
TARGET,SOURCE,FSTYPE,OPTIONS,MAJ:MIN | View examples |
| Show block topology | lsblk --fs --output \
NAME,KNAME,TYPE,FSTYPE,FSVER,LABEL,UUID,MOUNTPOINTS | View examples |
| Probe filesystem metadata | sudo blkid /dev/mapper/vg_data-lv_projects | View examples |
| Read device health | sudo smartctl --all /dev/nvme0n1 | View examples |
| Find storage errors | journalctl -k -g \
'I/O error|EXT4-fs error|XFS.*Corruption|nvme|ata' \
--since today --no-pager | View examples |
| Inspect ext metadata | sudo dumpe2fs -h /dev/mapper/vg_data-lv_projects | View examples |
| Read-only ext check | sudo e2fsck -f -n /dev/mapper/vg_data-lv_projects | View examples |
| Preen ext filesystem | sudo e2fsck -f -p /dev/mapper/vg_data-lv_projects | View examples |
| List backup superblocks | sudo mke2fs -n /dev/mapper/vg_data-lv_projects | View examples |
| Show ext parameters | sudo tune2fs -l /dev/mapper/vg_data-lv_projects | View examples |
| Show XFS geometry | sudo xfs_info /srv/data | View examples |
| Create XFS metadata image | sudo xfs_metadump /dev/mapper/vg_data-lv_projects \
/recovery/projects.metadump | View examples |
| Check XFS without changes | sudo xfs_repair -n /dev/mapper/vg_data-lv_projects | View examples |
| Repair XFS | sudo xfs_repair /dev/mapper/vg_data-lv_projects | View examples |
| Zero a corrupt XFS log | sudo xfs_repair -L /dev/mapper/vg_data-lv_projects | View examples |
| Mount read-only | sudo mount -o ro /dev/mapper/vg_data-lv_projects \
/mnt/recovery | View examples |
| Mount ext without journal replay | sudo mount -t ext4 -o ro,noload \
/dev/mapper/vg_data-lv_projects /mnt/recovery | View examples |
| Mount XFS without recovery | sudo mount -t xfs -o ro,norecovery \
/dev/mapper/vg_data-lv_projects /mnt/recovery | View examples |
| Unmount normally | sudo umount /srv/data | View examples |
| Find mount users | sudo fuser -vm /srv/data | View examples |
Filesystem repair rewrites metadata and can turn recoverable damage into permanent loss when run against the wrong device, a mounted filesystem, failing storage, or an incomplete snapshot. Confirm the entire block-device stack by UUID and major:minor, preserve evidence, obtain a restorable backup or clone, and use rescue media for root filesystems. ext4 and XFS require different tools: never run e2fsck on XFS or xfs_repair on ext4.
Step by step
Detailed examples
Resolve the exact filesystem through every storage layer
Paths may traverse partitions, dm-crypt, LVM, multipath, RAID, and snapshots. Device names can change after reboot; correlate mount source, UUID, major:minor, and parent topology. A repair command against a physical member instead of the assembled logical device can destroy the stack.
findmnt --target /srv/data -o TARGET,SOURCE,FSTYPE,OPTIONS,MAJ:MIN
lsblk --fs --output NAME,KNAME,PKNAME,TYPE,FSTYPE,FSVER,UUID,MOUNTPOINTS
sudo blkid /dev/mapper/vg_data-lv_projects
dmsetup ls --treeStabilize failing hardware before metadata repair
Filesystem corruption may be a symptom of media errors, cabling, controller faults, power loss, or degraded RAID. Repeated repair on failing storage compounds damage. Preserve logs, check array and device health, stop writes, and clone unstable media with a recovery-oriented tool before working on the clone.
journalctl -k -g 'I/O error|EXT4-fs error|XFS.*Corruption|nvme|ata' --since today --no-pager
lsblk --fs
cat /proc/mdstat
sudo smartctl --all /dev/nvme0n1Quiesce applications and verify the filesystem is unmounted
Repair tools require a stable offline image. Stop writers and dependent services, flush application state, unmount normally, and confirm the device has no mountpoints in any namespace. A lazy unmount does not make active references safe. Root filesystems generally require rescue media or an offline boot target.
findmnt --target /srv/data
sudo fuser -vm /srv/data
# Stop and verify dependent workloads, then unmount normally.
# sudo umount /srv/data
# findmnt --source /dev/mapper/vg_data-lv_projectsPreserve a restorable copy and metadata evidence
A snapshot is useful only if its underlying storage is healthy, has sufficient copy-on-write space, and is not mistaken for an independent backup. Prefer a block-level clone for failing media and test backup restoration. XFS metadumps can preserve diagnostic metadata and potentially filenames; protect them as production data.
# Choose a healthy destination outside the affected storage stack.
# sudo xfs_metadump /dev/mapper/vg_data-lv_projects /recovery/projects.metadump
# sha256sum /recovery/projects.metadump
# Record lsblk, blkid, kernel logs, and tool versions with the incident.Inspect ext4 features and state with ext-family tools
dumpe2fs and tune2fs report superblock state, mount counts, feature flags, and geometry. Do not use tune2fs to change features during incident triage. Tool version must understand on-disk features; booting old rescue media against a newer filesystem can be unsafe.
e2fsck -V
sudo dumpe2fs -h /dev/mapper/vg_data-lv_projects
sudo tune2fs -l /dev/mapper/vg_data-lv_projects
lsblk --fs /dev/mapper/vg_data-lv_projectsUse e2fsck offline and review every escalation
-n is a planning pass, but results on a mounted or changing image are invalid and journal replay behavior needs care. -p fixes only safe classes; interactive repair requires expert decisions. Alternate-superblock recovery must use geometry from the original filesystem. Never use -y reflexively on the only copy.
# After verified unmount and backup:
# sudo e2fsck -f -n /dev/mapper/vg_data-lv_projects
# Review output and preserve it before choosing repair mode.
# sudo e2fsck -f -p /dev/mapper/vg_data-lv_projectsUse XFS-aware inspection and feature-compatible tools
xfs_info reads geometry from a mounted filesystem or block device. XFS normally replays its log at mount; it does not use fsck.xfs for repair. Confirm xfsprogs supports filesystem features and preserve the existing log whenever possible because it contains pending metadata transactions.
xfs_repair -V
sudo xfs_info /srv/data
lsblk --fs /dev/mapper/vg_data-lv_projects
findmnt --target /srv/dataReserve xfs_repair -L for a documented last resort
Run xfs_repair only offline. -n is non-modifying but not a guarantee that repair will succeed. Normal log replay by mounting can be required before repair; if the log cannot replay, -L zeros it and loses pending metadata, potentially orphaning or corrupting recent changes. Work from a clone and preserve the original.
# After verified unmount and backup:
# sudo xfs_repair -n /dev/mapper/vg_data-lv_projects
# sudo xfs_repair /dev/mapper/vg_data-lv_projects
# Never add -L until normal recovery is impossible and data-loss impact is accepted.Mount recovered data read-only with filesystem-aware options
Generic ro can still allow journal or log replay during mount. ext4 noload and XFS norecovery prevent replay but expose an older or inconsistent view and are intended for controlled recovery. Copy critical data to healthy storage, validate it, then rebuild rather than returning a questionable filesystem directly to production.
# For ext4 evidence review:
# sudo mount -t ext4 -o ro,noload /dev/mapper/vg_data-lv_projects /mnt/recovery
# For XFS evidence review:
# sudo mount -t xfs -o ro,norecovery /dev/mapper/vg_data-lv_projects /mnt/recoverySources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.