7.4 Filesystem Integrity: fsck, e2fsck, xfs_repair, xfs_fsr & xfs_db (104.2)

7.4 Filesystem Integrity: fsck & e2fsck

Quick Summary: Filesystem consistency can be compromised by abrupt power failures, hardware faults, kernel panics, or storage detachment. Linux provides the fsck (filesystem check) frontend and specialized checkers such as e2fsck to scan, verify, and repair structural metadata errors (superblock corruption, free block bitmap discrepancies, and orphaned inodes). Running a repair tool on an actively mounted read-write filesystem causes catastrophic corruption; target partitions must always be unmounted or remounted read-only beforehand.

---

1. Filesystem Consistency & The fsck Frontend Architecture

Filesystem metadata consists of interconnected data structures: the superblock (storing geometry, block size, and clean flags), block group descriptors, inode allocation bitmaps, block allocation bitmaps, and directory entry trees.

When a filesystem is unmounted cleanly, the kernel marks a clean bit in the superblock. If the system crashes, this bit remains dirty, signaling that block allocations may be out of sync. fsck inspects these structures, corrects inconsistencies, and reconciles lost data.

Like mkfs, fsck acts as a generic frontend wrapper that locates and executes the appropriate filesystem-specific binary in /sbin/:

fsck Frontend Architecture:
                         ┌─────────────────────────────┐
                         │     fsck /dev/sdX1          │
                         └─────────────────────────────┘
                                        │
          ┌─────────────────────────────┼─────────────────────────────┐
          ▼                             ▼                             ▼
  /sbin/fsck.ext4               /sbin/fsck.vfat               /sbin/fsck.xfs
  (Symlink to e2fsck)           (dosfsck)                     (Dummy script for XFS)

---

2. THE CRITICAL SAFETY RULE: Unmount Before Checking

⚠️ LPIC-1 Mandatory Safety Rule — NEVER Check a Read-Write Mounted Filesystem: Running fsck or e2fsck with write/repair permissions on an actively mounted read-write filesystem will cause severe, irreversible data loss and filesystem corruption! The kernel caches block updates in RAM while fsck modifies raw disk blocks underneath, resulting in conflicting writes.

Safe Filesystem Checking Workflows

# 1. Standard Procedure: Unmount the target partition before checking
# umount /dev/sdb1
# fsck -y /dev/sdb1

# 2. For the Root Filesystem (/): Remount read-only in single-user / rescue mode
# mount -o remount,ro /
# fsck.ext4 -f /
# reboot -f

# 3. Alternative: Force automatic fsck at next system reboot via systemd
# systemctl reboot --boot-loader-entry=auto-reboot
# Or pass 'fsck.mode=force fsck.repair=yes' as kernel boot parameters in GRUB

---

3. Generic fsck Command Options Reference

Command Syntax:
  fsck [options] [-t fstype] [filesystem...]

fsck Exit Return Codes

fsck returns a bitmask integer exit code representing the scan outcome:

• 0: No errors detected.
• 1: Filesystem errors were detected and successfully corrected.
• 2: System should be rebooted (critical system areas were repaired).
• 4: Filesystem errors were left uncorrected.
• 8: Operational error encountered during execution.
• 16: Usage or syntax error.
• 32: fsck canceled by user request.
• 128: Shared library error.

4. Deep-Dive: e2fsck for ext2/ext3/ext4

e2fsck is the dedicated maintenance tool for ext2, ext3, and ext4 filesystems. (fsck.ext2, fsck.ext3, and fsck.ext4 are direct hard links or symlinks to e2fsck).

Command Syntax:
  e2fsck [options] <device>

Essential e2fsck Flags Reference

Recovering from Primary Superblock Corruption with Backup Superblocks

If the primary superblock is damaged, running e2fsck fails with:

e2fsck: Bad magic number in super-block while trying to open /dev/sdb1
The superblock could not be read or does not describe a valid ext2/ext3/ext4 filesystem.

To restore the filesystem, locate backup superblocks and pass one to e2fsck -b:

# 1. Query backup superblock block locations from mke2fs (dry-run with -n)
# mke2fs -n /dev/sdb1
...
Superblock backups stored on blocks:
	32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632

# 2. Repair filesystem using the first backup superblock at block 32768
# e2fsck -b 32768 -y /dev/sdb1

---

5. The /lost+found Directory Mechanics

Every ext2/ext3/ext4 filesystem allocates a special directory named /lost+found at its filesystem root during formatting (mkfs).

How Inodes End Up in /lost+found

In Unix filesystems, a file consists of two parts: an inode (storing metadata and block pointers) and a directory entry (storing the human-readable filename and mapping it to the inode number).

If directory tree structures are damaged during a crash, e2fsck may discover allocated inodes containing valid file data that have no directory entry linking to them (known as orphaned inodes).

