xfs

Identity

• Kernel module: Built-in (no module load needed on modern kernels)
• CLI tools: mkfs.xfs, xfs_repair, xfs_info, xfs_admin, xfs_growfs, xfs_db, xfs_freeze, xfs_fsr, xfsdump, xfsrestore
• Install: apt install xfsprogs / dnf install xfsprogs
• Default on: RHEL, CentOS Stream, Fedora (root filesystem)
• Logs: kernel ring buffer via dmesg | grep -i xfs

Key Operations

| Operation | Command | |-----------|---------| | Show filesystem info | xfs_info /mount/point or xfs_info /dev/sdXN | | Create filesystem | mkfs.xfs /dev/sdXN | | Create with label | mkfs.xfs -L mylabel /dev/sdXN | | Repair (unmounted) | xfs_repair /dev/sdXN | | Forced repair (corrupted log) | xfs_repair -L /dev/sdXN — zeroes the log; last resort | | Online grow | xfs_growfs /mount/point (device must already be larger) | | Change label | xfs_admin -L newlabel /dev/sdXN (unmounted) | | Change UUID | xfs_admin -U generate /dev/sdXN (unmounted) | | Freeze filesystem | xfs_freeze -f /mount/point (for consistent snapshot) | | Unfreeze filesystem | xfs_freeze -u /mount/point | | Enable project quota | Mount with prjquota; run xfs_quota -x -c 'project -s projname' /mnt | | Check quota usage | xfs_quota -x -c 'report -h' /mount/point | | Defragment (online) | xfs_fsr /mount/point or xfs_fsr /dev/sdXN | | Dump filesystem | xfsdump -l 0 -f /backup/dump.xfs /mount/point | | Restore from dump | xfsrestore -f /backup/dump.xfs /restore/point | | Check fragmentation | xfs_db -r -c frag /dev/sdXN | | Inspect superblock | xfs_db -r -c 'sb 0' -c p /dev/sdXN |

Expected State

• Filesystem mounts cleanly; xfs_info returns valid geometry without errors
• dmesg | grep -i xfs shows no corruption or I/O error messages
• Journal replays automatically on unclean shutdown (normal; not an error)
• Quotas active if prjquota/uquota/gquota in mount options

Health Checks

1. xfs_info /mount/point — returns block size, AG count, and geometry without error
2. dmesg | grep -i 'xfs.*error\|xfs.*corrupt' | tail -20 — empty is healthy
3. xfs_quota -x -c 'report -h' /mount/point — runs without error if quotas are enabled

Common Failures

| Symptom | Likely cause | Check/Fix | |---------|-------------|-----------| | Filesystem won't mount; journal dirty | Unclean shutdown; journal not yet replayed | Mount normally — kernel replays journal automatically; if it fails, run xfs_repair | | xfs_repair refuses to run | Filesystem is mounted | Unmount first; repair requires the device to be offline | | XFS metadata I/O error in dmesg | Failing hardware (disk or controller) | Run smartctl -a /dev/sdX; check controller logs; do not repair until hardware is confirmed good | | Cannot shrink XFS | XFS supports online grow only; shrink is not implemented | Plan partition size upfront; only option is dump, reformat, restore | | xfs_repair -L causes data loss | -L zeroes the log, discarding uncommitted transactions | Use only after normal xfs_repair fails; accept potential data loss | | Quotas not enforced | Mount options missing prjquota/uquota/gquota | Add quota mount option to /etc/fstab, remount, initialize with xfs_quota | | Fragmentation degrading performance | Many small files written over time (databases, mail spools) | Run xfs_fsr during low-I/O window; monitor with xfs_db -r -c frag | | xfs_growfs fails with "filesystem already maximum size" | Block device not yet resized | Resize the partition/LV/volume first, then run xfs_growfs |

Pain Points

• XFS cannot be shrunk: Only online growth is supported. Size the partition correctly at creation; recovery requires dump/reformat/restore.
• xfs_repair -L zeroes the log: This discards any transactions not yet written to disk. Use only when normal xfs_repair refuses to proceed and data loss is acceptable — not as a routine first step.
• Default on RHEL/CentOS/Fedora: These systems boot from XFS root by default. Know the tools before touching the root filesystem; a failed repair on an unmounted root requires rescue media.
• RHEL-specific xfs_repair behavior: Red Hat ships a patched xfs_repair with additional safety checks. Behavior may differ from upstream for certain corruption patterns; consult RHEL release notes for known bugs.
• Metadata locking on large directories: Very large directories (millions of entries) can cause extended hold times on metadata locks, stalling other operations. Distribute files across subdirectories where possible.
• norecovery mount option is dangerous: It bypasses journal replay and is intended for read-only forensic access on an unclean filesystem. Never use it on a filesystem you intend to write to.
• ftype=1 required for overlayfs/Docker: If mkfs.xfs was run without -n ftype=1 (the default on modern xfsprogs, but not on older versions), Docker's overlay2 storage driver will refuse to use the filesystem.

References

See references/ for:

• xfs-options.md — mkfs.xfs flags, mount options, and xfs_admin options with purpose and usage context
• docs.md — official documentation and man page links