1.\" Copyright (c) 2002 Marcel Moolenaar 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/sbin/gpt/gpt.8,v 1.17 2006/06/22 22:22:32 marcel Exp $ 26.\" 27.Dd March 2, 2019 28.Dt GPT 8 29.Os 30.Sh NAME 31.Nm gpt 32.Nd "GUID partition table maintenance utility" 33.Sh SYNOPSIS 34.Nm 35.Op Ar general_options 36.Ar command 37.Op Ar command_options 38.Ar device ... 39.Sh DESCRIPTION 40The 41.Nm 42utility provides the necessary functionality to manipulate GUID partition 43tables (GPTs), but see 44.Sx BUGS 45below for how and where functionality is missing. 46GPT partitions are accessed as 47.Dx 48disk slices, with same number as GPT partition, 49127 slices per disk device are supported. 50The basic usage model of the 51.Nm 52tool follows that of the 53.Xr cvs 1 54tool. 55The general options are described in the following paragraph. 56The remaining paragraphs describe the individual commands with their options. 57Here we conclude by mentioning that a 58.Ar device 59is either a special file 60corresponding to a disk-like device or a regular file. 61The command is applied to each 62.Ar device 63listed on the command line. 64.Ss General Options 65The general options allow the user to change default settings or otherwise 66change the behaviour that is applicable to all commands. 67Not all commands use all default settings, so some general options may not 68have an effect on all commands. 69.Pp 70The 71.Fl p Ar count 72option allows the user to change the number of partitions the GPT can 73accommodate. 74This is used whenever a new GPT is created. 75By default, the 76.Nm 77utility will create space for 128 partitions (or 32 sectors of 512 bytes). 78.Pp 79The 80.Fl r 81option causes the 82.Nm 83utility to open the device for reading only. 84Currently this option is primarily useful for the 85.Ic show 86command, but the intent 87is to use it to implement dry-run behaviour. 88.Pp 89The 90.Fl v 91option controls the verbosity level. 92The level increases with every occurrence of this option. 93There is no formalized definition of the different levels yet. 94.Ss Commands 95.Bl -tag -width indent 96.\" ==== add ==== 97.It Xo 98.Nm 99.Ic add 100.Op Fl b Ar number 101.Op Fl i Ar index 102.Op Fl s Ar count 103.Op Fl t Ar type 104.Ar device ... 105.Xc 106The 107.Ic add 108command allows the user to add a new partition to an existing table, 109the name of the disk slice for the added partition is printed. 110By default, it will create a 111.Cm dfly 112partition covering the first available block 113of an unused disk space. 114The command-specific options can be used to control this behaviour. 115.Pp 116The 117.Fl b Ar number 118option allows the user to specify the starting (beginning) sector number of 119the partition. 120The minimum sector number is 1, but has to fall inside an unused region of 121disk space that is covered by the GPT. 122.Pp 123The 124.Fl i Ar index 125option allows the user to specify which (free) entry in the GPT table is to 126be used for the new partition. 127By default, the first free entry is selected. 128Entries start at index 0 representing partition 0 of the GPT. 129.Pp 130The 131.Fl s Ar count 132option allows the user to specify the size of the partition in sectors. 133The minimum size is 1. 134.Pp 135The 136.Fl t Ar type 137option allows the user to specify the partition type. 138The type is given as an UUID, but 139.Nm 140accepts 141.Cm efi , swap , ufs , hfs , linux , dfly , hammer, hammer2 142and 143.Cm windows 144as aliases for the most commonly used partition types. 145.Cm ufs 146is a 147.Fx 148UFS UUID. 149.Cm dfly 150has the alias 151.Cm dragonfly 152and is a 153.Dx 154.Xr disklabel64 5 155UUID. 156You may also specify any symbolic name in the system 157.Xr uuids 5 158files. 159.Pp 160.Em NOTE! 161If you don't specify a beginning sector with 162.Fl b Ar number 163, the new partition will be aligned to 1MiB in size and position 164(in case of 512 byte sector sizes). 165.\" ==== boot ==== 166.It Nm Ic boot Ar device ... 167The 168.Ic boot 169command allows the user to create a small boot partition in a freshly 170created GPT. 171.Pp 172This command creates a small, 1GB boot partition as partition #0 173and hacks in a special 174.Sq slice 1 175in the PMBR which aliases it. 176The PMBR is further modified to add the necessary boot code. 177You can then disklabel GPT partition #0 and mount it, placing the contents of 178.Pa /boot 179directory within. 180You must add a line to 181.Pa loader.conf , 182like 183.Bd -literal -offset indent 184vfs.root.mountfrom="ufs:da1s1a" 185.Ed 186.Pp 187which point to the actual root mount. 188.Pp 189Your root partition may be another GPT partition and you may use a 64 bit 190disklabel within that partition if you desire. 191.Pp 192The 193.Sq boot0 194boot manager is used, it can be manipulated with the 195.Xr boot0cfg 8 196command, 197.Sq packet 198option usually needs to be set. 199.Pp 200.Em NOTE! 201A disk setup with the 202.Ar boot 203command may not be shared with another OS, 204as it doesn't use a fully standard GPT. 205.Pp 206.Em WARNING! 207Some BIOSes may not be able to deal with this hack, your mileage may vary. 208.\" ==== create ==== 209.It Nm Ic create Oo Fl fp Oc Ar device ... 210The 211.Ic create 212command allows the user to create a new (empty) GPT. 213By default, one cannot create a GPT when the device contains a MBR, 214however this can be overridden with the 215.Fl f 216option. 217If the 218.Fl f 219option is specified, an existing MBR is destroyed and any partitions 220described by the MBR are lost. 221.Pp 222The 223.Fl p 224option tells 225.Nm 226to create only the primary table and not the backup table. 227This option is only useful for debugging and should not be used otherwise. 228.\" ==== destroy ==== 229.It Nm Ic destroy Oo Fl r Oc Ar device ... 230The 231.Ic destroy 232command allows the user to destroy an existing, possibly not empty GPT. 233.Pp 234The 235.Fl r 236option instructs 237.Nm 238to destroy the table in a way that it can be recovered. 239.\" ==== expand ==== 240.It Nm Ic expand Ar device 241The 242.Ic expand 243command will expand an existing gpt label to cover a device which 244has grown in size, and will also expand the size of the last GPT 245partition to fit. 246This is typically the first step when expanding a hammer2 filesystem, 247after which disklabel -x and hammer2 growfs are run. 248.\" ==== init ==== 249.It Nm Ic init Fl f Oo Fl B Oc Oo Fl E Oc Ar device ... 250The 251.Ic init 252command allows the user to create a new GPT similar 253to the create command, but will also populate it with 254a boot slice (s0) and a 255.Dx 256slice (s1). 257The boot slice will be dos-formatted. 258The disklabel will be left empty and ready to edit. 259.Pp 260Due to the destructive nature of this directive, the 261.Fl f 262option must also be specified. 263.Pp 264If the 265.Fl B 266option is specified, /boot/bootx64.efi will be copied into 267the msdos slice (s0), and the disklabel will be initialized 268with -B in addition to the normal -r -w. 269.Pp 270If the 271.Fl E 272option is specified, the drive is TRIMed prior to the installation 273of the new label, if supported. The operation will continue if not 274supported. Note that this will complete destroy the contents of the 275drive. 276.\" ==== label ==== 277.It Xo 278.Nm 279.Ic label 280.Op Fl a 281.Aq Fl f Ar file | Fl l Ar label 282.Ar device ... 283.Xc 284.It Xo 285.Nm 286.Ic label 287.Op Fl b Ar number 288.Op Fl i Ar index 289.Op Fl s Ar count 290.Op Fl t Ar type 291.Aq Fl f Ar file | Fl l Ar label 292.Ar device ... 293.Xc 294The 295.Ic label 296command allows the user to label any partitions that match the selection. 297At least one of the following selection options must be specified. 298.Pp 299The 300.Fl a 301option specifies that all partitions should be labeled. 302It is mutually exclusive with all other selection options. 303.Pp 304The 305.Fl b Ar number 306option selects the partition that starts at the given block number. 307.Pp 308The 309.Fl i Ar index 310option selects the partition with the given partition number. 311Partition numbers start at 0. 312.Pp 313The 314.Fl s Ar count 315option selects all partitions that have the given size. 316This can cause multiple partitions to be removed. 317.Pp 318The 319.Fl t Ar type 320option selects all partitions that have the given type. 321The type is given as an UUID or by the aliases that the 322.Ic add 323command accepts. 324This can cause multiple partitions to be removed. 325.Pp 326The 327.Fl f Ar file 328or 329.Fl l Ar label 330options specify the new label to be assigned to the selected partitions. 331The 332.Fl f Ar file 333option is used to read the label from the specified file. 334Only the first line is read from the file and the trailing newline 335character is stripped. 336If the file name is the dash or minus sign 337.Pq Fl , 338the label is read from 339the standard input. 340The 341.Fl l Ar label 342option is used to specify the label in the command line. 343The label is assumed to be encoded in UTF-8. 344.\" ==== migrate ==== 345.It Nm Ic migrate Oo Fl fs Oc Ar device ... 346The 347.Ic migrate 348command allows the user to migrate an MBR-based disk partitioning into a 349GPT-based partitioning. 350By default, the MBR is not migrated when it contains partitions of an unknown 351type. 352This can be overridden with the 353.Fl f 354option. 355Specifying the 356.Fl f 357option will cause unknown partitions to be ignored and any data in it 358to be lost. 359.Pp 360The 361.Fl s 362option prevents migrating 363.Bx 364disk labels into GPT partitions by creating 365the GPT equivalent of a slice. 366.\" ==== remove ==== 367.It Nm Ic remove Oo Fl a Oc Ar device ... 368.It Xo 369.Nm 370.Ic remove 371.Op Fl b Ar number 372.Op Fl i Ar index 373.Op Fl s Ar count 374.Op Fl t Ar type 375.Ar device ... 376.Xc 377The 378.Ic remove 379command allows the user to remove any and all partitions that match the 380selection. 381It uses the same selection options as the 382.Ic label 383command. 384See above for a description of these options. 385Partitions are removed by clearing the partition type. 386No other information is changed. 387.\" ==== show ==== 388.It Nm Ic show Oo Fl glu Oc Ar device ... 389The 390.Ic show 391command displays the current partitioning on the listed devices and gives 392an overall view of the disk contents. 393By default, the GPT partition type is displayed in a user-friendly form. 394If the 395.Fl u 396option is specified, the GPT partition type is displayed as a UUID. 397With the 398.Fl l 399option, the GPT partition label will be displayed instead of the GPT partition 400type. 401With the 402.Fl g 403option, the GPT partition GUID will be displayed instead of the GPT partition 404type. 405None of the options has any effect on non-GPT partitions. 406The order of precedence of the options are: 407.Fl l , 408.Fl g , 409.Fl u . 410.El 411.Sh FILES 412.Bl -tag -width ".Pa /etc/defaults/uuids" 413.It Pa /boot/boot0 414The default 415.Sq boot0 416image. 417.It Pa /etc/defaults/uuids 418A list of UUIDs 419and their symbolic names provided by the OS vendor. 420.It Pa /etc/uuids 421A list of UUIDs 422and their symbolic names provided by the system administrator. 423.El 424.Sh EXAMPLES 425To install an empty GPT on 426.Pa ad6 : 427.Pp 428.Dl "gpt create ad6" 429.Pp 430GPT partitions are defined in number of sectors, the sector size is usually 512B, 431which is assumed in the examples below, it can be found using: 432.Pp 433.Dl "gpt -v show ad6" 434.Pp 435To add a dummy GPT partition 0: 436.Pp 437.Dl "gpt add -i0 -s16 ad6" 438.Pp 439You might want to do this to not use slice 0 for data; 440when GPT is not used on a disk, slice 0 is the compatibility slice, 441which is used for 442.Dq dangerously dedicated 443disks. 444For GPT slice 0 has no special meaning, it is just the first slice on the disk. 445.Pp 446To add a GPT partition of size approx. 100GB: 447.Pp 448.Dl "gpt add -s200000000 ad6" 449.Pp 450This will be GPT partition 1 as it is the first one free, 451it will be accessible as 452.Pa ad6s1 , 453which is also printed by the command. 454The type will be 455.Dq DragonFly Label64 , 456it will have to be set up by 457.Xr disklabel64 8 . 458.Pp 459To add GPT partition 5 with type 460.Dq DragonFly HAMMER 461using the remaining free space: 462.Bd -literal -offset indent 463gpt add -i5 -t "DragonFly HAMMER" ad6 464.Ed 465.Pp 466To print the contents of the GPT: 467.Pp 468.Dl "gpt show ad6" 469.Ss Boot Setup 470To setup a disk using GPT for booting, the steps below can be used. 471System is copied from an already installed disk, 472e.g.\& a hard disk or an install CD. 473This example will setup disk 474.Pa da1 475with GPT for booting, using the 476.Ic boot 477command. 478.Pp 479.Em WARNING! 480Any previous data on disk installed to will be deleted. 481.Bd -literal -offset indent 482gpt create -f da1 483gpt boot da1 484boot0cfg -s 2 da1 485disklabel -B -r -w da1s0 auto 486disklabel -e da1s0 # add `a: * * 4.2BSD', to add `a' partition 487 # with fstype `4.2BSD' covering whole slice 488 489gpt add da1 490disklabel64 -r -w da1s1 auto 491disklabel64 -e da1s1 # add `b: 4G * swap', to add `b' partition 492 # with fstype `swap' and size 4GB, 493 # add `a: * * HAMMER', to add `a' partition 494 # with fstype `HAMMER' covering rest of slice 495newfs_hammer -L ROOT /dev/da1s1a 496mount_hammer /dev/da1s1a /mnt 497 498newfs /dev/da1s0a 499mkdir /mnt/boot 500mount /dev/da1s0a /mnt/boot 501 502cpdup / /mnt # copy each file system you need, e.g. 503cpdup /boot /mnt/boot 504cpdup /var /mnt/var 505cpdup /var/tmp /mnt/var/tmp 506cpdup /usr /mnt/usr 507 508cd /mnt 509vi etc/fstab # add `/dev/da1s1a / hammer rw', 510 # add `/dev/da1s1b none swap sw', 511 # add `/dev/da1s0a /boot ufs rw 1 1', 512 # delete lines for file systems cpdup'ed above 513vi boot/loader.conf # add `vfs.root.mountfrom="hammer:da1s1a"' 514cd 515umount /mnt/boot 516umount /mnt 517.Ed 518.Sh COMPATIBILITY 519The GPT that 520.Nm 521manipulates is part of the EFI standard and is supported by many OSs. 522GPT uses 64 bits to store number of sectors, this supports very large disks. 523With the prevalent sector size of 512B this is 8 billion TB. 524.Sh SEE ALSO 525.Xr uuid 3 , 526.Xr disklabel64 5 , 527.Xr uuids 5 , 528.Xr boot0cfg 8 , 529.Xr disklabel 8 , 530.Xr disklabel64 8 , 531.Xr fdisk 8 , 532.Xr mount 8 , 533.Xr newfs 8 , 534.Xr newfs_hammer 8 , 535.Xr swapon 8 536.Sh HISTORY 537The 538.Nm 539utility appeared in 540.Fx 5.0 541for ia64. 542It was imported to 543.Dx 1.9 . 544.Sh BUGS 545The development of the 546.Nm 547utility is still work in progress. 548Many necessary features are missing or partially implemented. 549In practice this means that the manual page, supposed to describe these 550features, is farther removed from being complete or useful. 551As such, missing functionality is not even documented as missing. 552However, it is believed that the currently present functionality is reliable 553and stable enough that this tool can be used without bullet-proof footware if 554one thinks one does not make mistakes. 555.Pp 556It is expected that the basic usage model does not change, but it is 557possible that future versions will not be compatible in the strictest sense 558of the word. 559For example, the 560.Fl p Ar count 561option may be changed to a command option rather than a generic option. 562There are only two commands that use it so there is a chance that the natural 563tendency for people is to use it as a command option. 564Also, options primarily intended for diagnostic or debug purposes may be 565removed in future versions. 566.Pp 567Another possibility is that the current usage model is accompanied by 568other interfaces to make the tool usable as a back-end. 569This all depends on demand and thus feedback. 570.Pp 571The 572.Ic migrate 573command doesn't support 574.Dx 575partition types. 576