FreeBSD GPT Data Disk Layouts with gpart and Stable Labels

Adding a data disk to FreeBSD is straightforward when the device is new and correctly identified, but partitioning commands operate on whole providers and can destroy access to existing data. A safe workflow starts by proving which disk is the intended target, then creates a GPT partition aligned for modern media, formats only that partition, mounts it by a stable label, and records the final layout for recovery. This procedure is for a new, dedicated data disk; it is not a recipe for repartitioning a boot drive or preserving unknown contents.

FreeBSD’s Handbook recommends GPT when it is available and shows the gpart workflow for creating an aligned partition, formatting it, and mounting it. The advantage of a partition label is operational stability: device names such as ada1 can change when drives or controllers are added, while a GPT label appears under /dev/gpt/ and can be referenced from /etc/fstab.

Scope and preflight checks

Run these commands as root or through sudo from an administrative shell. Replace ada1 with the device you have independently identified. It is only an example; it is not a safe default for every machine. Never paste a partitioning sequence before checking the provider name, model, serial number, capacity, current mounts, and whether the device contains data you need.

geom disk list
gpart show -p
mount
swapinfo

geom disk list reports disk-provider properties such as model, serial, and capacity. gpart show -p presents existing partition tables and includes partition provider names. mount and swapinfo help catch a disk already in use as a mounted filesystem or swap device. Correlate this output with hardware inventory or the hypervisor’s disk assignment. A familiar name such as ada1 is not proof of identity, especially when USB devices, controllers, or virtual disks may enumerate differently after a reboot.

If the provider already contains a partition scheme, stop and inspect it before changing anything. Do not use gpart create merely to make the output look clean: creating a new scheme replaces existing partition metadata. If the disk is not blank, determine ownership, take an appropriate data backup, and plan a migration or recovery procedure instead. The commands below are intentionally limited to an unused whole disk dedicated to new data.

Create the GPT and aligned UFS partition

For a confirmed blank disk, create a GPT and one UFS partition with a human-readable GPT label:

gpart create -s GPT ada1
gpart add -t freebsd-ufs -a 1M -l appdata ada1
gpart show -lp ada1
gpart list ada1

gpart create -s GPT initializes a GUID Partition Table on the provider. gpart add creates a partition of type freebsd-ufs, asks GEOM to align its start and size to one mebibyte boundaries, and assigns the GPT label appdata. The Handbook demonstrates one-megabyte alignment for a new data disk. Alignment is intended to avoid making modern disks or storage layers split requests across larger physical blocks or stripes; it does not guarantee a particular performance improvement for every device.

The -l option labels the GPT partition. If the system already has a partition with that label, choose a distinct name rather than creating ambiguity. FreeBSD exposes GPT labels beneath /dev/gpt/; after GEOM has created the provider, confirm the actual path and metadata before formatting:

ls -l /dev/gpt
gpart show -lp ada1

Do not assume the partition number will always be p1 when a disk already had a table. If a device node does not appear, investigate GEOM metadata and the command’s output rather than substituting a guessed path. On a freshly initialized disk with one partition, the provider commonly appears as /dev/ada1p1, and its label as /dev/gpt/appdata.

Format only the new partition

Formatting writes filesystem metadata and makes prior contents on that partition inaccessible as a UFS filesystem. Confirm that /dev/gpt/appdata resolves to the newly created partition, not another disk, and then create UFS with soft updates enabled:

newfs -U /dev/gpt/appdata

The -U option enables soft updates. This example creates a UFS filesystem; it does not create a ZFS pool, mirror, or redundant storage. A single UFS partition on one disk has a single-disk failure domain. If the data requires redundancy, snapshots, checksums, or replication, design that storage layer separately instead of assuming GPT provides it.

After newfs completes, inspect its output and the resulting provider. Then create a mount point and mount the filesystem:

mkdir -p /srv/appdata
mount /dev/gpt/appdata /srv/appdata
df -h /srv/appdata
mount | grep ' /srv/appdata '

