xfs_check Command Linux: Complete Guide to XFS Filesystem Consistency Verification

The xfs_check command is a crucial system administration tool in Linux for verifying the consistency and integrity of XFS filesystems. As XFS has become increasingly popular in enterprise environments due to its high performance and scalability, understanding how to properly check and maintain XFS filesystems is essential for system administrators and Linux users.

What is xfs_check Command?

The xfs_check command is a read-only utility that examines XFS filesystem metadata for consistency without making any modifications to the filesystem. It performs comprehensive checks on various XFS structures including inodes, directory entries, free space maps, and allocation group headers to ensure the filesystem is in a healthy state.

Key characteristics of xfs_check:

• Read-only operation – never modifies filesystem data
• Can run on mounted or unmounted filesystems
• Provides detailed diagnostic information
• Part of the xfsprogs package
• Complementary to xfs_repair for filesystem maintenance

Installation and Prerequisites

Before using xfs_check, ensure the xfsprogs package is 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 and Options

The basic syntax for the xfs_check command is:

xfs_check [options] device

Essential Command Options:

Practical Examples and Usage

Example 1: Basic Filesystem Check

To perform a basic check on an XFS filesystem:

sudo xfs_check /dev/sdb1

Sample Output:

Phase 1: Check superblock...
Phase 2: Check allocation group headers...
Phase 3: Check inode allocation maps...
Phase 4: Check directory entries...
Phase 5: Check connectivity...
Phase 6: Check free space...
No errors found.

Example 2: Verbose Check with Detailed Output

For comprehensive diagnostic information:

sudo xfs_check -v /dev/sdb1

Sample Verbose Output:

Phase 1: Check superblock...
        - checking superblock
        - block cache size set to 248576 entries
Phase 2: Check allocation group headers...
        - agf and agi in ag 0
        - agf and agi in ag 1
        - agf and agi in ag 2
        - agf and agi in ag 3
Phase 3: Check inode allocation maps...
        - checking inode allocation maps
Phase 4: Check directory entries...
        - checking directory entries
Phase 5: Check connectivity...
        - checking connectivity
Phase 6: Check free space...
        - checking free space
Filesystem appears to be OK.

Example 3: Checking Specific Inode

To check a specific inode for corruption:

sudo xfs_check -i 12345 /dev/sdb1

Sample Output:

Checking inode 12345...
Inode 12345 appears to be OK.
Links: 1
Size: 4096 bytes
Blocks: 1

Example 4: Force Check on Clean Filesystem

To force a check even when the filesystem appears clean:

sudo xfs_check -f /dev/sdb1

Understanding xfs_check Output

The xfs_check command performs its analysis in six distinct phases:

Phase 1: Superblock Verification

• Validates filesystem magic numbers
• Checks superblock consistency
• Verifies filesystem geometry

Phase 2: Allocation Group Headers

• Examines AGF (Allocation Group Free space) headers
• Verifies AGI (Allocation Group Inode) headers
• Checks allocation group consistency

Phase 3: Inode Allocation Maps

• Validates inode allocation bitmaps
• Checks for orphaned inodes
• Verifies inode count consistency

Phase 4: Directory Entries

• Examines directory structure integrity
• Validates directory entry formats
• Checks for corrupted directory blocks

Phase 5: Connectivity

• Verifies filesystem tree connectivity
• Checks for unreachable files
• Validates parent-child relationships

Phase 6: Free Space

• Examines free space maps
• Validates allocation consistency
• Checks for space leaks

Error Detection and Interpretation

When xfs_check detects issues, it provides specific error messages. Here are common error types and their meanings:

Common Error Messages:

# Corrupted superblock
ERROR: bad magic number 0x42494e41 in superblock

# Inode corruption
ERROR: inode 67890 has bad magic number

# Directory corruption
ERROR: directory inode 12345 has bad entry at offset 128

# Free space inconsistency  
ERROR: free space count mismatch in AG 2

