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