df verifies that a mounted filesystem reports the expected capacity; the mount table verifies the source and target. If either result differs from expectation, stop before placing application data there. For services, set directory ownership and permissions deliberately after mounting, because permissions applied to the underlying mount-point directory are hidden when a filesystem is mounted over it.

Persist the mount using the GPT label

Use the label rather than a transient disk number in /etc/fstab:

/dev/gpt/appdata  /srv/appdata  ufs  rw  2  2

The final fields are the dump and filesystem-check pass settings used by fstab; use values appropriate for the host’s storage policy. A UFS data filesystem commonly uses pass 2 so it is checked after the root filesystem during a full boot check. Sites with different boot or filesystem-check policies should follow their local conventions.

Before rebooting, test the entry without a system restart. Unmount the filesystem only if no process is using it, then mount by its configured mount point:

fstat -f /srv/appdata
umount /srv/appdata
mount /srv/appdata
mount | grep ' /srv/appdata '

If umount reports the filesystem is busy, identify and stop the owning process through the service’s normal procedure; do not force an unmount on a live data volume. Verify that the mount command resolves /dev/gpt/appdata and that the target is /srv/appdata. A successful manual mount confirms that the label and fstab line work in the current environment, though it does not replace a planned reboot test on a maintenance window.

Save the partition table and document the change

After the layout is confirmed, save a gpart backup to a location outside the new disk:

gpart backup ada1 > /root/ada1-gpt-2026-10-03.backup
chmod 600 /root/ada1-gpt-2026-10-03.backup

The gpart backup output is a representation intended for gpart restore; it is not a filesystem backup and does not contain file data. Copy it to protected system configuration backup storage, and record the disk’s model, serial, purpose, mount point, filesystem type, label, and relevant fstab entry in the host’s inventory. A partition-table backup is useful only if it remains available after disk failure and if recovery is tested carefully.

For a disk that already had a partition scheme before a planned change, capture and verify a backup before making modifications, and preserve application data separately. Do not overwrite an existing backup file without reviewing it. For a new blank disk, the post-creation backup documents the resulting layout; it does not provide a way to restore any data that was never backed up.

Troubleshoot common failures

gpart: geom 'ada1' not found: the assumed provider is wrong, the device did not attach, or the controller driver has not made it available. Recheck geom disk list and /var/run/dmesg.boot; do not retry against another guessed device.

Device busy or an existing partition table: the provider may be mounted, used as swap, or contain a scheme. Inspect mount, swapinfo, gpart show -lp, and GEOM status. Do not destroy the scheme to silence the error.

/dev/gpt/appdata is missing: verify the label in gpart show -lp and gpart list, check for duplicate or mistyped labels, and allow GEOM to expose the provider. Do not run newfs against a similarly named raw disk as a workaround.

The mount works now but fails at boot: confirm the exact /etc/fstab source, filesystem type, mount point, and pass fields. Verify that the disk is present early enough in the boot sequence and that no other filesystem already uses the same label. A label avoids dependence on ada1 numbering but cannot compensate for a failed disk or unavailable controller.

Capacity is smaller than expected: check the partition size with gpart show -lp and the filesystem capacity with df -h. A partition table’s displayed size, the filesystem’s usable space, and vendor decimal capacity are not identical units. Do not resize until confirming that the disk contains no partition or filesystem data that would be overwritten.

Operational checklist

Before using the volume for application state, verify all of the following:

The physical or virtual disk identity was confirmed independently from its provider name.
The target was blank or its existing data was intentionally migrated and backed up.
GPT metadata, partition type, alignment, and label match the approved layout.
UFS was created only on the new labeled partition, not on the whole disk.
The mount source resolves through /dev/gpt/appdata, and the correct filesystem is mounted at /srv/appdata.
Ownership, permissions, monitoring, and backup policy are set for the consuming service.
A gpart backup file is stored separately from the new disk and included in configuration recovery.

The core safety principle is to separate identification, metadata changes, filesystem creation, and persistence into distinct checks. gpart makes partitioning flexible, while GPT labels make a system less dependent on enumeration order. Neither removes the need to confirm the target before writing or to maintain an independent backup of data.

Related:

Sources: