Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
GPART(8)		FreeBSD	System Manager's Manual		      GPART(8)

NAME
     gpart -- 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_EBR_COMPAT
	   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_EBR_COMPAT option enables backward com-
     patibility	for partition names in the EBR scheme.	Also it	makes impossi-
     ble any types of actions with such	partitions.  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 Master 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 [-a alignment] [-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 [-a alignment] [-s size] [-f	flags] geom
     gpart restore [-lF] [-f flags] provider [...]
     gpart set -a attrib -i index [-f flags] geom
     gpart show	[-l | -r] [-p] [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 omitted.  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:

	       -a alignment  If	specified, then	gpart utility tries to align
			     start offset and partition	size to	be multiple of
			     alignment value.

	       -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 rep-
			     resent 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 (see	the section entitled
	       BOOTSTRAPPING below).  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.	The -p
	       partcode	option specifies a file	that contains the bootstrap
	       code intended to	be written to a	partition.  The	partition is
	       specified by the	-i index option.  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:

	       -a alignment  If	specified, then	gpart utility tries to align
			     partition size to be multiple of alignment	value.

	       -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
	       table 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.

	       -p	   Show	provider names instead of partition indexes.

	       -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
     Partition types are identified on disk by particular strings or magic
     values.  The gpart	utility	uses symbolic names for	common partition types
     to	avoid the user needing to know these values or other details of	the
     partitioning scheme in question.  The gpart utility also allows the user
     to	specify	scheme-specific	partition types	for partition types that do
     not have symbolic names.  The symbolic names currently understood are:

     bios-boot	    The	system partition dedicated to second stage of the boot
		    loader program.  Usually it	used by	GRUB 2 loader when the
		    partition table is GPT.  The scheme-specific type is
		    "!21686148-6449-6E6F-744E-656564454649".

     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

BOOTSTRAPPING
     FreeBSD supports several partitioning schemes and each scheme uses	dif-
     ferent bootstrap code.  The bootstrap code	is located in the specific
     disk area for each	partitioning scheme and	also it	might have different
     size.

     The bootstrap code	could be separated into	two types.  The	first one is
     embedded in the partitioning scheme's metadata, the second	type is
     located on	the specific partition.	 The embedding bootstrap code should
     be	done only with the gpart bootcode command with -b bootcode option.
     The GEOM PART class has knowlege on how to	embed bootstrap	code into spe-
     cific partitioning	scheme metadata	without	damage.

     The Master	Boot Record (MBR) uses 512-bytes bootstrap code	image, embed-
     ded into partition	table's	metadata area.	There are two variants of this
     bootstrap code: /boot/mbr and /boot/boot0.	 The first one searches	parti-
     tion with active attribute	(see the ATTRIBUTES section) in	the partition
     table.  Then it runs next bootstrap stage.	 The /boot/boot0 image con-
     tains a boot manager with some additional interactive functions.

     The BSD disklabel is usually created on top of the	MBR partition (slice)
     with type freebsd (see the	PARTITION TYPES	section).  It uses 8 KB	size
     bootstrap code image /boot/boot, embedded into partition table's metadata
     area.

     Both types	of bootstrap code are used to boot from	the GUID Partition Ta-
     ble.  First of all, a protective MBR is embedded into first disk sector
     from the /boot/pmbr image.	 It searches the freebsd-boot partition	(see
     the PARTITION TYPES section) in the GPT and runs next bootstrap stage
     from it.  The freebsd-boot	partition should be smaller than 545 KB.
     There are two variants of bootstrap code to write to this partition:
     /boot/gptboot and /boot/gptzfsboot.  The first one	is used	to boot	from
     UFS.  It searches in the GPT partition with type freebsd-ufs, and it runs
     the third bootstrap stage ( /boot/loader) if it is	found.	The
     /boot/gptzfsboot is used to boot from ZFS.	 It searches partition with
     type freebsd-zfs and starts /boot/zfsloader from it.

     The VTOC8 scheme does not support embedding bootstrap code.  Instead, the
     8 KBytes bootstrap	code image /boot/boot1 should be written with gpart
     bootcode command with -p bootcode option to all sufficiently large	VTOC8
     partitions.  To do	this the -i index option could be ommited.

     The APM scheme also does not support embedding bootstrap code.  Instead,
     the 800 KBytes bootstrap code image /boot/boot1.hfs should	be written
     with gpart	bootcode command to a partition	of type	freebsd-boot, which
     should also be 800	KB in size.

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 PART class supports recovering of	partition tables only for GPT.
     The GUID partition	table has a primary and	secondary (backup) copy	of
     metadata for redundance, these are	stored at the begining and the end of
     the device	respectively.  As a result of having two copies, it is accept-
     able to have some corruption within the metadata that is not fatal	to the
     working of	GPT.  When the kernel detects corrupt metadata it marks	this
     table as corrupt and reports the corruption.  Any operations on corrupt
     tables are	prohibited except for destroy and recover.

     If	the first sector of a provider is corrupt, the kernel can not detect
     GPT even if partition table itself	is not corrupt.	 You can rewrite the
     protective	MBR using the dd(1) command, to	restore	the ability to detect
     the GPT.  The copy	of the protective MBR is usually located in the
     /boot/pmbr	file.

     If	one GPT	header appears to be corrupt but the other copy	remains
     intact, the kernel	will log the following:

	   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 such as show, status and list will report about cor-
     rupt tables.

     If	the size of the	device has changed (e.g. volume	expansion) the sec-
     ondary GPT	header will no longer be located in the	last sector.  This is
     not a metadata corruption,	but it is dangerous because any	corruption of
     the primary GPT will lead to loss of partition table.  This problem is
     reported by the kernel with the message:

	   GEOM: provider: the secondary GPT header is not in the last LBA.

     This situation can	be recovered with the recover command.	This command
     reconstructs the corrupt metadata using known valid metadata and relo-
     cates the secondary GPT to	the end	of the device.

     NOTE: The GEOM PART class can detect the same partition table visible
     through different GEOM providers, and some	of them	will be	marked as cor-
     rupt.  Be careful when choosing a provider	for recovery.  If you choose
     incorrectly you can destroy the metadata of another GEOM class, e.g. GEOM
     MIRROR or GEOM LABEL.

SYSCTL VARIABLES
     The following sysctl(8) variables can be used to control the behavior of
     the PART GEOM class.  The default value is	shown next to each variable.

     kern.geom.part.check_integrity: 1
	     This variable controls the	behaviour of metadata integrity
	     checks.  When integrity checks are	enabled, the PART GEOM class
	     verifies all generic partition parameters obtained	from the disk
	     metadata.	If some	inconsistency is detected, the partition table
	     will be rejected with a diagnostic	message: GEOM_PART: Integrity
	     check failed (provider, scheme).

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 MBR	scheme on ada0,	then create 30GB-sized FreeBSD slice, mark it
     active and	install	boot0 boot manager:

	   /sbin/gpart create -s MBR ada0
	   /sbin/gpart add -t freebsd -s 30G ada0
	   /sbin/gpart set -a active -i	1 ada0
	   /sbin/gpart bootcode	-b /boot/boot0 ada0

     Now create	BSD scheme (BSD	label) with ability to have up to 20 parti-
     tions:

	   /sbin/gpart create -s BSD -n	20 ada0s1

     Create 1GB-sized UFS partition and	4GB-sized swap partition:

	   /sbin/gpart add -t freebsd-ufs -s 1G	ada0s1
	   /sbin/gpart add -t freebsd-swap -s 4G ada0s1

     Install bootstrap code for	the BSD	label:

	   /sbin/gpart bootcode	-b /boot/boot ada0s1

     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

     Create a 15GB-sized freebsd-ufs partition that would contain UFS and
     aligned on	4KB boundaries:

	   /sbin/gpart add -s 15G -t freebsd-ufs -a 4k 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 ALSO
     dd(1), geom(4), boot0cfg(8), geom(8)

HISTORY
     The gpart utility appeared	in FreeBSD 7.0.

AUTHORS
     Marcel Moolenaar <marcel@FreeBSD.org>

FreeBSD	9.3			August 19, 2011			   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | PARTITION TYPES | ATTRIBUTES | BOOTSTRAPPING | OPERATIONAL FLAGS | RECOVERING | SYSCTL VARIABLES | EXIT STATUS | EXAMPLES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=gpart&sektion=8&manpath=FreeBSD+9.0-RELEASE>

home | help