1 .\" Copyright (c) 2007, 2008 Marcel Moolenaar
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd "control utility for the disk partitioning GEOM class"
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"
49 These options provide support for the various types of partitioning
50 schemes supported by the
54 .Sx "PARTITIONING SCHEMES"
55 below for more details.
76 .\" ==== BOOTCODE ====
80 .Op Fl p Ar partcode Fl i Ar index
100 .\" ==== DESTROY ====
114 .\" ==== RECOVER ====
123 .Op Fl a Ar alignment
127 .\" ==== RESTORE ====
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"
167 Add a new partition to the partitioning scheme given by
169 The partition begins on the logical block address given by the
172 Its size is given by the
175 SI unit suffixes are allowed.
180 options can be omitted.
181 If so they are automatically calculated.
182 The type of the partition is given by the
185 Partition types are discussed below in the section entitled
186 .Sx "PARTITION TYPES" .
188 Additional options include:
190 .It Fl a Ar alignment
193 utility tries to align
201 The index in the partition table at which the new partition is to be
203 The index determines the name of the device special file used
204 to represent the partition.
206 The label attached to the partition.
207 This option is only valid when used on partitioning schemes that support
210 Additional operational flags.
211 See the section entitled
212 .Sx "OPERATIONAL FLAGS"
213 below for a discussion
218 Dump a partition table to standard output in a special format used by the
221 .\" ==== BOOTCODE ====
223 Embed bootstrap code into the partitioning scheme's metadata on the
227 or write bootstrap code into a partition (using
231 Not all partitioning schemes have embedded bootstrap code, so the
233 option is scheme-specific in nature (see the section entitled
238 option specifies a file that contains the bootstrap code.
239 The contents and size of the file are determined by the partitioning
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
248 The size of the file must be smaller than the size of the partition.
250 Additional options include:
253 Additional operational flags.
254 See the section entitled
255 .Sx "OPERATIONAL FLAGS"
256 below for a discussion
261 Commit any pending changes for geom
263 All actions are committed by default and will not result in
265 Actions can be modified with the
267 option so that they are not committed, but become pending.
268 Pending changes are reflected by the geom and the
270 utility, but they are not actually written to disk.
273 action will write all pending changes to disk.
276 Create a new partitioning scheme on a provider given by
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.
284 Additional options include:
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
296 Additional operational flags.
297 See the section entitled
298 .Sx "OPERATIONAL FLAGS"
299 below for a discussion
304 Delete a partition from geom
306 and further identified by the
309 The partition cannot be actively used by the kernel.
311 Additional options include:
314 Additional operational flags.
315 See the section entitled
316 .Sx "OPERATIONAL FLAGS"
317 below for a discussion
320 .\" ==== DESTROY ====
322 Destroy the partitioning scheme as implemented by geom
325 Additional options include:
328 Forced destroying of the partition table even if it is not empty.
330 Additional operational flags.
331 See the section entitled
332 .Sx "OPERATIONAL FLAGS"
333 below for a discussion
338 Modify a partition from geom
340 and further identified by the
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
347 To change the label of a partition, specify the new label with the
350 Not all partitioning schemes support labels and it is invalid to
351 try to change a partition label in such cases.
353 Additional options include:
356 Additional operational flags.
357 See the section entitled
358 .Sx "OPERATIONAL FLAGS"
359 below for a discussion
362 .\" ==== RECOVER ====
364 Recover a corrupt partition's scheme metadata on the geom
366 See the section entitled
368 below for the additional information.
370 Additional options include:
373 Additional operational flags.
374 See the section entitled
375 .Sx "OPERATIONAL FLAGS"
376 below for a discussion
381 Resize a partition from geom
383 and further identified by the
386 New partition size is expressed in logical block
387 numbers and can be given by the
392 option is omitted then new size is automatically calculated
393 to maximum available from given geom
396 Additional options include:
398 .It Fl a Ar alignment
401 utility tries to align partition
407 Additional operational flags.
408 See the section entitled
409 .Sx "OPERATIONAL FLAGS"
410 below for a discussion
413 .\" ==== RESTORE ====
415 Restore the partition table from a backup previously created by the
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.
423 Additional options include:
426 Destroy partition table on the given
428 before doing restore.
430 Restore partition labels for partitioning schemes that support them.
432 Additional operational flags.
433 See the section entitled
434 .Sx "OPERATIONAL FLAGS"
435 below for a discussion
440 Set the named attribute on the partition entry.
441 See the section entitled
443 below for a list of available attributes.
445 Additional options include:
448 Additional operational flags.
449 See the section entitled
450 .Sx "OPERATIONAL FLAGS"
451 below for a discussion
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
464 Additional options include:
467 For partitioning schemes that support partition labels, print them
468 instead of partition type.
470 Show provider names instead of partition indexes.
472 Show raw partition type instead of symbolic name.
476 Revert any pending changes for geom
478 This action is the opposite of the
480 action and can be used to undo any changes that have not been committed.
483 Clear the named attribute on the partition entry.
484 See the section entitled
486 below for a list of available attributes.
488 Additional options include:
491 Additional operational flags.
492 See the section entitled
493 .Sx "OPERATIONAL FLAGS"
494 below for a discussion
498 .Sh PARTITIONING SCHEMES
499 Several partitioning schemes are supported by the
502 .Bl -tag -width ".Cm VTOC8"
504 Apple Partition Map, used by PowerPC(R) Macintosh(R) computers.
509 Traditional BSD disklabel, usually used to subdivide MBR partitions.
511 This scheme can also be used as the sole partitioning method, without
513 Partition editing tools from other operating systems often do not
514 understand the bare disklabel partition layout, so this is sometimes
516 .Dq dangerously dedicated .
522 The Logical Disk Manager is an implementation of volume manager for
523 Microsoft Windows NT.
528 GUID Partition Table is used on Intel-based Macintosh computers and
529 gradually replacing MBR on most PCs and other systems.
534 Master Boot Record is used on PCs and removable media.
540 option adds support for the Extended Boot Record (EBR),
541 which is used to define a logical partition.
543 .Cm GEOM_PART_EBR_COMPAT
544 option enables backward compatibility for partition names
546 It also prevents any type of actions on such partitions.
548 An MBR variant for NEC PC-98 and compatible computers.
553 Sun's SMI Volume Table Of Contents, used by
563 Partition types are identified on disk by particular strings or magic
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
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"
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" .
582 The system partition for computers that use the Extensible Firmware
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" .
590 partition subdivided into filesystems with a
593 This is a legacy partition type and should not be used for the APM
595 The scheme-specific types are
600 .Qq Li "!516e7cb4-6ecf-11d6-8ff8-00022d09712b"
605 partition dedicated to bootstrap code.
606 The scheme-specific type is
607 .Qq Li "!83bd6b9d-7f41-11dc-be0b-001560b84f0f"
612 partition dedicated to swap space.
613 The scheme-specific types are
614 .Qq Li "!FreeBSD-swap"
616 .Qq Li "!516e7cb5-6ecf-11d6-8ff8-00022d09712b"
617 for GPT, and tag 0x0901 for VTOC8.
621 partition that contains a UFS or UFS2 filesystem.
622 The scheme-specific types are
623 .Qq Li "!FreeBSD-UFS"
625 .Qq Li "!516e7cb6-6ecf-11d6-8ff8-00022d09712b"
626 for GPT, and tag 0x0902 for VTOC8.
630 partition that contains a Vinum volume.
631 The scheme-specific types are
632 .Qq Li "!FreeBSD-Vinum"
634 .Qq Li "!516e7cb8-6ecf-11d6-8ff8-00022d09712b"
635 for GPT, and tag 0x0903 for VTOC8.
639 partition that contains a ZFS volume.
640 The scheme-specific types are
641 .Qq Li "!FreeBSD-ZFS"
643 .Qq Li "!516e7cba-6ecf-11d6-8ff8-00022d09712b"
644 for GPT, and 0x0904 for VTOC8.
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"
651 A partition that contains Logical Disk Manager (LDM) volumes.
652 The scheme-specific types are
655 .Qq Li "!af9b60a0-1431-4f62-bc68-3311714a69ad"
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"
664 The scheme-specific attributes for EBR:
665 .Bl -tag -width ".Cm active"
669 The scheme-specific attributes for GPT:
670 .Bl -tag -width ".Cm bootfailed"
674 stage 1 boot loader will try to boot the system from this partition.
675 Multiple partitions might be marked with the
682 partitions one by one, until the next boot stage is successfully entered.
684 Setting this attribute automatically sets the
689 stage 1 boot loader will try to boot the system from this partition only once.
694 attributes are tried before partitions with only the
699 partition is tried, the
703 attribute and tries to execute the next boot stage.
706 attribute that is now alone is replaced with the
709 If the execution of the next boot stage succeeds, but the system is not fully
714 attributes alone (without the
716 attribute) on the next system boot and will replace those with the
719 If the system is fully booted, the
720 .Pa /etc/rc.d/gptboot
721 start-up script will look for partition with the
723 attribute alone, will remove the attribute and log that the system was
724 successfully booted from this partition.
725 There should be at most one
727 partition when system is successfully booted.
728 Multiple partitions might be marked with the
734 This attribute should not be manually managed.
737 stage 1 boot loader and the
738 .Pa /etc/rc.d/gptboot
740 This attribute is used to mark partitions that had the
742 attribute set, but we failed to boot from them.
743 Once we successfully boot, the
744 .Pa /etc/rc.d/gptboot
745 script will log all the partitions we failed to boot from and will remove the
750 The scheme-specific attributes for MBR:
751 .Bl -tag -width ".Cm active"
755 The scheme-specific attributes for PC98:
756 .Bl -tag -width ".Cm bootable"
762 supports several partitioning schemes and each scheme uses different
764 The bootstrap code is located in a specific disk area for each partitioning
765 scheme, and may vary in size for different schemes.
767 Bootstrap code can be separated into two types.
768 The first type is embedded in the partitioning scheme's metadata, while the
769 second type is located on a specific partition.
770 Embedding bootstrap code should only be done with the
775 The GEOM PART class knows how to safely embed bootstrap code into
776 specific partitioning scheme metadata without causing any damage.
778 The Master Boot Record (MBR) uses a 512-byte bootstrap code image, embedded
779 into the partition table's metadata area.
780 There are two variants of this bootstrap code:
785 searches for a partition with the
789 section) in the partition table.
790 Then it runs next bootstrap stage.
793 image contains a boot manager with some additional interactive functions
794 for multi-booting from a user-selected partition.
796 A BSD disklabel is usually created inside an MBR partition (slice)
800 .Sx "PARTITION TYPES"
802 It uses 8 KB size bootstrap code image
804 embedded into the partition table's metadata area.
806 Both types of bootstrap code are used to boot from the GUID Partition Table.
807 First, a protective MBR is embedded into the first disk sector from the
813 .Sx "PARTITION TYPES"
814 section) in the GPT and runs the next bootstrap stage from it.
817 partition should be smaller than 545 KB.
818 There are two variants of bootstrap code to write to this partition:
821 .Pa /boot/gptzfsboot .
823 is used to boot from UFS.
826 GPT partitions and starts
828 .Pq the third bootstrap stage
832 is used to boot from ZFS.
835 GPT partitions and starts
839 The VTOC8 scheme does not support embedding bootstrap code.
840 Instead, the 8 KBytes bootstrap code image
842 should be written with the
846 option to all sufficiently large VTOC8 partitions.
849 option could be omitted.
851 The APM scheme also does not support embedding bootstrap code.
852 Instead, the 800 KBytes bootstrap code image
854 should be written with the
856 command to a partition of type
858 which should also be 800 KB in size.
859 .Sh OPERATIONAL FLAGS
860 Actions other than the
864 actions take an optional
867 This option is used to specify action-specific operational flags.
872 flag so that the action is immediately
876 to have the action result in a pending change that can later, with
877 other pending changes, be committed as a single compound change with
880 action or reverted with the
884 The GEOM PART class supports recovering of partition tables only for GPT.
885 The GPT primary metadata is stored at the beginning of the device.
886 For redundancy, a secondary
888 copy of the metadata is stored at the end of the device.
889 As a result of having two copies, some corruption of metadata is not
890 fatal to the working of GPT.
891 When the kernel detects corrupt metadata, it marks this table as corrupt
892 and reports the problem.
896 are the only operations allowed on corrupt tables.
898 If the first sector of a provider is corrupt, the kernel can not detect GPT
899 even if the partition table itself is not corrupt.
900 The protective MBR can be rewritten using the
902 command, to restore the ability to detect the GPT.
903 The copy of the protective MBR is usually located in the
907 If one GPT header appears to be corrupt but the other copy remains intact,
908 the kernel will log the following:
909 .Bd -literal -offset indent
910 GEOM: provider: the primary GPT table is corrupt or invalid.
911 GEOM: provider: using the secondary instead -- recovery strongly advised.
915 .Bd -literal -offset indent
916 GEOM: provider: the secondary GPT table is corrupt or invalid.
917 GEOM: provider: using the primary only -- recovery suggested.
926 will report about corrupt tables.
928 If the size of the device has changed (e.g.,\& volume expansion) the
929 secondary GPT header will no longer be located in the last sector.
930 This is not a metadata corruption, but it is dangerous because any
931 corruption of the primary GPT will lead to loss of the partition table.
932 This problem is reported by the kernel with the message:
933 .Bd -literal -offset indent
934 GEOM: provider: the secondary GPT header is not in the last LBA.
937 This situation can be recovered with the
940 This command reconstructs the corrupt metadata using known valid
941 metadata and relocates the secondary GPT to the end of the device.
944 The GEOM PART class can detect the same partition table visible through
945 different GEOM providers, and some of them will be marked as corrupt.
946 Be careful when choosing a provider for recovery.
947 If you choose incorrectly you can destroy the metadata of another GEOM class,
948 e.g.\& GEOM MIRROR or GEOM LABEL.
952 variables can be used to control the behavior of the
955 The default value is shown next to each variable.
956 .Bl -tag -width indent
957 .It Va kern.geom.part.check_integrity : No 1
958 This variable controls the behaviour of metadata integrity checks.
959 When integrity checks are enabled, the
961 GEOM class verifies all generic partition parameters obtained from the
963 If some inconsistency is detected, the partition table will be
964 rejected with a diagnostic message:
965 .Sy "GEOM_PART: Integrity check failed (provider, scheme)" .
966 .It Va kern.geom.part.ldm.debug : No 0
967 Debug level of the Logical Disk Manager (LDM) module.
968 This can be set to a number between 0 and 2 inclusive.
969 If set to 0 minimal debug information is printed,
970 and if set to 2 the maximum amount of debug information is printed.
971 .It Va kern.geom.part.ldm.show_mirrors : No 0
972 This variable controls how the Logical Disk Manager (LDM) module handles
974 By default mirrored volumes are shown as partitions with type
977 .Sx "PARTITION TYPES"
979 If this variable set to 1 each component of the mirrored volume will be
980 present as independent partition.
982 This may break a mirrored volume and lead to data damage.
985 Exit status is 0 on success, and 1 if the command fails.
987 Create a GPT scheme on
989 .Bd -literal -offset indent
990 /sbin/gpart create -s GPT ada0
993 Embed GPT bootstrap code into a protective MBR:
994 .Bd -literal -offset indent
995 /sbin/gpart bootcode -b /boot/pmbr ada0
1000 partition that can boot
1004 partition, and install bootstrap code into it.
1005 This partition must be larger than the bootstrap code
1010 .Pa /boot/gptzfsboot
1012 but smaller than 545 kB since the first-stage loader will load the
1013 entire partition into memory during boot, regardless of how much data
1014 it actually contains.
1015 This example uses 88 blocks (44 kB) so the next partition will be
1016 aligned on a 64 kB boundary without the need to specify an explicit
1017 offset or alignment.
1018 The boot partition itself is aligned on a 4 kB boundary.
1019 .Bd -literal -offset indent
1020 /sbin/gpart add -b 40 -s 88 -t freebsd-boot ada0
1021 /sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
1024 Create a 512MB-sized
1026 partition to contain a UFS filesystem from which the system can boot.
1027 .Bd -literal -offset indent
1028 /sbin/gpart add -s 512M -t freebsd-ufs ada0
1031 Create an MBR scheme on
1033 then create a 30GB-sized
1035 slice, mark it active and
1039 .Bd -literal -offset indent
1040 /sbin/gpart create -s MBR ada0
1041 /sbin/gpart add -t freebsd -s 30G ada0
1042 /sbin/gpart set -a active -i 1 ada0
1043 /sbin/gpart bootcode -b /boot/boot0 ada0
1050 label) with space for up to 20 partitions:
1051 .Bd -literal -offset indent
1052 /sbin/gpart create -s BSD -n 20 ada0s1
1055 Create a 1GB-sized UFS partition and a 4GB-sized swap partition:
1056 .Bd -literal -offset indent
1057 /sbin/gpart add -t freebsd-ufs -s 1G ada0s1
1058 /sbin/gpart add -t freebsd-swap -s 4G ada0s1
1061 Install bootstrap code for the
1064 .Bd -literal -offset indent
1065 /sbin/gpart bootcode -b /boot/boot ada0s1
1068 Create a VTOC8 scheme on
1070 .Bd -literal -offset indent
1071 /sbin/gpart create -s VTOC8 da0
1074 Create a 512MB-sized
1076 partition to contain a UFS filesystem from which the system can boot.
1077 .Bd -literal -offset indent
1078 /sbin/gpart add -s 512M -t freebsd-ufs da0
1083 partition to contain a UFS filesystem and aligned on 4KB boundaries:
1084 .Bd -literal -offset indent
1085 /sbin/gpart add -s 15G -t freebsd-ufs -a 4k da0
1088 After creating all required partitions, embed bootstrap code into them:
1089 .Bd -literal -offset indent
1090 /sbin/gpart bootcode -p /boot/boot1 da0
1093 Create a backup of the partition table from
1095 .Bd -literal -offset indent
1096 /sbin/gpart backup da0 > da0.backup
1099 Restore the partition table from the backup to
1101 .Bd -literal -offset indent
1102 /sbin/gpart restore -l da0 < /mnt/da0.backup
1105 Clone the partition table from
1111 .Bd -literal -offset indent
1112 /sbin/gpart backup ada0 | /sbin/gpart restore -F ada1 ada2
1125 .An Marcel Moolenaar Aq marcel@FreeBSD.org