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