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