Best Practices and Safety Guidelines

When to Use xfs_check

• Regular maintenance: Schedule periodic filesystem checks
• After system crashes: Verify integrity after unexpected shutdowns
• Before backups: Ensure filesystem health before critical backups
• Storage issues: Diagnose hardware-related problems
• Performance problems: Check for filesystem-related bottlenecks

Safety Considerations

• Always unmount the filesystem when possible for accurate results
• Use read-only checks on production systems
• Combine with hardware diagnostics for comprehensive analysis
• Keep regular backups before running any filesystem utilities

Advanced Usage Scenarios

Checking Multiple Filesystems

Create a script to check multiple XFS filesystems:

#!/bin/bash
# Script to check multiple XFS filesystems

DEVICES=("/dev/sdb1" "/dev/sdc1" "/dev/sdd1")

for device in "${DEVICES[@]}"; do
    echo "Checking $device..."
    xfs_check "$device"
    echo "Check complete for $device"
    echo "------------------------"
done

Automated Health Monitoring

Implement automated XFS health monitoring:

#!/bin/bash
# XFS health monitoring script

LOG_FILE="/var/log/xfs_health.log"
DEVICE="/dev/sdb1"

{
    echo "$(date): Starting XFS check for $DEVICE"
    if xfs_check "$DEVICE" >&1; then
        echo "$(date): XFS check completed successfully"
    else
        echo "$(date): XFS check found errors - immediate attention required"
        # Send alert notification
        echo "XFS errors detected on $DEVICE" | mail -s "XFS Alert" [email protected]
    fi
} >> "$LOG_FILE"

Integration with System Monitoring

Cron Job for Regular Checks

Set up automated weekly XFS checks:

# Add to crontab (crontab -e)
0 2 * * 0 /usr/sbin/xfs_check /dev/sdb1 >> /var/log/xfs_weekly_check.log 2>&1

Systemd Service for XFS Monitoring

Create a systemd service for XFS health monitoring:

# /etc/systemd/system/xfs-check.service
[Unit]
Description=XFS Filesystem Check
After=multi-user.target

[Service]
Type=oneshot
ExecStart=/usr/sbin/xfs_check /dev/sdb1
User=root
StandardOutput=journal

[Install]
WantedBy=multi-user.target

Troubleshooting Common Issues

Permission Denied Errors

Ensure you have root privileges or use sudo:

sudo xfs_check /dev/sdb1

Device Busy Errors

If the filesystem is mounted, either unmount it or use the force option:

sudo umount /dev/sdb1
sudo xfs_check /dev/sdb1

Memory Issues on Large Filesystems

For very large filesystems, monitor system resources during checks and consider running during low-activity periods.

Comparison with Other Filesystem Check Tools

Performance Considerations

The xfs_check command’s performance depends on several factors:

• Filesystem size: Larger filesystems require more time
• Number of files: More inodes increase check duration
• Storage speed: SSD vs HDD significantly affects performance
• System load: I/O intensive operations slow down checks
• Available memory: More RAM allows for better caching

Security and Access Control

Important security considerations when using xfs_check:

• Requires root access or appropriate sudo permissions
• Can reveal filesystem structure information
• Should be logged for audit purposes
• Output may contain sensitive path information

Conclusion

The xfs_check command is an invaluable tool for maintaining XFS filesystem health and integrity. Its read-only nature makes it safe for regular use in production environments, while its comprehensive checking capabilities help identify potential issues before they become critical problems.

By incorporating regular xfs_check operations into your system maintenance routine, you can proactively monitor filesystem health, detect corruption early, and maintain optimal system performance. Remember to combine xfs_check with complementary tools like xfs_repair and hardware diagnostics for comprehensive storage system management.

Whether you’re managing a single server or a large-scale infrastructure, mastering the xfs_check command will help ensure your XFS filesystems remain reliable and performant throughout their operational lifetime.