xfs_repair Command Linux: Complete Guide to Fix and Repair XFS Filesystems

The xfs_repair command is a powerful utility in Linux designed specifically for checking and repairing XFS filesystems. As XFS is widely used in enterprise environments and high-performance computing systems, understanding how to properly use xfs_repair is crucial for system administrators and Linux users dealing with filesystem corruption or integrity issues.

What is xfs_repair?

xfs_repair is a filesystem repair utility that comes as part of the XFS utilities package. It’s designed to detect and repair corruption in XFS filesystems, making it an essential tool for maintaining data integrity and system stability. Unlike some filesystem checkers that can run on mounted filesystems, xfs_repair requires the filesystem to be unmounted before operation.

Installation and Prerequisites

Before using xfs_repair, ensure you have the XFS utilities installed on your system:

Ubuntu/Debian:

sudo apt update
sudo apt install xfsprogs

CentOS/RHEL/Fedora:

sudo yum install xfsprogs
# or for newer versions
sudo dnf install xfsprogs

Arch Linux:

sudo pacman -S xfsprogs

Basic Syntax

The basic syntax of the xfs_repair command is:

xfs_repair [options] device

Where device is the path to the XFS filesystem device (e.g., /dev/sda1, /dev/nvme0n1p2).

Important Safety Considerations

Common xfs_repair Options

Step-by-Step Repair Process

Step 1: Unmount the Filesystem

First, unmount the XFS filesystem you want to repair:

sudo umount /dev/sda1

If the filesystem is busy, you can check which processes are using it:

sudo lsof /mount/point
sudo fuser -v /mount/point

Step 2: Check Filesystem Status (Dry Run)

Before making any changes, perform a check-only scan to assess the damage:

sudo xfs_repair -n /dev/sda1

Example output:

Phase 1 - find and verify superblock...
Phase 2 - using internal log
        - zero log...
        - scan filesystem freespace and inode maps...
Phase 3 - for each AG...
        - scan and clear agi unlinked lists...
        - process known inodes and perform inode discovery...
        - agno = 0
        - agno = 1
        - agno = 2
        - agno = 3
        - process newly discovered inodes...
Phase 4 - check for duplicate blocks...
        - setting up duplicate extent list...
        - check for inodes claiming duplicate blocks...
        - agno = 0
        - agno = 1
        - agno = 2
        - agno = 3
Phase 5 - rebuild AG headers and trees...
        - reset superblock...
Phase 6 - check inode connectivity...
        - resetting contents of realtime bitmap and summary inodes
        - traversing filesystem ...
        - traversal finished ...
        - moving disconnected inodes to lost+found ...
Phase 7 - verify and correct link counts...
No modify flag set, skipping filesystem flush.
done

Step 3: Perform the Actual Repair

If issues were found in the check phase, run the repair:

sudo xfs_repair /dev/sda1

Real-World Examples

Example 1: Basic Filesystem Check

Let’s check an XFS filesystem for errors without making any repairs:

# Unmount the filesystem first
sudo umount /home

# Perform check-only scan
sudo xfs_repair -n /dev/sda2

Sample output for a clean filesystem:

Phase 1 - find and verify superblock...
Phase 2 - using internal log
        - zero log...
        - scan filesystem freespace and inode maps...
Phase 3 - for each AG...
        - scan and clear agi unlinked lists...
        - process known inodes and perform inode discovery...
        - agno = 0
        - agno = 1
        - process newly discovered inodes...
Phase 4 - check for duplicate blocks...
        - setting up duplicate extent list...
        - check for inodes claiming duplicate blocks...
Phase 5 - rebuild AG headers and trees...
        - reset superblock...
Phase 6 - check inode connectivity...
        - traversing filesystem ...
        - traversal finished ...
Phase 7 - verify and correct link counts...
No modify flag set, skipping filesystem flush.
done

Example 2: Verbose Repair Operation

For detailed information during the repair process:

sudo xfs_repair -v /dev/sda2

Sample verbose output:

Phase 1 - find and verify superblock...
        - block cache size set to 131072 entries
Phase 2 - using internal log
        - zero log...
        - scan filesystem freespace and inode maps...
        - found root inode chunk
Phase 3 - for each AG...
        - scan and clear agi unlinked lists...
        - process known inodes and perform inode discovery...
        - agno = 0
        - agno = 1
        - process newly discovered inodes...
Phase 4 - check for duplicate blocks...
        - setting up duplicate extent list...
        - check for inodes claiming duplicate blocks...
        - agno = 0
        - agno = 1
Phase 5 - rebuild AG headers and trees...
        - reset superblock counters...
Phase 6 - check inode connectivity...
        - resetting contents of realtime bitmap and summary inodes
        - traversing filesystem ...
        - traversal finished ...
        - moving disconnected inodes to lost+found ...
Phase 7 - verify and correct link counts...
done

Example 3: Emergency Log Zeroing

In extreme cases where the log is corrupted and preventing normal repair:

sudo xfs_repair -L /dev/sda2

Understanding xfs_repair Phases

