Skip to content
FreeBSDDeep Dive Published Updated 4 min readViews unavailable

FreeBSD GEOM Inventory: Read Providers, Classes, and Topology Without Changing Disks

Use geom's list, status, provider lookup, and topology tree to document FreeBSD block-device layers before maintenance work.

A storage incident is the wrong moment to infer a disk layout from names alone. FreeBSD’s GEOM framework builds block-device transformations out of classes, geoms, consumers, and providers. A partition, encrypted volume, or mirror may present a device node that is not the physical disk beneath it. The administrative geom(8) utility supplies read-only views of those relationships. Its list, status, provider lookup, and tree modes answer different questions; none is a substitute for confirming which mounted filesystem or pool will be affected by a proposed change. This article concerns inventory only, on the documented FreeBSD 14.2 interface. Check the local man geom on another release before scripting its output. FreeBSD geom(8)

Begin with the class, not a guessed device

geom class list prints detailed information for geoms in an existing class. With no geom name it covers the whole class; with names it narrows the request. geom class status prints a compact status view. The class must exist in the running kernel for either command. Thus an error from an absent class is not evidence that every disk or provider disappeared. Start with a common class and record both forms:

geom disk list
geom disk status
geom part list
geom part status

The manual itself uses geom disk list as an example for printing DISK providers. list is for configuration detail; status is for a quick inventory. Do not parse the human-oriented list output as if every class shares one stable table: class-aware commands can be implemented by shared libraries in /lib/geom/, and class-specific behavior differs. A direct gclass utility may also exist, but the explicit geom class spelling makes the target class visible in a runbook. FreeBSD geom(8)

Trace one provider in context

When a device node is already known, geom -p provider-name prints detailed information about the geom that provides it. geom -t displays the hierarchy as a tree. Use both views before drawing a diagram:

geom -t
geom -p ada0
geom part list

ada0 is only an example provider name, not an instruction to select that disk on a real host. Substitute a name discovered from the host’s own inventory. The tree helps expose layering; the provider lookup helps resolve one node. A class listing provides the class-local attributes. If these disagree with a diagram in a maintenance ticket, stop and update the diagram before acting. A tree also reflects the current running system, not the intended configuration after the next boot. FreeBSD geom(8)

For a compact capture, status -s is the manual’s script-friendly form. The -g option changes the unit of status from providers to geoms; -a adds geoms without providers when paired with -g. These are distinct views. A script comparing two captures must use the same options both times, or a missing row may merely reflect a different reporting unit. An illustrative read-only capture is:

geom disk status -s
geom part status -s
geom -t

Keep timestamps and the FreeBSD release alongside the captured output. Treat -s as easier to consume than ordinary status, not a promise that class-specific columns or semantics are identical across releases. Check exit status: geom(8) documents zero for success and one for failure. Empty output and a failed command should not be conflated. FreeBSD geom(8)

Avoid state-changing verbs during discovery

The same utility also exposes load and unload for class modules. load can bring in geom_<class>.ko from kern.module_path; unload removes a loaded module. Neither belongs in a passive inventory script. Similarly, class-specific subcommands may change labels, partitions, encryption layers, or mirror state. Keep the discovery phase to list, status, -p, and -t. If a class is not present, record that fact and investigate separately instead of auto-loading it merely to make a checklist green. FreeBSD geom(8)

An inventory also has a scope boundary. GEOM describes block-device topology; it does not certify filesystem health, prove that a backup is restorable, or identify the business owner of a volume. Before a destructive operation, reconcile provider topology with mounts, pools, serial numbers, and the approved change record. Names can be reused after hardware replacement; a screenshot of yesterday’s tree is not authority to write today’s disk. The valuable habit is to make the topology explicit while every command remains read-only, then seek separate confirmation for the eventual maintenance command.

Related:

Sources:

Comments