sbin/geom/class/part/gpart.8

   1 .\" Copyright (c) 2007, 2008 Marcel Moolenaar
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd July 1, 2013
  28 .Dt GPART 8
  29 .Os
  30 .Sh NAME
  31 .Nm gpart
  32 .Nd "control utility for the disk partitioning GEOM class"
  33 .Sh SYNOPSIS
  34 .\" ==== ADD ====
  35 .Nm
  36 .Cm add
  37 .Fl t Ar type
  38 .Op Fl a Ar alignment
  39 .Op Fl b Ar start
  40 .Op Fl s Ar size
  41 .Op Fl i Ar index
  42 .Op Fl l Ar label
  43 .Op Fl f Ar flags
  44 .Ar geom
  45 .\" ==== BACKUP ====
  46 .Nm
  47 .Cm backup
  48 .Ar geom
  49 .\" ==== BOOTCODE ====
  50 .Nm
  51 .Cm bootcode
  52 .Op Fl b Ar bootcode
  53 .Op Fl p Ar partcode Fl i Ar index
  54 .Op Fl f Ar flags
  55 .Ar geom
  56 .\" ==== COMMIT ====
  57 .Nm
  58 .Cm commit
  59 .Ar geom
  60 .\" ==== CREATE ====
  61 .Nm
  62 .Cm create
  63 .Fl s Ar scheme
  64 .Op Fl n Ar entries
  65 .Op Fl f Ar flags
  66 .Ar provider
  67 .\" ==== DELETE ====
  68 .Nm
  69 .Cm delete
  70 .Fl i Ar index
  71 .Op Fl f Ar flags
  72 .Ar geom
  73 .\" ==== DESTROY ====
  74 .Nm
  75 .Cm destroy
  76 .Op Fl F
  77 .Op Fl f Ar flags
  78 .Ar geom
  79 .\" ==== MODIFY ====
  80 .Nm
  81 .Cm modify
  82 .Fl i Ar index
  83 .Op Fl l Ar label
  84 .Op Fl t Ar type
  85 .Op Fl f Ar flags
  86 .Ar geom
  87 .\" ==== RECOVER ====
  88 .Nm
  89 .Cm recover
  90 .Op Fl f Ar flags
  91 .Ar geom
  92 .\" ==== RESIZE ====
  93 .Nm
  94 .Cm resize
  95 .Fl i Ar index
  96 .Op Fl a Ar alignment
  97 .Op Fl s Ar size
  98 .Op Fl f Ar flags
  99 .Ar geom
 100 .\" ==== RESTORE ====
 101 .Nm
 102 .Cm restore
 103 .Op Fl lF
 104 .Op Fl f Ar flags
 105 .Ar provider
 106 .Op Ar ...
 107 .\" ==== SET ====
 108 .Nm
 109 .Cm set
 110 .Fl a Ar attrib
 111 .Fl i Ar index
 112 .Op Fl f Ar flags
 113 .Ar geom
 114 .\" ==== SHOW ====
 115 .Nm
 116 .Cm show
 117 .Op Fl l | r
 118 .Op Fl p
 119 .Op Ar geom ...
 120 .\" ==== UNDO ====
 121 .Nm
 122 .Cm undo
 123 .Ar geom
 124 .\" ==== UNSET ====
 125 .Nm
 126 .Cm unset
 127 .Fl a Ar attrib
 128 .Fl i Ar index
 129 .Op Fl f Ar flags
 130 .Ar geom
 131 .\"
 132 .Sh DESCRIPTION
 133 The
 134 .Nm
 135 utility is used to partition GEOM providers, normally disks.
 136 The first argument is the action to be taken:
 137 .Bl -tag -width ".Cm bootcode"
 138 .\" ==== ADD ====
 139 .It Cm add
 140 Add a new partition to the partitioning scheme given by
 141 .Ar geom .
 142 The partition begins on the logical block address given by the
 143 .Fl b Ar start
 144 option.
 145 Its size is given by the
 146 .Fl s Ar size
 147 option.
 148 SI unit suffixes are allowed.
 149 One or both
 150 .Fl b
 151 and
 152 .Fl s
 153 options can be omitted.
 154 If so they are automatically calculated.
 155 The type of the partition is given by the
 156 .Fl t Ar type
 157 option.
 158 Partition types are discussed below in the section entitled
 159 .Sx "PARTITION TYPES" .
 160 .Pp
 161 Additional options include:
 162 .Bl -tag -width 12n
 163 .It Fl a Ar alignment
 164 If specified, then
 165 .Nm
 166 utility tries to align
 167 .Ar start
 168 offset and partition
 169 .Ar size
 170 to be multiple of
 171 .Ar alignment
 172 value.
 173 .It Fl i Ar index
 174 The index in the partition table at which the new partition is to be
 175 placed.
 176 The index determines the name of the device special file used
 177 to represent the partition.
 178 .It Fl l Ar label
 179 The label attached to the partition.
 180 This option is only valid when used on partitioning schemes that support
 181 partition labels.
 182 .It Fl f Ar flags
 183 Additional operational flags.
 184 See the section entitled
 185 .Sx "OPERATIONAL FLAGS"
 186 below for a discussion
 187 about its use.
 188 .El
 189 .\" ==== BACKUP ====
 190 .It Cm backup
 191 Dump a partition table to standard output in a special format used by the
 192 .Cm restore
 193 action.
 194 .\" ==== BOOTCODE ====
 195 .It Cm bootcode
 196 Embed bootstrap code into the partitioning scheme's metadata on the
 197 .Ar geom
 198 (using
 199 .Fl b Ar bootcode )
 200 or write bootstrap code into a partition (using
 201 .Fl p Ar partcode
 202 and
 203 .Fl i Ar index ) .
 204 Not all partitioning schemes have embedded bootstrap code, so the
 205 .Fl b Ar bootcode
 206 option is scheme-specific in nature (see the section entitled
 207 .Sx BOOTSTRAPPING
 208 below).
 209 The
 210 .Fl b Ar bootcode
 211 option specifies a file that contains the bootstrap code.
 212 The contents and size of the file are determined by the partitioning
 213 scheme.
 214 The
 215 .Fl p Ar partcode
 216 option specifies a file that contains the bootstrap code intended to be
 217 written to a partition.
 218 The partition is specified by the
 219 .Fl i Ar index
 220 option.
 221 The size of the file must be smaller than the size of the partition.
 222 .Pp
 223 Additional options include:
 224 .Bl -tag -width 10n
 225 .It Fl f Ar flags
 226 Additional operational flags.
 227 See the section entitled
 228 .Sx "OPERATIONAL FLAGS"
 229 below for a discussion
 230 about its use.
 231 .El
 232 .\" ==== COMMIT ====
 233 .It Cm commit
 234 Commit any pending changes for geom
 235 .Ar geom .
 236 All actions are committed by default and will not result in
 237 pending changes.
 238 Actions can be modified with the
 239 .Fl f Ar flags
 240 option so that they are not committed, but become pending.
 241 Pending changes are reflected by the geom and the
 242 .Nm
 243 utility, but they are not actually written to disk.
 244 The
 245 .Cm commit
 246 action will write all pending changes to disk.
 247 .\" ==== CREATE ====
 248 .It Cm create
 249 Create a new partitioning scheme on a provider given by
 250 .Ar provider .
 251 The
 252 .Fl s Ar scheme
 253 option determines the scheme to use.
 254 The kernel must have support for a particular scheme before
 255 that scheme can be used to partition a disk.
 256 .Pp
 257 Additional options include:
 258 .Bl -tag -width 10n
 259 .It Fl n Ar entries
 260 The number of entries in the partition table.
 261 Every partitioning scheme has a minimum and maximum number of entries.
 262 This option allows tables to be created with a number of entries
 263 that is within the limits.
 264 Some schemes have a maximum equal to the minimum and some schemes have
 265 a maximum large enough to be considered unlimited.
 266 By default, partition tables are created with the minimum number of
 267 entries.
 268 .It Fl f Ar flags
 269 Additional operational flags.
 270 See the section entitled
 271 .Sx "OPERATIONAL FLAGS"
 272 below for a discussion
 273 about its use.
 274 .El
 275 .\" ==== DELETE ====
 276 .It Cm delete
 277 Delete a partition from geom
 278 .Ar geom
 279 and further identified by the
 280 .Fl i Ar index
 281 option.
 282 The partition cannot be actively used by the kernel.
 283 .Pp
 284 Additional options include:
 285 .Bl -tag -width 10n
 286 .It Fl f Ar flags
 287 Additional operational flags.
 288 See the section entitled
 289 .Sx "OPERATIONAL FLAGS"
 290 below for a discussion
 291 about its use.
 292 .El
 293 .\" ==== DESTROY ====
 294 .It Cm destroy
 295 Destroy the partitioning scheme as implemented by geom
 296 .Ar geom .
 297 .Pp
 298 Additional options include:
 299 .Bl -tag -width 10n
 300 .It Fl F
 301 Forced destroying of the partition table even if it is not empty.
 302 .It Fl f Ar flags
 303 Additional operational flags.
 304 See the section entitled
 305 .Sx "OPERATIONAL FLAGS"
 306 below for a discussion
 307 about its use.
 308 .El
 309 .\" ==== MODIFY ====
 310 .It Cm modify
 311 Modify a partition from geom
 312 .Ar geom
 313 and further identified by the
 314 .Fl i Ar index
 315 option.
 316 Only the type and/or label of the partition can be modified.
 317 To change the type of a partition, specify the new type with the
 318 .Fl t Ar type
 319 option.
 320 To change the label of a partition, specify the new label with the
 321 .Fl l Ar label
 322 option.
 323 Not all partitioning schemes support labels and it is invalid to
 324 try to change a partition label in such cases.
 325 .Pp
 326 Additional options include:
 327 .Bl -tag -width 10n
 328 .It Fl f Ar flags
 329 Additional operational flags.
 330 See the section entitled
 331 .Sx "OPERATIONAL FLAGS"
 332 below for a discussion
 333 about its use.
 334 .El
 335 .\" ==== RECOVER ====
 336 .It Cm recover
 337 Recover a corrupt partition's scheme metadata on the geom
 338 .Ar geom .
 339 See the section entitled
 340 .Sx RECOVERING
 341 below for the additional information.
 342 .Pp
 343 Additional options include:
 344 .Bl -tag -width 10n
 345 .It Fl f Ar flags
 346 Additional operational flags.
 347 See the section entitled
 348 .Sx "OPERATIONAL FLAGS"
 349 below for a discussion
 350 about its use.
 351 .El
 352 .\" ==== RESIZE ====
 353 .It Cm resize
 354 Resize a partition from geom
 355 .Ar geom
 356 and further identified by the
 357 .Fl i Ar index
 358 option.
 359 New partition size is expressed in logical block
 360 numbers and can be given by the
 361 .Fl s Ar size
 362 option.
 363 If
 364 .Fl s
 365 option is omitted then new size is automatically calculated
 366 to maximum available from given geom
 367 .Ar geom .
 368 .Pp
 369 Additional options include:
 370 .Bl -tag -width 12n
 371 .It Fl a Ar alignment
 372 If specified, then
 373 .Nm
 374 utility tries to align partition
 375 .Ar size
 376 to be multiple of
 377 .Ar alignment
 378 value.
 379 .It Fl f Ar flags
 380 Additional operational flags.
 381 See the section entitled
 382 .Sx "OPERATIONAL FLAGS"
 383 below for a discussion
 384 about its use.
 385 .El
 386 .\" ==== RESTORE ====
 387 .It Cm restore
 388 Restore the partition table from a backup previously created by the
 389 .Cm backup
 390 action and read from standard input.
 391 Only the partition table is restored.
 392 This action does not affect the content of partitions.
 393 After restoring the partition table and writing bootcode if needed,
 394 user data must be restored from backup.
 395 .Pp
 396 Additional options include:
 397 .Bl -tag -width 10n
 398 .It Fl F
 399 Destroy partition table on the given
 400 .Ar provider
 401 before doing restore.
 402 .It Fl l
 403 Restore partition labels for partitioning schemes that support them.
 404 .It Fl f Ar flags
 405 Additional operational flags.
 406 See the section entitled
 407 .Sx "OPERATIONAL FLAGS"
 408 below for a discussion
 409 about its use.
 410 .El
 411 .\" ==== SET ====
 412 .It Cm set
 413 Set the named attribute on the partition entry.
 414 See the section entitled
 415 .Sx ATTRIBUTES
 416 below for a list of available attributes.
 417 .Pp
 418 Additional options include:
 419 .Bl -tag -width 10n
 420 .It Fl f Ar flags
 421 Additional operational flags.
 422 See the section entitled
 423 .Sx "OPERATIONAL FLAGS"
 424 below for a discussion
 425 about its use.
 426 .El
 427 .\" ==== SHOW ====
 428 .It Cm show
 429 Show current partition information for the specified geoms, or all
 430 geoms if none are specified.
 431 The default output includes the logical starting block of each
 432 partition, the partition size in blocks, the partition index number,
 433 the partition type, and a human readable partition size.
 434 Block sizes and locations are based on the device's Sectorsize
 435 as shown by
 436 .Cm gpart list .
 437 Additional options include:
 438 .Bl -tag -width 10n
 439 .It Fl l
 440 For partitioning schemes that support partition labels, print them
 441 instead of partition type.
 442 .It Fl p
 443 Show provider names instead of partition indexes.
 444 .It Fl r
 445 Show raw partition type instead of symbolic name.
 446 .El
 447 .\" ==== UNDO ====
 448 .It Cm undo
 449 Revert any pending changes for geom
 450 .Ar geom .
 451 This action is the opposite of the
 452 .Cm commit
 453 action and can be used to undo any changes that have not been committed.
 454 .\" ==== UNSET ====
 455 .It Cm unset
 456 Clear the named attribute on the partition entry.
 457 See the section entitled
 458 .Sx ATTRIBUTES
 459 below for a list of available attributes.
 460 .Pp
 461 Additional options include:
 462 .Bl -tag -width 10n
 463 .It Fl f Ar flags
 464 Additional operational flags.
 465 See the section entitled
 466 .Sx "OPERATIONAL FLAGS"
 467 below for a discussion
 468 about its use.
 469 .El
 470 .El
 471 .Sh PARTITIONING SCHEMES
 472 Several partitioning schemes are supported by the
 473 .Nm
 474 utility:
 475 .Bl -tag -width ".Cm VTOC8"
 476 .It Cm APM
 477 Apple Partition Map, used by PowerPC(R) Macintosh(R) computers.
 478 Requires the
 479 .Cd GEOM_PART_APM
 480 kernel option.
 481 .It Cm BSD
 482 Traditional BSD disklabel, usually used to subdivide MBR partitions.
 483 .Po
 484 This scheme can also be used as the sole partitioning method, without
 485 an MBR.
 486 Partition editing tools from other operating systems often do not
 487 understand the bare disklabel partition layout, so this is sometimes
 488 called
 489 .Dq dangerously dedicated .
 490 .Pc
 491 Requires the
 492 .Cm GEOM_PART_BSD
 493 kernel option.
 494 .It Cm LDM
 495 The Logical Disk Manager is an implementation of volume manager for
 496 Microsoft Windows NT.
 497 Requires the
 498 .Cd GEOM_PART_LDM
 499 kernel option.
 500 .It Cm GPT
 501 GUID Partition Table is used on Intel-based Macintosh computers and
 502 gradually replacing MBR on most PCs and other systems.
 503 Requires the
 504 .Cm GEOM_PART_GPT
 505 kernel option.
 506 .It Cm MBR
 507 Master Boot Record is used on PCs and removable media.
 508 Requires the
 509 .Cm GEOM_PART_MBR
 510 kernel option.
 511 The
 512 .Cm GEOM_PART_EBR
 513 option adds support for the Extended Boot Record (EBR),
 514 which is used to define a logical partition.
 515 The
 516 .Cm GEOM_PART_EBR_COMPAT
 517 option enables backward compatibility for partition names
 518 in the EBR scheme.
 519 It also prevents any type of actions on such partitions.
 520 .It Cm PC98
 521 An MBR variant for NEC PC-98 and compatible computers.
 522 Requires the
 523 .Cm GEOM_PART_PC98
 524 kernel option.
 525 .It Cm VTOC8
 526 Sun's SMI Volume Table Of Contents, used by
 527 .Tn SPARC64
 528 and
 529 .Tn UltraSPARC
 530 computers.
 531 Requires the
 532 .Cm GEOM_PART_VTOC8
 533 kernel option.
 534 .El
 535 .Sh PARTITION TYPES
 536 Partition types are identified on disk by particular strings or magic
 537 values.
 538 The
 539 .Nm
 540 utility uses symbolic names for common partition types so the user
 541 does not need to know these values or other details of the partitioning
 542 scheme in question.
 543 The
 544 .Nm
 545 utility also allows the user to specify scheme-specific partition types
 546 for partition types that do not have symbolic names.
 547 Symbolic names currently understood are:
 548 .Bl -tag -width ".Cm ms-ldm-metadata"
 549 .It Cm bios-boot
 550 The system partition dedicated to second stage of the boot loader program.
 551 Usually it is used by the GRUB 2 loader for GPT partitioning schemes.
 552 The scheme-specific type is
 553 .Qq Li "!21686148-6449-6E6F-744E-656564454649" .
 554 .It Cm efi
 555 The system partition for computers that use the Extensible Firmware
 556 Interface (EFI).
 557 In such cases, the GPT partitioning scheme is used and the
 558 actual partition type for the system partition can also be specified as
 559 .Qq Li "!c12a7328-f81f-11d2-ba4b-00a0c93ec93b" .
 560 .It Cm freebsd
 561 A
 562 .Fx
 563 partition subdivided into filesystems with a
 564 .Bx
 565 disklabel.
 566 This is a legacy partition type and should not be used for the APM
 567 or GPT schemes.
 568 The scheme-specific types are
 569 .Qq Li "!165"
 570 for MBR,
 571 .Qq Li "!FreeBSD"
 572 for APM, and
 573 .Qq Li "!516e7cb4-6ecf-11d6-8ff8-00022d09712b"
 574 for GPT.
 575 .It Cm freebsd-boot
 576 A
 577 .Fx
 578 partition dedicated to bootstrap code.
 579 The scheme-specific type is
 580 .Qq Li "!83bd6b9d-7f41-11dc-be0b-001560b84f0f"
 581 for GPT.
 582 .It Cm freebsd-swap
 583 A
 584 .Fx
 585 partition dedicated to swap space.
 586 The scheme-specific types are
 587 .Qq Li "!FreeBSD-swap"
 588 for APM,
 589 .Qq Li "!516e7cb5-6ecf-11d6-8ff8-00022d09712b"
 590 for GPT, and tag 0x0901 for VTOC8.
 591 .It Cm freebsd-ufs
 592 A
 593 .Fx
 594 partition that contains a UFS or UFS2 filesystem.
 595 The scheme-specific types are
 596 .Qq Li "!FreeBSD-UFS"
 597 for APM,
 598 .Qq Li "!516e7cb6-6ecf-11d6-8ff8-00022d09712b"
 599 for GPT, and tag 0x0902 for VTOC8.
 600 .It Cm freebsd-vinum
 601 A
 602 .Fx
 603 partition that contains a Vinum volume.
 604 The scheme-specific types are
 605 .Qq Li "!FreeBSD-Vinum"
 606 for APM,
 607 .Qq Li "!516e7cb8-6ecf-11d6-8ff8-00022d09712b"
 608 for GPT, and tag 0x0903 for VTOC8.
 609 .It Cm freebsd-zfs
 610 A
 611 .Fx
 612 partition that contains a ZFS volume.
 613 The scheme-specific types are
 614 .Qq Li "!FreeBSD-ZFS"
 615 for APM,
 616 .Qq Li "!516e7cba-6ecf-11d6-8ff8-00022d09712b"
 617 for GPT, and 0x0904 for VTOC8.
 618 .It Cm mbr
 619 A partition that is sub-partitioned by a Master Boot Record (MBR).
 620 This type is known as
 621 .Qq Li "!024dee41-33e7-11d3-9d69-0008c781f39f"
 622 by GPT.
 623 .It Cm ms-ldm-data
 624 A partition that contains Logical Disk Manager (LDM) volumes.
 625 The scheme-specific types are
 626 .Qq Li "!66"
 627 for MBR,
 628 .Qq Li "!af9b60a0-1431-4f62-bc68-3311714a69ad"
 629 for GPT.
 630 .It Cm ms-ldm-metadata
 631 A partition that contains Logical Disk Manager (LDM) database.
 632 The scheme-specific type is
 633 .Qq Li "!5808c8aa-7e8f-42e0-85d2-e1e90434cfb3"
 634 for GPT.
 635 .El
 636 .Sh ATTRIBUTES
 637 The scheme-specific attributes for EBR:
 638 .Bl -tag -width ".Cm active"
 639 .It Cm active
 640 .El
 641 .Pp
 642 The scheme-specific attributes for GPT:
 643 .Bl -tag -width ".Cm bootfailed"
 644 .It Cm bootme
 645 When set, the
 646 .Nm gptboot
 647 stage 1 boot loader will try to boot the system from this partition.
 648 Multiple partitions can be marked with the
 649 .Cm bootme
 650 attribute.
 651 See
 652 .Xr gptboot 8
 653 for more details.
 654 .It Cm bootonce
 655 Setting this attribute automatically sets the
 656 .Cm bootme
 657 attribute.
 658 When set, the
 659 .Nm gptboot
 660 stage 1 boot loader will try to boot the system from this partition only once.
 661 Multiple partitions can be marked with the
 662 .Cm bootonce
 663 and
 664 .Cm bootme
 665 attribute pairs.
 666 See
 667 .Xr gptboot 8
 668 for more details.
 669 .It Cm bootfailed
 670 This attribute should not be manually managed.
 671 It is managed by the
 672 .Nm gptboot
 673 stage 1 boot loader and the
 674 .Pa /etc/rc.d/gptboot
 675 start-up script.
 676 See
 677 .Xr gptboot 8
 678 for more details.
 679 .El
 680 .Pp
 681 The scheme-specific attributes for MBR:
 682 .Bl -tag -width ".Cm active"
 683 .It Cm active
 684 .El
 685 .Pp
 686 The scheme-specific attributes for PC98:
 687 .Bl -tag -width ".Cm bootable"
 688 .It Cm active
 689 .It Cm bootable
 690 .El
 691 .Sh BOOTSTRAPPING
 692 .Fx
 693 supports several partitioning schemes and each scheme uses different
 694 bootstrap code.
 695 The bootstrap code is located in a specific disk area for each partitioning
 696 scheme, and may vary in size for different schemes.
 697 .Pp
 698 Bootstrap code can be separated into two types.
 699 The first type is embedded in the partitioning scheme's metadata, while the
 700 second type is located on a specific partition.
 701 Embedding bootstrap code should only be done with the
 702 .Cm gpart bootcode
 703 command with the
 704 .Fl b Ar bootcode
 705 option.
 706 The GEOM PART class knows how to safely embed bootstrap code into
 707 specific partitioning scheme metadata without causing any damage.
 708 .Pp
 709 The Master Boot Record (MBR) uses a 512-byte bootstrap code image, embedded
 710 into the partition table's metadata area.
 711 There are two variants of this bootstrap code:
 712 .Pa /boot/mbr
 713 and
 714 .Pa /boot/boot0 .
 715 .Pa /boot/mbr
 716 searches for a partition with the
 717 .Cm active
 718 attribute (see the
 719 .Sx ATTRIBUTES
 720 section) in the partition table.
 721 Then it runs next bootstrap stage.
 722 The
 723 .Pa /boot/boot0
 724 image contains a boot manager with some additional interactive functions
 725 for multi-booting from a user-selected partition.
 726 .Pp
 727 A BSD disklabel is usually created inside an MBR partition (slice)
 728 with type
 729 .Cm freebsd
 730 (see the
 731 .Sx "PARTITION TYPES"
 732 section).
 733 It uses 8 KB size bootstrap code image
 734 .Pa /boot/boot ,
 735 embedded into the partition table's metadata area.
 736 .Pp
 737 Both types of bootstrap code are used to boot from the GUID Partition Table.
 738 First, a protective MBR is embedded into the first disk sector from the
 739 .Pa /boot/pmbr
 740 image.
 741 It searches through the GPT for a
 742 .Cm freebsd-boot
 743 partition (see the
 744 .Sx "PARTITION TYPES"
 745 section) and runs the next bootstrap stage from it.
 746 The
 747 .Cm freebsd-boot
 748 partition should be smaller than 545 KB.
 749 It can be located either before or after other
 750 .Fx
 751 partitions on the disk.
 752 There are two variants of bootstrap code to write to this partition:
 753 .Pa /boot/gptboot
 754 and
 755 .Pa /boot/gptzfsboot .
 756 .Pp
 757 .Pa /boot/gptboot
 758 is used to boot from UFS partitions.
 759 .Cm gptboot
 760 searches through
 761 .Cm freebsd-ufs
 762 partitions in the GPT and selects one to boot based on the
 763 .Cm bootonce
 764 and
 765 .Cm bootme
 766 attributes.
 767 If neither attribute is found,
 768 .Pa /boot/gptboot
 769 boots from the first
 770 .Cm freebsd-ufs
 771 partition.
 772 .Pa /boot/loader
 773 .Pq the third bootstrap stage
 774 is loaded from the first partition that matches these conditions.
 775 See
 776 .Xr gptboot 8
 777 for more information.
 778 .Pp
 779 .Pa /boot/gptzfsboot
 780 is used to boot from ZFS.
 781 It searches through the GPT for
 782 .Cm freebsd-zfs
 783 partitions, trying to detect ZFS pools.
 784 After all pools are detected,
 785 .Pa /boot/zfsloader
 786 is started from the first one found.
 787 .Pp
 788 The VTOC8 scheme does not support embedding bootstrap code.
 789 Instead, the 8 KBytes bootstrap code image
 790 .Pa /boot/boot1
 791 should be written with the
 792 .Cm gpart bootcode
 793 command with the
 794 .Fl p Ar bootcode
 795 option to all sufficiently large VTOC8 partitions.
 796 To do this the
 797 .Fl i Ar index
 798 option could be omitted.
 799 .Pp
 800 The APM scheme also does not support embedding bootstrap code.
 801 Instead, the 800 KBytes bootstrap code image
 802 .Pa /boot/boot1.hfs
 803 should be written with the
 804 .Cm gpart bootcode
 805 command to a partition of type
 806 .Cm freebsd-boot ,
 807 which should also be 800 KB in size.
 808 .Sh OPERATIONAL FLAGS
 809 Actions other than the
 810 .Cm commit
 811 and
 812 .Cm undo
 813 actions take an optional
 814 .Fl f Ar flags
 815 option.
 816 This option is used to specify action-specific operational flags.
 817 By default, the
 818 .Nm
 819 utility defines the
 820 .Ql C
 821 flag so that the action is immediately
 822 committed.
 823 The user can specify
 824 .Dq Fl f Cm x
 825 to have the action result in a pending change that can later, with
 826 other pending changes, be committed as a single compound change with
 827 the
 828 .Cm commit
 829 action or reverted with the
 830 .Cm undo
 831 action.
 832 .Sh RECOVERING
 833 The GEOM PART class supports recovering of partition tables only for GPT.
 834 The GPT primary metadata is stored at the beginning of the device.
 835 For redundancy, a secondary
 836 .Pq backup
 837 copy of the metadata is stored at the end of the device.
 838 As a result of having two copies, some corruption of metadata is not
 839 fatal to the working of GPT.
 840 When the kernel detects corrupt metadata, it marks this table as corrupt
 841 and reports the problem.
 842 .Cm destroy
 843 and
 844 .Cm recover
 845 are the only operations allowed on corrupt tables.
 846 .Pp
 847 If the first sector of a provider is corrupt, the kernel can not detect GPT
 848 even if the partition table itself is not corrupt.
 849 The protective MBR can be rewritten using the
 850 .Xr dd 1
 851 command, to restore the ability to detect the GPT.
 852 The copy of the protective MBR is usually located in the
 853 .Pa /boot/pmbr
 854 file.
 855 .Pp
 856 If one GPT header appears to be corrupt but the other copy remains intact,
 857 the kernel will log the following:
 858 .Bd -literal -offset indent
 859 GEOM: provider: the primary GPT table is corrupt or invalid.
 860 GEOM: provider: using the secondary instead -- recovery strongly advised.
 861 .Ed
 862 .Pp
 863 or
 864 .Bd -literal -offset indent
 865 GEOM: provider: the secondary GPT table is corrupt or invalid.
 866 GEOM: provider: using the primary only -- recovery suggested.
 867 .Ed
 868 .Pp
 869 Also
 870 .Nm
 871 commands such as
 872 .Cm show , status
 873 and
 874 .Cm list
 875 will report about corrupt tables.
 876 .Pp
 877 If the size of the device has changed (e.g.,\& volume expansion) the
 878 secondary GPT header will no longer be located in the last sector.
 879 This is not a metadata corruption, but it is dangerous because any
 880 corruption of the primary GPT will lead to loss of the partition table.
 881 This problem is reported by the kernel with the message:
 882 .Bd -literal -offset indent
 883 GEOM: provider: the secondary GPT header is not in the last LBA.
 884 .Ed
 885 .Pp
 886 This situation can be recovered with the
 887 .Cm recover
 888 command.
 889 This command reconstructs the corrupt metadata using known valid
 890 metadata and relocates the secondary GPT to the end of the device.
 891 .Pp
 892 .Em NOTE :
 893 The GEOM PART class can detect the same partition table visible through
 894 different GEOM providers, and some of them will be marked as corrupt.
 895 Be careful when choosing a provider for recovery.
 896 If you choose incorrectly you can destroy the metadata of another GEOM class,
 897 e.g.,\& GEOM MIRROR or GEOM LABEL.
 898 .Sh SYSCTL VARIABLES
 899 The following
 900 .Xr sysctl 8
 901 variables can be used to control the behavior of the
 902 .Nm PART
 903 GEOM class.
 904 The default value is shown next to each variable.
 905 .Bl -tag -width indent
 906 .It Va kern.geom.part.check_integrity : No 1
 907 This variable controls the behaviour of metadata integrity checks.
 908 When integrity checks are enabled, the
 909 .Nm PART
 910 GEOM class verifies all generic partition parameters obtained from the
 911 disk metadata.
 912 If some inconsistency is detected, the partition table will be
 913 rejected with a diagnostic message:
 914 .Sy "GEOM_PART: Integrity check failed (provider, scheme)" .
 915 .It Va kern.geom.part.ldm.debug : No 0
 916 Debug level of the Logical Disk Manager (LDM) module.
 917 This can be set to a number between 0 and 2 inclusive.
 918 If set to 0 minimal debug information is printed,
 919 and if set to 2 the maximum amount of debug information is printed.
 920 .It Va kern.geom.part.ldm.show_mirrors : No 0
 921 This variable controls how the Logical Disk Manager (LDM) module handles
 922 mirrored volumes.
 923 By default mirrored volumes are shown as partitions with type
 924 .Cm ms-ldm-data
 925 (see the
 926 .Sx "PARTITION TYPES"
 927 section).
 928 If this variable set to 1 each component of the mirrored volume will be
 929 present as independent partition.
 930 .Em NOTE :
 931 This may break a mirrored volume and lead to data damage.
 932 .El
 933 .Sh EXIT STATUS
 934 Exit status is 0 on success, and 1 if the command fails.
 935 .Sh EXAMPLES
 936 Create a GPT scheme on
 937 .Pa ada0 :
 938 .Bd -literal -offset indent
 939 /sbin/gpart create -s GPT ada0
 940 .Ed
 941 .Pp
 942 Embed GPT bootstrap code into a protective MBR:
 943 .Bd -literal -offset indent
 944 /sbin/gpart bootcode -b /boot/pmbr ada0
 945 .Ed
 946 .Pp
 947 Create a dedicated
 948 .Cm freebsd-boot
 949 partition that can boot
 950 .Fx
 951 from a
 952 .Cm freebsd-ufs
 953 partition, and install bootstrap code into it.
 954 This partition must be larger than the bootstrap code
 955 .Po
 956 usually either
 957 .Pa /boot/gptboot
 958 or
 959 .Pa /boot/gptzfsboot
 960 .Pc ,
 961 but smaller than 545 kB since the first-stage loader will load the
 962 entire partition into memory during boot, regardless of how much data
 963 it actually contains.
 964 This example uses 88 blocks (44 kB) so the next partition will be
 965 aligned on a 64 kB boundary without the need to specify an explicit
 966 offset or alignment.
 967 The boot partition itself is aligned on a 4 kB boundary.
 968 .Bd -literal -offset indent
 969 /sbin/gpart add -b 40 -s 88 -t freebsd-boot ada0
 970 /sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
 971 .Ed
 972 .Pp
 973 Create a 512MB-sized
 974 .Cm freebsd-ufs
 975 partition to contain a UFS filesystem from which the system can boot.
 976 .Bd -literal -offset indent
 977 /sbin/gpart add -s 512M -t freebsd-ufs ada0
 978 .Ed
 979 .Pp
 980 Create an MBR scheme on
 981 .Pa ada0 ,
 982 then create a 30GB-sized
 983 .Fx
 984 slice, mark it active and
 985 install the
 986 .Nm boot0
 987 boot manager:
 988 .Bd -literal -offset indent
 989 /sbin/gpart create -s MBR ada0
 990 /sbin/gpart add -t freebsd -s 30G ada0
 991 /sbin/gpart set -a active -i 1 ada0
 992 /sbin/gpart bootcode -b /boot/boot0 ada0
 993 .Ed
 994 .Pp
 995 Now create a
 996 .Bx
 997 scheme
 998 .Pf ( Bx
 999 label) with space for up to 20 partitions:
