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"
49 .\" ==== BOOTCODE ====
53 .Op Fl p Ar partcode Fl i Ar index
100 .\" ==== RESTORE ====
135 utility is used to partition GEOM providers, normally disks.
136 The first argument is the action to be taken:
137 .Bl -tag -width ".Cm bootcode"
140 Add a new partition to the partitioning scheme given by
142 The partition begins on the logical block address given by the
145 Its size is given by the
148 SI unit suffixes are allowed.
153 options can be omitted.
154 If so they are automatically calculated.
155 The type of the partition is given by the
158 Partition types are discussed below in the section entitled
159 .Sx "PARTITION TYPES" .
161 Additional options include:
163 .It Fl a Ar alignment
166 utility tries to align
174 The index in the partition table at which the new partition is to be
176 The index determines the name of the device special file used
177 to represent the partition.
179 The label attached to the partition.
180 This option is only valid when used on partitioning schemes that support
183 Additional operational flags.
184 See the section entitled
185 .Sx "OPERATIONAL FLAGS"
186 below for a discussion
191 Dump a partition table to standard output in a special format used by the
194 .\" ==== BOOTCODE ====
196 Embed bootstrap code into the partitioning scheme's metadata on the
200 or write bootstrap code into a partition (using
204 Not all partitioning schemes have embedded bootstrap code, so the
206 option is scheme-specific in nature (see the section entitled
211 option specifies a file that contains the bootstrap code.
212 The contents and size of the file are determined by the partitioning
216 option specifies a file that contains the bootstrap code intended to be
217 written to a partition.
218 The partition is specified by the
221 The size of the file must be smaller than the size of the partition.
223 Additional options include:
226 Additional operational flags.
227 See the section entitled
228 .Sx "OPERATIONAL FLAGS"
229 below for a discussion
234 Commit any pending changes for geom
236 All actions are committed by default and will not result in
238 Actions can be modified with the
240 option so that they are not committed, but become pending.
241 Pending changes are reflected by the geom and the
243 utility, but they are not actually written to disk.
246 action will write all pending changes to disk.
249 Create a new partitioning scheme on a provider given by
253 option determines the scheme to use.
254 The kernel must have support for a particular scheme before
255 that scheme can be used to partition a disk.
257 Additional options include:
260 The number of entries in the partition table.
261 Every partitioning scheme has a minimum and maximum number of entries.
262 This option allows tables to be created with a number of entries
263 that is within the limits.
264 Some schemes have a maximum equal to the minimum and some schemes have
265 a maximum large enough to be considered unlimited.
266 By default, partition tables are created with the minimum number of
269 Additional operational flags.
270 See the section entitled
271 .Sx "OPERATIONAL FLAGS"
272 below for a discussion
277 Delete a partition from geom
279 and further identified by the
282 The partition cannot be actively used by the kernel.
284 Additional options include:
287 Additional operational flags.
288 See the section entitled
289 .Sx "OPERATIONAL FLAGS"
290 below for a discussion
293 .\" ==== DESTROY ====
295 Destroy the partitioning scheme as implemented by geom
298 Additional options include:
301 Forced destroying of the partition table even if it is not empty.
303 Additional operational flags.
304 See the section entitled
305 .Sx "OPERATIONAL FLAGS"
306 below for a discussion
311 Modify a partition from geom
313 and further identified by the
316 Only the type and/or label of the partition can be modified.
317 To change the type of a partition, specify the new type with the
320 To change the label of a partition, specify the new label with the
323 Not all partitioning schemes support labels and it is invalid to
324 try to change a partition label in such cases.
326 Additional options include:
329 Additional operational flags.
330 See the section entitled
331 .Sx "OPERATIONAL FLAGS"
332 below for a discussion
335 .\" ==== RECOVER ====
337 Recover a corrupt partition's scheme metadata on the geom
339 See the section entitled
341 below for the additional information.
343 Additional options include:
346 Additional operational flags.
347 See the section entitled
348 .Sx "OPERATIONAL FLAGS"
349 below for a discussion
354 Resize a partition from geom
356 and further identified by the
359 New partition size is expressed in logical block
360 numbers and can be given by the
365 option is omitted then new size is automatically calculated
366 to maximum available from given geom
369 Additional options include:
371 .It Fl a Ar alignment
374 utility tries to align partition
380 Additional operational flags.
381 See the section entitled
382 .Sx "OPERATIONAL FLAGS"
383 below for a discussion
386 .\" ==== RESTORE ====
388 Restore the partition table from a backup previously created by the
390 action and read from standard input.
391 Only the partition table is restored.
392 This action does not affect the content of partitions.
393 After restoring the partition table and writing bootcode if needed,
394 user data must be restored from backup.
396 Additional options include:
399 Destroy partition table on the given
401 before doing restore.
403 Restore partition labels for partitioning schemes that support them.
405 Additional operational flags.
406 See the section entitled
407 .Sx "OPERATIONAL FLAGS"
408 below for a discussion
413 Set the named attribute on the partition entry.
414 See the section entitled
416 below for a list of available attributes.
418 Additional options include:
421 Additional operational flags.
422 See the section entitled
423 .Sx "OPERATIONAL FLAGS"
424 below for a discussion
429 Show current partition information for the specified geoms, or all
430 geoms if none are specified.
431 The default output includes the logical starting block of each
432 partition, the partition size in blocks, the partition index number,
433 the partition type, and a human readable partition size.
434 Block sizes and locations are based on the device's Sectorsize
437 Additional options include:
440 For partitioning schemes that support partition labels, print them
441 instead of partition type.
443 Show provider names instead of partition indexes.
445 Show raw partition type instead of symbolic name.
449 Revert any pending changes for geom
451 This action is the opposite of the
453 action and can be used to undo any changes that have not been committed.
456 Clear the named attribute on the partition entry.
457 See the section entitled
459 below for a list of available attributes.
461 Additional options include:
464 Additional operational flags.
465 See the section entitled
466 .Sx "OPERATIONAL FLAGS"
467 below for a discussion
471 .Sh PARTITIONING SCHEMES
472 Several partitioning schemes are supported by the
475 .Bl -tag -width ".Cm VTOC8"
477 Apple Partition Map, used by PowerPC(R) Macintosh(R) computers.
482 Traditional BSD disklabel, usually used to subdivide MBR partitions.
484 This scheme can also be used as the sole partitioning method, without
486 Partition editing tools from other operating systems often do not
487 understand the bare disklabel partition layout, so this is sometimes
489 .Dq dangerously dedicated .
495 The Logical Disk Manager is an implementation of volume manager for
496 Microsoft Windows NT.
501 GUID Partition Table is used on Intel-based Macintosh computers and
502 gradually replacing MBR on most PCs and other systems.
507 Master Boot Record is used on PCs and removable media.
513 option adds support for the Extended Boot Record (EBR),
514 which is used to define a logical partition.
516 .Cm GEOM_PART_EBR_COMPAT
517 option enables backward compatibility for partition names
519 It also prevents any type of actions on such partitions.
521 An MBR variant for NEC PC-98 and compatible computers.
526 Sun's SMI Volume Table Of Contents, used by
536 Partition types are identified on disk by particular strings or magic
540 utility uses symbolic names for common partition types so the user
541 does not need to know these values or other details of the partitioning
545 utility also allows the user to specify scheme-specific partition types
546 for partition types that do not have symbolic names.
547 Symbolic names currently understood are:
548 .Bl -tag -width ".Cm ms-ldm-metadata"
550 The system partition dedicated to second stage of the boot loader program.
551 Usually it is used by the GRUB 2 loader for GPT partitioning schemes.
552 The scheme-specific type is
553 .Qq Li "!21686148-6449-6E6F-744E-656564454649" .
555 The system partition for computers that use the Extensible Firmware
557 In such cases, the GPT partitioning scheme is used and the
558 actual partition type for the system partition can also be specified as
559 .Qq Li "!c12a7328-f81f-11d2-ba4b-00a0c93ec93b" .
563 partition subdivided into filesystems with a
566 This is a legacy partition type and should not be used for the APM
568 The scheme-specific types are
573 .Qq Li "!516e7cb4-6ecf-11d6-8ff8-00022d09712b"
578 partition dedicated to bootstrap code.
579 The scheme-specific type is
580 .Qq Li "!83bd6b9d-7f41-11dc-be0b-001560b84f0f"
585 partition dedicated to swap space.
586 The scheme-specific types are
587 .Qq Li "!FreeBSD-swap"
589 .Qq Li "!516e7cb5-6ecf-11d6-8ff8-00022d09712b"
590 for GPT, and tag 0x0901 for VTOC8.
594 partition that contains a UFS or UFS2 filesystem.
595 The scheme-specific types are
596 .Qq Li "!FreeBSD-UFS"
598 .Qq Li "!516e7cb6-6ecf-11d6-8ff8-00022d09712b"
599 for GPT, and tag 0x0902 for VTOC8.
603 partition that contains a Vinum volume.
604 The scheme-specific types are
605 .Qq Li "!FreeBSD-Vinum"
607 .Qq Li "!516e7cb8-6ecf-11d6-8ff8-00022d09712b"
608 for GPT, and tag 0x0903 for VTOC8.
612 partition that contains a ZFS volume.
613 The scheme-specific types are
614 .Qq Li "!FreeBSD-ZFS"
616 .Qq Li "!516e7cba-6ecf-11d6-8ff8-00022d09712b"
617 for GPT, and 0x0904 for VTOC8.
619 A partition that is sub-partitioned by a Master Boot Record (MBR).
620 This type is known as
621 .Qq Li "!024dee41-33e7-11d3-9d69-0008c781f39f"
624 A partition that contains Logical Disk Manager (LDM) volumes.
625 The scheme-specific types are
628 .Qq Li "!af9b60a0-1431-4f62-bc68-3311714a69ad"
630 .It Cm ms-ldm-metadata
631 A partition that contains Logical Disk Manager (LDM) database.
632 The scheme-specific type is
633 .Qq Li "!5808c8aa-7e8f-42e0-85d2-e1e90434cfb3"
637 The scheme-specific attributes for EBR:
638 .Bl -tag -width ".Cm active"
642 The scheme-specific attributes for GPT:
643 .Bl -tag -width ".Cm bootfailed"
647 stage 1 boot loader will try to boot the system from this partition.
648 Multiple partitions can be marked with the
655 Setting this attribute automatically sets the
660 stage 1 boot loader will try to boot the system from this partition only once.
661 Multiple partitions can be marked with the
670 This attribute should not be manually managed.
673 stage 1 boot loader and the
674 .Pa /etc/rc.d/gptboot
681 The scheme-specific attributes for MBR:
682 .Bl -tag -width ".Cm active"
686 The scheme-specific attributes for PC98:
687 .Bl -tag -width ".Cm bootable"
693 supports several partitioning schemes and each scheme uses different
695 The bootstrap code is located in a specific disk area for each partitioning
696 scheme, and may vary in size for different schemes.
698 Bootstrap code can be separated into two types.
699 The first type is embedded in the partitioning scheme's metadata, while the
700 second type is located on a specific partition.
701 Embedding bootstrap code should only be done with the
706 The GEOM PART class knows how to safely embed bootstrap code into
707 specific partitioning scheme metadata without causing any damage.
709 The Master Boot Record (MBR) uses a 512-byte bootstrap code image, embedded
710 into the partition table's metadata area.
711 There are two variants of this bootstrap code:
716 searches for a partition with the
720 section) in the partition table.
721 Then it runs next bootstrap stage.
724 image contains a boot manager with some additional interactive functions
725 for multi-booting from a user-selected partition.
727 A BSD disklabel is usually created inside an MBR partition (slice)
731 .Sx "PARTITION TYPES"
733 It uses 8 KB size bootstrap code image
735 embedded into the partition table's metadata area.
737 Both types of bootstrap code are used to boot from the GUID Partition Table.
738 First, a protective MBR is embedded into the first disk sector from the
741 It searches through the GPT for a
744 .Sx "PARTITION TYPES"
745 section) and runs the next bootstrap stage from it.
748 partition should be smaller than 545 KB.
749 It can be located either before or after other
751 partitions on the disk.
752 There are two variants of bootstrap code to write to this partition:
755 .Pa /boot/gptzfsboot .
758 is used to boot from UFS partitions.
762 partitions in the GPT and selects one to boot based on the
767 If neither attribute is found,
773 .Pq the third bootstrap stage
774 is loaded from the first partition that matches these conditions.
777 for more information.
780 is used to boot from ZFS.
781 It searches through the GPT for
783 partitions, trying to detect ZFS pools.
784 After all pools are detected,
786 is started from the first one found.
788 The VTOC8 scheme does not support embedding bootstrap code.
789 Instead, the 8 KBytes bootstrap code image
791 should be written with the
795 option to all sufficiently large VTOC8 partitions.
798 option could be omitted.
800 The APM scheme also does not support embedding bootstrap code.
801 Instead, the 800 KBytes bootstrap code image
803 should be written with the
805 command to a partition of type
807 which should also be 800 KB in size.
808 .Sh OPERATIONAL FLAGS
809 Actions other than the
813 actions take an optional
816 This option is used to specify action-specific operational flags.
821 flag so that the action is immediately
825 to have the action result in a pending change that can later, with
826 other pending changes, be committed as a single compound change with
829 action or reverted with the
833 The GEOM PART class supports recovering of partition tables only for GPT.
834 The GPT primary metadata is stored at the beginning of the device.
835 For redundancy, a secondary
837 copy of the metadata is stored at the end of the device.
838 As a result of having two copies, some corruption of metadata is not
839 fatal to the working of GPT.
840 When the kernel detects corrupt metadata, it marks this table as corrupt
841 and reports the problem.
845 are the only operations allowed on corrupt tables.
847 If the first sector of a provider is corrupt, the kernel can not detect GPT
848 even if the partition table itself is not corrupt.
849 The protective MBR can be rewritten using the
851 command, to restore the ability to detect the GPT.
852 The copy of the protective MBR is usually located in the
856 If one GPT header appears to be corrupt but the other copy remains intact,
857 the kernel will log the following:
858 .Bd -literal -offset indent
859 GEOM: provider: the primary GPT table is corrupt or invalid.
860 GEOM: provider: using the secondary instead -- recovery strongly advised.
864 .Bd -literal -offset indent
865 GEOM: provider: the secondary GPT table is corrupt or invalid.
866 GEOM: provider: using the primary only -- recovery suggested.
875 will report about corrupt tables.
877 If the size of the device has changed (e.g.,\& volume expansion) the
878 secondary GPT header will no longer be located in the last sector.
879 This is not a metadata corruption, but it is dangerous because any
880 corruption of the primary GPT will lead to loss of the partition table.
881 This problem is reported by the kernel with the message:
882 .Bd -literal -offset indent
883 GEOM: provider: the secondary GPT header is not in the last LBA.
886 This situation can be recovered with the
889 This command reconstructs the corrupt metadata using known valid
890 metadata and relocates the secondary GPT to the end of the device.
893 The GEOM PART class can detect the same partition table visible through
894 different GEOM providers, and some of them will be marked as corrupt.
895 Be careful when choosing a provider for recovery.
896 If you choose incorrectly you can destroy the metadata of another GEOM class,
897 e.g.,\& GEOM MIRROR or GEOM LABEL.
901 variables can be used to control the behavior of the
904 The default value is shown next to each variable.
905 .Bl -tag -width indent
906 .It Va kern.geom.part.check_integrity : No 1
907 This variable controls the behaviour of metadata integrity checks.
908 When integrity checks are enabled, the
910 GEOM class verifies all generic partition parameters obtained from the
912 If some inconsistency is detected, the partition table will be
913 rejected with a diagnostic message:
914 .Sy "GEOM_PART: Integrity check failed (provider, scheme)" .
915 .It Va kern.geom.part.ldm.debug : No 0
916 Debug level of the Logical Disk Manager (LDM) module.
917 This can be set to a number between 0 and 2 inclusive.
918 If set to 0 minimal debug information is printed,
919 and if set to 2 the maximum amount of debug information is printed.
920 .It Va kern.geom.part.ldm.show_mirrors : No 0
921 This variable controls how the Logical Disk Manager (LDM) module handles
923 By default mirrored volumes are shown as partitions with type
926 .Sx "PARTITION TYPES"
928 If this variable set to 1 each component of the mirrored volume will be
929 present as independent partition.
931 This may break a mirrored volume and lead to data damage.
934 Exit status is 0 on success, and 1 if the command fails.
936 Create a GPT scheme on
938 .Bd -literal -offset indent
939 /sbin/gpart create -s GPT ada0
942 Embed GPT bootstrap code into a protective MBR:
943 .Bd -literal -offset indent
944 /sbin/gpart bootcode -b /boot/pmbr ada0
949 partition that can boot
953 partition, and install bootstrap code into it.
954 This partition must be larger than the bootstrap code
961 but smaller than 545 kB since the first-stage loader will load the
962 entire partition into memory during boot, regardless of how much data
963 it actually contains.
964 This example uses 88 blocks (44 kB) so the next partition will be
965 aligned on a 64 kB boundary without the need to specify an explicit
967 The boot partition itself is aligned on a 4 kB boundary.
968 .Bd -literal -offset indent
969 /sbin/gpart add -b 40 -s 88 -t freebsd-boot ada0
970 /sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
975 partition to contain a UFS filesystem from which the system can boot.
976 .Bd -literal -offset indent
977 /sbin/gpart add -s 512M -t freebsd-ufs ada0
980 Create an MBR scheme on
982 then create a 30GB-sized
984 slice, mark it active and
988 .Bd -literal -offset indent
989 /sbin/gpart create -s MBR ada0
990 /sbin/gpart add -t freebsd -s 30G ada0
991 /sbin/gpart set -a active -i 1 ada0
992 /sbin/gpart bootcode -b /boot/boot0 ada0
999 label) with space for up to 20 partitions:
1000 .Bd -literal -offset indent
1001 /sbin/gpart create -s BSD -n 20 ada0s1
1004 Create a 1GB-sized UFS partition and a 4GB-sized swap partition:
1005 .Bd -literal -offset indent
1006 /sbin/gpart add -t freebsd-ufs -s 1G ada0s1
1007 /sbin/gpart add -t freebsd-swap -s 4G ada0s1
1010 Install bootstrap code for the
1013 .Bd -literal -offset indent
1014 /sbin/gpart bootcode -b /boot/boot ada0s1
1017 Create a VTOC8 scheme on
1019 .Bd -literal -offset indent
1020 /sbin/gpart create -s VTOC8 da0
1023 Create a 512MB-sized
1025 partition to contain a UFS filesystem from which the system can boot.
1026 .Bd -literal -offset indent
1027 /sbin/gpart add -s 512M -t freebsd-ufs da0
1032 partition to contain a UFS filesystem and aligned on 4KB boundaries:
1033 .Bd -literal -offset indent
1034 /sbin/gpart add -s 15G -t freebsd-ufs -a 4k da0
1037 After creating all required partitions, embed bootstrap code into them:
1038 .Bd -literal -offset indent
1039 /sbin/gpart bootcode -p /boot/boot1 da0
1042 Create a backup of the partition table from
1044 .Bd -literal -offset indent
1045 /sbin/gpart backup da0 > da0.backup
1048 Restore the partition table from the backup to
1050 .Bd -literal -offset indent
1051 /sbin/gpart restore -l da0 < /mnt/da0.backup
1054 Clone the partition table from
1060 .Bd -literal -offset indent
1061 /sbin/gpart backup ada0 | /sbin/gpart restore -F ada1 ada2
1075 .An Marcel Moolenaar Aq marcel@FreeBSD.org