FreeBSD fsck_ffs Recovery: Check and Repair UFS Without Guesswork

fsck_ffs checks and repairs UFS filesystem consistency. It is a recovery tool, not a generic disk repair command and not a way to fix failing hardware. A filesystem can be inconsistent because of an unclean shutdown, but repeated I/O errors, a failing drive, a bad cable, or an incorrect device path require separate investigation.

This procedure starts with identification and read-only evidence. Do not run a repair against a mounted writable filesystem. Do not point fsck at a whole disk when the UFS filesystem resides on a partition, mirror, encrypted provider, or another GEOM layer. The correct path is the filesystem provider shown by mount and fstab, not necessarily the raw physical disk.

Identify the filesystem and preserve the failure context

Capture the boot or mount error verbatim, note recent power loss and hardware changes, and record the exact provider:

mount
cat /etc/fstab
gpart show -lp
geom disk list
dmesg | tail -200

If the system is already running, do not assume that every target is unmounted. Check mount output and find the UFS entry. A root filesystem cannot be treated like a detached data partition while the machine is operating normally. Use single-user mode, installation media, or another appropriate recovery environment for root repair.

Before modifying a valuable filesystem, preserve a block-level image or a verified backup when possible, especially if there are read errors or the data is irreplaceable. If the physical device is failing, repeated scans and repairs can worsen the situation. Consider a controlled imaging process to healthy storage before repair. Do not write a recovered image back onto the source until the evidence and recovery plan are clear.

Use fstyp on the candidate provider only as an identification aid; it does not prove that the filesystem is healthy. Cross-check device identifiers, partition labels, mount records, and filesystem type. If the path belongs to ZFS, MSDOSFS, or another filesystem, fsck_ffs is the wrong tool.

Run a non-writing assessment first

For an unmounted UFS provider, fsck_ffs -n answers no to repair questions and does not open the filesystem for writing. The manual notes that the CONTINUE prompt is answered affirmatively, so the check can proceed while declining changes:

fsck_ffs -n /dev/ada0p2

Replace the example with the verified UFS provider. Preserve the complete output and exit status. Diagnostic messages often identify the phase and inconsistency type; do not jump directly to yes-all repair because a message looks familiar. A read-only assessment can still stress failing media, so stop if the kernel reports I/O errors and prioritize device imaging.

When the filesystem uses an alternate superblock or has a suspected damaged primary superblock, do not guess alternate block numbers. fsck_ffs supports -b, and its manual identifies typical locations for UFS1 and UFS2, but the correct choice depends on filesystem layout. Consult newfs(8), dumpfs(8), and the filesystem’s creation details before attempting an alternate superblock. A wrong superblock can produce misleading output.

Understand the repair modes

The -p preen mode fixes only a restricted set of inconsistencies considered safe for automatic correction. If fsck_ffs encounters a more serious inconsistency, it exits abnormally rather than attempting an unrestricted repair. Preen is useful during controlled startup checks, but it is not proof that a filesystem with hardware errors is safe.

Without -p, fsck_ffs prompts before corrective actions. Some corrections can lose file or directory data, and the diagnostic output can help assess the likely consequences. An operator should understand each prompt, preserve the transcript, and choose deliberately. The -y option answers yes to all questions; it can apply many changes without human review and should not be used as a reflexive incident response.

For routine automated checks on an unmounted data filesystem:

fsck_ffs -p /dev/ada0p2

For investigation without changes:

fsck_ffs -n /dev/ada0p2

These are different operations. Never describe -n as a repair mode or -p as a full interactive reconstruction. If preen stops on unexpected damage, collect the result and move to an interactive recovery plan only after the target has been verified and a backup or image exists.

Repair an unmounted data filesystem

If the provider is a non-root data filesystem and can be safely taken offline, stop applications that use it, check open files, and unmount it:

fstat -f /srv/archive
umount /srv/archive
mount | grep -F '/srv/archive'

Confirm the mount is gone before running any repair. Then begin with the restricted preen path if its scope fits the incident:

fsck_ffs -p /dev/ada0p2

If preen reports an inconsistency outside its automatic correction set, do not simply add -y. Review a copy of the output and decide whether to use interactive mode, recover from backup, or image the disk first. A carefully supervised interactive run is safer than accepting unknown changes wholesale, but it can still discard damaged structures.

After repair, run a read-only check and review the result:

fsck_ffs -n /dev/ada0p2
mount -o ro /dev/ada0p2 /mnt
ls -la /mnt

Read-only mounting is useful for inspection but does not validate every application-level file. Check ownership, expected directory layout, and representative file contents. Do not remount read-write until the filesystem check and hardware assessment support it.

Recover root and boot failures

For a root filesystem problem, boot from installation media or a recovery environment and identify the root UFS partition carefully. The boot failure may involve GPT, a loader configuration, a missing provider, or an unavailable GEOM class rather than filesystem metadata. Verify the boot path with gpart, geom, and the kernel messages before running a filesystem checker.

Mounting a damaged root read-write just to inspect it is not a safe first step. Run a non-writing check against the offline provider, then use the recovery environment’s repair procedure. If the root is part of a mirror, encryption stack, or another GEOM transformation, resolve that layer first and check the resulting filesystem provider. Never fsck an individual mirror member while the mounted filesystem is active through the mirror.

After a repaired root is mounted, preserve fsck output and inspect /var/log/messages and boot diagnostics. A successful reboot does not explain why the filesystem became inconsistent. Check power loss, storage resets, controller firmware, device error counters, and UPS logs. If the same filesystem repeatedly needs repair, investigate the underlying cause rather than scheduling aggressive repairs.

Know what a successful check does not prove

fsck_ffs validates filesystem structures and relationships; it does not verify that every user file matches its intended contents or that a database is transactionally consistent. A repaired inode or directory may be moved into lost+found or have names and relationships that require manual interpretation. Compare application-level checksums or restore selected data from backup where integrity matters.

A filesystem can be structurally consistent while the underlying disk is about to fail. Conversely, an unclean shutdown does not automatically mean that the filesystem is damaged; Soft Updates and journaling behavior affect recovery. Do not repeatedly run a checker against a live system when the actual fault is an unstable cable or power supply.

If fsck_ffs reports lost or orphaned objects, retain the output and inspect the resulting recovery directory only after the filesystem is mounted safely. Do not assume that a recovered file has its original name, ownership, or application-level consistency. A database file recovered by inode scanning may be structurally present but unusable without matching logs or transaction metadata. Compare with a backup and let the owning application validate its own data.

If the check is interrupted, record exactly which provider and mode were in use before restarting it. Do not switch from -n to -y simply because the first pass found many problems. The second pass may write extensively and discard structures that an expert could otherwise recover. For a high-value or actively failing disk, use a forensic or data-recovery workflow that images the source and preserves a copy before repair.

Acceptance criteria and records

Before returning the filesystem to service, establish that the target is the intended provider, the check completed without unexplained I/O errors, a read-only inspection succeeds, and essential files or application records are accessible. If repair changed data, document the affected paths and restore missing content from backup.

Record the initial mount state, source command output, selected repair mode, operator decisions, final check result, and physical-device diagnostics. Keep both the original and final logs. A clean fsck run is one signal, not a full restore test or proof of hardware reliability.

Related:

Sources: