How to Check Filesystem Integrity with `fsck` on FreeBSD

Introduction

FreeBSD, like other Unix-like operating systems, relies on filesystems to organize and store data. Over time, these filesystems can develop inconsistencies due to improper shutdowns, hardware failures, software bugs, or other system issues. The File System Consistency Check (fsck) utility is a critical tool for detecting and repairing these inconsistencies, helping maintain system stability and data integrity.

This article explores how to effectively use fsck on FreeBSD systems, covering basic concepts, common usage scenarios, and best practices to ensure your filesystems remain healthy and reliable.

Understanding Filesystems in FreeBSD

Before diving into fsck, it’s helpful to understand the common filesystems used in FreeBSD:

1. UFS (Unix File System): The traditional and most common filesystem on FreeBSD. UFS2, the current iteration, offers excellent performance, reliability, and features like soft updates and snapshots.

2. ZFS (Zettabyte File System): An advanced filesystem that integrates volume management with features like data integrity verification, automatic repair, snapshots, and more.

3. FAT/NTFS: Supported primarily for interoperability with other operating systems, especially when dealing with removable storage.

It’s important to note that fsck is primarily designed for UFS filesystems. ZFS has its own set of maintenance tools (zpool and zfs commands) that include built-in integrity checking and repair functionality.

The Role of fsck in FreeBSD

The fsck utility in FreeBSD examines filesystem metadata structures, looking for inconsistencies such as:

• Incorrect link counts
• Duplicate blocks
• Incorrect block counts
• Bad inodes
• Directory inconsistencies
• Superblock issues

When problems are found, fsck can attempt repairs based on its understanding of the filesystem structure. While effective, it’s important to understand that fsck focuses on structural integrity rather than file content recovery.

When to Run fsck

FreeBSD is designed to maintain filesystem integrity under normal operations. Several scenarios warrant running fsck:

1. After Improper Shutdown: If your system crashes or loses power unexpectedly, the boot process will automatically run fsck on the next startup.

2. When Filesystem Problems Are Suspected: Strange behavior like files disappearing, permission issues, or “stale NFS file handle” errors might indicate filesystem corruption.

3. During Boot Problems: If your system won’t boot properly and reports filesystem errors.

4. As Preventive Maintenance: Running periodic checks on non-root filesystems can help catch and address minor issues before they become serious.

5. After Hardware Issues: Disk errors, failing hardware, or other storage-related issues may necessitate filesystem checks.

Running fsck on FreeBSD

Basic Usage

The basic syntax for running fsck is:

fsck [options] filesystem

Where filesystem can be a device name (such as /dev/da0s1a) or a mount point (such as /usr).

Common Options

• -p: “Preen” mode - automatically fixes common inconsistencies without user intervention
• -y: Assume “yes” to all questions (non-interactive mode)
• -n: Assume “no” to all questions (report only, don’t make changes)
• -f: Force checking even if the filesystem appears clean
• -v: Verbose output

Checking the Root Filesystem

The root filesystem requires special handling because it’s typically mounted when FreeBSD is running. To check the root filesystem:

1. During the Boot Process: FreeBSD automatically checks the root filesystem during boot if necessary.

2. In Single-User Mode:

   # reboot
   

   At the boot menu, select “Boot FreeBSD in single user mode” or press “4”. Once in single-user mode:

   # fsck -p /
   

3. Using a Live Environment: Boot from FreeBSD installation media and select the “Live CD” option or “Shell” to access a command prompt without mounting local disks.

Checking Non-Root Filesystems

For non-root filesystems, you’ll need to unmount them before checking:

# umount /dev/da0s1e
# fsck -f /dev/da0s1e

Replace /dev/da0s1e with your specific device.

Understanding fsck Output

When running fsck, you’ll see output like:

** /dev/da0s1a
** Last Mounted on /
** Phase 1 - Check Blocks and Sizes
** Phase 2 - Check Pathnames
** Phase 3 - Check Connectivity
** Phase 4 - Check Reference Counts
** Phase 5 - Check Cyl groups
123 files, 12345 used, 54321 free

