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