LFCS 92 🐧 Filesystem Repair — e2fsck, xfs_repair - KandZ

⏱️ Estimated read: 10 min | |

The previous chapter introduced the decision to run a repair. This chapter covers the tools themselves. e2fsck and xfs_repair are not interchangeable frontends for the same operation. They operate on different filesystem architectures, accept different flags, and enforce different preconditions. e2fsck assumes the filesystem may be dirty and performs a multi-pass check that can rebuild directory indexes and extend trees. xfs_repair requires a cleanly unmounted filesystem, refuses to operate on a dirty log, and processes metadata in a fixed sequence of phases. Passing the wrong flag to either tool can delete data, or worse, leave the filesystem in a state that no subsequent tool can repair.

Key point: e2fsck is the checker for ext2/3/4 filesystems. xfs_repair is the checker for XFS. They share a common goal—restoring metadata consistency—but their preconditions, flags, and failure modes are distinct. The LFCS exam tests both.

Why these two tools exist separately

The ext4 architecture. ext4 stores metadata in a superblock, block group descriptors, inode tables, and extent trees. A repair must verify that these structures agree: that every allocated inode is reachable from a directory, that no block is claimed by two files, and that the free block bitmap matches the actual free blocks. e2fsck performs this check in five passes, each addressing a different metadata layer .

The XFS architecture. XFS organizes metadata into allocation groups (AGs), each with its own free space trees and inode allocation maps. The XFS log is a circular buffer that records metadata transactions; unlike ext4’s journal, it cannot be replayed by userspace tools. Only the kernel can replay the XFS log. This is why xfs_repair refuses to run on a filesystem with a dirty log and exits with status 2 .

The clean unmount requirement. xfs_repair requires the filesystem to have been unmounted cleanly. If the log is dirty, the correct procedure is to mount and immediately unmount the filesystem on the same machine that crashed, allowing the kernel to replay the log. Only if that fails should xfs_repair -L be used to erase the log—a last resort that discards metadata updates that were in progress .

The e2fsck preen mode. e2fsck -p is designed for boot scripts. It automatically fixes problems that can be safely resolved without human intervention. If it encounters a problem that requires administrator action, it exits with code 4, signaling that the boot process should not continue without manual intervention . This is the mode most commonly encountered during system startup.

The trade-off. e2fsck is more automated and can handle a dirty filesystem directly. xfs_repair is more conservative—it refuses to proceed if the log is dirty and requires explicit intervention. The trade-off is safety: XFS avoids replaying a log it does not understand, at the cost of requiring a kernel mount in the recovery path.

a. e2fsck: the ext4 repair tool

e2fsck is the userspace checker for ext2, ext3, and ext4 filesystems. It must be run on an unmounted filesystem. The -f flag forces a check even if the filesystem appears clean; the -n flag performs a read-only check; the -y flag answers yes to all prompts .

# Force a check, read-only
sudo e2fsck -f -n /dev/sdb1

# Force an interactive check
sudo e2fsck -f /dev/sdb1

# Force an automatic repair
sudo e2fsck -f -y /dev/sdb1

The -p flag is the preen mode. It is not a full repair—it fixes only what can be fixed automatically. If the filesystem requires manual intervention, e2fsck prints a description and exits with code 4 . This distinction matters on the exam: -p is what boot scripts use, and it is not equivalent to -y.

The -D flag optimizes directories. It rebuilds directory indexes (htrees) and removes slack space. This is useful after enabling metadata checksums, as the kernel documentation notes that tune2fs may request e2fsck -D to rebuild directories with checksums .

b. xfs_repair: the XFS repair tool

xfs_repair operates in phases: it finds and verifies the superblock, checks inode allocation maps, scans inodes, checks directories, checks pathnames, verifies link counts, checks free space maps, and finally verifies the superblock again . Each phase builds on the previous one, and the tool aborts on most disk I/O errors .

# No-modify mode: report what would be done
sudo xfs_repair -n /dev/sdc1

# Standard repair (requires clean unmount)
sudo xfs_repair /dev/sdc1

# Verbose output
sudo xfs_repair -v /dev/sdc1

The -n flag returns exit status 1 if corruption is detected, 0 if the filesystem is clean . This is the diagnostic mode. The -n flag is not completely accurate: it does not catch inconsistencies in the free space and inode maps, particularly lost blocks or subtly corrupted maps . It can also generate repeated warnings about the same problem because it cannot fix the problem as it encounters it.

The -L flag clears the log. It should be used only when the filesystem cannot be mounted and xfs_repair reports a dirty log. Clearing the log discards all metadata updates that were in progress at the time of the crash, which may cause significant filesystem damage .

