share/man/man4/geom.4

   1 .\"
   2 .\" Copyright (c) 2002 Poul-Henning Kamp
   3 .\" Copyright (c) 2002 Networks Associates Technology, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This software was developed for the FreeBSD Project by Poul-Henning Kamp
   7 .\" and NAI Labs, the Security Research Division of Network Associates, Inc.
   8 .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
   9 .\" DARPA CHATS research program.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\" 3. The names of the authors may not be used to endorse or promote
  20 .\"    products derived from this software without specific prior written
  21 .\"    permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .Dd October 6, 2023
  36 .Dt GEOM 4
  37 .Os
  38 .Sh NAME
  39 .Nm GEOM
  40 .Nd "modular disk I/O request transformation framework"
  41 .Sh SYNOPSIS
  42 .Cd options GEOM_BDE
  43 .Cd options GEOM_CACHE
  44 .Cd options GEOM_CONCAT
  45 .Cd options GEOM_ELI
  46 .Cd options GEOM_GATE
  47 .Cd options GEOM_JOURNAL
  48 .Cd options GEOM_LABEL
  49 .Cd options GEOM_LINUX_LVM
  50 .Cd options GEOM_MAP
  51 .Cd options GEOM_MIRROR
  52 .Cd options GEOM_MOUNTVER
  53 .Cd options GEOM_MULTIPATH
  54 .Cd options GEOM_NOP
  55 .Cd options GEOM_PART_APM
  56 .Cd options GEOM_PART_BSD
  57 .Cd options GEOM_PART_BSD64
  58 .Cd options GEOM_PART_EBR
  59 .Cd options GEOM_PART_EBR_COMPAT
  60 .Cd options GEOM_PART_GPT
  61 .Cd options GEOM_PART_LDM
  62 .Cd options GEOM_PART_MBR
  63 .Cd options GEOM_RAID
  64 .Cd options GEOM_RAID3
  65 .Cd options GEOM_SHSEC
  66 .Cd options GEOM_STRIPE
  67 .Cd options GEOM_UZIP
  68 .Cd options GEOM_VIRSTOR
  69 .Cd options GEOM_ZERO
  70 .Sh DESCRIPTION
  71 The
  72 .Nm
  73 framework provides an infrastructure in which
  74 .Dq classes
  75 can perform transformations on disk I/O requests on their path from
  76 the upper kernel to the device drivers and back.
  77 .Pp
  78 Transformations in a
  79 .Nm
  80 context range from the simple geometric
  81 displacement performed in typical disk partitioning modules over RAID
  82 algorithms and device multipath resolution to full blown cryptographic
  83 protection of the stored data.
  84 .Pp
  85 Compared to traditional
  86 .Dq "volume management" ,
  87 .Nm
  88 differs from most
  89 and in some cases all previous implementations in the following ways:
  90 .Bl -bullet
  91 .It
  92 .Nm
  93 is extensible.
  94 It is trivially simple to write a new class
  95 of transformation and it will not be given stepchild treatment.
  96 If
  97 someone for some reason wanted to mount IBM MVS diskpacks, a class
  98 recognizing and configuring their VTOC information would be a trivial
  99 matter.
 100 .It
 101 .Nm
 102 is topologically agnostic.
 103 Most volume management implementations
 104 have very strict notions of how classes can fit together, very often
 105 one fixed hierarchy is provided, for instance, subdisk - plex -
 106 volume.
 107 .El
 108 .Pp
 109 Being extensible means that new transformations are treated no differently
 110 than existing transformations.
 111 .Pp
 112 Fixed hierarchies are bad because they make it impossible to express
 113 the intent efficiently.
 114 In the fixed hierarchy above, it is not possible to mirror two
 115 physical disks and then partition the mirror into subdisks, instead
 116 one is forced to make subdisks on the physical volumes and to mirror
 117 these two and two, resulting in a much more complex configuration.
 118 .Nm
 119 on the other hand does not care in which order things are done,
 120 the only restriction is that cycles in the graph will not be allowed.
 121 .Sh "TERMINOLOGY AND TOPOLOGY"
 122 .Nm
 123 is quite object oriented and consequently the terminology
 124 borrows a lot of context and semantics from the OO vocabulary:
 125 .Pp
 126 A
 127 .Dq class ,
 128 represented by the data structure
 129 .Vt g_class
 130 implements one
 131 particular kind of transformation.
 132 Typical examples are MBR disk
 133 partition, BSD disklabel, and RAID5 classes.
 134 .Pp
 135 An instance of a class is called a
 136 .Dq geom
 137 and represented by the data structure
 138 .Vt g_geom .
 139 In a typical i386
 140 .Fx
 141 system, there
 142 will be one geom of class MBR for each disk.
 143 .Pp
 144 A
 145 .Dq provider ,
 146 represented by the data structure
 147 .Vt g_provider ,
 148 is the front gate at which a geom offers service.
 149 A provider is
 150 .Do
 151 a disk-like thing which appears in
 152 .Pa /dev
 153 .Dc - a logical
 154 disk in other words.
 155 All providers have three main properties:
 156 .Dq name ,
 157 .Dq sectorsize
 158 and
 159 .Dq size .
 160 .Pp
 161 A
 162 .Dq consumer
 163 is the backdoor through which a geom connects to another
 164 geom provider and through which I/O requests are sent.
 165 .Pp
 166 The topological relationship between these entities are as follows:
 167 .Bl -bullet
 168 .It
 169 A class has zero or more geom instances.
 170 .It
 171 A geom has exactly one class it is derived from.
 172 .It
 173 A geom has zero or more consumers.
 174 .It
 175 A geom has zero or more providers.
 176 .It
 177 A consumer can be attached to zero or one providers.
 178 .It
 179 A provider can have zero or more consumers attached.
 180 .El
 181 .Pp
 182 All geoms have a rank-number assigned, which is used to detect and
 183 prevent loops in the acyclic directed graph.
 184 This rank number is
 185 assigned as follows:
 186 .Bl -enum
 187 .It
 188 A geom with no attached consumers has rank=1.
 189 .It
 190 A geom with attached consumers has a rank one higher than the
 191 highest rank of the geoms of the providers its consumers are
 192 attached to.
 193 .El
 194 .Sh "SPECIAL TOPOLOGICAL MANEUVERS"
 195 In addition to the straightforward attach, which attaches a consumer
 196 to a provider, and detach, which breaks the bond, a number of special
 197 topological maneuvers exists to facilitate configuration and to
 198 improve the overall flexibility.
 199 .Bl -inset
 200 .It Em TASTING
 201 is a process that happens whenever a new class or new provider
 202 is created, and it provides the class a chance to automatically configure an
 203 instance on providers which it recognizes as its own.
 204 A typical example is the MBR disk-partition class which will look for
 205 the MBR table in the first sector and, if found and validated, will
 206 instantiate a geom to multiplex according to the contents of the MBR.
 207 .Pp
 208 A new class will be offered to all existing providers in turn and a new
 209 provider will be offered to all classes in turn.
 210 .Pp
 211 Exactly what a class does to recognize if it should accept the offered
 212 provider is not defined by
 213 .Nm ,
 214 but the sensible set of options are:
 215 .Bl -bullet
 216 .It
 217 Examine specific data structures on the disk.
 218 .It
 219 Examine properties like
 220 .Dq sectorsize
 221 or
 222 .Dq mediasize
 223 for the provider.
 224 .It
 225 Examine the rank number of the provider's geom.
 226 .It
 227 Examine the method name of the provider's geom.
 228 .El
 229 .Pp
 230 Tasting is controlled by the
 231 .Va kern.geom.notaste
 232 sysctl.
 233 To disable tasting, set the sysctl to 1, to
 234 re-enable tasting, set the sysctl to 0.
 235 .It Em ORPHANIZATION
 236 is the process by which a provider is removed while
 237 it potentially is still being used.
 238 .Pp
 239 When a geom orphans a provider, all future I/O requests will
 240 .Dq bounce
 241 on the provider with an error code set by the geom.
 242 Any
 243 consumers attached to the provider will receive notification about
 244 the orphanization when the event loop gets around to it, and they
 245 can take appropriate action at that time.
 246 .Pp
 247 A geom which came into being as a result of a normal taste operation
 248 should self-destruct unless it has a way to keep functioning whilst
 249 lacking the orphaned provider.
 250 Geoms like disk slicers should therefore self-destruct whereas
 251 RAID5 or mirror geoms will be able to continue as long as they do
 252 not lose quorum.
 253 .Pp
 254 When a provider is orphaned, this does not necessarily result in any
 255 immediate change in the topology: any attached consumers are still
 256 attached, any opened paths are still open, any outstanding I/O
 257 requests are still outstanding.
 258 .Pp
 259 The typical scenario is:
 260 .Pp
 261 .Bl -bullet -offset indent -compact
 262 .It
 263 A device driver detects a disk has departed and orphans the provider for it.
 264 .It
 265 The geoms on top of the disk receive the orphanization event and
 266 orphan all their providers in turn.
 267 Providers which are not attached to will typically self-destruct
 268 right away.
 269 This process continues in a quasi-recursive fashion until all
 270 relevant pieces of the tree have heard the bad news.
 271 .It
 272 Eventually the buck stops when it reaches geom_dev at the top
 273 of the stack.
 274 .It
 275 Geom_dev will call
 276 .Xr destroy_dev 9
 277 to stop any more requests from
 278 coming in.
 279 It will sleep until any and all outstanding I/O requests have
 280 been returned.
 281 It will explicitly close (i.e.: zero the access counts), a change
 282 which will propagate all the way down through the mesh.
 283 It will then detach and destroy its geom.
 284 .It
 285 The geom whose provider is now detached will destroy the provider,
 286 detach and destroy its consumer and destroy its geom.
 287 .It
 288 This process percolates all the way down through the mesh, until
 289 the cleanup is complete.
 290 .El
 291 .Pp
 292 While this approach seems byzantine, it does provide the maximum
 293 flexibility and robustness in handling disappearing devices.
 294 .Pp
 295 The one absolutely crucial detail to be aware of is that if the
 296 device driver does not return all I/O requests, the tree will
 297 not unravel.
 298 .It Em SPOILING
 299 is a special case of orphanization used to protect
 300 against stale metadata.
 301 It is probably easiest to understand spoiling by going through
 302 an example.
 303 .Pp
 304 Imagine a disk,
 305 .Pa da0 ,
 306 on top of which an MBR geom provides
 307 .Pa da0s1
 308 and
 309 .Pa da0s2 ,
 310 and on top of
 311 .Pa da0s1
 312 a BSD geom provides
 313 .Pa da0s1a
 314 through
 315 .Pa da0s1e ,
 316 and that both the MBR and BSD geoms have
 317 autoconfigured based on data structures on the disk media.
 318 Now imagine the case where
 319 .Pa da0
 320 is opened for writing and those
 321 data structures are modified or overwritten: now the geoms would
 322 be operating on stale metadata unless some notification system
 323 can inform them otherwise.
 324 .Pp
 325 To avoid this situation, when the open of
 326 .Pa da0
 327 for write happens,
 328 all attached consumers are told about this and geoms like
 329 MBR and BSD will self-destruct as a result.
 330 When
 331 .Pa da0
 332 is closed, it will be offered for tasting again
 333 and, if the data structures for MBR and BSD are still there, new
 334 geoms will instantiate themselves anew.
 335 .Pp
 336 Now for the fine print:
 337 .Pp
 338 If any of the paths through the MBR or BSD module were open, they
 339 would have opened downwards with an exclusive bit thus rendering it
 340 impossible to open
 341 .Pa da0
 342 for writing in that case.
 343 Conversely,
 344 the requested exclusive bit would render it impossible to open a
 345 path through the MBR geom while
 346 .Pa da0
 347 is open for writing.
 348 .Pp
 349 From this it also follows that changing the size of open geoms can
 350 only be done with their cooperation.
 351 .Pp
 352 Finally: the spoiling only happens when the write count goes from
 353 zero to non-zero and the retasting happens only when the write count goes
 354 from non-zero to zero.
 355 .It Em CONFIGURE
 356 is the process where the administrator issues instructions
 357 for a particular class to instantiate itself.
 358 There are multiple
 359 ways to express intent in this case - a particular provider may be
 360 specified with a level of override forcing, for instance, a BSD
 361 disklabel module to attach to a provider which was not found palatable
 362 during the TASTE operation.
 363 .Pp
 364 Finally, I/O is the reason we even do this: it concerns itself with
 365 sending I/O requests through the graph.
 366 .It Em "I/O REQUESTS" ,
 367 represented by
 368 .Vt "struct bio" ,
 369 originate at a consumer,
 370 are scheduled on its attached provider and, when processed, are returned
 371 to the consumer.
 372 It is important to realize that the
 373 .Vt "struct bio"
 374 which enters through the provider of a particular geom does not
 375 .Do
 376 come out on the other side
 377 .Dc .
 378 Even simple transformations like MBR and BSD will clone the
 379 .Vt "struct bio" ,
 380 modify the clone, and schedule the clone on their
 381 own consumer.
 382 Note that cloning the
 383 .Vt "struct bio"
 384 does not involve cloning the
 385 actual data area specified in the I/O request.
 386 .Pp
 387 In total, four different I/O requests exist in
 388 .Nm :
 389 read, write, delete, and
 390 .Dq "get attribute".
 391 .Pp
 392 Read and write are self explanatory.
 393 .Pp
 394 Delete indicates that a certain range of data is no longer used
 395 and that it can be erased or freed as the underlying technology
 396 supports.
 397 Technologies like flash adaptation layers can arrange to erase
 398 the relevant blocks before they will become reassigned and
 399 cryptographic devices may want to fill random bits into the
 400 range to reduce the amount of data available for attack.
 401 .Pp
 402 It is important to recognize that a delete indication is not a
 403 request and consequently there is no guarantee that the data actually
 404 will be erased or made unavailable unless guaranteed by specific
 405 geoms in the graph.
 406 If
 407 .Dq "secure delete"
 408 semantics are required, a
 409 geom should be pushed which converts delete indications into (a
 410 sequence of) write requests.
 411 .Pp
 412 .Dq "Get attribute"
 413 supports inspection and manipulation
 414 of out-of-band attributes on a particular provider or path.
 415 Attributes are named by
 416 .Tn ASCII
 417 strings and they will be discussed in
 418 a separate section below.
 419 .El
 420 .Pp
 421 (Stay tuned while the author rests his brain and fingers: more to come.)
 422 .Sh DIAGNOSTICS
 423 Several flags are provided for tracing
 424 .Nm
 425 operations and unlocking
 426 protection mechanisms via the
 427 .Va kern.geom.debugflags
 428 sysctl.
 429 All of these flags are off by default, and great care should be taken in
 430 turning them on.
 431 .Bl -tag -width indent
 432 .It 0x01 Pq Dv G_T_TOPOLOGY
 433 Provide tracing of topology change events.
 434 .It 0x02 Pq Dv G_T_BIO
 435 Provide tracing of buffer I/O requests.
 436 .It 0x04 Pq Dv G_T_ACCESS
 437 Provide tracing of access check controls.
 438 .It 0x08 (unused)
 439 .It 0x10 (allow foot shooting)
 440 Allow writing to Rank 1 providers.
 441 This would, for example, allow the super-user to overwrite the MBR on the root
 442 disk or write random sectors elsewhere to a mounted disk.
 443 The implications are obvious.
 444 .It 0x40 Pq Dv G_F_DISKIOCTL
 445 This is unused at this time.
 446 .It 0x80 Pq Dv G_F_CTLDUMP
 447 Dump contents of gctl requests.
 448 .El
 449 .Sh SEE ALSO
 450 .Xr libgeom 3 ,
 451 .Xr geom 8 ,
 452 .Xr DECLARE_GEOM_CLASS 9 ,
 453 .Xr disk 9 ,
 454 .Xr g_access 9 ,
 455 .Xr g_attach 9 ,
 456 .Xr g_bio 9 ,
 457 .Xr g_consumer 9 ,
 458 .Xr g_data 9 ,
 459 .Xr g_event 9 ,
 460 .Xr g_geom 9 ,
 461 .Xr g_provider 9 ,
 462 .Xr g_provider_by_name 9
 463 .Sh HISTORY
 464 This software was initially developed for the
 465 .Fx
 466 Project by
 467 .An Poul-Henning Kamp
 468 and NAI Labs, the Security Research Division of Network Associates, Inc.\&
 469 under DARPA/SPAWAR contract N66001-01-C-8035
 470 .Pq Dq CBOSS ,
 471 as part of the
 472 DARPA CHATS research program.
 473 .Pp
 474 The following obsolete
 475 .Nm
 476 components were removed in
 477 .Fx 13.0 :
 478 .Bl -bullet -offset indent -compact
 479 .It
 480 .Cd GEOM_BSD ,
 481 .It
 482 .Cd GEOM_FOX ,
 483 .It
 484 .Cd GEOM_MBR ,
 485 .It
 486 .Cd GEOM_SUNLABEL ,
 487 and
 488 .It
 489 .Cd GEOM_VOL .
 490 .El
 491 .Pp
 492 Use
 493 .Bl -bullet -offset indent -compact
 494 .It
 495 .Cd GEOM_PART_BSD ,
 496 .It
 497 .Cd GEOM_MULTIPATH ,
 498 .It
 499 .Cd GEOM_PART_MBR ,
 500 and
 501 .It
 502 .Cd GEOM_LABEL
 503 .El
 504 options, respectively, instead.
 505 .Sh AUTHORS
 506 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org