GPART(8) BSD System Manager's Manual GPART(8)NAMEgpart — control utility for the disk partitioning GEOM class
SYNOPSIS
To add support for the disk partitioning GEOM class, place one or more of
the following lines in your kernel configuration file:
options GEOM_PART_APM
options GEOM_PART_BSD
options GEOM_PART_EBR
options GEOM_PART_GPT
options GEOM_PART_MBR
options GEOM_PART_PC98
options GEOM_PART_VTOC8
The GEOM_PART_APM option adds support for the Apple Partition Map (APM)
found on Apple Macintosh computers. The GEOM_PART_BSD option adds sup‐
port for the traditional BSD disklabel. The GEOM_PART_EBR option adds
support for the Extended Boot Record (EBR), which is used to define a
logical partition. The GEOM_PART_GPT option adds support for the GUID
Partition Table (GPT) found on Intel Itanium computers and Intel-based
Macintosh computers. The GEOM_PART_MBR option adds support for the Mas‐
ter Boot Record (MBR) found on PCs and used on many removable media. The
GEOM_PART_PC98 option adds support for the MBR variant as used on NEC
PC-98 computers. The GEOM_PART_VTOC8 option adds support for Sun's SMI
VTOC8 label as found on computers based on SPARC64 and UltraSPARC.
Usage of the gpart utility:
gpart add -t type [-b start] [-s size] [-i index] [-l label] [-f flags]
geom
gpart backup geom
gpart bootcode [-b bootcode] [-p partcode -i index] [-f flags] geom
gpart commit geom
gpart create -s scheme [-n entries] [-f flags] provider
gpart delete -i index [-f flags] geom
gpart destroy [-F] [-f flags] geom
gpart modify -i index [-l label] [-t type] [-f flags] geom
gpart recover [-f flags] geom
gpart resize -i index [-s size] [-f flags] geom
gpart restore [-lF] [-f flags] provider [...]
gpart set -a attrib -i index [-f flags] geom
gpart show [-lr] [geom ...]
gpart undo geom
gpart unset -a attrib -i index [-f flags] geom
DESCRIPTION
The gpart utility is used to partition GEOM providers, normally disks.
The first argument of which is the action to be taken:
add Add a new partition to the partitioning scheme given by geom.
The partition begins on the logical block address given by the
-b start option. Its size is given by the -s size option. SI
unit suffixes are allowed. One or both -b and -s options can be
ommitted. If so they are automatically calculated. The type of
the partition is given by the -t type option. Partition types
are discussed below in the section entitled PARTITION TYPES.
Additional options include:
-i index The index in the partition table at which the new
partition is to be placed. The index determines
the name of the device special file used to repre‐
sent the partition.
-l label The label attached to the partition. This option
is only valid when used on partitioning schemes
that support partition labels.
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
backup Dump a partition table to standard output in special format
used by restore action.
bootcode Embed bootstrap code into the partitioning scheme's metadata on
the geom (using -b bootcode) or write bootstrap code into a
partition (using -p partcode and -i index). Not all partition‐
ing schemes have embedded bootstrap code, so the -b bootcode
option is scheme-specific in nature. For the GPT scheme,
embedded bootstrap code is supported. The bootstrap code is
embedded in the protective MBR rather than the GPT. The -b
bootcode option specifies a file that contains the bootstrap
code. The contents and size of the file are determined by the
partitioning scheme. For the MBR scheme, it is a 512 byte file
of which the first 446 bytes are installed as bootstrap code.
The -p partcode option specifies a file that contains the boot‐
strap code intended to be written to a partition. For the
VTOC8 scheme, it is a 8192 byte file of which the last 7680
bytes are installed as bootstrap code. The partition is speci‐
fied by the -i index option. For the VTOC8 scheme, if the -i
index option is omitted, the bootstrap code is written to all
sufficiently large partitions. The size of the file must be
smaller than the size of the partition.
Additional options include:
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
commit Commit any pending changes for geom geom. All actions are
being committed by default and will not result in pending
changes. Actions can be modified with the -f flags option so
that they are not being committed by default. As such, they
become pending. Pending changes are reflected by the geom and
the gpart utility, but they are not actually written to disk.
The commit action will write any and all pending changes to
disk.
create Create a new partitioning scheme on a provider given by
provider. The -s scheme option determines the scheme to use.
The kernel needs to have support for a particular scheme before
that scheme can be used to partition a disk.
Additional options include:
-n entries The number of entries in the partition table.
Every partitioning scheme has a minimum and a maxi‐
mum number of entries and this option allows tables
to be created with the number of entries that lies
anywhere between the minimum and the maximum. Some
schemes have a maximum equal to the minimum and
some schemes have a maximum large enough to be con‐
sidered unlimited. By default, partition tables
are created with the minimum number of entries.
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
delete Delete a partition from geom geom and further identified by the
-i index option. The partition cannot be actively used by the
kernel.
Additional options include:
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
destroy Destroy the partitioning scheme as implemented by geom geom.
Additional options include:
-F Forced destroying of the partition table even if it
is not empty.
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
modify Modify a partition from geom geom and further identified by the
-i index option. Only the the type and/or label of the parti‐
tion can be modified. To change the type of a partition, spec‐
ify the new type with the -t type option. To change the label
of a partition, specify the new label with the -l label option.
Not all partitioning schemes support labels and it is invalid
to try to change a partition label in such cases.
Additional options include:
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
recover Recover corrupt partition's scheme metadata on the geom geom.
See the section entitled RECOVERING below for the additional
information.
Additional options include:
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
resize Resize a partition from geom geom and further identified by the
-i index option. New partition size is expressed in logical
block numbers and can be given by the -s size option. If -s
option is omitted then new size is automatically calculated to
maximum available from given geom geom.
Additional options include:
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
restore Restore the partition table from backup previously created by
backup action and given from standard input. Only partition ta‐
ble may be restored. This action does not affect content of
partitions. This mean that you should copy your data from
backup after restoring partition table and write bootcode again
if it is needed.
Additional options include:
-F Destroy partition table on the given provider
before doing restore.
-l Restore partition labels for partitioning schemes
that support them.
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
set Set the named attribute on the partition entry. See the sec‐
tion entitled ATTRIBUTES below for a list of available
attributes.
Additional options include:
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
show Show the current partition information of the specified geoms
or all geoms if none are specified. Additional options
include:
-l For partition schemes that support partition labels
print them instead of partition type.
-r Show raw partition type instead of symbolic name.
undo Revert any pending changes for geom geom. This action is the
opposite of the commit action and can be used to undo any
changes that have not been committed.
unset Clear the named attribute on the partition entry. See the sec‐
tion entitled ATTRIBUTES below for a list of available
attributes.
Additional options include:
-f flags Additional operational flags. See the section
entitled OPERATIONAL FLAGS below for a discussion
about its use.
PARTITION TYPES
The gpart utility uses symbolic names for common partition types to avoid
that the user needs to know what the partitioning scheme in question is
and what the actual number or identification needs to be used for a par‐
ticular type. The gpart utility also allows the user to specify scheme-
specific partition types for partition types that do not have symbol
names. The symbolic names currently understood are:
efi The system partition for computers that use the Extensible
Firmware Interface (EFI). In such cases, the GPT parti‐
tioning scheme is being used and the actual partition type
for the system partition can also be specified as
"!c12a7328-f81f-11d2-ba4b-00a0c93ec93ab".
freebsd A FreeBSD partition that uses the BSD disklabel to sub-
divide the partition into file systems. This is a legacy
partition type and should not be used for the APM or GPT
schemes. The scheme-specific types are "!165" for MBR,
"!FreeBSD" for APM, and
"!516e7cb4-6ecf-11d6-8ff8-00022d09712b" for GPT.
freebsd-boot A FreeBSD partition dedicated to bootstrap code. The
scheme-specific type is
"!83bd6b9d-7f41-11dc-be0b-001560b84f0f" for GPT.
freebsd-swap A FreeBSD partition dedicated to swap space. The scheme-
specific types are "!FreeBSD-swap" for APM,
"!516e7cb5-6ecf-11d6-8ff8-00022d09712b" for GPT, and tag
0x0901 for VTOC8.
freebsd-ufs A FreeBSD partition that contains a UFS or UFS2 file sys‐
tem. The scheme-specific types are "!FreeBSD-UFS" for
APM, "!516e7cb6-6ecf-11d6-8ff8-00022d09712b" for GPT, and
tag 0x0902 for VTOC8.
freebsd-vinum A FreeBSD partition that contains a Vinum volume. The
scheme-specific types are "!FreeBSD-Vinum" for APM,
"!516e7cb8-6ecf-11d6-8ff8-00022d09712b" for GPT, and tag
0x0903 for VTOC8.
freebsd-zfs A FreeBSD partition that contains a ZFS volume. The
scheme-specific types are "!FreeBSD-ZFS" for APM,
"!516e7cba-6ecf-11d6-8ff8-00022d09712b" for GPT, and
0x0904 for VTOC8.
mbr A partition that is sub-partitioned by a master boot
record (MBR). This type is known as
"!024dee41-33e7-11d3-9d69-0008c781f39f" by GPT.
ATTRIBUTES
The scheme-specific attributes for EBR:
active
The scheme-specific attributes for GPT:
bootme When set, the gptboot stage 1 boot loader will try to boot
the system from this partition. Multiple partitions might be
marked with the bootme attribute. In such scenario the
gptboot will try all bootme partitions one by one, until the
next boot stage is successfully entered.
bootonce Setting this attribute automatically sets the bootme
attribute. When set, the gptboot stage 1 boot loader will
try to boot the system from this partition only once. Parti‐
tions with both bootonce and bootme attributes are tried
before partitions with only the bootme attribute. Before
bootonce partition is tried, the gptboot removes the bootme
attribute and tries to execute the next boot stage. If it
fails, the bootonce attribute that is now alone is replaced
with the bootfailed attribute. If the execution of the next
boot stage succeeds, but the system is not fully booted, the
gptboot will look for bootonce attributes alone (without the
bootme attribute) on the next system boot and will replace
those with the bootfailed attribute. If the system is fully
booted, the /etc/rc.d/gptboot start-up script will look for
partition with the bootonce attribute alone, will remove the
attribute and log that the system was successfully booted
from this partition. There should be at most one bootonce
partition when system is successfully booted. Multiple par‐
titions might be marked with the bootonce and bootme
attribute pairs.
bootfailed This attribute should not be manually managed. It is managed
by the gptboot stage 1 boot loader and the /etc/rc.d/gptboot
start-up script. This attribute is used to mark partitions
that had the bootonce attribute set, but we failed to boot
from them. Once we successfully boot, the /etc/rc.d/gptboot
script will log all the partitions we failed to boot from and
will remove the bootfailed attributes.
The scheme-specific attributes for MBR:
active
The scheme-specific attributes for PC98:
active
bootable
OPERATIONAL FLAGS
Actions other than the commit and undo actions take an optional -f flags
option. This option is used to specify action-specific operational
flags. By default, the gpart utility defines the ‘C’ flag so that the
action is immediately committed. The user can specify “-f x” to have the
action result in a pending change that can later, with other pending
changes, be committed as a single compound change with the commit action
or reverted with the undo action.
RECOVERING
The GEOM class PART supports recovering of partition tables only for GPT.
The GUID partition table has a primary and secondary (backup) copy of
metadata for redundance. They are stored in the begining and in the end
of device respectively. Therefore it is acceptable to have some corrup‐
tions in the metadata that are not fatal to work with GPT. When kernel
detects corrupt metadata it marks this table as corrupt and reports about
corruption. Any changes in corrupt table are prohibited except destroy
and recover.
In case when only first sector is corrupt kernel can not detect GPT even
if partition table is not corrupt. You can write protective MBR with
dd(1) command to restore ability of GPT detection. The copy of protective
MBR is usually located in the /boot/pmbr file.
In case when some of metadata is corrupt you will get to know about this
from kernel's messages like these:
GEOM: provider: the primary GPT table is corrupt or invalid.
GEOM: provider: using the secondary instead -- recovery strongly advised.
or
GEOM: provider: the secondary GPT table is corrupt or invalid.
GEOM: provider: using the primary only -- recovery suggested.
Also gpart commands like show, status and list will report about corrupt
table.
In case when the size of device has changed (e.g. volume expansion) the
secondary GPT header will become located not in the last sector. This is
not a metadata corruption, but it is dangerous because any corruption of
the primary GPT will lead to lost of partition table. Kernel reports
about this problem with message:
GEOM: provider: the secondary GPT header is not in the last LBA.
A corrupt table can be recovered with gpart recover command. This command
does reconstruction of corrupt metadata using known valid metadata. Also
it can relocate secondary GPT to the end of device.
NOTE: The GEOM class PART can detect the same partition table on differ‐
ent GEOM providers and some of them will marked as corrupt. Be careful
when choising a provider for recovering. If you did incorrect choise you
can destroy metadata of another GEOM class, e.g. GEOM MIRROR or GEOM
LABEL.
EXIT STATUS
Exit status is 0 on success, and 1 if the command fails.
EXAMPLES
Create GPT scheme on ad0.
/sbin/gpart create -s GPT ad0
Embed GPT bootstrap code into protective MBR.
/sbin/gpart bootcode -b /boot/pmbr ad0
Create a dedicated freebsd-boot partition that can boot FreeBSD from a
freebsd-ufs partition, and install bootstrap code into it. This parti‐
tion must be larger than /boot/gptboot, or the GPT boot you are planning
to write, but smaller than 545 KB. A size of 15 blocks (7680 bytes)
would be sufficient for booting from UFS but let's use 128 blocks (64 KB)
here in this example, in order to reserve some space for potential future
need (e.g. from a ZFS partition).
/sbin/gpart add -b 34 -s 128 -t freebsd-boot ad0
/sbin/gpart bootcode -p /boot/gptboot -i 1 ad0
Create a 512MB-sized freebsd-ufs partition that would contain UFS where
the system boots from.
/sbin/gpart add -b 162 -s 1048576 -t freebsd-ufs ad0
Create VTOC8 scheme on da0.
/sbin/gpart create -s VTOC8 da0
Create a 512MB-sized freebsd-ufs partition that would contain UFS where
the system boots from.
/sbin/gpart add -s 512M -t freebsd-ufs da0
After having created all required partitions, embed bootstrap code into
them.
/sbin/gpart bootcode -p /boot/boot1 da0
Create backup of partition table from da0
/sbin/gpart backup da0 > da0.backup
Restore partition table from backup to da0
/sbin/gpart restore -l da0 < /mnt/da0.backup
Clone partition table from ada0 to ada1 and ada2
/sbin/gpart backup ada0 | /sbin/gpart restore -F ada1 ada2
SEE ALSOdd(1), geom(4), geom(8)HISTORY
The gpart utility appeared in FreeBSD 7.0.
AUTHORS
Marcel Moolenaar ⟨marcel@FreeBSD.org⟩
BSD November 22, 2010 BSD