c. Choosing the right flags for the exam

The LFCS exam is performance-based. The commands must be executed correctly under time pressure, and the result must be verifiable. For e2fsck, the critical distinction is between -n (diagnostic), -p (preen, boot script mode), and -y (automatic repair). For xfs_repair, the critical distinction is between -n (diagnostic), the default mode (standard repair), and -L (log clear, last resort).

Scenario	ext4 command	XFS command
Diagnose without changes	`e2fsck -f -n`	`xfs_repair -n`
Automatic repair	`e2fsck -f -y`	`xfs_repair`
Interactive repair	`e2fsck -f`	`xfs_repair`
Boot script mode	`e2fsck -p`	(not applicable)
Dirty log recovery	(journal replay on mount)	Mount/unmount, then `xfs_repair`
Log clear (data loss)	(not applicable)	`xfs_repair -L`

The e2fsck -p mode does not exist for XFS because XFS relies on kernel log replay, not a userspace journal. The XFS equivalent of “automatic repair” is simply xfs_repair, but it requires a clean log first.

Complete Example Session

# ============================================
# PART 1: DIAGNOSE EXT4 WITH e2fsck -n
# ============================================

sudo umount /dev/sdb1
sudo e2fsck -f -n /dev/sdb1
# Output: Pass 1: Checking inodes, blocks, and sizes
#         Inode 1234 has illegal block(s).  Fix? no

# ============================================
# PART 2: INTERACTIVE REPAIR (EXT4)
# ============================================

sudo e2fsck -f /dev/sdb1
# Prompt: Inode 1234 has illegal block(s).  Fix? yes
# Continue answering prompts for each inconsistency.

# ============================================
# PART 3: AUTOMATIC REPAIR (EXT4)
# ============================================

sudo e2fsck -f -y /dev/sdb1
# Answers yes to all prompts.

# ============================================
# PART 4: PREEN MODE (EXT4)
# ============================================

sudo e2fsck -p /dev/sdb1
# Automatically fixes safe problems.
# Exit code 4 if manual intervention required.

# ============================================
# PART 5: DIAGNOSE XFS WITH xfs_repair -n
# ============================================

sudo umount /dev/sdc1
sudo xfs_repair -n /dev/sdc1
# Exit code 1 if corruption detected, 0 if clean.

# ============================================
# PART 6: STANDARD XFS REPAIR
# ============================================

sudo xfs_repair /dev/sdc1
# Phase 1: Find and verify superblock...
# Phase 2: Using internal log...
# ...
# Phase 7: Checking free inode list...

# ============================================
# PART 7: DIRTY LOG RECOVERY (XFS)
# ============================================

# If xfs_repair exits with status 2 (dirty log):
sudo mount /dev/sdc1 /mnt
sudo umount /mnt
# Kernel replays the log during mount.
sudo xfs_repair /dev/sdc1

# ============================================
# PART 8: LOG CLEAR (XFS, LAST RESORT)
# ============================================

# Only if mount fails and log cannot be replayed.
sudo xfs_repair -L /dev/sdc1
# WARNING: Discards all uncommitted transactions.

# ============================================
# PART 9: VERIFY AFTER REPAIR
# ============================================

sudo mount /dev/sdb1 /mnt/data
ls -la /mnt/data/lost+found/
# Orphaned files are placed here.

The nine parts trace the diagnostic and repair paths for both filesystems: e2fsck dry run, interactive repair, automatic repair, preen mode; xfs_repair dry run, standard repair, dirty log recovery, log clear, and post-repair verification.

Quick Reference

e2fsck Flags

Flag	Purpose
`-f`	Force check even if clean
`-n`	Read-only, no changes
`-y`	Answer yes to all prompts
`-p`	Preen mode (boot script)
`-D`	Optimize directories

xfs_repair Flags

Flag	Purpose
`-n`	No-modify mode (diagnostic)
(default)	Standard repair
`-L`	Clear log (data loss)
`-v`	Verbose output

Exit Codes

Tool	Code	Meaning
`e2fsck`	0	No errors
`e2fsck`	4	Uncorrected errors (preen mode)
`xfs_repair -n`	0	No corruption
`xfs_repair -n`	1	Corruption detected
`xfs_repair`	2	Dirty log, cannot proceed

Best Practices

✅ Do This:

sudo umount /dev/sdb1
sudo e2fsck -f -n /dev/sdb1

✅ Unmount and dry-run before repairing

sudo xfs_repair -n /dev/sdc1

✅ Use no-modify mode to assess XFS damage

sudo mount /dev/sdc1 /mnt && sudo umount /mnt