This indicates the five phases fsck goes through:

1. Check Blocks and Sizes: Verifies inode information like size, format, and block allocation.
2. Check Pathnames: Examines directories for correctness.
3. Check Connectivity: Ensures all directories are connected to the filesystem hierarchy.
4. Check Reference Counts: Verifies link counts are correct.
5. Check Cylinder Groups: Checks block and inode maps for consistency.

If issues are found, fsck will report them and, depending on your options, may prompt for repair actions or automatically fix them.

Advanced fsck Usage

Setting Filesystem Parameters

FreeBSD’s implementation of fsck allows you to tweak parameters that affect how filesystems are checked. These are typically set in /etc/fstab:

# Device        Mountpoint      FStype  Options     Dump    Pass
/dev/da0s1a     /               ufs     rw          1       1
/dev/da0s1e     /var            ufs     rw          2       2

The last column (Pass) tells fsck in what order to check filesystems:

• 0: Don’t check
• 1: Check first (typically root filesystem)
• 2: Check after pass 1 filesystems

Background fsck with Soft Updates

FreeBSD’s UFS2 with Soft Updates allows for background fsck operation. When a filesystem using Soft Updates is marked for checking, the system can mount it for use immediately while consistency checking happens in the background.

To enable this feature, add the background keyword to the options field in /etc/fstab:

/dev/da0s1e     /var            ufs     rw,softdep,background     2       2

Using fsck_ffs Directly

FreeBSD’s fsck is actually a front-end to filesystem-specific checkers. For UFS/FFS filesystems, you can use fsck_ffs directly with additional options:

# fsck_ffs -c 2 /dev/da0s1d

This example sets the conversion level for old filesystems to 2.

Dealing with Serious Filesystem Problems

When confronted with serious filesystem corruption, consider these approaches:

Multiple Passes

Sometimes, a single fsck run can’t fix all problems. Running fsck multiple times can help resolve cascading issues:

# fsck -y /dev/da0s1e
# fsck -y /dev/da0s1e

Using Alternate Superblocks

If the primary superblock is damaged, fsck can use alternate superblocks:

# fsck_ffs -b 32 /dev/da0s1e

This uses the backup superblock at sector 32.

To find alternate superblock locations:

# newfs -N /dev/da0s1e

Data Recovery

When fsck can’t repair a filesystem or you’re concerned about data loss:

1. Create a byte-for-byte copy of the partition:

   # dd if=/dev/da0s1e of=/path/to/backup bs=64k
   

2. Work on the copy rather than the original:

   # mdconfig -a -t vnode -f /path/to/backup -u 0
   # fsck -y /dev/md0
   

Best Practices for Filesystem Maintenance

1. Regular Backups: The best defense against filesystem corruption is having current backups.

2. Use UFS with Soft Updates: This provides filesystem consistency and minimizes the need for full fsck runs.

3. Consider Using Journaling: FreeBSD’s UFS can use journaling (gjournal) to improve recovery from crashes.

4. Consider ZFS: For critical data, ZFS offers built-in data integrity features that go beyond what fsck can provide.

5. Proper Shutdowns: Always shut down your FreeBSD system properly to avoid filesystem inconsistencies.

6. Monitor SMART Data: Use smartctl from the smartmontools package to monitor drive health and anticipate failures.

7. Update FreeBSD Regularly: Kernel and filesystem improvements are regularly added to FreeBSD.

Conclusion

The fsck utility is a crucial tool in maintaining filesystem integrity on FreeBSD systems. By understanding how and when to use it, you can ensure your data remains accessible and your systems stable. While newer technologies like ZFS offer advanced integrity features, fsck remains essential for UFS filesystems that form the backbone of many FreeBSD installations.

Regular maintenance, combined with good backup practices, will help keep your FreeBSD systems running smoothly and protect your valuable data from corruption or loss.