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 August 19, 2011
  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 To add support for the disk partitioning GEOM class,
  35 place one or more of the following
  36 lines in your kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "options GEOM_PART_APM"
  39 .Cd "options GEOM_PART_BSD"
  40 .Cd "options GEOM_PART_EBR"
  41 .Cd "options GEOM_PART_EBR_COMPAT"
  42 .Cd "options GEOM_PART_GPT"
  43 .Cd "options GEOM_PART_MBR"
  44 .Cd "options GEOM_PART_PC98"
  45 .Cd "options GEOM_PART_VTOC8"
  46 .Ed
  47 .Pp
  48 The
  49 .Dv GEOM_PART_APM
  50 option adds support for the Apple Partition Map (APM)
  51 found on Apple Macintosh computers.
  52 The
  53 .Dv GEOM_PART_BSD
  54 option adds support for the traditional
  55 .Bx
  56 disklabel.
  57 The
  58 .Dv GEOM_PART_EBR
  59 option adds support for the Extended Boot Record (EBR),
  60 which is used to define a logical partition.
  61 The
  62 .Dv GEOM_PART_EBR_COMPAT
  63 option enables backward compatibility for partition names
  64 in the EBR scheme. Also it makes impossible any types of actions
  65 with such partitions.
  66 The
  67 .Dv GEOM_PART_GPT
  68 option adds support for the GUID Partition Table (GPT)
  69 found on Intel Itanium computers and Intel-based Macintosh computers.
  70 The
  71 .Dv GEOM_PART_MBR
  72 option adds support for the Master Boot Record (MBR)
  73 found on PCs and used on many removable media.
  74 The
  75 .Dv GEOM_PART_PC98
  76 option adds support for the MBR variant as used on
  77 NEC PC-98 computers.
  78 The
  79 .Dv GEOM_PART_VTOC8
  80 option adds support for Sun's SMI VTOC8 label as
  81 found on computers based on
  82 .Tn SPARC64
  83 and
  84 .Tn UltraSPARC.
  85 .Pp
  86 Usage of the
  87 .Ns Nm
  88 utility:
  89 .Pp
  90 .\" ==== ADD ====
  91 .Nm
  92 .Cm add
  93 .Fl t Ar type
  94 .Op Fl a Ar alignment
  95 .Op Fl b Ar start
  96 .Op Fl s Ar size
  97 .Op Fl i Ar index
  98 .Op Fl l Ar label
  99 .Op Fl f Ar flags
 100 .Ar geom
 101 .\" ==== BACKUP ====
 102 .Nm
 103 .Cm backup
 104 .Ar geom
 105 .\" ==== BOOTCODE ====
 106 .Nm
 107 .Cm bootcode
 108 .Op Fl b Ar bootcode
 109 .Op Fl p Ar partcode Fl i Ar index
 110 .Op Fl f Ar flags
 111 .Ar geom
 112 .\" ==== COMMIT ====
 113 .Nm
 114 .Cm commit
 115 .Ar geom
 116 .\" ==== CREATE ====
 117 .Nm
 118 .Cm create
 119 .Fl s Ar scheme
 120 .Op Fl n Ar entries
 121 .Op Fl f Ar flags
 122 .Ar provider
 123 .\" ==== DELETE ====
 124 .Nm
 125 .Cm delete
 126 .Fl i Ar index
 127 .Op Fl f Ar flags
 128 .Ar geom
 129 .\" ==== DESTROY ====
 130 .Nm
 131 .Cm destroy
 132 .Op Fl F\r
 133 .Op Fl f Ar flags
 134 .Ar geom
 135 .\" ==== MODIFY ====
 136 .Nm
 137 .Cm modify
 138 .Fl i Ar index
 139 .Op Fl l Ar label
 140 .Op Fl t Ar type
 141 .Op Fl f Ar flags
 142 .Ar geom
 143 .\" ==== RECOVER ====
 144 .Nm
 145 .Cm recover
 146 .Op Fl f Ar flags
 147 .Ar geom
 148 .\" ==== RESIZE ====
 149 .Nm
 150 .Cm resize
 151 .Fl i Ar index
 152 .Op Fl a Ar alignment
 153 .Op Fl s Ar size
 154 .Op Fl f Ar flags
 155 .Ar geom
 156 .\" ==== RESTORE ====
 157 .Nm
 158 .Cm restore
 159 .Op Fl lF
 160 .Op Fl f Ar flags
 161 .Ar provider
 162 .Op Ar ...
 163 .\" ==== SET ====
 164 .Nm
 165 .Cm set
 166 .Fl a Ar attrib
 167 .Fl i Ar index
 168 .Op Fl f Ar flags
 169 .Ar geom
 170 .\" ==== SHOW ====
 171 .Nm
 172 .Cm show
 173 .Op Fl lrp
 174 .Op Ar geom ...
 175 .\" ==== UNDO ====
 176 .Nm
 177 .Cm undo
 178 .Ar geom
 179 .\" ==== UNSET ====
 180 .Nm
 181 .Cm unset
 182 .Fl a Ar attrib
 183 .Fl i Ar index
 184 .Op Fl f Ar flags
 185 .Ar geom
 186 .\"
 187 .Sh DESCRIPTION
 188 The
 189 .Nm
 190 utility is used to partition GEOM providers, normally disks.
 191 The first argument of which is the action to be taken:
 192 .Bl -tag -width ".Cm bootcode"
 193 .\" ==== ADD ====
 194 .It Cm add
 195 Add a new partition to the partitioning scheme given by
 196 .Ar geom .
 197 The partition begins on the logical block address given by the
 198 .Fl b Ar start
 199 option.
 200 Its size is given by the
 201 .Fl s Ar size
 202 option. SI unit suffixes are allowed. One or both
 203 .Fl b
 204 and
 205 .Fl s
 206 options can be ommitted. If so they are automatically calculated.
 207 The type of the partition is given by the
 208 .Fl t Ar type
 209 option.
 210 Partition types are discussed below in the section entitled
 211 .Sx "PARTITION TYPES" .
 212 .Pp
 213 Additional options include:
 214 .Bl -tag -width 12n
 215 .It Fl a Ar alignment
 216 If specified, then
 217 .Nm
 218 utility tries to align
 219 .Ar start
 220 offset and partition
 221 .Ar size
 222 to be multiple of
 223 .Ar alignment
 224 value.
 225 .It Fl i Ar index
 226 The index in the partition table at which the new partition is to be
 227 placed.
 228 The index determines the name of the device special file used
 229 to represent the partition.
 230 .It Fl l Ar label
 231 The label attached to the partition.
 232 This option is only valid when used on partitioning schemes that support
 233 partition labels.
 234 .It Fl f Ar flags
 235 Additional operational flags.
 236 See the section entitled
 237 .Sx "OPERATIONAL FLAGS"
 238 below for a discussion
 239 about its use.
 240 .El
 241 .\" ==== BACKUP ====
 242 .It Cm backup
 243 Dump a partition table to standard output in special format used by
 244 .Cm restore
 245 action.
 246 .\" ==== BOOTCODE ====
 247 .It Cm bootcode
 248 Embed bootstrap code into the partitioning scheme's metadata on the
 249 .Ar geom
 250 (using
 251 .Fl b Ar bootcode )
 252 or write bootstrap code into a partition (using
 253 .Fl p Ar partcode
 254 and
 255 .Fl i Ar index ) .
 256 Not all partitioning schemes have embedded bootstrap code, so the
 257 .Fl b Ar bootcode
 258 option is scheme-specific in nature (see the section entitled
 259 .Sx BOOTSTRAPPING
 260 below).
 261 The
 262 .Fl b Ar bootcode
 263 option specifies a file that contains the bootstrap code.
 264 The contents and size of the file are determined by the partitioning
 265 scheme.
 266 The
 267 .Fl p Ar partcode
 268 option specifies a file that contains the bootstrap code intended to be
 269 written to a partition.
 270 The partition is specified by the
 271 .Fl i Ar index
 272 option.
 273 The size of the file must be smaller than the size of the partition.
 274 .Pp
 275 Additional options include:
 276 .Bl -tag -width 10n
 277 .It Fl f Ar flags
 278 Additional operational flags.
 279 See the section entitled
 280 .Sx "OPERATIONAL FLAGS"
 281 below for a discussion
 282 about its use.
 283 .El
 284 .\" ==== COMMIT ====
 285 .It Cm commit
 286 Commit any pending changes for geom
 287 .Ar geom .
 288 All actions are being committed by default and will not result in
 289 pending changes.
 290 Actions can be modified with the
 291 .Fl f Ar flags
 292 option so that they are not being committed by default.
 293 As such, they become pending.
 294 Pending changes are reflected by the geom and the
 295 .Nm
 296 utility, but they are not actually written to disk.
 297 The
 298 .Cm commit
 299 action will write any and all pending changes to disk.
 300 .\" ==== CREATE ====
 301 .It Cm create
 302 Create a new partitioning scheme on a provider given by
 303 .Ar provider .
 304 The
 305 .Fl s Ar scheme
 306 option determines the scheme to use.
 307 The kernel needs to have support for a particular scheme before
 308 that scheme can be used to partition a disk.
 309 .Pp
 310 Additional options include:
 311 .Bl -tag -width 10n
 312 .It Fl n Ar entries
 313 The number of entries in the partition table.
 314 Every partitioning scheme has a minimum and a maximum number of entries
 315 and this option allows tables to be created with the number of entries
 316 that lies anywhere between the minimum and the maximum.
 317 Some schemes have a maximum equal to the minimum and some schemes have
 318 a maximum large enough to be considered unlimited.
 319 By default, partition tables are created with the minimum number of
 320 entries.
 321 .It Fl f Ar flags
 322 Additional operational flags.
 323 See the section entitled
 324 .Sx "OPERATIONAL FLAGS"
 325 below for a discussion
 326 about its use.
 327 .El
 328 .\" ==== DELETE ====
 329 .It Cm delete
 330 Delete a partition from geom
 331 .Ar geom
 332 and further identified by the
 333 .Fl i Ar index
 334 option.
 335 The partition cannot be actively used by the kernel.
 336 .Pp
 337 Additional options include:
 338 .Bl -tag -width 10n
 339 .It Fl f Ar flags
 340 Additional operational flags.
 341 See the section entitled
 342 .Sx "OPERATIONAL FLAGS"
 343 below for a discussion
 344 about its use.
 345 .El
 346 .\" ==== DESTROY ====
 347 .It Cm destroy
 348 Destroy the partitioning scheme as implemented by geom
 349 .Ar geom .
 350 .Pp
 351 Additional options include:
 352 .Bl -tag -width 10n
 353 .It Fl F\r
 354 Forced destroying of the partition table even if it is not empty.\r
 355 .It Fl f Ar flags
 356 Additional operational flags.
 357 See the section entitled
 358 .Sx "OPERATIONAL FLAGS"
 359 below for a discussion
 360 about its use.
 361 .El
 362 .\" ==== MODIFY ====
 363 .It Cm modify
 364 Modify a partition from geom
 365 .Ar geom
 366 and further identified by the
 367 .Fl i Ar index
 368 option.
 369 Only the type and/or label of the partition can be modified.
 370 To change the type of a partition, specify the new type with the
 371 .Fl t Ar type
 372 option.
 373 To change the label of a partition, specify the new label with the
 374 .Fl l Ar label
 375 option.
 376 Not all partitioning schemes support labels and it is invalid to
 377 try to change a partition label in such cases.
 378 .Pp
 379 Additional options include:
 380 .Bl -tag -width 10n
 381 .It Fl f Ar flags
 382 Additional operational flags.
 383 See the section entitled
 384 .Sx "OPERATIONAL FLAGS"
 385 below for a discussion
 386 about its use.
 387 .El
 388 .\" ==== RECOVER ====
 389 .It Cm recover
 390 Recover corrupt partition's scheme metadata on the geom
 391 .Ar geom .
 392 See the section entitled
 393 .Sx "RECOVERING"
 394 below for the additional information.
 395 .Pp
 396 Additional options include:
 397 .Bl -tag -width 10n
 398 .It Fl f Ar flags
 399 Additional operational flags.
 400 See the section entitled
 401 .Sx "OPERATIONAL FLAGS"
 402 below for a discussion
 403 about its use.
 404 .El
 405 .\" ==== RESIZE ====
 406 .It Cm resize
 407 Resize a partition from geom
 408 .Ar geom
 409 and further identified by the
 410 .Fl i Ar index
 411 option.
 412 New partition size is expressed in logical block
 413 numbers and can be given by the
 414 .Fl s Ar size
 415 option.
 416 If
 417 .Fl s
 418 option is omitted then new size is automatically calculated
 419 to maximum available from given geom
 420 .Ar geom .
 421 .Pp
 422 Additional options include:
 423 .Bl -tag -width 12n
 424 .It Fl a Ar alignment
 425 If specified, then
 426 .Nm
 427 utility tries to align partition
 428 .Ar size
 429 to be multiple of
 430 .Ar alignment
 431 value.
 432 .It Fl f Ar flags
 433 Additional operational flags.
 434 See the section entitled
 435 .Sx "OPERATIONAL FLAGS"
 436 below for a discussion
 437 about its use.
 438 .El
 439 .\" ==== RESTORE ====
 440 .It Cm restore
 441 Restore the partition table from backup previously created by
 442 .Cm backup
 443 action and given from standard input.
 444 Only partition table may be restored.
 445 This action does not affect content of partitions.
 446 This mean that you should copy your data from backup after restoring
 447 partition table and write bootcode again if it is needed.
 448 .Pp
 449 Additional options include:
 450 .Bl -tag -width 10n
 451 .It Fl F
 452 Destroy partition table on the given
 453 .Ar provider
 454 before doing restore.
 455 .It Fl l
 456 Restore partition labels for partitioning schemes that support them.
 457 .It Fl f Ar flags
 458 Additional operational flags.
 459 See the section entitled
 460 .Sx "OPERATIONAL FLAGS"
 461 below for a discussion
 462 about its use.
 463 .El
 464 .\" ==== SET ====
 465 .It Cm set
 466 Set the named attribute on the partition entry.
 467 See the section entitled
 468 .Sx "ATTRIBUTES"
 469 below for a list of available attributes.
 470 .Pp
 471 Additional options include:
 472 .Bl -tag -width 10n
 473 .It Fl f Ar flags
 474 Additional operational flags.
 475 See the section entitled
 476 .Sx "OPERATIONAL FLAGS"
 477 below for a discussion
 478 about its use.
 479 .El
 480 .\" ==== SHOW ====
 481 .It Cm show
 482 Show the current partition information of the specified geoms
 483 or all geoms if none are specified.
 484 Additional options include:
 485 .Bl -tag -width 10n
 486 .It Fl l
 487 For partition schemes that support partition labels print them
 488 instead of partition type.
 489 .It Fl p
 490 Show provider names instead of partition indexes.
 491 .It Fl r
 492 Show raw partition type instead of symbolic name.
 493 .El
 494 .\" ==== UNDO ====
 495 .It Cm undo
 496 Revert any pending changes for geom
 497 .Ar geom .
 498 This action is the opposite of the
 499 .Cm commit
 500 action and can be used to undo any changes that have not been committed.
 501 .\" ==== UNSET ====
 502 .It Cm unset
 503 Clear the named attribute on the partition entry.
 504 See the section entitled
 505 .Sx "ATTRIBUTES"
 506 below for a list of available attributes.
 507 .Pp
 508 Additional options include:
 509 .Bl -tag -width 10n
 510 .It Fl f Ar flags
 511 Additional operational flags.
 512 See the section entitled
 513 .Sx "OPERATIONAL FLAGS"
 514 below for a discussion
 515 about its use.
 516 .El
 517 .El
 518 .\"
 519 .Sh PARTITION TYPES
 520 Partition types are identified on disk by particular strings or magic
 521 values.
 522 The
 523 .Nm
 524 utility uses symbolic names for common partition types to avoid the
 525 user needing to know these values or other details of the partitioning
 526 scheme in question.
 527 The
 528 .Nm
 529 utility also allows the user to specify scheme-specific partition types
 530 for partition types that do not have symbolic names.
 531 The symbolic names currently understood are:
 532 .Bl -tag -width ".Cm freebsd-vinum"
 533 .It Cm bios-boot
 534 The system partition dedicated to second stage of the boot loader program.
 535 Usually it used by GRUB 2 loader when the partition table is GPT.
 536 The scheme-specific type is
 537 .Qq Li "!21686148-6449-6E6F-744E-656564454649" .
 538 .It Cm efi
 539 The system partition for computers that use the Extensible Firmware
 540 Interface (EFI).
 541 In such cases, the GPT partitioning scheme is being used and the
 542 actual partition type for the system partition can also be specified as
 543 .Qq Li "!c12a7328-f81f-11d2-ba4b-00a0c93ec93ab" .
 544 .It Cm freebsd
 545 A
 546 .Fx
 547 partition that uses the
 548 .Bx
 549 disklabel to sub-divide the
 550 partition into file systems.
 551 This is a legacy partition type and should not be used for the APM
 552 or GPT schemes.
 553 The scheme-specific types are
 554 .Qq Li "!165"
 555 for MBR,
 556 .Qq Li "!FreeBSD"
 557 for APM, and
 558 .Qq Li "!516e7cb4-6ecf-11d6-8ff8-00022d09712b"
 559 for GPT.
 560 .It Cm freebsd-boot
 561 A
 562 .Fx
 563 partition dedicated to bootstrap code.
 564 The scheme-specific type is
 565 .Qq Li "!83bd6b9d-7f41-11dc-be0b-001560b84f0f"
 566 for GPT.
 567 .It Cm freebsd-swap
 568 A
 569 .Fx
 570 partition dedicated to swap space.
 571 The scheme-specific types are
 572 .Qq Li "!FreeBSD-swap"
 573 for APM,
 574 .Qq Li "!516e7cb5-6ecf-11d6-8ff8-00022d09712b"
 575 for GPT, and tag 0x0901 for VTOC8.
 576 .It Cm freebsd-ufs
 577 A
 578 .Fx
 579 partition that contains a UFS or UFS2 file system.
 580 The scheme-specific types are
 581 .Qq Li "!FreeBSD-UFS"
 582 for APM,
 583 .Qq Li "!516e7cb6-6ecf-11d6-8ff8-00022d09712b"
 584 for GPT, and tag 0x0902 for VTOC8.
 585 .It Cm freebsd-vinum
 586 A
 587 .Fx
 588 partition that contains a Vinum volume.
 589 The scheme-specific types are
 590 .Qq Li "!FreeBSD-Vinum"
 591 for APM,
 592 .Qq Li "!516e7cb8-6ecf-11d6-8ff8-00022d09712b"
 593 for GPT, and tag 0x0903 for VTOC8.
 594 .It Cm freebsd-zfs
 595 A
 596 .Fx
 597 partition that contains a ZFS volume.
 598 The scheme-specific types are
 599 .Qq Li "!FreeBSD-ZFS"
 600 for APM,
 601 .Qq Li "!516e7cba-6ecf-11d6-8ff8-00022d09712b"
 602 for GPT, and 0x0904 for VTOC8.
 603 .It Cm mbr
 604 A partition that is sub-partitioned by a master boot record (MBR).
 605 This type is known as
 606 .Qq Li "!024dee41-33e7-11d3-9d69-0008c781f39f"
 607 by GPT.
 608 .El
 609 .Sh ATTRIBUTES
 610 The scheme-specific attributes for EBR:
 611 .Bl -tag -width ".Ar active"
 612 .It Ar active
 613 .El
 614 .Pp
 615 The scheme-specific attributes for GPT:
 616 .Bl -tag -width ".Ar bootfailed"
 617 .It Ar bootme
 618 When set, the
 619 .Nm gptboot
 620 stage 1 boot loader will try to boot the system from this partition.
 621 Multiple partitions might be marked with the
 622 .Ar bootme
 623 attribute.
 624 In such scenario the
 625 .Nm gptboot
 626 will try all
 627 .Ar bootme
 628 partitions one by one, until the next boot stage is successfully entered.
 629 .It Ar bootonce
 630 Setting this attribute automatically sets the
 631 .Ar bootme
 632 attribute.
 633 When set, the
 634 .Nm gptboot
 635 stage 1 boot loader will try to boot the system from this partition only once.
 636 Partitions with both
 637 .Ar bootonce
 638 and
 639 .Ar bootme
 640 attributes are tried before partitions with only the
 641 .Ar bootme
 642 attribute.
 643 Before
 644 .Ar bootonce
 645 partition is tried, the
 646 .Nm gptboot
 647 removes the
 648 .Ar bootme
 649 attribute and tries to execute the next boot stage.
 650 If it fails, the
 651 .Ar bootonce
 652 attribute that is now alone is replaced with the
 653 .Ar bootfailed
 654 attribute.
 655 If the execution of the next boot stage succeeds, but the system is not fully
 656 booted, the
 657 .Nm gptboot
 658 will look for
 659 .Ar bootonce
 660 attributes alone (without the
 661 .Ar bootme
 662 attribute) on the next system boot and will replace those with the
 663 .Ar bootfailed
 664 attribute.
 665 If the system is fully booted, the
 666 .Pa /etc/rc.d/gptboot
 667 start-up script will look for partition with the
 668 .Ar bootonce
 669 attribute alone, will remove the attribute and log that the system was
 670 successfully booted from this partition.
 671 There should be at most one
 672 .Ar bootonce
 673 partition when system is successfully booted.
 674 Multiple partitions might be marked with the
 675 .Ar bootonce
 676 and
 677 .Ar bootme
 678 attribute pairs.
 679 .It Ar bootfailed
 680 This attribute should not be manually managed.
 681 It is managed by the
 682 .Nm gptboot
 683 stage 1 boot loader and the
 684 .Pa /etc/rc.d/gptboot
 685 start-up script.
 686 This attribute is used to mark partitions that had the
 687 .Ar bootonce
 688 attribute set, but we failed to boot from them.
 689 Once we successfully boot, the
 690 .Pa /etc/rc.d/gptboot
 691 script will log all the partitions we failed to boot from and will remove the
 692 .Ar bootfailed
 693 attributes.
 694 .El
 695 .Pp
 696 The scheme-specific attributes for MBR:
 697 .Bl -tag -width ".Ar active"
 698 .It Ar active
 699 .El
 700 .Pp
 701 The scheme-specific attributes for PC98:
 702 .Bl -tag -width ".Ar bootable"
 703 .It Ar active
 704 .It Ar bootable
 705 .El
 706 .Sh BOOTSTRAPPING
 707 .Fx
 708 supports several partitioning schemes and each scheme uses different
 709 bootstrap code.
 710 The bootstrap code is located in the specific disk area for each partitioning
 711 scheme and also it might have different size.
 712 .Pp
 713 The bootstrap code could be separated into two types.
 714 The first one is embedded in the partitioning scheme's metadata, the second
 715 type is located on the specific partition.
 716 The embedding bootstrap code should be done only with the
 717 .Cm gpart bootcode
 718 command with
 719 .Fl b Ar bootcode
 720 option.
 721 The GEOM PART class has knowlege on how to embed bootstrap code into specific
 722 partitioning scheme metadata without damage.
 723 .Pp
 724 The Master Boot Record (MBR) uses 512-bytes bootstrap code image, embedded into
 725 partition table's metadata area.
 726 There are two variants of this bootstrap code:
 727 .Pa /boot/mbr
 728 and
 729 .Pa /boot/boot0 .
 730 The first one searches partition with
 731 .Cm active
 732 attribute (see the
 733 .Sx ATTRIBUTES
 734 section) in the partition table.
 735 Then it runs next bootstrap stage.
 736 The
 737 .Pa /boot/boot0
 738 image contains a boot manager with some additional interactive functions.
 739 .Pp
 740 The BSD disklabel is usually created on top of the MBR partition (slice)
 741 with type
 742 .Cm freebsd
 743 (see the
 744 .Sx "PARTITION TYPES"
 745 section).
 746 It uses 8 KB size bootstrap code image
 747 .Pa /boot/boot ,
 748 embedded into partition table's metadata area.
 749 .Pp
 750 Both types of bootstrap code are used to boot from the GUID Partition Table.
 751 First of all, a protective MBR is embedded into first disk sector from the
 752 .Pa /boot/pmbr
 753 image.
 754 It searches the
 755 .Cm freebsd-boot
 756 partition (see the
 757 .Sx "PARTITION TYPES"
 758 section) in the GPT and runs next bootstrap stage from it.
 759 The
 760 .Cm freebsd-boot
 761 partition should be smaller than 545 KB.
 762 There are two variants of bootstrap code to write to this partition:
 763 .Pa /boot/gptboot
 764 and
 765 .Pa /boot/gptzfsboot .
 766 The first one is used to boot from UFS.
 767 It searches in the GPT partition with type
 768 .Cm freebsd-ufs ,
 769 and it runs the third bootstrap stage (
 770 .Pa /boot/loader )
 771 if it is found.
 772 The
 773 .Pa /boot/gptzfsboot
 774 is used to boot from ZFS.
 775 It searches partition with type
 776 .Cm freebsd-zfs
 777 and starts
 778 .Pa /boot/zfsloader
 779 from it.
 780 .Pp
 781 The VTOC8 scheme does not support embedding bootstrap code.
 782 Instead, the 8 KBytes bootstrap code image
 783 .Pa /boot/boot1
 784 should be written with
 785 .Cm gpart bootcode
 786 command with
 787 .Fl p Ar bootcode
 788 option to all sufficiently large VTOC8 partitions.
 789 To do this the
 790 .Fl i Ar index
 791 option could be ommited.
 792 .Pp
 793 The APM scheme also does not support embedding bootstrap code.
 794 Instead, the 800 KBytes bootstrap code image
 795 .Pa /boot/boot1.hfs
 796 should be written with
 797 .Cm gpart bootcode
 798 command to a partition of type
 799 .Cm freebsd-boot ,
 800 which should also be 800 KB in size.
 801 .Sh OPERATIONAL FLAGS
 802 Actions other than the
 803 .Cm commit
 804 and
 805 .Cm undo
 806 actions take an optional
 807 .Fl f Ar flags
 808 option.
 809 This option is used to specify action-specific operational flags.
 810 By default, the
 811 .Nm
 812 utility defines the
 813 .Ql C
 814 flag so that the action is immediately
 815 committed.
 816 The user can specify
 817 .Dq Fl f Cm x
 818 to have the action result in a pending change that can later, with
 819 other pending changes, be committed as a single compound change with
 820 the
 821 .Cm commit
 822 action or reverted with the
 823 .Cm undo
 824 action.
 825 .Sh RECOVERING
 826 The GEOM PART class supports recovering of partition tables only for GPT.
 827 The GUID partition table has a primary and secondary (backup) copy of
 828 metadata for redundance, these are stored at the begining and the end
 829 of the device respectively.
 830 As a result of having two copies, it is acceptable to have some corruption
 831 within the metadata that is not fatal to the working of GPT.
 832 When the kernel detects corrupt metadata it marks this table as corrupt and
 833 reports the corruption.
 834 Any operations on corrupt tables are prohibited except for
 835 .Cm destroy
 836 and
 837 .Cm recover .
 838 .Pp
 839 If the first sector of a provider is corrupt, the kernel can not detect GPT
 840 even if partition table itself is not corrupt.
 841 You can rewrite the protective MBR using the
 842 .Xr dd 1
 843 command, to restore the ability to detect the GPT.
 844 The copy of the protective MBR is usually located in the
 845 .Pa /boot/pmbr
 846 file.
 847 .Pp
 848 If one GPT header appears to be corrupt but the other copy remains intact,
 849 the kernel will log the following:
 850 .Bd -literal -offset indent
 851 GEOM: provider: the primary GPT table is corrupt or invalid.
 852 GEOM: provider: using the secondary instead -- recovery strongly advised.
 853 .Ed
 854 .Pp
 855 or
 856 .Bd -literal -offset indent
 857 GEOM: provider: the secondary GPT table is corrupt or invalid.
 858 GEOM: provider: using the primary only -- recovery suggested.
 859 .Ed
 860 .Pp
 861 Also
 862 .Nm
 863 commands such as
 864 .Cm show , status
 865 and
 866 .Cm list
 867 will report about corrupt tables.
 868 .Pp
 869 If the size of the device has changed (e.g.\& volume expansion) the
 870 secondary GPT header will no longer be located in the last sector.
 871 This is not a metadata corruption, but it is dangerous because any
 872 corruption of the primary GPT will lead to loss of partition table.
 873 This problem is reported by the kernel with the message:
 874 .Bd -literal -offset indent
 875 GEOM: provider: the secondary GPT header is not in the last LBA.
 876 .Ed
 877 .Pp
 878 This situation can be recovered with the
 879 .Cm recover
 880 command.
 881 This command reconstructs the corrupt metadata using known valid
 882 metadata and relocates the secondary GPT to the end of the device.
 883 .Pp
 884 .Em NOTE :
 885 The GEOM PART class can detect the same partition table visible through
 886 different GEOM providers, and some of them will be marked as corrupt.
 887 Be careful when choosing a provider for recovery.
 888 If you choose incorrectly you can destroy the metadata of another GEOM class,
 889 e.g.\& GEOM MIRROR or GEOM LABEL.
 890 .Sh EXIT STATUS
 891 Exit status is 0 on success, and 1 if the command fails.
 892 .Sh EXAMPLES
 893 Create GPT scheme on
 894 .Pa ad0 .
 895 .Bd -literal -offset indent
 896 /sbin/gpart create -s GPT ad0
 897 .Ed
 898 .Pp
 899 Embed GPT bootstrap code into protective MBR.
 900 .Bd -literal -offset indent
 901 /sbin/gpart bootcode -b /boot/pmbr ad0
 902 .Ed
 903 .Pp
 904 Create a dedicated
 905 .Cm freebsd-boot
 906 partition that can boot
 907 .Fx
 908 from a
 909 .Cm freebsd-ufs
 910 partition, and install bootstrap code into it.
 911 This partition must be larger than
 912 .Pa /boot/gptboot ,
 913 or the GPT boot you are planning to write, but smaller than 545 KB.
 914 A size of 15 blocks (7680 bytes) would be sufficient for
 915 booting from UFS but let's use 128 blocks (64 KB) here in
 916 this example, in order to reserve some space for potential
 917 future need (e.g.\& from a ZFS partition).
 918 .Bd -literal -offset indent
 919 /sbin/gpart add -b 34 -s 128 -t freebsd-boot ad0
 920 /sbin/gpart bootcode -p /boot/gptboot -i 1 ad0
 921 .Ed
 922 .Pp
 923 Create a 512MB-sized
 924 .Cm freebsd-ufs
 925 partition that would contain UFS where the system boots from.
 926 .Bd -literal -offset indent
 927 /sbin/gpart add -b 162 -s 1048576 -t freebsd-ufs ad0
 928 .Ed
 929 .Pp
 930 Create VTOC8 scheme on
 931 .Pa da0 .
 932 .Bd -literal -offset indent
 933 /sbin/gpart create -s VTOC8 da0
 934 .Ed
 935 .Pp
 936 Create a 512MB-sized
 937 .Cm freebsd-ufs
 938 partition that would contain UFS where the system boots from.
 939 .Bd -literal -offset indent
 940 /sbin/gpart add -s 512M -t freebsd-ufs da0
 941 .Ed
 942 .Pp
 943 Create a 15GB-sized
 944 .Cm freebsd-ufs
 945 partition that would contain UFS and aligned on 4KB boundaries:
 946 .Bd -literal -offset indent
 947 /sbin/gpart add -s 15G -t freebsd-ufs -a 4k da0
 948 .Ed
 949 .Pp
 950 After having created all required partitions, embed bootstrap code into them.
 951 .Bd -literal -offset indent
 952 /sbin/gpart bootcode -p /boot/boot1 da0
 953 .Ed
 954 .Pp
 955 Create backup of partition table from
 956 .Pa da0
 957 .Bd -literal -offset indent
 958 /sbin/gpart backup da0 > da0.backup
 959 .Ed
 960 .Pp
 961 Restore partition table from backup to
 962 .Pa da0
 963 .Bd -literal -offset indent
 964 /sbin/gpart restore -l da0 < /mnt/da0.backup
 965 .Ed
 966 .Pp
 967 Clone partition table from
 968 .Pa ada0
 969 to
 970 .Pa ada1
 971 and
 972 .Pa ada2
 973 .Bd -literal -offset indent
 974 /sbin/gpart backup ada0 | /sbin/gpart restore -F ada1 ada2
 975 .Ed
 976 .Sh SEE ALSO
 977 .Xr dd 1 ,
 978 .Xr geom 4 ,
 979 .Xr boot0cfg 8 ,
 980 .Xr geom 8
 981 .Sh HISTORY
 982 The
 983 .Nm
 984 utility appeared in
 985 .Fx 7.0 .
 986 .Sh AUTHORS
 987 .An Marcel Moolenaar Aq marcel@FreeBSD.org