diff options
Diffstat (limited to 'static/freebsd/man4/geom.4 3.html')
| -rw-r--r-- | static/freebsd/man4/geom.4 3.html | 375 |
1 files changed, 0 insertions, 375 deletions
diff --git a/static/freebsd/man4/geom.4 3.html b/static/freebsd/man4/geom.4 3.html deleted file mode 100644 index 51c52e01..00000000 --- a/static/freebsd/man4/geom.4 3.html +++ /dev/null @@ -1,375 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">GEOM(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">GEOM(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">GEOM</code> — <span class="Nd">modular - disk I/O request transformation framework</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="Cd">options GEOM_CACHE</code> - <br/> - <code class="Cd">options GEOM_CONCAT</code> - <br/> - <code class="Cd">options GEOM_ELI</code> - <br/> - <code class="Cd">options GEOM_GATE</code> - <br/> - <code class="Cd">options GEOM_JOURNAL</code> - <br/> - <code class="Cd">options GEOM_LABEL</code> - <br/> - <code class="Cd">options GEOM_LINUX_LVM</code> - <br/> - <code class="Cd">options GEOM_MAP</code> - <br/> - <code class="Cd">options GEOM_MIRROR</code> - <br/> - <code class="Cd">options GEOM_MOUNTVER</code> - <br/> - <code class="Cd">options GEOM_MULTIPATH</code> - <br/> - <code class="Cd">options GEOM_NOP</code> - <br/> - <code class="Cd">options GEOM_PART_APM</code> - <br/> - <code class="Cd">options GEOM_PART_BSD</code> - <br/> - <code class="Cd">options GEOM_PART_BSD64</code> - <br/> - <code class="Cd">options GEOM_PART_EBR</code> - <br/> - <code class="Cd">options GEOM_PART_EBR_COMPAT</code> - <br/> - <code class="Cd">options GEOM_PART_GPT</code> - <br/> - <code class="Cd">options GEOM_PART_LDM</code> - <br/> - <code class="Cd">options GEOM_PART_MBR</code> - <br/> - <code class="Cd">options GEOM_RAID</code> - <br/> - <code class="Cd">options GEOM_RAID3</code> - <br/> - <code class="Cd">options GEOM_SHSEC</code> - <br/> - <code class="Cd">options GEOM_STRIPE</code> - <br/> - <code class="Cd">options GEOM_UZIP</code> - <br/> - <code class="Cd">options GEOM_VIRSTOR</code> - <br/> - <code class="Cd">options GEOM_ZERO</code></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">GEOM</code> framework provides an - infrastructure in which “classes” can perform transformations - on disk I/O requests on their path from the upper kernel to the device - drivers and back.</p> -<p class="Pp">Transformations in a <code class="Nm">GEOM</code> context range - from the simple geometric displacement performed in typical disk - partitioning modules over RAID algorithms and device multipath resolution to - full blown cryptographic protection of the stored data.</p> -<p class="Pp">Compared to traditional “volume management”, - <code class="Nm">GEOM</code> differs from most and in some cases all - previous implementations in the following ways:</p> -<ul class="Bl-bullet"> - <li><code class="Nm">GEOM</code> 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.</li> - <li><code class="Nm">GEOM</code> is topologically agnostic. Most volume - management implementations have very strict notions of how classes can fit - together, very often one fixed hierarchy is provided, for instance, - subdisk - plex - volume.</li> -</ul> -<p class="Pp">Being extensible means that new transformations are treated no - differently than existing transformations.</p> -<p class="Pp">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. - <code class="Nm">GEOM</code> 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.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="TERMINOLOGY_AND_TOPOLOGY"><a class="permalink" href="#TERMINOLOGY_AND_TOPOLOGY">TERMINOLOGY - AND TOPOLOGY</a></h1> -<p class="Pp"><code class="Nm">GEOM</code> is quite object oriented and - consequently the terminology borrows a lot of context and semantics from the - OO vocabulary:</p> -<p class="Pp">A “class”, represented by the data structure - <var class="Vt">g_class</var> implements one particular kind of - transformation. Typical examples are MBR disk partition, BSD disklabel, and - RAID5 classes.</p> -<p class="Pp">An instance of a class is called a “geom” and - represented by the data structure <var class="Vt">g_geom</var>. In a typical - i386 <span class="Ux">FreeBSD</span> system, there will be one geom of class - MBR for each disk.</p> -<p class="Pp">A “provider”, represented by the data structure - <var class="Vt">g_provider</var>, is the front gate at which a geom offers - service. A provider is “a disk-like thing which appears in - <span class="Pa">/dev</span>” - a logical disk in other words. All - providers have three main properties: “name”, - “sectorsize” and “size”.</p> -<p class="Pp">A “consumer” is the backdoor through which a geom - connects to another geom provider and through which I/O requests are - sent.</p> -<p class="Pp">The topological relationship between these entities are as - follows:</p> -<ul class="Bl-bullet"> - <li>A class has zero or more geom instances.</li> - <li>A geom has exactly one class it is derived from.</li> - <li>A geom has zero or more consumers.</li> - <li>A geom has zero or more providers.</li> - <li>A consumer can be attached to zero or one providers.</li> - <li>A provider can have zero or more consumers attached.</li> -</ul> -<p class="Pp">All geoms have a rank-number assigned, which is used to detect and - prevent loops in the acyclic directed graph. This rank number is assigned as - follows:</p> -<ol class="Bl-enum"> - <li>A geom with no attached consumers has rank=1.</li> - <li>A geom with attached consumers has a rank one higher than the highest rank - of the geoms of the providers its consumers are attached to.</li> -</ol> -</section> -<section class="Sh"> -<h1 class="Sh" id="SPECIAL_TOPOLOGICAL_MANEUVERS"><a class="permalink" href="#SPECIAL_TOPOLOGICAL_MANEUVERS">SPECIAL - TOPOLOGICAL MANEUVERS</a></h1> -<p class="Pp">In addition to the straightforward attach, which attaches a - consumer to a provider, and detach, which breaks the bond, a number of - special topological maneuvers exists to facilitate configuration and to - improve the overall flexibility.</p> -<dl class="Bl-inset"> - <dt id="TASTING"><a class="permalink" href="#TASTING"><i class="Em">TASTING</i></a></dt> - <dd>is a process that happens whenever a new class or new provider is created, - and it provides the class a chance to automatically configure an instance - on providers which it recognizes 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, will instantiate a geom to multiplex - according to the contents of the MBR. - <p class="Pp">A new class will be offered to all existing providers in turn - and a new provider will be offered to all classes in turn.</p> - <p class="Pp">Exactly what a class does to recognize if it should accept the - offered provider is not defined by <code class="Nm">GEOM</code>, but the - sensible set of options are:</p> - <ul class="Bl-bullet"> - <li>Examine specific data structures on the disk.</li> - <li>Examine properties like “sectorsize” or - “mediasize” for the provider.</li> - <li>Examine the rank number of the provider's geom.</li> - <li>Examine the method name of the provider's geom.</li> - </ul> - <p class="Pp">Tasting is controlled by the - <var class="Va">kern.geom.notaste</var> sysctl. To disable tasting, set - the sysctl to 1, to re-enable tasting, set the sysctl to 0.</p> - </dd> - <dt id="ORPHANIZATION"><a class="permalink" href="#ORPHANIZATION"><i class="Em">ORPHANIZATION</i></a></dt> - <dd>is the process by which a provider is removed while it potentially is - still being used. - <p class="Pp">When a geom orphans a provider, all future I/O requests will - “bounce” on the provider with an error code set by the - geom. Any consumers attached to the provider will receive notification - about the orphanization when the event loop gets around to it, and they - can take appropriate action at that time.</p> - <p class="Pp">A geom which came into being as a result of a normal taste - operation should self-destruct unless it has a way to keep functioning - whilst lacking the orphaned provider. Geoms like disk slicers should - therefore self-destruct whereas RAID5 or mirror geoms will be able to - continue as long as they do not lose quorum.</p> - <p class="Pp">When a provider is orphaned, this does not necessarily result - in any immediate change in the topology: any attached consumers are - still attached, any opened paths are still open, any outstanding I/O - requests are still outstanding.</p> - <p class="Pp">The typical scenario is:</p> - <p class="Pp"></p> - <ul class="Bl-bullet Bd-indent Bl-compact"> - <li>A device driver detects a disk has departed and orphans the provider - for it.</li> - <li>The geoms on top of the disk receive the orphanization event and - orphan all their providers in turn. Providers which are not attached - to will typically self-destruct right away. This process continues in - a quasi-recursive fashion until all relevant pieces of the tree have - heard the bad news.</li> - <li>Eventually the buck stops when it reaches geom_dev at the top of the - stack.</li> - <li>Geom_dev will call <a class="Xr">destroy_dev(9)</a> to stop any more - requests from coming in. It will sleep until any and all outstanding - I/O requests have been returned. It will explicitly close (i.e.: zero - the access counts), a change which will propagate all the way down - through the mesh. It will then detach and destroy its geom.</li> - <li>The geom whose provider is now detached will destroy the provider, - detach and destroy its consumer and destroy its geom.</li> - <li>This process percolates all the way down through the mesh, until the - cleanup is complete.</li> - </ul> - <p class="Pp">While this approach seems byzantine, it does provide the - maximum flexibility and robustness in handling disappearing devices.</p> - <p class="Pp">The one absolutely crucial detail to be aware of is that if - the device driver does not return all I/O requests, the tree will not - unravel.</p> - </dd> - <dt id="SPOILING"><a class="permalink" href="#SPOILING"><i class="Em">SPOILING</i></a></dt> - <dd>is a special case of orphanization used to protect against stale metadata. - It is probably easiest to understand spoiling by going through an example. - <p class="Pp">Imagine a disk, <span class="Pa">da0</span>, on top of which - an MBR geom provides <span class="Pa">da0s1</span> and - <span class="Pa">da0s2</span>, and on top of - <span class="Pa">da0s1</span> a BSD geom provides - <span class="Pa">da0s1a</span> through <span class="Pa">da0s1e</span>, - and that both the MBR and BSD geoms have autoconfigured based on data - structures on the disk media. Now imagine the case where - <span class="Pa">da0</span> 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.</p> - <p class="Pp">To avoid this situation, when the open of - <span class="Pa">da0</span> for write happens, all attached consumers - are told about this and geoms like MBR and BSD will self-destruct as a - result. When <span class="Pa">da0</span> is closed, it will be offered - for tasting again and, if the data structures for MBR and BSD are still - there, new geoms will instantiate themselves anew.</p> - <p class="Pp">Now for the fine print:</p> - <p class="Pp">If any of the paths through the MBR or BSD module were open, - they would have opened downwards with an exclusive bit thus rendering it - impossible to open <span class="Pa">da0</span> for writing in that case. - Conversely, the requested exclusive bit would render it impossible to - open a path through the MBR geom while <span class="Pa">da0</span> is - open for writing.</p> - <p class="Pp">From this it also follows that changing the size of open geoms - can only be done with their cooperation.</p> - <p class="Pp">Finally: 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.</p> - </dd> - <dt id="CONFIGURE"><a class="permalink" href="#CONFIGURE"><i class="Em">CONFIGURE</i></a></dt> - <dd>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 may 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. - <p class="Pp">Finally, I/O is the reason we even do this: it concerns itself - with sending I/O requests through the graph.</p> - </dd> - <dt id="I/O"><a class="permalink" href="#I/O"><i class="Em">I/O - REQUESTS</i></a>,</dt> - <dd>represented by <var class="Vt">struct bio</var>, originate at a consumer, - are scheduled on its attached provider and, when processed, are returned - to the consumer. It is important to realize that the - <var class="Vt">struct bio</var> which enters through the provider of a - particular geom does not “come out on the other side”. Even - simple transformations like MBR and BSD will clone the - <var class="Vt">struct bio</var>, modify the clone, and schedule the clone - on their own consumer. Note that cloning the <var class="Vt">struct - bio</var> does not involve cloning the actual data area specified in the - I/O request. - <p class="Pp">In total, four different I/O requests exist in - <code class="Nm">GEOM</code>: read, write, delete, and “get - attribute”.</p> - <p class="Pp">Read and write are self explanatory.</p> - <p class="Pp">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. Technologies 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.</p> - <p class="Pp">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.</p> - <p class="Pp">“Get 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.</p> - </dd> -</dl> -<p class="Pp">(Stay tuned while the author rests his brain and fingers: more to - come.)</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> -<p class="Pp">Several flags are provided for tracing - <code class="Nm">GEOM</code> operations and unlocking protection mechanisms - via the <var class="Va">kern.geom.debugflags</var> sysctl. All of these - flags are off by default, and great care should be taken in turning them - on.</p> -<dl class="Bl-tag"> - <dt>0x01 (<code class="Dv">G_T_TOPOLOGY</code>)</dt> - <dd>Provide tracing of topology change events.</dd> - <dt>0x02 (<code class="Dv">G_T_BIO</code>)</dt> - <dd>Provide tracing of buffer I/O requests.</dd> - <dt>0x04 (<code class="Dv">G_T_ACCESS</code>)</dt> - <dd>Provide tracing of access check controls.</dd> - <dt>0x08 (unused)</dt> - <dd style="width: auto;"> </dd> - <dt>0x10 (allow foot shooting)</dt> - <dd>Allow writing to Rank 1 providers. This would, for example, allow the - super-user to overwrite the MBR on the root disk or write random sectors - elsewhere to a mounted disk. The implications are obvious.</dd> - <dt>0x40 (<code class="Dv">G_F_DISKIOCTL</code>)</dt> - <dd>This is unused at this time.</dd> - <dt>0x80 (<code class="Dv">G_F_CTLDUMP</code>)</dt> - <dd>Dump contents of gctl requests.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">libgeom(3)</a>, <a class="Xr">geom(8)</a>, - <a class="Xr">DECLARE_GEOM_CLASS(9)</a>, <a class="Xr">disk(9)</a>, - <a class="Xr">g_access(9)</a>, <a class="Xr">g_attach(9)</a>, - <a class="Xr">g_bio(9)</a>, <a class="Xr">g_consumer(9)</a>, - <a class="Xr">g_data(9)</a>, <a class="Xr">g_event(9)</a>, - <a class="Xr">g_geom(9)</a>, <a class="Xr">g_provider(9)</a>, - <a class="Xr">g_provider_by_name(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">This software was initially developed for the - <span class="Ux">FreeBSD</span> Project by <span class="An">Poul-Henning - Kamp</span> 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.</p> -<p class="Pp">The following obsolete <code class="Nm">GEOM</code> components - were removed in <span class="Ux">FreeBSD 13.0</span>:</p> -<ul class="Bl-bullet Bd-indent Bl-compact"> - <li><code class="Cd">GEOM_BSD</code>,</li> - <li><code class="Cd">GEOM_FOX</code>,</li> - <li><code class="Cd">GEOM_MBR</code>,</li> - <li><code class="Cd">GEOM_SUNLABEL</code>, and</li> - <li><code class="Cd">GEOM_VOL</code>.</li> -</ul> -<p class="Pp">Use</p> -<ul class="Bl-bullet Bd-indent Bl-compact"> - <li><code class="Cd">GEOM_PART_BSD</code>,</li> - <li><code class="Cd">GEOM_MULTIPATH</code>,</li> - <li><code class="Cd">GEOM_PART_MBR</code>, and</li> - <li><code class="Cd">GEOM_LABEL</code></li> -</ul> -options, respectively, instead. -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp"><span class="An">Poul-Henning Kamp</span> - <<a class="Mt" href="mailto:phk@FreeBSD.org">phk@FreeBSD.org</a>></p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">July 8, 2024</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |