DragonFly On-Line Manual Pages
GPT(8) DragonFly System Manager's Manual GPT(8)
NAME
gpt - GUID partition table maintenance utility
SYNOPSIS
gpt [general_options] command [command_options] device ...
DESCRIPTION
The gpt utility provides the necessary functionality to manipulate GUID
partition tables (GPTs), but see BUGS below for how and where
functionality is missing.
The basic usage model of the gpt tool follows that of the cvs(1) tool.
The general options are described in the following subsection. The
remaining subsections describe the individual commands with their
options. A device is either a special file corresponding to a disk-like
device or a regular file. The command is applied to each device listed
on the command line.
General Options
The general options allow the user to change default settings or
otherwise change the behaviour that is applicable to all commands. Not
all commands use all default settings, so some general options may not
have an effect on all commands.
-r Open the device for reading only. Currently this option is
primarily useful for the show command, but the intent is to use
it to implement dry-run behaviour.
-v Control the verbosity level. The level increases with every
occurrence of this option. There is no formalized definition of
the different levels yet.
Commands
gpt add [-a alignment] [-b number] [-i index] [-l label] [-s size] [-t
type] device ...
The add command allows the user to add a new partition to an
existing table. By default, it will create a dfly partition
covering the first available block of an unused disk space.
The -a alignment option specifies the alignment of the partition
position and size. The alignment is given in bytes and may have
the k, K, m, M, g and G suffixes to indicate KB, MB and GB,
respectively. By default, gpt will align the partition to 1MB in
size and position.
The -b number option specifies the starting (beginning) sector
number of the partition. The minimum sector number is 1, but has
to fall inside an unused region of disk space that is covered by
the GPT.
The -i index option specifies which (free) entry in the GPT table
is to be used for the new partition. By default, the first free
entry is selected. Entries start at index 0 representing
partition 0 of the GPT.
The -l label option specifies the label for the partition.
The -s size option specifies the size of the partition. If there
is no suffix, the size is in sectors; otherwise, the following
suffixes may be used:
s, S sectors
b, B bytes (B)
k, K kilobytes (KB)
m, M megabytes (MB)
g, G gigabytes (GB)
t, T terabytes (TB)
p, P petabytes (PB)
The minimum size is 1 sector.
The -t type option allows the user to specify the partition type.
The type is given as a UUID, but gpt accepts the following
aliases for the most commonly used partition types:
apple-apfs Apple APFS
apple-hfs Apple HFS
apple-ufs Apple UFS
apple-zfs Apple ZFS
bios BIOS Boot (e.g., used by GRUB 2)
ccd DragonFly ccd(4)
dfly DragonFly disklabel64(5)
dragonfly An alias for dfly
efi EFI System
freebsd-legacy FreeBSD Legacy
freebsd-boot FreeBSD Boot
freebsd-swap FreeBSD Swap
freebsd-ufs FreeBSD UFS/UFS2
freebsd-zfs FreeBSD ZFS
hammer DragonFly HAMMER(5)
hammer2 DragonFly HAMMER2
label32 DragonFly disklabel32(5)
label64 DragonFly disklabel64(5)
linux Linux Data
linux-lvm Linux LVM
linux-raid Linux RAID
linux-swap Linux Swap
netbsd-ccd NetBSD CCD
netbsd-cgd NetBSD CGD
netbsd-ffs NetBSD FFSv1/FFSv2
netbsd-lfs NetBSD LFS
netbsd-swap NetBSD Swap
openbsd OpenBSD Data
swap DragonFly Swap
ufs DragonFly UFS(5)
vinum DragonFly vinum(4)
windows Microsoft Basic Data
windows-reserved Microsoft Reserved
windows-recovery Microsoft Recovery
Any symbolic name in the system uuids(5) files may also be
specified.
gpt boot device ...
The boot command allows the user to create a small boot partition
in a freshly created GPT.
This command creates a small, 1GB boot partition as partition #0
and hacks in a special `slice 1' in the PMBR which aliases it.
The PMBR is further modified to add the necessary boot code. You
can then disklabel GPT partition #0 and mount it, placing the
contents of /boot directory within. You must add a line to
loader.conf, like
vfs.root.mountfrom="ufs:da1s1a"
which point to the actual root mount.
Your root partition may be another GPT partition and you may use
a 64 bit disklabel within that partition if you desire.
The `boot0' boot manager is used, it can be manipulated with the
boot0cfg(8) command, `packet' option usually needs to be set.
NOTE! A disk setup with the boot command may not be shared with
another OS, as it doesn't use a fully standard GPT.
WARNING! Some BIOSes may not be able to deal with this hack, your
mileage may vary.
gpt create [-fP] [-p nparts] device ...
The create command allows the user to create a new (empty) GPT.
By default, one cannot create a GPT when the device contains a
MBR, however this can be overridden with the -f option. If the
-f option is specified, an existing MBR is destroyed and any
partitions described by the MBR are lost.
The -p nparts option specifies the number of partitions the GPT
can accommodate. By default, the gpt utility will create space
for 128 partitions.
The -P option tells gpt to create only the primary table but not
the secondary/backup table. This option is only useful for
debugging and should not be used otherwise.
gpt destroy [-r] device ...
The destroy command allows the user to destroy an existing,
possibly not empty GPT.
The -r option instructs gpt to destroy the table in a way that it
can be recovered.
gpt expand device
The expand command will expand an existing GPT table to cover a
device which has grown in size, and will also expand the size of
the last GPT partition to fit. This is typically the first step
when expanding a HAMMER2 filesystem, after which commands
disklabel -x and hammer2 growfs are run.
gpt init -f [-B] [-E] device ...
The init command will create a new GPT similar to the create
command, but also populate it with a boot slice (s0) and a
DragonFly slice (s1). The boot slice (s0) will be formatted with
newfs_msdos(8). The disklabel in the DragonFly slice (s1) will
be left empty and ready to edit.
Due to the destructive nature of this directive, the -f option
must also be specified.
If the -B option is specified, the boot loader /boot/boot1.efi
will be copied into the boot slice (s0), and the disklabel will
be initialized with disklabel -r -w -B.
If the -E option is specified, the device will be first erased by
using the TRIM command, if supported. The operation will
continue if not supported. Note that this will completely
destroy the contents of the device.
gpt label [-a] <-f file | -l label> device ...
gpt label [-b number] [-i index] [-s count] [-t type] <-f file | -l
label> device ...
The label command allows the user to label any partitions that
match the selection. At least one of the following selection
options must be specified.
The -a option specifies that all partitions should be labeled.
It is mutually exclusive with all other selection options.
The -b number option selects the partition that starts at the
given block number.
The -i index option selects the partition with the given
partition index. Partition indexes start at 0.
The -s count option selects all partitions that have the given
size. This can cause multiple partitions to be labeled.
The -t type option selects all partitions that have the given
type. The type is given as a UUID or by the aliases that the add
command accepts. This can cause multiple partitions to be
labeled.
The -f file or -l label options specify the new label to be
assigned to the selected partitions. The -f file option is used
to read the label from the specified file. Only the first line
is read from the file and the trailing newline character is
stripped. If the file name is `-' (dash), the label is read from
the standard input. The -l label option is used to specify the
label in the command line. The label is assumed to be encoded in
UTF-8.
gpt migrate [-fs] [-p nparts] device ...
The migrate command allows the user to migrate an MBR-based disk
partitioning into a GPT-based partitioning. By default, the MBR
is not migrated when it contains partitions of an unknown type.
This can be overridden with the -f option. Specifying the -f
option will cause unknown partitions to be ignored and any data
in it to be lost.
The -p nparts option specifies the number of partitions the GPT
can accommodate. By default, the gpt utility will create space
for 128 partitions (i.e., 32 sectors of 512 bytes).
The -s option prevents migrating BSD disklabels into GPT
partitions by creating the GPT equivalent of a slice.
gpt recover
The recover command tries to recover the primary GPT table from
the secondary/backup table at the end of the disk, or vice versa.
If the PMBR is missing, it will be recreated as well.
gpt remove [-a] device ...
gpt remove [-b number] [-i index] [-s count] [-t type] device ...
The remove command allows the user to remove any and all
partitions that match the selection. It uses the same selection
options as the label command. See above for a description of
these options. Partitions are removed by clearing the partition
type. No other information is changed.
gpt show [-glu] device ...
The show command displays the current partitioning on the listed
devices and gives an overall view of the disk contents. By
default, the GPT partition type is displayed in a user-friendly
form. If the -u option is specified, the GPT partition type is
displayed as a UUID. With the -l option, the GPT partition label
will be displayed instead of the GPT partition type. With the -g
option, the GPT partition GUID will be displayed instead of the
GPT partition type. None of the options has any effect on non-
GPT partitions. The order of precedence of the options are: -l,
-g, -u.
FILES
/boot/boot0 The default `boot0' image.
/boot/boot1.efi The first stage UEFI bootstrap.
/etc/defaults/uuids A list of UUIDs and their symbolic names
provided by the OS vendor.
/etc/uuids A list of UUIDs and their symbolic names
provided by the system administrator.
EXAMPLES
To install an empty GPT on da1:
gpt create da1
To add a GPT partition of size 200MB with type efi:
gpt add -s 200M -t efi da1
To add GPT partition 5 with type hammer2 using the remaining free space:
gpt add -i 5 -t hammer2 da1
To print the contents of the GPT:
gpt show da1
Boot Setup
To setup a disk using GPT for UEFI booting, the following examples may be
used. Adjust the partition scheme and sizes to your needs.
WARNING! Any previous data on disk installed to will be deleted.
This example only uses GPT partitions.
# Setup disk partitions
gpt create -f da1 # WARNING! DATA WILL BE DELETED!
gpt add -s 200M -t efi da1 # da1s0: EFI system partition
gpt add -s 2G -t ufs da1 # da1s1: UFS boot partition
gpt add -s 8G -t swap da1 # da1s2: recommended to be twice of RAM
gpt add -s 100G -t hammer2 da1 # da1s3: root partition; add to loader.conf:
# `vfs.root.mountfrom="hammer2:da1s3@ROOT"'
gpt add -t hammer2 da1 # da1s4: home partition; using free space
# Setup UEFI bootstrap
newfs_msdos -F 16 -L EFI /dev/da1s0
mkdir /mnt/efi
mount -t msdos /dev/da1s0 /mnt/efi
mkdir -p /mnt/efi/EFI/BOOT
cp /boot/boot1.efi /mnt/efi/EFI/BOOT/BOOTX64.efi
umount /mnt/efi
The follwoing example combines GPT partitions with disklabel(8). The
system is copied from an already installed disk, e.g., an installation
CD.
NOTE! This example uses the boot command to create a hybrid MBR/GPT
partition table. This is not standard GPT and may not work with other
OSes.
# Setup slices and partitions
gpt create -f da1 # WARNING! DATA WILL BE DELETED!
gpt boot da1 # create hybrid MBR
boot0cfg -s 2 da1
disklabel -B -r -w da1s0
disklabel -e da1s0 # add `a: * * 4.2BSD', to add `a' partition
# with fstype `4.2BSD' covering whole slice
gpt add da1
disklabel64 -r -w da1s1
disklabel64 -e da1s1 # add `b: 4G * swap', to add `b' partition
# with fstype `swap' and size 4GB
# add `a: * * HAMMER2', to add `a' partition
# with fstype `HAMMER2' covering rest of slice
# Format partitions and mount filesystems
newfs /dev/da1s0a
newfs_hammer2 -L ROOT /dev/da1s1a
mount_hammer2 /dev/da1s1a@ROOT /mnt
mkdir /mnt/boot
mount /dev/da1s0a /mnt/boot
# Copy system
cpdup / /mnt
cpdup /boot /mnt/boot
cpdup /var /mnt/var
cpdup /var/tmp /mnt/var/tmp
cpdup /usr /mnt/usr
# Delete unwanted files from installation CD
cd /mnt
rm -rf README* autorun* dflybsd.ico index.html
rm -rf etc
mv etc.hdd etc
# Create/edit necessary configs
vi boot/loader.conf # add `vfs.root.mountfrom="hammer2:da1s1a@ROOT"'
vi etc/fstab # add `/dev/da1s1a@ROOT / hammer2 rw 1 1'
# add `/dev/da1s1b none swap sw 0 0'
# add `/dev/da1s0a /boot ufs rw 2 2'
vi etc/rc.conf # add `dumpdev="/dev/da1s1b"'
# add other configs per your needs
# Update user and password
pwd_mkdb -p -d /mnt/etc /mnt/etc/master.passwd
pw -V /mnt/etc userdel installer
chroot /mnt passwd
# Umount
cd
umount /mnt/boot
umount /mnt
COMPATIBILITY
The GPT that gpt manipulates is part of the EFI standard and is supported
by many OSes. GPT uses 64 bits to store number of sectors, this supports
very large disks. With the prevalent sector size of 512B this is 8
billion TB.
SEE ALSO
uuid(3), disklabel32(5), disklabel64(5), uuids(5), boot0cfg(8),
disklabel32(8), disklabel64(8), efibootmgr(8), fdisk(8), mount(8),
newfs(8), newfs_hammer(8), newfs_hammer2(8), swapon(8), uefi(8)
HISTORY
The gpt utility appeared in FreeBSD 5.0 for IA64. It was imported to
DragonFly 1.9.
BUGS
The development of the gpt utility is still work in progress. Many
necessary features are missing or partially implemented. In practice
this means that the manual page, supposed to describe these features, is
farther removed from being complete or useful. As such, missing
functionality is not even documented as missing. However, it is believed
that the currently present functionality is reliable and stable enough
that this tool can be used without bullet-proof footware if one thinks
one does not make mistakes.
Another possibility is that the current usage model is accompanied by
other interfaces to make the tool usable as a back-end. This all depends
on demand and thus feedback.
DragonFly 6.5-DEVELOPMENT February 22, 2026 DragonFly 6.5-DEVELOPMENT