Skip to content
FreeBSDHow-To Published Updated 8 min readViews unavailable

Growing a FreeBSD UFS Filesystem After a Disk Expansion

A careful FreeBSD UFS expansion runbook: verify new disk capacity, grow the correct GPT partition, run growfs, and validate mounted space safely.

Increasing a virtual disk or storage LUN does not automatically enlarge the filesystem stored on it. FreeBSD exposes the work as a sequence of distinct layers: the provider must report the new capacity, a partition table may need its backup metadata relocated, the correct UFS partition must be expanded into contiguous free space, and growfs must then enlarge the filesystem inside that provider. Skipping a layer can leave capacity unused; changing the wrong layer can destroy a partition layout.

This procedure is specifically about UFS. A ZFS pool and vdev have different expansion commands and behavior. Do not run growfs against a ZFS provider, and do not assume that a growing virtual disk implies ZFS automatically consumes its new space. First identify the filesystem and the complete device path with mount, df -T, gpart show -p, and the relevant GEOM labels. If the filesystem sits behind GELI, a mirror, multipath, or another GEOM class, each layer has its own capacity and resize procedure.

Establish a recoverable baseline

Before modifying storage, confirm an external backup exists and that the recovery method has been tested. A snapshot on the same disk is not a substitute for an independent copy if the operation targets that disk. Record the provider name, GPT partition index, filesystem mountpoint, current sizes, GPT backup, fstab row, and the virtualization or SAN change that increased the device. Keep a console or out-of-band session available if the root filesystem or boot disk is involved.

Start with read-only inspection:

freebsd-version -kru
gpart show -p
geom disk list
mount
df -hT

Map the mounted filesystem to its actual provider, then confirm that the provider is the one whose capacity was increased. Device names such as ada0 or da0 are not interchangeable with a partition name such as ada0p2. Labels can help identify a filesystem, but verify their current mapping with glabel status, gpart show, and mount output before making a change.

The storage layer must already have recognized the expanded capacity. On virtualized and SAN systems, the hypervisor or array change may require a rescan or reprobe using platform-specific procedures. FreeBSD cannot allocate sectors the provider does not report. If geom disk list and gpart show still report the old size, stop at the provider layer and resolve discovery there rather than running growfs.

Repair GPT metadata and find contiguous space

After a GPT disk grows, its backup table may remain at the former end of the device. gpart show can mark the table CORRUPT for this specific reason. Compare the reported provider size and backup-header location with the change record. If the only discrepancy is the stale backup GPT location after capacity growth, the Handbook documents gpart recover to relocate it. Do not use this command as a general repair for an unexplained damaged partition table.

Once the table is consistent, inspect the exact free-space map. A partition can be extended only into adjacent contiguous free sectors. If swap or another partition lies after the UFS partition, the free capacity may not touch the filesystem partition. Resizing the partition table while a filesystem is mounted has data-loss risk. For a root filesystem or a layout requiring partitions to be moved or removed, boot a release-appropriate live environment, ensure the target filesystem is unmounted, and follow a reviewed layout-specific plan. Do not toggle GEOM safety flags on a live production root just to force an online partition change.

Use stable inventory and a reviewed partition index. A command such as gpart resize -i N PROVIDER is schematic: N must be the verified UFS partition number, and the provider must be the correct whole disk. If the intended target is not the last partition, determine how every following partition and any swap area will be preserved before running a resize. The partition operation changes only the partition boundary; it does not resize UFS.

For a table with a single UFS partition and contiguous trailing free space, the partition can be enlarged to the approved end boundary. Avoid blindly using “all remaining space” if the design reserves room for swap, another filesystem, or future metadata. After resizing, inspect gpart show again and confirm the expected start sector, new size, type, label, and remaining free space before proceeding.

Grow UFS only after its provider is larger

The growfs utility expands an existing UFS filesystem to use a larger containing partition or slice. The FreeBSD manual requires extending that partition or slice first. The filesystem remains at its old size until growfs updates its own metadata. On current supported FreeBSD releases, a UFS filesystem may be grown while mounted; that does not make the preceding partition-table operation risk-free or universally online-safe.

Use the filesystem mountpoint or the verified special device, and review growfs output before confirming the proposed old and new sizes. A typical interactive command is:

growfs /srv/data
df -h /srv/data
mount | grep '/srv/data'

The exact mountpoint is illustrative. Do not substitute a device from a different disk. growfs will ask for confirmation when it detects a mounted writable filesystem and may temporarily suspend writes during expansion. Schedule the operation when that pause is acceptable. Keep the terminal attached until it completes and preserve its complete output in the change record.

The -N option prints proposed filesystem parameters without enlarging the filesystem. It is a planning aid, not a complete simulation: the manual documents a read operation that may yield unexpected data in test mode and is therefore skipped. Do not treat an apparent successful -N run as proof that the actual writes cannot fail. The -y option automatically answers yes; avoid it in interactive production work because it removes the last human confirmation of the target and size.

If the filesystem is not mounted, the command can target the special device, but the filesystem must be in a state suitable for modification. Confirm the filesystem type and check its health using the release’s fsck_ffs and growfs guidance. Never run a repair or consistency check against a mounted writable UFS filesystem. If the maintenance plan requires an offline run, unmount the filesystem and follow the documented offline sequence.

Verify each layer after the operation

After the tool returns successfully, verify both the partition boundary and the filesystem-reported capacity. gpart show should show the intended expanded partition, while df should show the mountpoint’s larger size. Compare the exact device and mountpoint, not only the aggregate root filesystem. Run a small controlled create/read/remove test in the target filesystem, then inspect logs and service health. An extra partition of free sectors is not evidence that UFS grew.

If the system uses fstab, confirm that the persistent identifier still resolves to the same provider and that the mountpoint remains correct. A partition expansion normally preserves the provider identity, but manual table reconstruction, label changes, or device replacement can invalidate configuration. Do not rewrite fstab merely because a size changed.

For a root UFS filesystem, confirm that the boot provider, mount output, and expected filesystem are consistent before reboot. Keep a console session and a tested rescue image. For a data volume, validate application-level reads and writes and confirm that backup, quota, and monitoring systems now see the intended capacity. A larger filesystem can expose storage pressure elsewhere, such as larger backup windows or quota thresholds.

Failure cases and rollback boundaries

If gpart reports the disk still has its old size, the problem is provider discovery, not UFS. If gpart reports a corrupt GPT after a disk expansion, determine whether the backup GPT simply remains at the old end before using gpart recover. If the intended free space is not contiguous, do not use a different partition index or delete a partition by guesswork. Stop and redesign the layout with a backup and offline recovery path.

If growfs reports that the partition did not grow, compare the provider and partition sizes and verify the exact special file. If it cannot open the filesystem, inspect whether it is UFS and whether it is mounted or busy as expected. If the filesystem size remains unchanged after the command, retain the output and do not repeat blindly; first establish whether the operation completed and what size its superblock now reports.

Capacity expansion is generally not a reversible transaction. Shrinking UFS is not the inverse of growfs, and shrinking a partition below the filesystem’s recorded size can make data inaccessible. The rollback plan should therefore be restore-from-backup or attach a known-good replacement, not “resize it back.” Verify the backup before starting, capture each layer’s before-state, and perform the work in provider-to-filesystem order.

Production acceptance requires: confirmed provider capacity, consistent partition metadata, contiguous space assigned only to the intended partition, successful growfs completion, matching gpart and df output, a controlled data test, and a documented recovery path. Separating the storage layers keeps the operation understandable and prevents a successful partition edit from being mistaken for a completed filesystem expansion.

Related:

Sources:

Comments