Freeze an XFS Mount Safely for a Snapshot

You will use xfs_freeze to stop new changes to a mounted XFS filesystem, give a volume manager or storage array time to capture a consistent image, and then allow the filesystem to continue. The examples use the installed xfs_freeze from xfsprogs 6.6.0, packaged here as xfsprogs 6.6.0-1ubuntu2.1.

Allow about fifteen minutes for a planned snapshot, plus however long your storage snapshot takes. You need an XFS mount point, a snapshot facility that operates below or alongside that filesystem, and an account permitted to freeze it. Read access to the mount is not enough: use sudo when your account is not authorised to perform the operation.

1. Check the installed command

First confirm the binary and version. These are ordinary, read-only commands:

$ command -v xfs_freeze
/usr/sbin/xfs_freeze
$ xfs_freeze -V
xfs_freeze version 6.6.0
$ dpkg-query -W -f='${Package} ${Version}\n' xfsprogs
xfsprogs 6.6.0-1ubuntu2.1

The interface is deliberately small. Unless you ask for the version, you must supply exactly one of -f to freeze or -u to unfreeze, followed by the mount point. The command does not take a block-device path in place of the mounted directory.

2. Confirm the mount point and filesystem type

Set a variable to the directory where XFS is mounted. Replace the example path with the real one. The quoting keeps spaces in a path from changing the command:

$ MOUNT_POINT=/mnt/xfs-data
$ findmnt --target "$MOUNT_POINT" --output TARGET,FSTYPE,SOURCE
TARGET      FSTYPE SOURCE
/mnt/xfs-data xfs   /dev/mapper/example-data

The exact source and spacing are host-specific. The important checks are that the target is the mount point you intend to affect and that FSTYPE is xfs. If findmnt reports no mount, stop. Do not point xfs_freeze at a directory merely because its name suggests it contains the data.

Checkpoint: before continuing, write down the mount point and the command that will create the snapshot. Check that the snapshot destination is different from the live filesystem and that you know how to mount or export the resulting image for later verification.

3. Freeze the filesystem

Freezing waits for current filesystem transactions to complete, writes dirty data, metadata and log information to disk, and blocks new writes. This command changes live system state and normally needs elevated privileges:

$ sudo xfs_freeze -f "$MOUNT_POINT"

A successful command normally prints nothing and returns status zero. Check the status immediately:

$ printf 'freeze exit status: %s\n' "$?"
freeze exit status: 0

This is the point at which applications writing to the mount can block. Reads and inspection are not a substitute for a snapshot, and a successful exit status only says that the freeze request completed. It does not say that your storage tool captured an image.

4. Create the storage snapshot

While the filesystem is frozen, run the snapshot operation supplied by your volume manager, RAID device or storage platform. The exact command depends on that product, so do not substitute an invented LVM or array command here. Follow its documentation and record the snapshot identifier.

Keep this interval short. Do not run backups that read the live mount and do not start unrelated maintenance while writes are blocked. If the snapshot tool fails, skip any further snapshot attempts and go straight to thawing. You can investigate the failed snapshot after applications are writing again.

If you are writing a script, arrange an error path before the freeze request so every path after a successful freeze calls the unfreeze operation. A minimal outline is:

#!/bin/sh
set -eu
MOUNT_POINT=/mnt/xfs-data

sudo xfs_freeze -f "$MOUNT_POINT"
trap 'sudo xfs_freeze -u "$MOUNT_POINT"' EXIT INT TERM

# Replace this comment with your verified storage snapshot command.
# Keep the operation short and save its snapshot identifier.

trap - EXIT INT TERM
sudo xfs_freeze -u "$MOUNT_POINT"

Do not run that outline unchanged: the comment is a deliberate stop for the storage-specific command. The trap is a recovery guard for an ordinary shell error or interruption. Test the finished script on a disposable filesystem before using it for a service.

5. Unfreeze promptly

Restore normal access as soon as the snapshot request has completed. This also requires elevated privileges:

$ sudo xfs_freeze -u "$MOUNT_POINT"
$ printf 'thaw exit status: %s\n' "$?"
thaw exit status: 0

The -u operation releases filesystem modifications that were waiting behind the freeze. There is no separate restart command and no need to unmount and remount a healthy filesystem. If you lose your terminal, open another administrative session and run the same unfreeze command with the same mount point.

Do not assume that a failed snapshot automatically thawed the filesystem. Run the unfreeze command explicitly, then investigate the snapshot failure. If the unfreeze command itself fails, keep writes away from the affected service, preserve the error text, and involve the storage or filesystem administrator rather than repeatedly retrying a busy production mount.

6. Verify the result and avoid UUID surprises

After thawing, check the mount and perform a small application-level write appropriate to your service. For a disposable test file only:

$ findmnt --target "$MOUNT_POINT" --output TARGET,FSTYPE
TARGET        FSTYPE
/mnt/xfs-data xfs
$ sudo sh -c 'test -w "$1"' sh "$MOUNT_POINT"; printf 'mount is writable\n'
mount is writable

The command above checks the directory permission as root; it does not prove that a particular service account or application can write. Use the service's own health check for that. Remove any test file you create, and do not use a production data file as a write probe.

A filesystem copy normally retains the original XFS UUID. That can prevent the copy being mounted alongside the original. If your snapshot workflow mounts a copy for inspection, plan for the XFS nouuid mount option described by the local manual, and make sure you understand the storage tool's own clone semantics. Never mount an unverified copy read-write against a production host just to see whether it works.

Common traps

• Wrong path: a directory can exist without being the intended mount. Check it with findmnt --target first.
• Wrong object: the argument is a mount-point directory, not the underlying device such as /dev/mapper/example-data.
• Missing privilege: adding sudo does not fix a wrong mount point or create a snapshot capability.
• Forgotten thaw: keep sudo xfs_freeze -u /mnt/xfs-data visible in the runbook and use a trap in automation.
• UUID collision: a copied XFS filesystem can have the same UUID as its source, so a concurrent mount may be refused unless the workflow explicitly handles it.