Two new disks sit in a server that has not yet been asked to do anything. The administrator wants them mirrored, wants a partition table on the mirror, and wants the partition that will hold the customer data encrypted. On FreeBSD that comes to four lines, each of which takes the device the line before it has just made:
gmirror label -v gm0 ada0 ada1
gpart create -s gpt mirror/gm0
gpart add -t freebsd-ufs -l data mirror/gm0
geli init -s 4096 /dev/gpt/data
After geli attach, the encrypted volume appears as /dev/gpt/data.eli, and geom -t prints the whole arrangement as a tree, from the two disks at the bottom to the encrypted partition at the top.
A careful administrator will want to know what the mirror does when a disk misbehaves, before anybody's invoices live on it. That is one more layer. gnop create -w 50 ada1 lays a transparent device called ada1.nop over the second disk, and half of the writes sent to it fail on purpose. Build the mirror on ada0 and ada1.nop instead, and the test rig is the production layout with one extra class in it; when the test is done, the class goes and the layout stays, which makes the whole exercise a doddle.
The framework underneath is called GEOM. Poul-Henning Kamp wrote it with NAI Labs, the research arm of Network Associates, under a DARPA contract for the CHATS research programme, and committed it on 11 March 2002 with a modest explanation: "First commit of the GEOM subsystem to make it easier for people to test and play with this." FreeBSD 5.0 shipped it as the default on 19 January 2003, and the announcement called it "the extensible and flexible storage framework". Most of the classes administrators use today came afterwards from Pawel Jakub Dawidek, the first of them gnop in May 2004.
Two words for every layer
GEOM describes storage with a short vocabulary, and the whole design rests on it. A class is one kind of transformation, such as a mirror or a partition scheme. A running instance of a class is a geom. A geom offers its service through a provider, which geom(4) defines with some economy as "a disk-like thing which appears in /dev", and it reaches the layer below through a consumer, "the backdoor through which a geom connects to another geom provider".
Every class speaks those two words and no others. A mirror consumes two providers and offers one. A partition scheme consumes one and offers several. An encryption class consumes one and offers one that looks identical from above, except that what reaches the platter is ciphertext. Because every layer has the same shape on both sides, any layer can sit on any other, which is exactly what a pipe does for programs that read text and write text.
According to geom(4), most volume managers of 2002 had one fixed hierarchy, and in such a hierarchy "it is not possible to mirror two physical disks and then partition the mirror into subdisks". GEOM imposes a single rule: "cycles in the graph will not be allowed." Each geom carries a rank one higher than the highest rank beneath it, and a loop would need a geom to sit above itself, which the rank makes impossible to arrange.
Even ZFS plays by the same rules. OpenZFS on FreeBSD declares its own GEOM class in vdev_geom.c, names its geoms zfs::vdev, and attaches consumers to disks with g_attach() like any other class. The pool that most FreeBSD machines boot from is, as far as the storage stack is concerned, one more tenant of the graph.
When a disk leaves the room
Storage shows its quality at the moment something changes, and GEOM has three rules for that moment.
The first rule, tasting, is how the graph builds itself. Whenever a provider appears, every class is offered a look at it, and whenever a class loads, it is offered every provider. gmirror keeps its metadata in the last sector of each component, so when the two disks come up at boot, the mirror class recognises its own sectors and reassembles gm0 without a line of configuration. The partition class then tastes the mirror, finds the GPT, and offers gpt/data, and so on up the tree.
The second, spoiling, is how the graph notices that somebody has written over its foundations. When a provider is opened for writing from outside the classes that tasted it, every geom built from its metadata is told and quietly takes itself apart; when the writer closes, the provider is tasted afresh. The manual pins the moment down: "the spoiling only happens when the write count goes from zero to non-zero and the retasting happens only when the write count goes from non-zero to zero."
The third, orphanization, deals with a disk that simply goes away. The driver orphans its provider, every request to it bounces with an error, and the news travels upwards "until all relevant pieces of the tree have heard the bad news". A partition geom on a vanished disk destroys itself. A mirror geom loses one consumer, keeps its own provider, and carries on with the disk it still has, which is the whole point of having bought two.
The requests themselves are cheap to pass along. A struct bio entering a geom does not come out the other side. The class sends a modified clone down instead, and "cloning the struct bio does not involve cloning the actual data area". Since October 2013, when Alexander Motin merged direct dispatch, a request travels down in the thread that sent it, provided both ends have declared that they can take it. The queue of the g_down thread is kept for the classes that want it and for the moment the kernel stack runs low.
The same layers, from separate parts
On Linux the same four lines need two frameworks in the kernel and several projects in userland. The software RAID lives in md, driven by mdadm; encryption and logical volumes live in device-mapper, driven by cryptsetup and by lvm2, which also carries dmsetup; partition tables are read by a third piece of code in the block layer. Where the two frameworks have to meet, a target was written for the purpose: dm-raid, whose documentation describes it as "a bridge from DM to MD".
Administrators know every one of these parts, and they know just as well that each brings a command and a metadata format of its own, which makes the set fiddly to combine. Counted like GEOM, mdadm alone comes to 47,692 lines. The two userland projects around device-mapper, lvm2 with 152,077 and cryptsetup with 55,693, bring the total to 255,462 lines for the jobs that the GEOM userland does in 8,632. In the kernel, the core of device-mapper is 6,249 lines and md.c another 8,300, beside 3,017 for the core of GEOM.
The FreeBSD tree even keeps a class for the neighbours. geom_linux_lvm, added by Andrew Thompson in February 2008, reads Linux LVM metadata and offers each linear logical volume as a provider, so a disk carried over from a Linux machine shows up as a set of devices like any other.
The sheet
Efficiency. FreeBSD 15.1 (releng/15.1, commit bb03631), lines without comments and blank lines: the GEOM core in geom_subr.c, geom_io.c, geom_event.c, geom_kern.c, geom.h and geom_int.h comes to 3,017; all of sys/geom with its twenty class directories to 60,222. In userland, sbin/geom is 1,742, the class libraries in lib/geom 5,676 and libgeom 1,214, together 8,632. Single classes, kernel plus userland: gmirror 4,362 plus 426, geli 4,257 plus 1,600, gnop 896 plus 59. For comparison, Linux 7.3 (commit c03c1a1): the device-mapper core 6,249, md.c 8,300, block/partitions 4,708; in userland 255,462 across mdadm (47,692), lvm2 (152,077) and cryptsetup (55,693), each at its head of 17 to 19 November 2026.
Security. Of the four questions: the geom command and its class tools need root; the framework takes no data from the network, with one exception in GEOM Gate, whose ggatec daemon forwards requests to another machine; tasting parses on-disk metadata from every provider that appears, which is why kern.geom.notaste exists; and the classes run in the kernel without a long-running privileged process beside them. Of 750 FreeBSD security advisories, two carry a GEOM tool in their name, FreeBSD-SA-21:14.ggatec and FreeBSD-SA-23:01.geli, and both concern the userland utility. Neither concerns the framework.
Longevity. First commit on 11 March 2002, default since FreeBSD 5.0 on 19 January 2003, 2,449 commits to sys/geom since, 162 of them to geom_subr.c. The section of geom(4) that ends with "(stay tuned while the author rests his brain and fingers: more to come.)" stood in the page of March 2002. It stands in the page of FreeBSD 15.1 with a capital S (its one change in twenty-four years), which is a long rest by any standard.
Stability. The example in gmirror(8) for FreeBSD 5.3, gmirror label -v -b split -s 2048 data da0 da1 da2, stands word for word in the page for 15.1. Five obsolete classes left in FreeBSD 13.0 (GEOM_BSD, GEOM_FOX, GEOM_MBR, GEOM_SUNLABEL and GEOM_VOL), and the manual names the class that replaces each of them.
Measured on 20 November 2026: lines counted with a script that strips C comments and blank lines, over freebsd-src releng/15.1, torvalds/linux v7.3 and the heads of the Linux userland projects; commits counted on the history of sys/geom; advisories counted on the FreeBSD advisory index; the I/O path read in geom_io.c, the ZFS class in vdev_geom.c.
The limit
Thin provisioning and caching are ZFS's job on FreeBSD. device-mapper carries targets for thin volumes, caches, integrity and deduplication. GEOM has no class for most of them, because the pool above it does that work, and a machine without ZFS goes without.
Tasting reads whatever is plugged in. When a disk from elsewhere arrives, every class reads the sectors where its own metadata would sit, unless the cautious have set kern.geom.notaste, after which the graph grows only on the administrator's word.
The class for the neighbours reads the simple case. The parser in g_linux_lvm.c says so in a comment, "only a single linear stripe is supported". Striped volumes and thin pools want copying off on Linux first, and everything linear comes across as a provider.
Unix taught programs to pass text along a pipe, and GEOM taught disks the same manners, so the order of the layers became the administrator's business and nobody else's.