GPT(8) | System Manager's Manual | GPT(8) |
gpt
—
gpt |
[-nrqv ] [-m
mediasize] [-s
sectorsize] [-T
timestamp] command
[command_options] device |
gpt |
set -l |
gpt |
unset -l |
gpt |
type -l |
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 paragraph. The remaining
paragraphs describe the individual commands with their options. Here we
conclude by mentioning that 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.
-m
mediasize-n
gpt
changed. You need to use the
dkctl(8) command manually
update the device's wedge configuration if you do that.-r
gpt
Currently
this option is primarily useful for the show
command, but the intent is to use it to implement dry-run behaviour.-q
-s
sectorsize512
for plain files.-T
timestamp-v
gpt
add
[-a
alignment]
[-b
blocknr]
[-i
index]
[-l
label]
[-s
size]
[-t
type]add
command allows the user to add a new
partition to an existing table. By default, it will create a UFS partition
covering the first available block of an unused disk space. The
command-specific options can be used to control this behaviour.
The -a
alignment
option allows the user to specify an alignment for the start and size.
The alignment is given in bytes and may have a suffix to indicate its
magnitude. gpt
will attempt to align the
partition.
The -b
blocknr
option allows the user to specify 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 allows the user to specify which (free) entry in the GPT table is
to be used for the new partition. By default, the first free entry is
selected.
The -l
label
option allows the user to specify a label for the partition.
The -s
size
option allows the user to specify the size of the partition. If there is
no suffix, or the suffix is ‘s’ or ‘S’ then
size is in sectors, otherwise size is in bytes which must be a multiple
of the device's sector size. Accepted suffix units are ‘b’
to denote bytes, ‘k’ to denote kilobytes,
‘m’ to denote megabytes and ‘g’ to denote
gigabytes. The minimum size is 1 sector.
The -t
type
option allows the user to specify the partition type. The type is given
as an UUID, but gpt
accepts
apple
apple-ufs
bios
efi
fbsd-legacy
fbsd-swap
fbsd-ufs
fbsd-vinum
fbsd-zfs
linux-data
linux-raid
linux-swap
linux-lvm
windows
windows-reserved
ccd
cgd
ffs
lfs
raid
swap
gpt
backup
[-o
outfile]backup
command dumps the MBR or (PMBR) and GPT
partition tables to standard output or to a file specified by the
outfile argument in a format to be used by the
restore
command. The format is a plist. It should
not be modified.gpt
biosboot
[-A
] [-c
bootcode] [-b
startsec] [-i
index] [-L
label]biosboot
command allows the user to configure
the partition that contains the primary bootstrap program, used during
boot(8).
The -A
options sets the PMBR partition
active.
The -c
option allows the user to
specify the filename that gpt
should read the
bootcode from. The default is to read from
/usr/mdec/gptmbr.bin.
The -i
option selects the partition
that should contain the primary bootstrap code, as installed via
installboot(8). The
-L
option selects the partition by label. If
there are multiple partitions with the same label, the first one found
will be used. The -b
options selects the
partition by start block.
gpt
create
[-AfP
] [-p
partitions]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 -A
options sets the PMBR partition
active.
The -P
option tells
gpt
to create only the primary table and not the
backup table. This option is only useful for debugging and should not be
used otherwise.
The -p
option changes the default
number of partitions the GPT can accommodate. This is used whenever a
new GPT is created. By default, the gpt
utility
will create space for 128 partitions (or 32 sectors of 512 bytes).
gpt
destroy
[-r
]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
header
header
command displays size information about
the media and information from the GPT header if it exists.gpt
label
[-a
] ⟨-f
file | -l
label⟩gpt
label
[-b
blocknr]
[-i
index]
[-L
label]
[-s
sectors]
[-t
type]
⟨-f
file |
-l
label⟩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
blocknr
option selects the partition that starts at the given block number.
The -i
index
option selects the partition with the given partition number.
The -L
label
option selects all partitions that have the given label. This can cause
multiple partitions to be relabeled.
The -s
sectors
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 an 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 the dash or minus sign (-
), 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
[-Afs
] [-p
partitions]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 -A
options sets the PMBR partition
active.
The -s
option prevents migrating
BSD disk labels into GPT partitions by creating
the GPT equivalent of a slice. Note that the -s
option is not applicable to NetBSD
partitions.
The -p
option changes the default
number of partitions the GPT can accommodate. This is used whenever a
new GPT is created. By default, the gpt
utility
will create space for 128 partitions (or 32 sectors of 512 bytes).
The migrate
command requires space at
the beginning and the end of the device outside any partitions to store
the GPTs. Space is required for the GPT header (which takes one sector)
and the GPT partition table. See the -p
option
for the size of the GPT partition table. By default, just about all
devices have a minimum of 62 sectors free at the beginning of the
device, but do not have any free space at the end. For the default GPT
partition table size on a 512 byte sector size device, 33 sectors at the
end of the device would need to be freed.
gpt
recover
recover
command tries to restore the GPT
partition label from the backup near the end of the disk. It is very
useful in case the primary label was deleted.gpt
remove
[-a
]gpt
remove
[-b
blocknr]
[-i
index]
[-L
label]
[-s
sectors]
[-t
type]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
resize
[-i
index]
[-b
startsec]
[-a
alignment]
[-s
size]resize
command allows the user to resize a
partition. The partition may be shrunk and if there is sufficient free
space immediately after it then it may be expanded. The
-s
option allows the new size to be specified,
otherwise the partition will be increased to the maximum available size.
If there is no suffix, or the suffix is ‘s’ or
‘S’ then size is in sectors, otherwise size is in bytes
which must be a multiple of the device's sector size. Accepted suffix
units are ‘b’ to denote bytes, ‘k’ to denote
kilobytes, ‘m’ to denote megabytes and ‘g’ to
denote gigabytes. The minimum size is 1 sector. If the
-a
option is specified then the size will be
adjusted to be a multiple of alignment if possible.gpt
resizedisk
[-s
size]resizedisk
command allows the user to resize a
disk. With GPTs, a backup copy is stored at the end of the disk. If the
underlying medium changes size (or is going to change size), then the
backup copy needs to be moved to the new end of the disk, and the last
sector available for data storage needs to be adjusted. This command does
that. If the backup copy no longer exists due to the medium shrinking,
then a new backup copy will be created using the primary copy.
The -s
option allows the new size to
be specified, otherwise the backup copy will automatically be placed at
the current end of the disk. If there is no suffix, or the suffix is
‘s’ or ‘S’ then size is in sectors,
otherwise size is in bytes which must be a multiple of the device's
sector size. Accepted suffix units are ‘b’ to denote
bytes, ‘k’ to denote kilobytes, ‘m’ to
denote megabytes and ‘g’ to denote gigabytes. Using the
-s
option allows you to move the backup copy
prior to resizing the medium. This is primarily useful when shrinking
the medium.
gpt
restore
[-F
] [-i
infile]restore
command restores a partition table
that was previously saved using the backup
command. The partition table is read from standard input or a file
specified in the infile argument and is expected to
be in the format of a plist. It assumes an empty disk. The
-F
option can be used to blank the disk. The new
disk does not have to be the same size as the old disk as long as all the
partitions fit, as restore
will automatically
adjust. However, the new disk must use the same sector size as the old
disk.gpt
set
[-a
attribute]
[-N
] [-i
index] [-b
startsec]gpt
set
-l
set
command sets various partition attributes.
The -l
flag lists all available attributes. The
-a
option specifies which attributes to set and
may be specified more than once, or the attributes can be comma-separated.
If the -N
option and no -a
option are specified, all attributes are removed. The
-i
or the -b
option
specify which entry to update. The possible attributes are
“biosboot”, “bootme”,
“bootonce”, “bootfailed”,
“noblockio”, and “required”. The biosboot flag
is used to indicate which partition should be booted by legacy BIOS boot
code. See the biosboot
command for more
information. The bootme flag is used to indicate which partition should be
booted by UEFI boot code. The other attributes are for compatibility with
FreeBSD and are not currently used by
NetBSD. They may be used by
NetBSD in the future.gpt
show
[-aglu
] [-i
index] [-b
startsec]show
command displays the current partitioning
on the listed devices and gives an overall view of the disk contents. With
the -g
option the GPT partition GUID will be
displayed instead of the GPT partition type. With the
-l
option the GPT partition label will be
displayed instead of the GPT partition type. With the
-u
option the GPT partition type is displayed as
an UUID instead of in a user friendly form. With the
-i
or the -b
option, all
the details of a particular GPT partition will be displayed. The format of
this display is subject to change. With the -a
option, all information for all GPT partitions (just like with
-i
index) will be printed.
None of the options have any effect on non-GPT partitions. The order of
precedence for the options are: -a
,
-i
, -l
,
-g
, -u
.gpt
type
[-a
] -T
newtypegpt
type
[-b
blocknr]
[-i
index]
[-L
label]
[-s
sectors]
[-t
type]
-T
newtypegpt
type
-l
type
command allows the user to change the
type of 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. The -l
flag
lists available types.gpt
unset
-a
attribute
[-i
index]
[-b
startsec]gpt
unset
-l
unset
command unsets various partition
attributes. The -l
flag lists all available
attributes. The -a
option specifies which
attributes to unset and may be specified more than once. Alternatively a
comma separated list of attributes can be used. The
-i
or the -b
option
specifies which entry to update. The possible attributes are
“biosboot”, “bootme”,
“bootonce”, “bootfailed”,
“noblockio”, and “required”. The biosboot flag
is used to indicate which partition should be booted by legacy BIOS boot
code. See the biosboot
command for more
information. The other attributes are for compatibility with
FreeBSD and are not currently used by any
NetBSD code. They may be used by
NetBSD code in the future.gpt
uuid
[-a
]gpt
uuid
[-b
blocknr]
[-i
index]
[-L
label]
[-s
sectors]
[-t
type]uuid
command allows the user to change the
UUID of 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. If -a
is used,
then the header UUID is changed as well.
The primary purpose of this command is for use after cloning a disk to prevent collisions when both disks are used in the same system.
gpt
command exits with a failure status (1) when the
header command is used and no GPT header is found. This can be used to check
for the existence of a GPT in shell scripts.
nas# gpt show wd3 start size index contents 0 1 PMBR 1 3907029167 nas# gpt create wd3 nas# gpt show wd3 start size index contents 0 1 PMBR 1 1 Pri GPT header 2 32 Pri GPT table 34 3907029101 3907029135 32 Sec GPT table 3907029167 1 Sec GPT header nas# gpt add -s 10486224 -t swap -i 1 wd3 nas# gpt label -i 1 -l swap_1 wd3 partition 1 on rwd3d labeled swap_1 nas# gpt show wd3 start size index contents 0 1 PMBR 1 1 Pri GPT header 2 32 Pri GPT table 34 10486224 1 GPT part - NetBSD swap 10486258 3896542877 3907029135 32 Sec GPT table 3907029167 1 Sec GPT header nas# gpt show -l wd3 start size index contents 0 1 PMBR 1 1 Pri GPT header 2 32 Pri GPT table 34 10486224 1 GPT part - "swap_1" 10486258 3896542877 3907029135 32 Sec GPT table 3907029167 1 Sec GPT header nas#
Booting from GPT on a BIOS system: this creates a bootable partition.
xotica# gpt create wd1 xotica# gpt add -b 1024 -l bootroot -t ffs -s 1g wd1 /dev/rwd1: Partition 1 added: 49f48d5a-b10e-11dc-b99b-0019d1879648 1024 2097152 xotica ~# dmesg | tail -2 wd1: GPT GUID: 660e0630-0a3f-47c0-bc52-c88bcec79392 dk0 at wd1: "bootroot", 2097152 blocks at 1024, type: ffs xotica# gpt biosboot -L bootroot wd1 xotica# newfs dk0 xotica# installboot /dev/rdk0 /usr/mdec/bootxx_ffsv1 xotica# mount /dev/dk0 /mnt xotica# cp /usr/mdec/boot /mnt
Note that biosboot
is not needed for UEFI
systems.
gpt
utility appeared in FreeBSD
5.0 for ia64. gpt
utility first appeared in
NetBSD 5.0.
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.
It is expected that the basic usage model does not change, but it is possible that future versions will not be compatible in the strictest sense of the word. Also, options primarily intended for diagnostic or debug purposes may be removed in future versions.
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.
July 26, 2019 | NetBSD 9.4 |