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

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

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

$ 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

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

$ 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.

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.