FreeBSD Manual Pages
GEOM(4) FreeBSD Kernel Interfaces Manual GEOM(4) NAME GEOM -- modular disk I/O request transformation framework. DESCRIPTION The GEOM framework provides an infrastructure in which modules can per- form transformations on disk I/O requests on their path from the upper kernel to the device drivers and back. Transformations in a GEOM context range from the simple geometric dis- placement performed in typical disklabel modules over RAID algorithms and device multipath resolution to full blown cryptographic protection of the stored data. Compared to traditional "volume management", GEOM differs from most and in some cases all previous implementations in the following ways: +o GEOM is extensible. It is trivially simple to write a new class of transformation and it will not be given stepchild treatment. If someone for some reason wanted to mount IBM MVS diskpacks, a class recognizing and configuring their VTOC information would be a trivial matter. +o GEOM is topologically agnostic. Most volume management implementa- tions have very strict notions of how classes can fit together, very often one fixed hierarchy is provided for instance subdisk - plex - volume. Being extensible means that new transformations are treated no differ- ently than existing transformations. Fixed hierarchies are bad because they make it impossible to express the intent efficiently. In the fixed hierarchy above it is not possible to mirror two physical disks and then partition the mirror into subdisks, instead one is forced to make subdisks on the physical volumes and to mirror these two and two resulting in a much more complex configuration. GEOM on the other hand does not care in which order things are done, the only restriction is that cycles in the graph will not be allowed. TERMINOLOGY and TOPOLOGY Geom is quite object oriented and consequently the terminology borrows a lot of context and semantics from the OO vocabulary: A "class", represented by the data structure g_class implements one par- ticular kind of transformation. Typical examples are MBR disk partition, BSD disklabel, and RAID5 classes. An instance of a class is called a "geom" and represented by the data structure "g_geom". In a typical i386 FreeBSD system, there will be one geom of class MBR for each disk. A "provider", represented by the data structure "g_provider", is the front gate at which a geom offers service. A provider is "a disk-like thing which appears in /dev" - a logical disk in other words. All providers have three main properties: name, sectorsize and size. A "consumer" is the backdoor through which a geom connects to another geom provider and through which I/O requests are sent. The topological relationship between these entities are as follows: +o A class has zero or more geom instances. +o A geom has exactly one class it is derived from. +o A geom has zero or more consumers. +o A geom has zero or more providers. +o A consumer can be attached to zero or one providers. +o A provider can have zero or more consumers attached. All geoms have a rank-number assigned, which is used to detect and pre- vent loops in the acyclic directed graph. This rank number is assigned as follows: 1. A geom with no attached consumers has rank=1 2. A geom with attached consumers has a rank one higher than the high- est rank of the geoms of the providers its consumers are attached to. SPECIAL TOPOLOGICAL MANEUVRES In addition to the straightforward attach, which attaches a consumer to a provider, and dettach, which breaks the bond, a number of special toplog- ical maneuvres exists to facilitate configuration and to improve the overall flexibility. TASTING is a process that happens whenever a new class or new provider is created and it is the class' chance to automatically configure an instance on providers, which it recognize as its own. A typical example is the MBR disk-partition class which will look for the MBR table in the first sector and if found and validated it will instantiate a geom to multiplex according to the contents of the MBR. A new class will be offered to all existing providers in turn and a new provider will be offered to all classes in turn. Exactly what a class does to recognize if it should accept the offered provider is not defined by GEOM, but the sensible set of options are: +o Examine specific data structures on the disk. +o Examine properties like sectorsize or mediasize for the provider. +o Examine the rank number of the provider's geom. +o Examine the method name of the provider's geom. ORPHANIZATION is the process by which a provider is removed while it potentially is still being used. When a geom makes a provider an orphan, all future I/O requests will "bounce" on the provider with an error code set by the geom. Any con- sumers attached to the provider will receive notification about the orph- anization and need to take appropriate action. A geom which came into being as a result of a normal taste operation should selfdestruct unless it has a way to keep functioning. Geoms like disklabels and stripes should therefore selfdestruct whereas RAID5 or mirror geoms can continue to function as long as they do not loose quo- rum. When a provider is orphaned, this does not result in any immediate change in the topology, any attached consumers are still attached, any opened paths are still open, it is the responsibility of the geoms above to close and dettach as soon as this can happen. The typical scenario is that a device driver notices a disk has gone and orphans the provider for it. The geoms on top receive the orphanization event and orphan all their providers in turn. Providers, which are not attached, are destroyed right away. Eventually at the toplevel the geom which interfaces to the DEVFS received an orphan event on its consumer and it calls destroy_dev(9) and does an explicit close if the device was open and then dettaches its consumer. The provider below is now no longer attached to and can be destroyed, if the geom has no more providers it can dettach its consumer and selfdestruct and so the carnage passes back down the tree, until the original provider is dettached from and it can be destroyed by the geom serving the device driver. While this approach seems byzantine, it does provide the maximum flexi- bility in handling disappearing devices. SPOILING is a special case of orphanization used to protect against stale metadata. It is probably easiest to understand spoiling by going through an example. Imagine a disk, "da0" on top of which a MBR geom provides "da0s1" and "da0s2" and on top of "da0s1" a BSD geom provides "da0s1a" through "da0s1e", both the MBR and BSD geoms have autoconfigured based on data structures on the disk media. Now imagine the case where "da0" is opened for writing and those data structures are modified or overwritten: Now the geoms would be operating on stale metadata unless some notification system can inform them otherwise. To avoid this situation, when the open of "da0" for write happens, all attached consumers are told about this, and geoms like MBR and BSD will selfdestruct as a result. When "da0" is closed again, it will be offered for tasting again and if the data struc- tures for MBR and BSD are still there, new geoms will instantiate them- selves anew. Now for the fine print: If any of the paths through the MBR or BSD module were open, they would have opened downwards with an exclusive bit rendering it impossible to open "da0" for writing in that case and conversely the requested exclu- sive bit would render it impossible to open a path through the MBR geom while "da0" is open for writing. From this it also follows that changing the size of open geoms can only be done through their cooperation. Finally: the spoiling only happens when the write count goes from zero to non-zero and the retasting only when the write count goes back to zero. INSERT/DELETE are a very special operation which allows a new geom to be instantiated between a consumer and a provider attached to each other and to remove it again. To understand the utility of this, imagine a provider with being mounted as a file system. Between the DEVFS geoms consumer and its provider we insert a mirror module which configures itself with one mirror copy and consequently is transparent to the I/O requests on the path. We can now configure yet a mirror copy on the mirror geom, request a synchroniza- tion, and finally drop the first mirror copy. We have now in essence moved a mounted file system from one disk to another while it was being used. At this point the mirror geom can be deleted from the path again, it has served its purpose. CONFIGURE is the process where the administrator issues instructions for a particular class to instantiate itself. There are multiple ways to express intent in this case, a particular provider can be specified with a level of override forcing for instance a BSD disklabel module to attach to a provider which was not found palatable during the TASTE operation. Finally IO is the reason we even do this: it concerns itself with sending I/O requests through the graph. I/O REQUESTS represented by struct bio, originate at a consumer, are scheduled on its attached provider, and when processed, returned to the consumer. It is important to realize that the struct bio which enters throuh the provider of a particular geom does not "come out on the other side". Even simple transformations like MBR and BSD will clone the struct bio, modify the clone, and schedule the clone on their own con- sumer. Note that cloning the struct bio does not involve cloning the actual data area specified in the IO request. In total five different IO requests exist in GEOM: read, write, delete, format, get attribute, and set attribute. Read and write are self explanatory. Delete indicates that a certain range of data is no longer used and that it can be erased or freed as the underlying technology supports. Tech- nologies like flash adaptation layers can arrange to erase the relevant blocks before they will become reassigned and cryptographic devices may want to fill random bits into the range to reduce the amount of data available for attack. It is important to recognize that a delete indication is not a request and consequently there is no guarantee that the data actually will be erased or made unavailable unless guaranteed by specific geoms in the graph. If "secure delete" semantics are required, a geom should be pushed which converts delete indications into (a sequence of) write requests. Get attribute and set attribute supports inspection and manipulation of out-of-band attributes on a particular provider or path. Attributes are named by ascii strings and they will be discussed in a separate section below. (stay tuned while the author rests his brain and fingers: more to come.) HISTORY This software was developed for the FreeBSD Project by Poul-Henning Kamp and NAI Labs, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS research program. The first precursor for GEOM was a gruesome hack to Minix 1.2 and was never distributed. An earlier attempt to implement a less general scheme in FreeBSD never succeeded. AUTHORS Poul-Henning Kamp <phk@FreeBSD.org> FreeBSD 11.1 March 27, 2002 FreeBSD 11.1
NAME | DESCRIPTION | TERMINOLOGY and TOPOLOGY | SPECIAL TOPOLOGICAL MANEUVRES | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=geom&sektion=4&manpath=FreeBSD+5.0-RELEASE>