e2fsck reconnects these orphaned files into /lost+found, naming each file after its raw numeric inode number:

# Inspect files recovered into /lost+found
# ls -la /mnt/data/lost+found
total 248
drwx------ 2 root root  16384 Aug 29 10:00 .
drwxr-xr-x 4 root root   4096 Aug 29 09:30 ..
-rw-r--r-- 1 root root 104857 Aug 29 08:15 #182394
-rwxr-xr-x 1 root root  45020 Aug 29 08:20 #293810

# Identify the file types of recovered orphaned inodes
# file /mnt/data/lost+found/*
/mnt/data/lost+found/#182394: ASCII text, with very long lines
/mnt/data/lost+found/#293810: ELF 64-bit LSB executable, x86-64

---

6. XFS Integrity & The xfs_repair Utility

XFS handles filesystem integrity differently from the ext family:

1. No Boot-Time fsck: XFS does not execute a full scan at boot time. When an uncleanly unmounted XFS filesystem is mounted, the Linux kernel automatically replays the journal log in memory, bringing metadata back to a clean state instantly.
2. fsck.xfs is a Dummy Wrapper: The system binary /sbin/fsck.xfs is simply a script that exits immediately with return code 0.
3. Offline Repair via xfs_repair: If an XFS filesystem suffers severe corruption that journal replay cannot resolve, administrators use xfs_repair on an unmounted filesystem.

# 1. Run xfs_repair in check-only dry-run mode (-n)
# xfs_repair -n /dev/sdb2

# 2. Perform offline repair on unmounted XFS volume
# umount /dev/sdb2
# xfs_repair /dev/sdb2

# 3. Extreme emergency: Zero a corrupted journal log to permit mounting (-L)
# xfs_repair -L /dev/sdb2

⚠️ LPIC-1 Trap — The xfs_repair -L Flag: The -L flag on xfs_repair forces the utility to zero and discard a corrupted transaction log. This allows an otherwise unmountable XFS filesystem to mount, but any uncommitted transactions in the journal are lost forever. It must be used only as a last resort.

---

7. The Rest of the XFS Toolkit: xfs_fsr and xfs_db

The 104.2 Terms and Utilities list names three XFS tools, not one: xfs_repair, xfs_fsr and xfs_db. They do three different jobs, and the exam distinguishes them by when the filesystem must be mounted.

xfs_fsr — Filesystem Reorganiser

XFS resists fragmentation by design, but a long-lived volume holding databases or VM images can still accumulate files split across many extents. xfs_fsr copies each fragmented file into contiguous space and swaps it back, while the filesystem stays mounted and in use.

# Report how fragmented a mounted XFS filesystem is
# xfs_db -c frag -r /dev/sdb1
actual 129382, ideal 118201, fragmentation factor 8.64%

# Defragment everything listed in /etc/mtab (the default with no arguments)
# xfs_fsr

# Defragment one filesystem, stopping after 600 seconds
# xfs_fsr -t 600 /dev/sdb1

# Defragment a single file
# xfs_fsr /var/lib/libvirt/images/db.qcow2

# Verbose output showing each file processed
# xfs_fsr -v /mnt/data

xfs_fsr keeps a progress file (/var/tmp/.fsrlast_xfs) so a time-limited run resumes where the previous one stopped. Many distributions ship a weekly systemd timer or cron job that invokes it.

xfs_db — XFS Debugger

xfs_db opens the raw metadata of an XFS filesystem and lets you walk superblocks, allocation groups, inodes and B-trees. It is a diagnostic and forensic tool, not a repair tool.

# Read-only inspection is always safe; without -r, xfs_db can WRITE to metadata
# xfs_db -r /dev/sdb1

# Run a single command non-interactively
# xfs_db -r -c "sb 0" -c "print" /dev/sdb1

# The fragmentation report used above
# xfs_db -c frag -r /dev/sdb1

# Report free-space distribution across allocation groups
# xfs_db -r -c freesp /dev/sdb1

Exam Trap — Mounted vs Unmounted: xfs_repair refuses to run on a mounted filesystem and tells you to mount and unmount it first so the log can replay. xfs_fsr is the opposite — it requires the filesystem to be mounted, because it works through normal file operations. xfs_db should be run with -r (read-only) on anything you care about; without -r it can modify metadata directly and corrupt the filesystem.

Exam Rule: For ext filesystems the parallel tool set is e2fsck (repair), tune2fs (change superblock parameters), dumpe2fs (dump superblock and group descriptors), and debugfs (interactive debugger). Map them across: xfs_repair ↔ e2fsck, xfs_admin ↔ tune2fs, xfs_info ↔ dumpe2fs, xfs_db ↔ debugfs. There is no ext equivalent of xfs_fsr in the objective list (e4defrag exists but is not named).