FreeBSD UFS Snapshot Operations: Create, Mount, Inspect, and Retire Safely

FreeBSD’s FFS/UFS filesystem supports snapshots through mksnap_ffs(8). A snapshot is represented by a file within the filesystem being snapshotted, commonly below a .snap directory. The manual describes it as a file whose apparent size equals the source filesystem size, and it can be mounted elsewhere through a read-only vnode-backed md device for inspection.

This feature is useful for consistent filesystem-level inspection and for some backup workflows. It is not a second copy of the filesystem, a replication mechanism, or an application transaction. The snapshot and live filesystem share the same storage failure domain, and a database or mail service may have buffered state that is not logically consistent merely because the filesystem captured a point in time.

Confirm filesystem type and available capacity

Before creating a snapshot, identify the mountpoint and the device or provider beneath it:

mount -p
df -h /home
gpart show

Use the real target mountpoint, not a path that may refer to a different filesystem through nullfs or another mount layer. Ensure the snapshot directory is on that filesystem and is not itself a different mount. The mksnap_ffs manual says the snapshot path must be within the filesystem to snapshot; .snap at the filesystem root is conventional.

Capacity planning is critical. The manual warns that a full filesystem is not handled gracefully by this facility and may lead to a system panic when no free blocks remain. It also documents a maximum of 20 active snapshots per filesystem for the described implementation. These are operational constraints, not capacity recommendations. Keep headroom based on expected write activity during the snapshot’s lifetime and inspect the installed manual for release-specific behavior.

Plan the maintenance window around the write rate, not merely the source filesystem’s nominal size. A mostly idle archive volume and a busy mail spool can have very different snapshot-retention costs even at the same capacity. Collect baseline free space and write activity first, then set an alert threshold that leaves room to stop the workload or retire the snapshot before exhaustion. If the underlying filesystem is already close to its limit, prefer an external backup or a separate recovery environment rather than creating another retention object.

Track active snapshots as first-class filesystem state. A deployment check can list the snapshot directory and compare it with the owner and expiry inventory, but a filename alone does not establish that a backup completed. Pair the directory entry with a recorded mksnap_ffs result, source mountpoint, creation time, and backup job identifier. This makes an orphan distinguishable from a planned recovery point.

Create the conventional directory only after verifying its filesystem and ownership:

install -d -o root -g operator -m 0750 /home/.snap
df -h /home

Do not lower filesystem free-space alarms just to make a snapshot fit. A long-lived snapshot can retain blocks that later writes would otherwise be able to reclaim. The retained space grows with changed data, so a snapshot that starts small can become operationally expensive under heavy churn.

Create a snapshot with a named owner and expiry

Choose a unique name that records purpose and creation window. mksnap_ffs accepts a snapshot path, and the manual’s example creates one under .snap:

mksnap_ffs /home/.snap/pre-migration-20261004
snapinfo /home
df -h /home

Check the exit status and retain the exact output with a timestamp. The command’s completion does not establish application quiescence or backup integrity. If the target contains a database, coordinate an application-native checkpoint or backup mode and record its start and end state separately.

Keep an inventory with snapshot path, source mountpoint, creation reason, owner, expiry, and whether a consumer is mounted or being dumped. Without an expiry policy, snapshots can accumulate until the active-snapshot limit is reached or filesystem headroom is exhausted. Avoid naming a snapshot only current or latest; those labels do not reveal which change window produced it.

Mount a snapshot read-only for inspection

The mksnap_ffs manual shows using mdconfig with a vnode-backed, read-only device and mounting it elsewhere. A controlled example is:

install -d -m 0700 /mnt/ffs-snapshot
mdconfig -a -t vnode -o readonly \
  -f /home/.snap/pre-migration-20261004

Record the md unit printed by the command, then mount that specific device read-only:

mount -t ufs -o ro /dev/md0 /mnt/ffs-snapshot
mount -p | grep ffs-snapshot
find /mnt/ffs-snapshot -maxdepth 2 -type f | head

Replace md0 with the unit returned by mdconfig. Do not copy the sample unit blindly: an existing md device may already own that name. Verify mount output and that the snapshot is read-only before opening files. Avoid running repair tools against a mounted snapshot or writing into it.

When inspection is finished, unmount before detaching the md device:

umount /mnt/ffs-snapshot
mdconfig -d -u 0

Use the unit number associated with the device you created. If unmount or detach reports the device is busy, find the process holding files or the mountpoint and release it normally. Do not force detach while a reader is still using the snapshot.

Use snapshots as a backup input carefully

UFS dump can use a snapshot as a stable source for backup operations. That does not turn one snapshot into a durable backup. A dump file or tape must be copied to another failure domain, retained according to policy, and periodically restored in a test environment. Preserve the dump level and timestamps needed for incremental restore.

The snapshot file’s apparent size can be misleading if treated as allocated storage. Use filesystem capacity and snapshot tooling to understand retained data and available headroom. Do not infer “no space used” from the output of ls alone. If an incremental backup depends on a prior snapshot, retain that snapshot until the backup system confirms that the necessary restore chain is complete and tested.

Coordinate write-heavy applications before relying on filesystem state. An atomic filesystem snapshot gives a consistent point-in-time view at the filesystem layer, but it may capture a database after the filesystem has recorded some writes and before the application has completed a transaction. Use database-native backup or quiesce hooks when application consistency matters.

Remove snapshots only after checking consumers

The manual describes deleting the snapshot file to remove the snapshot. Before removal, check whether it is mounted through mdconfig, used by an active dump process, or part of an approved rollback or audit window:

snapinfo /home
mount -p | grep ffs-snapshot
mdconfig -l -v

Once the snapshot is no longer required and no consumer depends on it, remove the exact path:

rm /home/.snap/pre-migration-20261004
snapinfo /home
df -h /home

Do not use a wildcard such as rm /home/.snap/* in an incident runbook. A mistaken path can remove multiple recovery points, and an active snapshot may be represented by a file that looks ordinary. Confirm the precise filesystem and filename before deleting.

Snapshot removal does not necessarily make every block immediately available for unrelated use if another snapshot still references changes. Recheck filesystem capacity after cleanup and monitor it during normal writes. If a snapshot remains unexpectedly listed, inspect mount references, path spelling, and local manual guidance rather than attempting unsupported metadata edits.

Failure cases and safe operations

If mksnap_ffs reports an error, inspect the path, mountpoint, active snapshot list, filesystem free space, and kernel logs. ENOSPC can reflect the active snapshot limit as well as available storage; confirm both. Never repeatedly retry snapshot creation on a nearly full filesystem. Free space or expire a specific, approved snapshot first, then review whether the filesystem is healthy.

If mdconfig fails, verify that the snapshot exists, the vnode path is correct, and no other process already owns the requested unit. If mounting fails, do not run fsck against the snapshot path or source filesystem as a guess. Preserve the error, verify the device mapping, and check the installed mount_ufs and mksnap_ffs manuals.

For a rollback, remember that a mounted snapshot is normally an inspection view; copying files back is a separate, potentially destructive procedure. Compare file ownership, ACLs, flags, hard links, and application state before restoring. Prefer a tested restore process to ad hoc recursive copy commands.

Acceptance criteria

A production snapshot schedule is ready when each filesystem has a capacity threshold and expiry policy, snapshot creation is tested under representative write load, the active count is monitored, application consistency is addressed, and a restore or inspection drill has succeeded. Record where the resulting backup is stored outside the source filesystem.

FFS snapshots provide a local point-in-time view useful for inspection and backup coordination. They do not replace independent backups, application checkpoints, or capacity monitoring.

Related:

Sources: