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 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"
50 option adds support for the Apple Partition Map (APM)
51 found on Apple Macintosh computers.
54 option adds support for the traditional
59 option adds support for the Extended Boot Record (EBR),
60 which is used to define a logical partition.
62 .Dv GEOM_PART_EBR_COMPAT
63 option enables backward compatibility for partition names
65 Also it makes impossible any types of actions
69 option adds support for the GUID Partition Table (GPT)
70 found on Intel Itanium computers and Intel-based Macintosh computers.
73 option adds support for the Master Boot Record (MBR)
74 found on PCs and used on many removable media.
77 option adds support for the MBR variant as used on
81 option adds support for Sun's SMI VTOC8 label as
82 found on computers based on
106 .\" ==== BOOTCODE ====
110 .Op Fl p Ar partcode Fl i Ar index
130 .\" ==== DESTROY ====
144 .\" ==== RECOVER ====
153 .Op Fl a Ar alignment
157 .\" ==== RESTORE ====
192 utility is used to partition GEOM providers, normally disks.
193 The first argument of which is the action to be taken:
194 .Bl -tag -width ".Cm bootcode"
197 Add a new partition to the partitioning scheme given by
199 The partition begins on the logical block address given by the
202 Its size is given by the
205 SI unit suffixes are allowed.
210 options can be omitted.
211 If so they are automatically calculated.
212 The type of the partition is given by the
215 Partition types are discussed below in the section entitled
216 .Sx "PARTITION TYPES" .
218 Additional options include:
220 .It Fl a Ar alignment
223 utility tries to align
231 The index in the partition table at which the new partition is to be
233 The index determines the name of the device special file used
234 to represent the partition.
236 The label attached to the partition.
237 This option is only valid when used on partitioning schemes that support
240 Additional operational flags.
241 See the section entitled
242 .Sx "OPERATIONAL FLAGS"
243 below for a discussion
248 Dump a partition table to standard output in special format used by
251 .\" ==== BOOTCODE ====
253 Embed bootstrap code into the partitioning scheme's metadata on the
257 or write bootstrap code into a partition (using
261 Not all partitioning schemes have embedded bootstrap code, so the
263 option is scheme-specific in nature (see the section entitled
268 option specifies a file that contains the bootstrap code.
269 The contents and size of the file are determined by the partitioning
273 option specifies a file that contains the bootstrap code intended to be
274 written to a partition.
275 The partition is specified by the
278 The size of the file must be smaller than the size of the partition.
280 Additional options include:
283 Additional operational flags.
284 See the section entitled
285 .Sx "OPERATIONAL FLAGS"
286 below for a discussion
291 Commit any pending changes for geom
293 All actions are being committed by default and will not result in
295 Actions can be modified with the
297 option so that they are not being committed by default.
298 As such, they become pending.
299 Pending changes are reflected by the geom and the
301 utility, but they are not actually written to disk.
304 action will write any and all pending changes to disk.
307 Create a new partitioning scheme on a provider given by
311 option determines the scheme to use.
312 The kernel needs to have support for a particular scheme before
313 that scheme can be used to partition a disk.
315 Additional options include:
318 The number of entries in the partition table.
319 Every partitioning scheme has a minimum and a maximum number of entries
320 and this option allows tables to be created with the number of entries
321 that lies anywhere between the minimum and the maximum.
322 Some schemes have a maximum equal to the minimum and some schemes have
323 a maximum large enough to be considered unlimited.
324 By default, partition tables are created with the minimum number of
327 Additional operational flags.
328 See the section entitled
329 .Sx "OPERATIONAL FLAGS"
330 below for a discussion
335 Delete a partition from geom
337 and further identified by the
340 The partition cannot be actively used by the kernel.
342 Additional options include:
345 Additional operational flags.
346 See the section entitled
347 .Sx "OPERATIONAL FLAGS"
348 below for a discussion
351 .\" ==== DESTROY ====
353 Destroy the partitioning scheme as implemented by geom
356 Additional options include:
359 Forced destroying of the partition table even if it is not empty.
361 Additional operational flags.
362 See the section entitled
363 .Sx "OPERATIONAL FLAGS"
364 below for a discussion
369 Modify a partition from geom
371 and further identified by the
374 Only the the type and/or label of the partition can be modified.
375 To change the type of a partition, specify the new type with the
378 To change the label of a partition, specify the new label with the
381 Not all partitioning schemes support labels and it is invalid to
382 try to change a partition label in such cases.
384 Additional options include:
387 Additional operational flags.
388 See the section entitled
389 .Sx "OPERATIONAL FLAGS"
390 below for a discussion
393 .\" ==== RECOVER ====
395 Recover corrupt partition's scheme metadata on the geom
397 See the section entitled
399 below for the additional information.
401 Additional options include:
404 Additional operational flags.
405 See the section entitled
406 .Sx "OPERATIONAL FLAGS"
407 below for a discussion
412 Resize a partition from geom
414 and further identified by the
417 New partition size is expressed in logical block
418 numbers and can be given by the
423 option is omitted then new size is automatically calculated
424 to maximum available from given geom
427 Additional options include:
429 .It Fl a Ar alignment
432 utility tries to align partition
438 Additional operational flags.
439 See the section entitled
440 .Sx "OPERATIONAL FLAGS"
441 below for a discussion
444 .\" ==== RESTORE ====
446 Restore the partition table from backup previously created by
448 action and given from standard input.
449 Only partition table may be restored.
450 This action does not affect content of partitions.
451 This mean that you should copy your data from backup after restoring
452 partition table and write bootcode again if it is needed.
454 Additional options include:
457 Destroy partition table on the given
459 before doing restore.
461 Restore partition labels for partitioning schemes that support them.
463 Additional operational flags.
464 See the section entitled
465 .Sx "OPERATIONAL FLAGS"
466 below for a discussion
471 Set the named attribute on the partition entry.
472 See the section entitled
474 below for a list of available attributes.
476 Additional options include:
479 Additional operational flags.
480 See the section entitled
481 .Sx "OPERATIONAL FLAGS"
482 below for a discussion
487 Show the current partition information of the specified geoms
488 or all geoms if none are specified.
489 Additional options include:
492 For partition schemes that support partition labels print them
493 instead of partition type.
495 Show provider names instead of partition indexes.
497 Show raw partition type instead of symbolic name.
501 Revert any pending changes for geom
503 This action is the opposite of the
505 action and can be used to undo any changes that have not been committed.
508 Clear the named attribute on the partition entry.
509 See the section entitled
511 below for a list of available attributes.
513 Additional options include:
516 Additional operational flags.
517 See the section entitled
518 .Sx "OPERATIONAL FLAGS"
519 below for a discussion
525 Partition types are identified on disk by particular strings or magic
529 utility uses symbolic names for common partition types to avoid the
530 user needing to know these values or other details of the partitioning
534 utility also allows the user to specify scheme-specific partition types
535 for partition types that do not have symbolic names.
536 The symbolic names currently understood are:
537 .Bl -tag -width ".Cm freebsd-vinum"
539 The system partition dedicated to second stage of the boot loader program.
540 Usually it used by GRUB 2 loader when the partition table is GPT.
541 The scheme-specific type is
542 .Qq Li "!21686148-6449-6E6F-744E-656564454649" .
544 The system partition for computers that use the Extensible Firmware
546 In such cases, the GPT partitioning scheme is being used and the
547 actual partition type for the system partition can also be specified as
548 .Qq Li "!c12a7328-f81f-11d2-ba4b-00a0c93ec93ab" .
552 partition that uses the
554 disklabel to sub-divide the
555 partition into file systems.
556 This is a legacy partition type and should not be used for the APM
558 The scheme-specific types are
563 .Qq Li "!516e7cb4-6ecf-11d6-8ff8-00022d09712b"
568 partition dedicated to bootstrap code.
569 The scheme-specific type is
570 .Qq Li "!83bd6b9d-7f41-11dc-be0b-001560b84f0f"
575 partition dedicated to swap space.
576 The scheme-specific types are
577 .Qq Li "!FreeBSD-swap"
579 .Qq Li "!516e7cb5-6ecf-11d6-8ff8-00022d09712b"
580 for GPT, and tag 0x0901 for VTOC8.
584 partition that contains a UFS or UFS2 file system.
585 The scheme-specific types are
586 .Qq Li "!FreeBSD-UFS"
588 .Qq Li "!516e7cb6-6ecf-11d6-8ff8-00022d09712b"
589 for GPT, and tag 0x0902 for VTOC8.
593 partition that contains a Vinum volume.
594 The scheme-specific types are
595 .Qq Li "!FreeBSD-Vinum"
597 .Qq Li "!516e7cb8-6ecf-11d6-8ff8-00022d09712b"
598 for GPT, and tag 0x0903 for VTOC8.
602 partition that contains a ZFS volume.
603 The scheme-specific types are
604 .Qq Li "!FreeBSD-ZFS"
606 .Qq Li "!516e7cba-6ecf-11d6-8ff8-00022d09712b"
607 for GPT, and 0x0904 for VTOC8.
609 A partition that is sub-partitioned by a master boot record (MBR).
610 This type is known as
611 .Qq Li "!024dee41-33e7-11d3-9d69-0008c781f39f"
615 The scheme-specific attributes for EBR:
616 .Bl -tag -width ".Cm active"
620 The scheme-specific attributes for GPT:
621 .Bl -tag -width ".Cm bootfailed"
625 stage 1 boot loader will try to boot the system from this partition.
626 Multiple partitions might be marked with the
633 partitions one by one, until the next boot stage is successfully entered.
635 Setting this attribute automatically sets the
640 stage 1 boot loader will try to boot the system from this partition only once.
645 attributes are tried before partitions with only the
650 partition is tried, the
654 attribute and tries to execute the next boot stage.
657 attribute that is now alone is replaced with the
660 If the execution of the next boot stage succeeds, but the system is not fully
665 attributes alone (without the
667 attribute) on the next system boot and will replace those with the
670 If the system is fully booted, the
671 .Pa /etc/rc.d/gptboot
672 start-up script will look for partition with the
674 attribute alone, will remove the attribute and log that the system was
675 successfully booted from this partition.
676 There should be at most one
678 partition when system is successfully booted.
679 Multiple partitions might be marked with the
685 This attribute should not be manually managed.
688 stage 1 boot loader and the
689 .Pa /etc/rc.d/gptboot
691 This attribute is used to mark partitions that had the
693 attribute set, but we failed to boot from them.
694 Once we successfully boot, the
695 .Pa /etc/rc.d/gptboot
696 script will log all the partitions we failed to boot from and will remove the
701 The scheme-specific attributes for MBR:
702 .Bl -tag -width ".Cm active"
706 The scheme-specific attributes for PC98:
707 .Bl -tag -width ".Cm bootable"
713 supports several partitioning schemes and each scheme uses different
715 The bootstrap code is located in the specific disk area for each partitioning
716 scheme and also it might have different size.
718 The bootstrap code could be separated into two types.
719 The first one is embedded in the partitioning scheme's metadata, the second
720 type is located on the specific partition.
721 The embedding bootstrap code should be done only with the
726 The GEOM PART class has knowlege on how to embed bootstrap code into specific
727 partitioning scheme metadata without damage.
729 The Master Boot Record (MBR) uses 512-bytes bootstrap code image, embedded into
730 partition table's metadata area.
731 There are two variants of this bootstrap code:
735 The first one searches partition with
739 section) in the partition table.
740 Then it runs next bootstrap stage.
743 image contains a boot manager with some additional interactive functions.
745 The BSD disklabel is usually created on top of the MBR partition (slice)
749 .Sx "PARTITION TYPES"
751 It uses 8 KB size bootstrap code image
753 embedded into partition table's metadata area.
755 Both types of bootstrap code are used to boot from the GUID Partition Table.
756 First of all, a protective MBR is embedded into first disk sector from the
762 .Sx "PARTITION TYPES"
763 section) in the GPT and runs next bootstrap stage from it.
766 partition should be smaller than 545 KB.
767 There are two variants of bootstrap code to write to this partition:
770 .Pa /boot/gptzfsboot .
771 The first one is used to boot from UFS.
772 It searches in the GPT partition with type
774 and it runs the third bootstrap stage (
779 is used to boot from ZFS.
780 It searches partition with type
786 The VTOC8 scheme does not support embedding bootstrap code.
787 Instead, the 8 KBytes bootstrap code image
789 should be written with
793 option to all sufficiently large VTOC8 partitions.
796 option could be ommited.
798 The APM scheme also does not support embedding bootstrap code.
799 Instead, the 800 KBytes bootstrap code image
801 should be written with
803 command to a partition of type
805 which should also be 800 KB in size.
806 .Sh OPERATIONAL FLAGS
807 Actions other than the
811 actions take an optional
814 This option is used to specify action-specific operational flags.
819 flag so that the action is immediately
823 to have the action result in a pending change that can later, with
824 other pending changes, be committed as a single compound change with
827 action or reverted with the
831 The GEOM PART class supports recovering of partition tables only for GPT.
832 The GUID partition table has a primary and secondary (backup) copy of
833 metadata for redundance, these are stored at the begining and the end
834 of the device respectively.
835 As a result of having two copies, it is acceptable to have some corruption
836 within the metadata that is not fatal to the working of GPT.
837 When the kernel detects corrupt metadata it marks this table as corrupt and
838 reports the corruption.
839 Any operations on corrupt tables are prohibited except for
844 If the first sector of a provider is corrupt, the kernel can not detect GPT
845 even if partition table itself is not corrupt.
846 You can rewrite the protective MBR using the
848 command, to restore the ability to detect the GPT.
849 The copy of the protective MBR is usually located in the
853 If one GPT header appears to be corrupt but the other copy remains intact,
854 the kernel will log the following:
855 .Bd -literal -offset indent
856 GEOM: provider: the primary GPT table is corrupt or invalid.
857 GEOM: provider: using the secondary instead -- recovery strongly advised.
861 .Bd -literal -offset indent
862 GEOM: provider: the secondary GPT table is corrupt or invalid.
863 GEOM: provider: using the primary only -- recovery suggested.
872 will report about corrupt tables.
874 If the size of the device has changed (e.g.\& volume expansion) the
875 secondary GPT header will no longer be located in the last sector.
876 This is not a metadata corruption, but it is dangerous because any
877 corruption of the primary GPT will lead to loss of partition table.
878 This problem is reported by the kernel with the message:
879 .Bd -literal -offset indent
880 GEOM: provider: the secondary GPT header is not in the last LBA.
883 This situation can be recovered with the
886 This command reconstructs the corrupt metadata using known valid
887 metadata and relocates the secondary GPT to the end of the device.
890 The GEOM PART class can detect the same partition table visible through
891 different GEOM providers, and some of them will be marked as corrupt.
892 Be careful when choosing a provider for recovery.
893 If you choose incorrectly you can destroy the metadata of another GEOM class,
894 e.g.\& GEOM MIRROR or GEOM LABEL.
898 variables can be used to control the behavior of the
901 The default value is shown next to each variable.
902 .Bl -tag -width indent
903 .It Va kern.geom.part.check_integrity : No 1
904 This variable controls the behaviour of metadata integrity checks.
905 When integrity checks are enabled, the
907 GEOM class verifies all generic partition parameters obtained from the
909 If some inconsistency is detected, the partition table will be
910 rejected with a diagnostic message:
911 .Sy "GEOM_PART: Integrity check failed (provider, scheme)" .
914 Exit status is 0 on success, and 1 if the command fails.
918 .Bd -literal -offset indent
919 /sbin/gpart create -s GPT ad0
922 Embed GPT bootstrap code into protective MBR:
923 .Bd -literal -offset indent
924 /sbin/gpart bootcode -b /boot/pmbr ad0
929 partition that can boot
933 partition, and install bootstrap code into it.
934 This partition must be larger than
936 or the GPT boot you are planning to write, but smaller than 545 KB.
937 A size of 15 blocks (7680 bytes) would be sufficient for
938 booting from UFS but let's use 128 blocks (64 KB) here in
939 this example, in order to reserve some space for potential
940 future need (e.g.\& from a ZFS partition).
941 .Bd -literal -offset indent
942 /sbin/gpart add -b 34 -s 128 -t freebsd-boot ad0
943 /sbin/gpart bootcode -p /boot/gptboot -i 1 ad0
948 partition that would contain UFS where the system boots from:
949 .Bd -literal -offset indent
950 /sbin/gpart add -b 162 -s 1048576 -t freebsd-ufs ad0
955 then create 30GB-sized
957 slice, mark it active and
961 .Bd -literal -offset indent
962 /sbin/gpart create -s MBR ada0
963 /sbin/gpart add -t freebsd -s 30G ada0
964 /sbin/gpart set -a active -i 1 ada0
965 /sbin/gpart bootcode -b /boot/boot0 ada0
972 label) with ability to have up to 20 partitions:
973 .Bd -literal -offset indent
974 /sbin/gpart create -s BSD -n 20 ada0s1
977 Create 1GB-sized UFS partition and 4GB-sized swap partition:
978 .Bd -literal -offset indent
979 /sbin/gpart add -t freebsd-ufs -s 1G ada0s1
980 /sbin/gpart add -t freebsd-swap -s 4G ada0s1
983 Install bootstrap code for the
986 .Bd -literal -offset indent
987 /sbin/gpart bootcode -b /boot/boot ada0s1
990 Create VTOC8 scheme on
992 .Bd -literal -offset indent
993 /sbin/gpart create -s VTOC8 da0
998 partition that would contain UFS where the system boots from:
999 .Bd -literal -offset indent
1000 /sbin/gpart add -s 512M -t freebsd-ufs da0
1005 partition that would contain UFS and aligned on 4KB boundaries:
1006 .Bd -literal -offset indent
1007 /sbin/gpart add -s 15G -t freebsd-ufs -a 4k da0
1010 After having created all required partitions, embed bootstrap code into them:
1011 .Bd -literal -offset indent
1012 /sbin/gpart bootcode -p /boot/boot1 da0
1015 Create backup of partition table from
1017 .Bd -literal -offset indent
1018 /sbin/gpart backup da0 > da0.backup
1021 Restore partition table from backup to
1023 .Bd -literal -offset indent
1024 /sbin/gpart restore -l da0 < /mnt/da0.backup
1027 Clone partition table from
1033 .Bd -literal -offset indent
1034 /sbin/gpart backup ada0 | /sbin/gpart restore -F ada1 ada2
1047 .An Marcel Moolenaar Aq marcel@FreeBSD.org