Safely Inspect and Change an XFS Filesystem with xfs_admin

xfs_admin reads or rewrites an XFS filesystem's label and UUID, and handles a few one-way feature upgrades too.

By the end of this guide you can identify an XFS filesystem by label or UUID, change its label, and judge when a UUID or feature change is too risky to make casually. Examples use the xfsprogs 6.6.0 command installed here. Allow 10 minutes for inspection, longer if you need to unmount a busy filesystem.

Before you start

You need the xfs_admin command and the device name for an XFS filesystem. Replace /dev/DEVICE in every example with the real block device, such as /dev/mapper/data. Do not guess this value; check it first:

$ command -v xfs_admin
$ lsblk -f

Reading a label or UUID is normally harmless. Changes need root privileges and an unmounted filesystem. Check with findmnt and stop if it is serving a live workload:

$ findmnt --source /dev/DEVICE

Checkpoint: you have identified the correct XFS device, know whether it is mounted, and have a current backup before changing any metadata.

1. Confirm the installed command

Check the local version before relying on an option; feature and compatibility rules have changed between xfsprogs releases.

$ xfs_admin -V
xfs_admin version 6.6.0

Command missing? Install the distribution's xfsprogs package through its normal package manager. Do not substitute a similarly named filesystem utility.

2. Read the label and UUID

Use -l for the label and -u for the UUID. Neither changes the filesystem, which makes them useful for confirming a device before an administrative operation:

$ sudo xfs_admin -l /dev/DEVICE
$ sudo xfs_admin -u /dev/DEVICE

Record the values before making a change, and cross-check against the kernel's own view:

$ findmnt --source /dev/DEVICE --output SOURCE,FSTYPE,LABEL,UUID,TARGET

Checkpoint: the device reports xfs, and the label and UUID match what you expected. If not, stop and re-check the device path.

3. Change a label on an unmounted filesystem

Unmount cleanly, then set a short label. XFS labels are limited to 12 characters; supply a longer value and xfs_admin truncates it and prints a warning, so keep your example within the limit.

$ sudo umount /mount/point
$ sudo xfs_admin -L archive01 /dev/DEVICE
$ sudo xfs_admin -l /dev/DEVICE

That last command is the verification step. Clear a label with the special value --:

$ sudo xfs_admin -L -- /dev/DEVICE
$ sudo xfs_admin -l /dev/DEVICE

Recovery: changing a label is reversible, just set the previous label again. Mount it only after verification succeeds:

$ sudo mount /dev/DEVICE /mount/point
$ findmnt --source /dev/DEVICE

Do not treat a successful mount as proof you had the right device; a label change on the wrong disk is still a successful command.

4. Treat UUID changes as an outage and compatibility change

Warning: changing a UUID can break /etc/fstab, boot configuration, monitoring, backups, or scripts that identify the filesystem by UUID. It also changes the identity other systems may rely on. Record the old UUID and update every consumer before remounting.

After unmounting, generate creates a new UUID and nil sets the null UUID. On CRC-enabled filesystems, generating a UUID sets an incompatible flag that stops older kernels mounting the filesystem. The manpage documents restore as the recovery value: it puts back the original UUID and clears that incompatible flag as needed.

$ sudo umount /mount/point
$ sudo xfs_admin -u /dev/DEVICE
$ sudo xfs_admin -U generate /dev/DEVICE
$ sudo xfs_admin -u /dev/DEVICE

Recovery: there is no general undo for a UUID you failed to record. To back out the CRC-related compatibility change, use the documented restore operation and verify the result:

$ sudo xfs_admin -U restore /dev/DEVICE
$ sudo xfs_admin -u /dev/DEVICE

5. Handle feature upgrades deliberately

The -O option adds or removes selected features on an existing V5 filesystem. The supported features in this installed manpage are inobtcount, bigtime, and nrext64. Most cannot be disabled once enabled.

Warning: enabling one of these can make the filesystem unmountable or unwritable on older kernels, and these changes generally cannot be downgraded.

Before an upgrade, inspect without repairing:

$ sudo umount /mount/point
$ sudo xfs_repair -n /dev/DEVICE

Corruption reported here means stop and follow recovery procedures before touching -O. A dry-run repair is an inspection, not a repair; xfs_repair without -n is a separate, potentially disruptive operation.

Only once the state is confirmed clean and kernel support is checked should you perform a planned upgrade, for example:

$ sudo xfs_admin -O bigtime=1 /dev/DEVICE

Verify with your normal XFS inspection tooling and test a mount on every kernel that must access the filesystem. A zero exit status here is not proof that older hosts can use the new format.

Common traps

Mounted device: xfs_admin cannot modify a mounted filesystem. Unmount it, or use the relevant mounted-filesystem operation in xfs_growfs where appropriate.
External log: if the filesystem uses an external log, pass its log device as the optional logdev argument. A separate realtime device, when present, is supplied with -r.
Legacy options: -e, -j, -p, and lazy-counter changes apply to deprecated V4 formats or have format-specific limits. Do not copy them into a V5 procedure without checking the filesystem format.
Wrong recovery assumption: a label can be set back, but a generated UUID is not automatically recoverable unless you recorded the old value or use the documented restore behaviour.

Done means

Version and device confirmed: you confirmed the package version and the exact XFS device.
Mount state checked: you checked whether the device was mounted before changing it.
Changes verified: you verified the label or UUID after every metadata change.
Consumers updated: you recorded and updated UUID consumers before remounting.
Repair checked first: you ran xfs_repair -n before any planned V5 feature upgrade and stopped if it found corruption.