The xfs_repair utility works in seven distinct phases:

1. Phase 1: Locates and verifies the superblock
2. Phase 2: Checks the log and scans filesystem metadata
3. Phase 3: Processes inodes and allocation groups
4. Phase 4: Identifies and resolves duplicate blocks
5. Phase 5: Rebuilds allocation group headers and trees
6. Phase 6: Verifies inode connectivity and moves orphaned files
7. Phase 7: Corrects link counts

Common Error Scenarios and Solutions

Scenario 1: Filesystem is Mounted

Error:

xfs_repair: /dev/sda1 contains a mounted filesystem
xfs_repair: /dev/sda1 contains a mounted and writable filesystem

fatal error -- couldn't initialize XFS library

Solution:

# Unmount the filesystem first
sudo umount /dev/sda1

# Then run repair
sudo xfs_repair /dev/sda1

Scenario 2: Dirty Log Detected

Error:

Log appears to be dirty, not replaying log.
Use -L option to destroy the log and attempt repair.

Solution:

# First try normal repair
sudo xfs_repair /dev/sda1

# If that fails, use -L as last resort (DATA LOSS POSSIBLE)
sudo xfs_repair -L /dev/sda1

Scenario 3: Superblock Corruption

If the primary superblock is corrupted, xfs_repair will automatically try to use secondary superblocks:

sudo xfs_repair /dev/sda1

You can also manually specify a secondary superblock:

sudo xfs_repair -s 1 /dev/sda1

Best Practices and Tips

1. Regular Filesystem Monitoring

Use xfs_info to monitor filesystem health:

xfs_info /mount/point

2. Check Filesystem Statistics

Before repair, gather filesystem information:

sudo xfs_db -r /dev/sda1 -c "sb 0" -c "print"

3. Monitor Repair Progress

For large filesystems, repairs can take hours. Monitor progress with:

sudo xfs_repair -v /dev/sda1 | tee repair.log

4. Post-Repair Verification

After repair, mount the filesystem and check for a lost+found directory:

sudo mount /dev/sda1 /mount/point
ls -la /mount/point/lost+found

Performance Considerations

For large XFS filesystems, consider these performance optimizations:

1. Increase Buffer Cache

sudo xfs_repair -t 60 /dev/sda1

2. Use Multiple Threads (for newer versions)

sudo xfs_repair -m 8 /dev/sda1

Troubleshooting Common Issues

Issue: Repair Takes Too Long

Symptoms: Repair process seems stuck or takes excessive time

Solutions:

• Ensure sufficient system RAM
• Check for hardware issues using dmesg
• Consider using -m option for multi-threading

Issue: Out of Space During Repair

Symptoms: Repair fails with “No space left on device”

Solutions:

• Free up space on the root filesystem
• Use a different temporary directory with -t option
• Clean up system logs and temporary files

Advanced Usage Examples

Repairing RAID Arrays

For XFS filesystems on RAID arrays:

# Check RAID status first
cat /proc/mdstat

# Repair the XFS filesystem
sudo xfs_repair /dev/md0

Network Attached Storage

For NFS-exported XFS filesystems:

# Stop NFS services
sudo systemctl stop nfs-server

# Unmount and repair
sudo umount /export/data
sudo xfs_repair /dev/sdb1

# Remount and restart services
sudo mount /dev/sdb1 /export/data
sudo systemctl start nfs-server

Prevention and Maintenance

Regular Monitoring Script

Create a monitoring script to check XFS filesystem health:

#!/bin/bash
# xfs_health_check.sh

DEVICE="/dev/sda1"
LOGFILE="/var/log/xfs_health.log"

echo "$(date): Checking XFS filesystem health" >> $LOGFILE

# Perform read-only check
if xfs_repair -n $DEVICE >> $LOGFILE 2>&1; then
    echo "$(date): Filesystem is clean" >> $LOGFILE
else
    echo "$(date): Issues detected - manual intervention required" >> $LOGFILE
    # Send alert notification here
fi

Automated Backup Before Repair

#!/bin/bash
# backup_and_repair.sh

DEVICE="/dev/sda1"
MOUNT_POINT="/data"
BACKUP_DIR="/backup/$(date +%Y%m%d_%H%M%S)"

# Create backup
mkdir -p $BACKUP_DIR
rsync -av $MOUNT_POINT/ $BACKUP_DIR/

# Unmount and repair
umount $MOUNT_POINT
xfs_repair $DEVICE

# Remount
mount $DEVICE $MOUNT_POINT

Conclusion

The xfs_repair command is an essential tool for maintaining XFS filesystem integrity in Linux environments. By understanding its various options, phases, and best practices, system administrators can effectively diagnose and repair filesystem corruption while minimizing data loss risks.

Remember the golden rules: always unmount the filesystem before repair, create backups when possible, and start with check-only mode before making actual repairs. With proper usage and regular monitoring, xfs_repair can help maintain stable and reliable XFS filesystems in production environments.

For complex scenarios or critical data recovery situations, consider consulting with filesystem specialists or using professional data recovery services to minimize the risk of permanent data loss.