Safely Scrub a Mounted XFS Filesystem with xfs_scrub

xfs_scrub checks a mounted XFS filesystem and hands you a clear verdict: clean, fixable errors, or an operational failure. The examples use xfs_scrub from xfsprogs 6.6.0-1ubuntu2.1, whose executable reports version 6.6.0.

Allow at least fifteen minutes for a small filesystem and much longer for a busy or large one. The scan holds filesystem locks and can keep the filesystem busy. Have a current backup before starting: the installed manual describes this utility as experimental and warns not to run it without backups.

You need root access, a mounted XFS filesystem, a kernel with the metadata scrub ioctl, and enough time to watch the result. Replace /srv/data below with the mount point you intend to inspect.

1. Confirm the installed tool

Check the binary and package as ordinary, read-only commands. This does not inspect or change a filesystem:

$ command -v xfs_scrub
/usr/sbin/xfs_scrub
$ xfs_scrub -V
EXPERIMENTAL xfs_scrub program in use! Use at your own risk!
xfs_scrub version 6.6.0
$ dpkg-query -W -f='${Package} ${Version}\n' xfsprogs
xfsprogs 6.6.0-1ubuntu2.1

The version and warning are useful evidence when comparing logs from different machines. Do not assume that an option or repair available in another xfsprogs release exists here.

2. Check the mount before scanning

Confirm that the path is the mounted filesystem you think it is. These checks are read-only and do not require root:

$ findmnt -no SOURCE,FSTYPE,TARGET /srv/data
/dev/mapper/vg0-data xfs /srv/data
$ test "$(findmnt -no FSTYPE /srv/data)" = xfs && echo 'XFS mount confirmed'
XFS mount confirmed

If findmnt prints no row, or the filesystem type is not xfs, stop. A wrong mount point is an operational error, not a reason to add flags until the command accepts it.

Checkpoint: Write down the exact target shown by findmnt. If you are working on a production host, tell the service owner that this check may consume storage and CPU bandwidth.

3. Run a metadata-only dry run

Use -n first. It checks filesystem metadata but does not repair or optimise anything. This is the safest first pass, but it still needs elevated privileges because it asks the kernel to inspect the mounted filesystem:

# xfs_scrub -n -v /srv/data

-v adds periodic status updates. The exact lines depend on the filesystem and kernel, so do not copy a sample transcript as a success criterion. Let the command finish and capture its status:

# xfs_scrub -n -v /srv/data
# scrub_status=$?
# printf 'xfs_scrub exit status: %s\n' "$scrub_status"
xfs_scrub exit status: 0

Status 0 means no errors were reported. Status 1 means filesystem errors were left uncorrected, status 2 means optimisations are possible, status 4 means an operational error, and status 8 means a usage or syntax error. The value is a sum, so a status of 3 means uncorrected errors plus possible optimisations. Treat every non-zero value as a reason to read the diagnostic output before proceeding.

4. Decide whether an ordinary run may change metadata

Without -n, xfs_scrub asks the kernel to repair supported metadata problems and perform supported optimisations. Examples include rebuilding free-space information, rebuilding inode indexes and recalculating reference counts. It may also discard unused extents with TRIM.

This is the point where the command stops being a read-only check. Do not run it blindly on a machine without a backup or during a workload that cannot tolerate extra I/O. There is no general undo command for a successful metadata repair. Recovery means restoring from backup or following your incident and filesystem-repair procedure.

If you have reviewed the backup and maintenance plan, run the normal online scrub as root:

# xfs_scrub -v /srv/data
# printf 'xfs_scrub exit status: %s\n' "$?"
xfs_scrub exit status: 0

A repair that succeeds is reported as a successful repair rather than as an outstanding corruption report. A kernel that cannot repair a finding does not make the filesystem safe by itself. Follow the diagnostic output and escalate to offline xfs_repair when instructed.

5. Add a storage read only when you need it

The normal scrub checks metadata. Add -x when you also need to read all file data extents for media errors:

# xfs_scrub -n -x -v /srv/data
# printf 'xfs_scrub exit status: %s\n' "$?"
xfs_scrub exit status: 0

-x issues direct, aligned reads to the block device, or READ VERIFY commands for SCSI disks. It can take substantially longer and consume more storage bandwidth. The report may include a disk offset, and for an affected file it may include an inode and file offset. Start with -n if you want the data scan without metadata repairs.

Do not interpret a clean metadata-only run as proof that every file block is readable. Conversely, a media error is a storage problem to investigate, not a prompt to keep retrying a destructive repair command.

6. Reduce impact or stop safely

For a background-style run, use -b. Once limits are reached, this restricts scrubbing to one thread; supplying it more than once adds an artificial delay to each scrub call:

# xfs_scrub -b -v /srv/data

This reduces CPU pressure but does not impose a time limit. Monitor the workload and the command's output. If you need to stop the foreground process, use your normal terminal interrupt and then check the exit status and system logs. The manual says the filesystem can remain busy for a long time, so plan a maintenance window rather than relying on a quick cancellation.

-e shutdown changes the response to detected errors by taking the filesystem offline. That is service-disrupting and should only be used when the availability and recovery consequences are understood. The default, -e continue, takes no such action. Do not add -e shutdown as a generic safety flag.

7. Know when xfs_repair is required

xfs_scrub is an online check and repair tool, not a replacement for offline repair. If corruption cannot be repaired by the kernel, the filesystem must be unmounted and xfs_repair run against it. Do not unmount a live service filesystem just because a scrub returned status 1. First preserve the output, confirm the affected mount, arrange downtime and follow your backup and incident procedure.

Keep the command output with the exit status, xfsprogs version, kernel version and mount details. That context prevents a later operator from confusing a stale report with a new failure.

Done means