✅ Replay XFS log via kernel before xfs_repair

❌ Don’t Do This:

sudo e2fsck -y /dev/sda1

❌ Never run on a mounted filesystem

sudo xfs_repair -L /dev/sdc1

❌ Log clear discards uncommitted transactions

sudo xfs_repair /dev/sdc1

❌ Fails if log is dirty; mount/unmount first

Common Pitfalls

Pitfall	Why It Happens	Fix
`e2fsck` on mounted filesystem	Forgetting to unmount	Unmount first; verify with `df`
`xfs_repair` exits with status 2	Dirty log	Mount/unmount to replay, then repair
`e2fsck -p` exits with 4	Manual intervention required	Run `e2fsck -f` interactively
Data loss after `-L`	Log cleared	Last resort only; back up first
`xfs_repair -n` misses errors	No-modify mode incomplete	Review output carefully; run actual repair

Real-World Examples

1. Force ext4 Check

sudo e2fsck -f /dev/sdb1

2. ext4 Read-Only

sudo e2fsck -f -n /dev/sdb1

3. ext4 Auto-Repair

sudo e2fsck -f -y /dev/sdb1

4. ext4 Preen Mode

sudo e2fsck -p /dev/sdb1

5. XFS Dry Run

sudo xfs_repair -n /dev/sdc1

6. XFS Standard Repair

sudo xfs_repair /dev/sdc1

7. XFS Dirty Log Replay

sudo mount /dev/sdc1 /mnt && sudo umount /mnt

8. XFS Log Clear

sudo xfs_repair -L /dev/sdc1

9. Verify After Repair

sudo mount /dev/sdb1 /mnt && ls /mnt/lost+found

10. Check Superblock State

sudo dumpe2fs -h /dev/sdb1 | grep "Filesystem state"

Visual

e2fsck Passes

┌──────────────────────────────────────────────┐
│  e2fsck /dev/sdb1                            │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Pass 1: Inodes, blocks, sizes               │
│  Pass 2: Directory structure                 │
│  Pass 3: Directory connectivity              │
│  Pass 4: Reference counts                    │
│  Pass 5: Group summary information           │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Orphaned inodes → lost+found                │
│  Inconsistent blocks → freed or reassigned   │
└──────────────────────────────────────────────┘

Each pass addresses a different metadata layer. The filesystem is not modified until inconsistencies are confirmed.

XFS Log Decision

┌──────────────────────────────────────────────┐
│  xfs_repair /dev/sdc1                        │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Is the log clean?                           │
└──────────┬───────────────────────┬───────────┘
           │ YES                   │ NO (dirty)
           ▼                       ▼
┌──────────────────────┐  ┌──────────────────────┐
│  Proceed with repair │  │  Exit status 2       │
│                      │  │  Mount/unmount to    │
│                      │  │  replay log          │
└──────────────────────┘  └──────────────────────┘

xfs_repair cannot replay the log. Only the kernel can. The mount/unmount step is mandatory before repair.

Summary

Item	Value
ext4 checker	`e2fsck`
XFS checker	`xfs_repair`
ext4 dry run	`e2fsck -f -n`
XFS dry run	`xfs_repair -n`
ext4 auto-repair	`e2fsck -f -y`
XFS standard repair	`xfs_repair`
ext4 preen	`e2fsck -p`
XFS dirty log	Mount/unmount, then repair
XFS log clear	`xfs_repair -L` (last resort)

Key takeaways:

e2fsck and xfs_repair are different tools for different filesystems. Passing e2fsck an XFS device produces an error; passing xfs_repair an ext4 device does the same.
e2fsck -n is diagnostic only. It reveals the damage without modifying the filesystem, allowing you to assess before committing to a repair .
xfs_repair -n returns exit code 1 if corruption is detected. This is the fastest way to determine whether the filesystem needs repair .
xfs_repair cannot replay a dirty log. It exits with status 2. The correct recovery is to mount and unmount the filesystem on the crashed machine, allowing the kernel to replay the log .
xfs_repair -L erases the log. It is a last resort. All metadata updates that were in progress at the time of the crash are lost.
e2fsck -p is preen mode, not automatic repair. It fixes only what can be safely fixed without intervention and exits with code 4 when manual action is required .

Remember: The repair tool is not the hard part. The hard part is knowing when to run it, which flags to pass, and what to do when it refuses. e2fsck -n and xfs_repair -n are the diagnostic entry points. e2fsck -f and xfs_repair are the repair commands. The -y and -L flags are the irreversible ones—use them only after a dry run has confirmed the damage and a backup has been taken.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!