1000 .Bd -literal -offset indent
1001 /sbin/gpart create -s BSD -n 20 ada0s1
1002 .Ed
1003 .Pp
1004 Create a 1GB-sized UFS partition and a 4GB-sized swap partition:
1005 .Bd -literal -offset indent
1006 /sbin/gpart add -t freebsd-ufs -s 1G ada0s1
1007 /sbin/gpart add -t freebsd-swap -s 4G ada0s1
1008 .Ed
1009 .Pp
1010 Install bootstrap code for the
1011 .Bx
1012 label:
1013 .Bd -literal -offset indent
1014 /sbin/gpart bootcode -b /boot/boot ada0s1
1015 .Ed
1016 .Pp
1017 Create a VTOC8 scheme on
1018 .Pa da0 :
1019 .Bd -literal -offset indent
1020 /sbin/gpart create -s VTOC8 da0
1021 .Ed
1022 .Pp
1023 Create a 512MB-sized
1024 .Cm freebsd-ufs
1025 partition to contain a UFS filesystem from which the system can boot.
1026 .Bd -literal -offset indent
1027 /sbin/gpart add -s 512M -t freebsd-ufs da0
1028 .Ed
1029 .Pp
1030 Create a 15GB-sized
1031 .Cm freebsd-ufs
1032 partition to contain a UFS filesystem and aligned on 4KB boundaries:
1033 .Bd -literal -offset indent
1034 /sbin/gpart add -s 15G -t freebsd-ufs -a 4k da0
1035 .Ed
1036 .Pp
1037 After creating all required partitions, embed bootstrap code into them:
1038 .Bd -literal -offset indent
1039 /sbin/gpart bootcode -p /boot/boot1 da0
1040 .Ed
1041 .Pp
1042 Create a backup of the partition table from
1043 .Pa da0 :
1044 .Bd -literal -offset indent
1045 /sbin/gpart backup da0 > da0.backup
1046 .Ed
1047 .Pp
1048 Restore the partition table from the backup to
1049 .Pa da0 :
1050 .Bd -literal -offset indent
1051 /sbin/gpart restore -l da0 < /mnt/da0.backup
1052 .Ed
1053 .Pp
1054 Clone the partition table from
1055 .Pa ada0
1056 to
1057 .Pa ada1
1058 and
1059 .Pa ada2 :
1060 .Bd -literal -offset indent
1061 /sbin/gpart backup ada0 | /sbin/gpart restore -F ada1 ada2
1062 .Ed
1063 .Sh SEE ALSO
1064 .Xr dd 1 ,
1065 .Xr geom 4 ,
1066 .Xr boot0cfg 8 ,
1067 .Xr geom 8 ,
1068 .Xr gptboot 8
1069 .Sh HISTORY
1070 The
1071 .Nm
1072 utility appeared in
1073 .Fx 7.0 .
1074 .Sh AUTHORS
1075 .An Marcel Moolenaar Aq marcel@FreeBSD.org