Skip to content
FreeBSDDeep Dive Published Updated 6 min readViews unavailable

FreeBSD glabel Operations: Stable GEOM Provider Names Without Guesswork

Compare automatic and manual GEOM labels, map provider paths, and change labels safely without confusing GPT names, filesystem labels, or disk identity.

FreeBSD’s glabel(8) gives GEOM providers names that can be easier to use than probe-order-dependent device numbers. A label can make a filesystem or storage layer easier to identify in /etc/fstab, recovery notes, and monitoring. But “label” refers to several distinct mechanisms: GPT partition names, UFS filesystem labels, and GEOM LABEL providers are not interchangeable. A stable-looking path is useful only after you know which layer created it and what on-disk metadata it represents.

This guide focuses on the GEOM LABEL class and operational identity. It does not recommend relabeling a mounted production device. Start by mapping the physical disk, partition, GEOM stack, filesystem, and mount point. Then decide whether the desired identity is a partition name, a filesystem label, or an automatically tasted GEOM provider.

Map the existing storage graph first

Capture the live provider topology and mounted filesystems without changing anything:

glabel status
glabel list
gpart show -lp
geom disk list
mount

glabel status summarizes label providers and their backing providers; gpart show -lp displays partition layout and labels; mount shows which provider currently backs each mount point. Correlate model, serial number, capacity, partition index, and filesystem before making any change. /dev/label/name, /dev/gpt/name, and /dev/ufs/name can refer to different providers even when their final label text matches.

Build a simple path record such as ada2 -> ada2p2 -> label-provider -> UFS -> /srv. The exact GEOM stack can include mirror, encryption, multipath, or ZFS layers. A label on a leaf disk does not necessarily identify the filesystem consumed by the mount. Inspect the full graph with geom -t, class-specific geom ... list, gpart show, and zpool status where relevant.

Do not infer disk identity from da1 or ada0 alone. Enumeration may change with controller order or hardware replacement. Before destructive work, compare the device serial and enclosure slot with the storage inventory, then verify the target partition and mount state independently.

Automatic and manual GEOM labels

The GEOM LABEL class supports two operational styles. An automatic label stores metadata on the provider so that GEOM can taste the provider and recreate its label after boot. A manual label is configured at runtime without writing on-disk metadata; it must be recreated when needed. These behaviors have different persistence and recovery characteristics.

An automatically stored label can be created only on a provider that is safe to modify. The command writes metadata and may overwrite information at the provider’s end. It is not a harmless alias operation. Do not experiment on a disk that contains data, another GEOM class’s metadata, GPT backup structures, or an imported pool. The glabel(8) manual explicitly describes the on-disk metadata behavior; inspect its warnings and provider constraints before using a write command.

Manual labels can be useful for a short-lived lab mapping or a controlled test, but they do not survive a reboot unless recreated by a separate supported configuration. Avoid treating a manual label as durable inventory. Record its creation and removal, and ensure no mount or consumer remains before stopping the GEOM provider.

The following is a read-only inventory pattern, not a label-creation recipe:

glabel status
geom label list
ls -l /dev/label /dev/gpt /dev/ufs 2>/dev/null

The directories present depend on which providers the system has tasted. An absent /dev/label path does not prove that the physical device is missing; the relevant class may not be loaded, the metadata may be absent, or the provider may not yet be available.

Distinguish label namespaces

GPT names are stored in the partition table and commonly appear below /dev/gpt. A filesystem label is stored in filesystem metadata and may appear below /dev/ufs for UFS. GEOM labels are created by the LABEL class and can expose paths such as /dev/label/name. They are separate identity sources with different tools and write effects.

If the requirement is “mount partition X even if the disk’s device number changes,” a GPT partition label may be the appropriate path. If the requirement is “identify this UFS filesystem,” a UFS label may be more direct. If a GEOM transformation needs a named provider, a GEOM label may suit that graph. Choose the layer intentionally; do not create a second label just because a path is unfamiliar.

Duplicate names create ambiguity and operational mistakes. Before choosing a label, search all mounted and unmounted providers. Choose names that are unique within the relevant class, document the owning system and physical asset, and avoid names that could be reused by a replacement device before the old device has been retired.

Change labels only in a controlled maintenance window

For a new, empty lab provider, first verify that it is not mounted, in swap, part of a pool, or consumed by a GEOM transformation. Use glabel status, geom -t, mount, swapinfo, zpool status, and fstat to find active consumers. Back up any data and preserve existing partition metadata. If any result is ambiguous, stop and resolve the storage graph before issuing a write.

When adding a UFS label, the UFS-specific tool tunefs(8) owns that metadata. When naming a GPT partition, use gpart and verify the resulting partition path. Use glabel only for the GEOM LABEL operation documented for the intended provider. The command name similarity is not a reason to mix their procedures.

After a change, run glabel status and the matching class-specific inventory command. Then validate the full chain from backing provider to filesystem mount. A new /dev symlink alone is not evidence that the right disk was selected. For a persistent mount, test the /etc/fstab entry with the appropriate read-only or non-disruptive mount validation procedure and maintain a console path before rebooting.

Do not remove a label while a consumer is active. Unmount the filesystem cleanly, detach higher GEOM layers only with their own supported commands, confirm the provider is no longer open, and then remove or clear the label using the documented operation. Forced detach options can turn a useful busy refusal into data loss.

Failure cases and recovery evidence

If a label disappears after reboot, check whether it was manual, whether the relevant GEOM class loaded, whether the provider appeared, and whether its metadata remained intact. If multiple devices publish the same label, stop before mounting either one read-write and inspect their backing paths and serials. If /etc/fstab fails, use the console to boot into a recovery environment and identify the actual providers before editing the entry.

If a disk was replaced, preserve the old label only when the storage and recovery design explicitly calls for it. A copied or cloned label can cause duplicate paths and may make the wrong device appear to be the expected one. Clear stale identity only after data ownership, pool membership, and backup state are confirmed.

Record label class, label string, backing provider, partition scheme, device serial, filesystem type, mount point, persistence mechanism, and evidence from glabel status and the class-specific tools. This makes a future replacement or recovery decision repeatable instead of dependent on a /dev pathname remembered from the last boot.

Acceptance requires a unique label resolving to the intended backing provider, no conflicting metadata or duplicate provider, a verified mount or consumer path, and a tested recovery plan if the labeled device is absent. GEOM names improve identity only when the entire storage graph is understood.

Related:

Sources:

Comments