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