Back to Commands

xfs_repair

filesystemLinux/Unix

The xfs_repair command is one of the most frequently used commands in Linux/Unix-like operating systems. xfs_repair Repair an XFS filesystem

See Examples View Syntax

Quick Reference

Command Name:

xfs_repair

Category:

filesystem

Platform:

Linux/Unix

Basic Usage:

xfs_repair [options] [arguments]

Common Use Cases

Syntax

xfs_repair [-nfdPLvVm] [-o options] [-l logdev] [-r rtdev] [-t interval] device

Options

Option	Description
`-n`	No-modify mode, check only, don't modify filesystem
`-f`	Force repair even if the filesystem is mounted (dangerous, may cause corruption)
`-d`	Repair dangerously, skip checking some directories
`-P`	Disable prefetching of inode and directory blocks
`-L`	Force log zeroing (overrides -n)
`-v`	Verbose mode, show what's being fixed
`-V`	Print version information
`-m`	Enable additional runtime memory usage measurements
`-o options`	Specify options (e.g., noquota, force_geometry)
`-l logdev`	Specify a device with an external log
`-r rtdev`	Specify a real-time device
`-t interval`	Display progress information at specified intervals (in seconds)
`device`	The special file containing the XFS filesystem (e.g., /dev/sda1)

Additional Options

The -o flag can take the following options:

Option	Description
`bhash=size`	Size of buffer cache hash table
`ag_stride=blocks`	Allocation group stride length
`phase2=size`	Size of buffer cache for phase 2
`noquota`	Skip phase 6 (quota checking)
`force_geometry`	Force geometry information even if it's inconsistent

Examples

How to Use These Examples

The examples below show common ways to use the xfs_repair command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

Basic Examples:

Check XFS filesystem without making any changes

xfs_repair -n /dev/sda1

Repair an XFS filesystem

xfs_repair /dev/sda1

Force repair even if the filesystem is mounted

xfs_repair -f /dev/sda1

Advanced Examples:

Repair with maximum verbosity

xfs_repair -v /dev/sda1

Repair a filesystem that has an external log device

xfs_repair -l /dev/sdc1 /dev/sda1

Repair a filesystem that has a real-time device

xfs_repair -r /dev/sdd1 /dev/sda1

Display progress information at specified intervals (in seconds)

xfs_repair -t 10 /dev/sda1

Skip the Phase 6 (quota) checking

xfs_repair -o force_geometry -o noquota /dev/sda1

Try It Yourself

Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

Understanding Syntax

Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

Notes

The `xfs_repair` command is a robust tool designed to check and fix inconsistencies in an XFS filesystem. It operates in multiple phases to thoroughly analyze and repair different aspects of the filesystem. Unlike filesystem checkers for other filesystems, `xfs_repair` is specifically optimized for XFS and offers unique capabilities. **Key Features:** 1. **Multi-Phase Operation**: xfs_repair operates in several distinct phases, each focusing on different filesystem structures: - Phase 1: Scan inodes - Phase 2: Check directory structure - Phase 3: Check directory connectivity - Phase 4: Check reference counts - Phase 5: Check free space - Phase 6: Check quota information - Phase 7: Check real-time bitmap 2. **No-Modify Mode**: The -n option allows you to check a filesystem without modifying it, making it a safe diagnostic tool. 3. **External Log Support**: XFS supports external logging, and xfs_repair can handle filesystems with separate log devices using the -l option. 4. **Real-Time Device Support**: For XFS filesystems with a real-time section, xfs_repair can handle this configuration using the -r option. 5. **Progress Reporting**: The -t option allows periodic progress updates, which is valuable for large filesystems where repair might take significant time. **Important Safety Considerations:** 1. **Unmount First**: It's strongly recommended to run xfs_repair only on unmounted filesystems. Running it on a mounted filesystem can cause severe data corruption, even with the -f flag. 2. **Backup Before Repair**: Always back up critical data before running xfs_repair, as there's always a risk when modifying filesystem structures. 3. **Check First**: Use the -n option first to see what issues exist before running a full repair. 4. **Last Resort**: Consider xfs_repair as a last resort for fixing serious filesystem issues. For minor issues, other tools like xfs_db may be more appropriate. **Technical Details:** 1. **Memory Usage**: xfs_repair can use significant amounts of memory, especially on large filesystems. The memory requirements scale with filesystem size and complexity. 2. **Temporary Files**: During operation, xfs_repair may create temporary files in /tmp to store intermediate data. 3. **Time Requirements**: Repairing a large XFS filesystem can take a considerable amount of time, potentially hours for multi-terabyte filesystems. 4. **Unrecoverable Corruption**: In cases of severe corruption, xfs_repair might not be able to recover all data. It prioritizes filesystem integrity over preserving all data. **Common Scenarios:** 1. **After System Crash**: If a system crashes while writing to an XFS filesystem, running xfs_repair after rebooting can fix any inconsistencies. 2. **Hardware Issues**: If storage hardware experiences problems, resulting filesystem corruption might be fixable with xfs_repair. 3. **Regular Maintenance**: Some administrators run xfs_repair -n periodically as part of filesystem health checks, similar to fsck for other filesystems. 4. **Before Data Migration**: Checking and repairing an XFS filesystem before migrating data to a new storage system can prevent propagating existing issues. **Comparison to Other Filesystem Repair Tools:** 1. **e2fsck (for ext2/3/4)**: While similar in purpose, xfs_repair has a different approach, focusing on aggressive parallelism and efficient handling of large filesystems. 2. **fsck.btrfs**: Btrfs has a different repair philosophy, focusing on online repairs through the filesystem itself rather than an offline repair tool. 3. **fsck.ntfs**: Unlike NTFS repair tools, xfs_repair is fully open-source and integrated with the filesystem development. **Advanced Usage Scenarios:** 1. **Filesystem Conversion**: When converting from another filesystem to XFS, running xfs_repair after the conversion can ensure the new filesystem is consistent. 2. **Forensic Analysis**: Using xfs_repair -n in conjunction with xfs_db can help in forensic analysis of XFS filesystems. 3. **Automated System Recovery**: Many automated recovery systems use xfs_repair as part of their toolkit for handling filesystem inconsistencies during system recovery. 4. **Cloud Storage Systems**: Large-scale cloud storage systems that use XFS often implement automated repair procedures using xfs_repair for self-healing. XFS is known for its robustness, and many XFS filesystems can run for years without requiring repair. However, when issues do occur, xfs_repair is an essential tool for maintaining filesystem health and recovering from corruption.

Related Commands

These commands are frequently used alongside xfs_repair or serve similar purposes:

Explore All Commands

Use Cases

Learn By Doing

The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the xfs_repair command works in different scenarios.

See Examples Try Lab Exercises

$ xfs_repair

View All Commands