1.\" $NetBSD: gpt.8,v 1.63 2018/05/01 21:16:02 kre Exp $ 2.\" 3.\" Copyright (c) 2002 Marcel Moolenaar 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $FreeBSD: src/sbin/gpt/gpt.8,v 1.17 2006/06/22 22:22:32 marcel Exp $ 28.\" 29.Dd May 1, 2018 30.Dt GPT 8 31.Os 32.Sh NAME 33.Nm gpt 34.Nd GUID partition table maintenance utility 35.Sh SYNOPSIS 36.Nm 37.Op Fl nrqv 38.Op Fl m Ar mediasize 39.Op Fl s Ar sectorsize 40.Op Fl T Ar timestamp 41.Ar command 42.Op Ar command_options 43.Ar device 44.Nm 45.Ar set 46.Fl l 47.Nm 48.Ar unset 49.Fl l 50.Nm 51.Ar type 52.Fl l 53.Sh DESCRIPTION 54The 55.Nm 56utility provides the necessary functionality to manipulate GUID partition 57tables 58.Pq GPTs , 59but see 60.Sx BUGS 61below for how and where functionality is missing. 62The basic usage model of the 63.Nm 64tool follows that of the 65.Xr cvs 1 66tool. 67The general options are described in the following paragraph. 68The remaining paragraphs describe the individual commands with their options. 69Here we conclude by mentioning that a 70.Ar device 71is either a special file 72corresponding to a disk-like device or a regular file. 73The command is applied to each 74.Ar device 75listed on the command line. 76.Ss General Options 77The general options allow the user to change default settings or otherwise 78change the behaviour that is applicable to all commands. 79Not all commands use all default settings, so some general options may not 80have an effect on all commands. 81.Bl -tag -width XXXX 82.It Fl m Ar mediasize 83Override the default media size for the device (obtained 84from the kernel if possible) or defaulting to the file size for 85plain files. 86.It Fl n 87Do not update the wedge information that 88.Nm 89changed. 90You need to use the 91.Xr dkctl 8 92command manually update the device's wedge configuration if you do that. 93.It Fl r 94Open the device for reading only. 95.Nm 96Currently this option is primarily useful for the 97.Ic show 98command, but the intent is to use it to implement dry-run behaviour. 99.It Fl q 100Do not print error messages. 101This is not implemented completely yet. 102.It Fl s Ar sectorsize 103Override the default sector size for the device (obtained 104from the kernel if possible) or 105.Dv 512 106for plain files. 107.It Fl T Ar timestamp 108Specify a timestamp to be used for uuid generation so that uuids 109are not random and can be consistent for reproducible builds. 110The timestamp can be a pathname, where the timestamps are derived from 111that file, a parseable date for parsedate(3) (this option is not 112yet available in the tools build), or an integer value interpreted 113as the number of seconds from the Epoch. 114.It Fl v 115Controls the verbosity level. 116The level increases with every occurrence of this option. 117There is no formalized definition of the different levels yet. 118.El 119.Ss Commands 120.Bl -tag -width indent 121.\" ==== add ==== 122.It Nm Ic add Oo Fl a Ar alignment Oc Oo Fl b Ar blocknr Oc \ 123Oo Fl i Ar index Oc Oo Fl l Ar label Oc Oo Fl s Ar size Oc \ 124Oo Fl t Ar type Oc 125The 126.Ic add 127command allows the user to add a new partition to an existing table. 128By default, it will create a UFS partition covering the first available block 129of an unused disk space. 130The command-specific options can be used to control this behaviour. 131.Pp 132The 133.Fl a Ar alignment 134option allows the user to specify an alignment for the start and size. 135The alignment is given in bytes and may have a suffix to indicate its 136magnitude. 137.Nm 138will attempt to align the partition. 139.Pp 140The 141.Fl b Ar blocknr 142option allows the user to specify the starting (beginning) sector number of 143the partition. 144The minimum sector number is 1, but has to fall inside an unused region of 145disk space that is covered by the GPT. 146.Pp 147The 148.Fl i Ar index 149option allows the user to specify which (free) entry in the GPT table is to 150be used for the new partition. 151By default, the first free entry is selected. 152.Pp 153The 154.Fl l Ar label 155option allows the user to specify a label for the partition. 156.Pp 157The 158.Fl s Ar size 159option allows the user to specify the size of the partition. 160If there is no suffix, or the suffix is 161.Sq s 162or 163.Sq S 164then size is in sectors, otherwise size is in bytes which must be 165a multiple of the device's sector size. 166Accepted suffix units are 167.Sq b 168to denote bytes, 169.Sq k 170to denote kilobytes, 171.Sq m 172to denote megabytes and 173.Sq g 174to denote gigabytes. 175The minimum size is 1 sector. 176.Pp 177The 178.Fl t Ar type 179option allows the user to specify the partition type. 180The type is given as an UUID, but 181.Nm 182accepts 183.Bl -tag -width "windows-reserved" -compact -offset indent 184.It Cm apple 185Apple HFS 186.It Cm apple-ufs 187Apple UFS 188.It Cm bios 189BIOS Boot 190.It Cm efi 191EFI System 192.It Cm fbsd-legacy 193.Fx 194legacy 195.It Cm fbsd-swap 196.Fx 197swap 198.It Cm fbsd-ufs 199.Fx 200UFS/UFS2 201.It Cm fbsd-vinum 202.Fx 203vinum 204.It Cm fbsd-zfs 205.Fx 206ZFS 207.It Cm linux-data 208Linux data 209.It Cm linux-raid 210Linux RAID 211.It Cm linux-swap 212Linux swap 213.It Cm linux-lvm 214Linux LVM 215.It Cm windows 216Windows basic data 217.It Cm windows-reserved 218Windows reserved 219.It Cm ccd 220.Nx 221ccd component 222.It Cm cgd 223.Nx 224Cryptographic Disk 225.It Cm ffs 226.Nx 227FFSv1/FFSv2 228.It Cm lfs 229.Nx 230LFS 231.It Cm raid 232.Nx 233RAIDFrame component 234.It Cm swap 235.Nx 236swap 237.El 238as aliases for the most commonly used partition types. 239.\" ==== backup ==== 240.It Nm Ic backup Oo Fl o Ar outfile Oc 241The 242.Ic backup 243command dumps the MBR or (PMBR) and GPT partition tables to standard 244output or to a file specified by the 245.Ar outfile 246argument in a format to be used by the 247.Ic restore 248command. 249The format is a plist. 250It should not be modified. 251.\" ==== biosboot ==== 252.It Nm Ic biosboot Oo Fl A Oc Oo Fl c Ar bootcode Oc Oo Fl i Ar index Oc \ 253Oo Fl L Ar label Oc 254The 255.Ic biosboot 256command allows the user to configure the partition that contains the 257primary bootstrap program, used during 258.Xr boot 8 . 259.Pp 260The 261.Fl A 262options sets the PMBR partition active. 263.Pp 264The 265.Fl c 266option allows the user to specify the filename that 267.Nm 268should read the bootcode from. 269The default is to read from 270.Pa /usr/mdec/gptmbr.bin . 271.Pp 272The 273.Fl i 274option selects the partition that should contain the primary 275bootstrap code, as installed via 276.Xr installboot 8 . 277The 278.Fl L 279option selects the partition by label. 280If there are multiple partitions with the same label, the 281first one found will be used. 282.\" ==== create ==== 283.It Nm Ic create Oo Fl AfP Oc Oo Fl p Ar partitions Oc 284The 285.Ic create 286command allows the user to create a new (empty) GPT. 287By default, one cannot create a GPT when the device contains a MBR, 288however this can be overridden with the 289.Fl f 290option. 291If the 292.Fl f 293option is specified, an existing MBR is destroyed and any partitions 294described by the MBR are lost. 295.Pp 296The 297.Fl A 298options sets the PMBR partition active. 299.Pp 300The 301.Fl P 302option tells 303.Nm 304to create only the primary table and not the backup table. 305This option is only useful for debugging and should not be used otherwise. 306.Pp 307The 308.Fl p 309option changes the default number of partitions the GPT can 310accommodate. 311This is used whenever a new GPT is created. 312By default, the 313.Nm 314utility will create space for 128 partitions (or 32 sectors of 512 bytes). 315.\" ==== destroy ==== 316.It Nm Ic destroy Oo Fl r Oc 317The 318.Ic destroy 319command allows the user to destroy an existing, possibly not empty GPT. 320.Pp 321The 322.Fl r 323option instructs 324.Nm 325to destroy the table in a way that it can be recovered. 326.\" ==== header ==== 327.It Nm Ic header 328The 329.Ic header 330command displays size information about the media and information from the 331GPT header if it exists. 332.\" ==== label ==== 333.It Nm Ic label Oo Fl a Oc Ao Fl f Ar file | Fl l Ar label Ac 334.It Nm Ic label Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 335Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc \ 336Ao Fl f Ar file | Fl l Ar label Ac 337The 338.Ic label 339command allows the user to label any partitions that match the selection. 340At least one of the following selection options must be specified. 341.Pp 342The 343.Fl a 344option specifies that all partitions should be labeled. 345It is mutually exclusive with all other selection options. 346.Pp 347The 348.Fl b Ar blocknr 349option selects the partition that starts at the given block number. 350.Pp 351The 352.Fl i Ar index 353option selects the partition with the given partition number. 354.Pp 355The 356.Fl L Ar label 357option selects all partitions that have the given label. 358This can cause multiple partitions to be relabeled. 359.Pp 360The 361.Fl s Ar sectors 362option selects all partitions that have the given size. 363This can cause multiple partitions to be labeled. 364.Pp 365The 366.Fl t Ar type 367option selects all partitions that have the given type. 368The type is given as an UUID or by the aliases that the 369.Ic add 370command accepts. 371This can cause multiple partitions to be labeled. 372.Pp 373The 374.Fl f Ar file 375or 376.Fl l Ar label 377options specify the new label to be assigned to the selected partitions. 378The 379.Fl f Ar file 380option is used to read the label from the specified file. 381Only the first line is read from the file and the trailing newline 382character is stripped. 383If the file name is the dash or minus sign 384.Pq Fl , 385the label is read from 386the standard input. 387The 388.Fl l Ar label 389option is used to specify the label in the command line. 390The label is assumed to be encoded in UTF-8. 391.\" ==== migrate ==== 392.It Nm Ic migrate Oo Fl Afs Oc Oo Fl p Ar partitions Oc 393The 394.Ic migrate 395command allows the user to migrate an MBR-based disk partitioning into a 396GPT-based partitioning. 397By default, the MBR is not migrated when it contains partitions of an unknown 398type. 399This can be overridden with the 400.Fl f 401option. 402Specifying the 403.Fl f 404option will cause unknown partitions to be ignored and any data in it 405to be lost. 406.Pp 407The 408.Fl A 409options sets the PMBR partition active. 410.Pp 411The 412.Fl s 413option prevents migrating 414.Bx 415disk labels into GPT partitions by creating 416the GPT equivalent of a slice. 417Note that the 418.Fl s 419option is not applicable to 420.Nx 421partitions. 422.Pp 423The 424.Fl p 425option changes the default number of partitions the GPT can 426accommodate. 427This is used whenever a new GPT is created. 428By default, the 429.Nm 430utility will create space for 128 partitions (or 32 sectors of 512 bytes). 431.Pp 432The 433.Ic migrate 434command requires space at the beginning and the end of the device outside 435any partitions to store the GPTs. 436Space is required for the GPT header 437.Pq which takes one sector 438and the GPT partition table. 439See the 440.Fl p 441option 442for the size of the GPT partition table. 443By default, just about all devices have a minimum of 62 sectors free at the 444beginning of the device, but do not have any free space at the end. 445For the default GPT partition table size on a 512 byte sector size device, 44633 sectors at the end of the device would need to be freed. 447.\" ==== recover ==== 448.It Nm Ic recover 449The 450.Ic recover 451command tries to restore the GPT partition label from the backup 452near the end of the disk. 453It is very useful in case the primary label was deleted. 454.\" ==== remove ==== 455.It Nm Ic remove Oo Fl a Oc 456.It Nm Ic remove Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 457Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc 458The 459.Ic remove 460command allows the user to remove any and all partitions that match the 461selection. 462It uses the same selection options as the 463.Ic label 464command. 465See above for a description of these options. 466Partitions are removed by clearing the partition type. 467No other information is changed. 468.\" ==== resize ==== 469.It Nm Ic resize Fl i Ar index Oo Fl a Ar alignment Oc \ 470Oo Fl s Ar size Oc 471The 472.Ic resize 473command allows the user to resize a partition. 474The partition may be shrunk and if there is sufficient free space 475immediately after it then it may be expanded. 476The 477.Fl s 478option allows the new size to be specified, otherwise the partition will 479be increased to the maximum available size. 480If there is no suffix, or the suffix is 481.Sq s 482or 483.Sq S 484then size is in sectors, otherwise size is in bytes which must be 485a multiple of the device's sector size. 486Accepted suffix units are 487.Sq b 488to denote bytes, 489.Sq k 490to denote kilobytes, 491.Sq m 492to denote megabytes and 493.Sq g 494to denote gigabytes. 495The minimum size is 1 sector. 496If the 497.Fl a 498option is specified then the size will be adjusted to be a multiple of 499alignment if possible. 500.\" ==== resizedisk ==== 501.It Nm Ic resizedisk Oo Fl s Ar size Oc 502The 503.Ic resizedisk 504command allows the user to resize a disk. 505With GPTs, a backup copy is stored at the end of the disk. 506If the underlying medium changes size 507.Pq or is going to change size , 508then the backup copy needs to be moved to the new end of the disk, 509and the last sector available for data storage needs to be adjusted. 510This command does that. 511If the backup copy no longer exists due to the medium shrinking, then 512a new backup copy will be created using the primary copy. 513.Pp 514The 515.Fl s 516option allows the new size to be specified, otherwise the backup copy 517will automatically be placed at the current end of the disk. 518If there is no suffix, or the suffix is 519.Sq s 520or 521.Sq S 522then size is in sectors, otherwise size is in bytes which must be 523a multiple of the device's sector size. 524Accepted suffix units are 525.Sq b 526to denote bytes, 527.Sq k 528to denote kilobytes, 529.Sq m 530to denote megabytes and 531.Sq g 532to denote gigabytes. 533Using the 534.Fl s 535option allows you to move the backup copy prior to resizing the medium. 536This is primarily useful when shrinking the medium. 537.\" ==== restore ==== 538.It Nm Ic restore Oo Fl F Oc Oo Fl i Ar infile Oc 539The 540.Ic restore 541command restores a partition table that was previously saved using the 542.Ic backup 543command. 544The partition table is read from standard input or a file specified in 545the 546.Ar infile 547argument and is expected to be in the format of a plist. 548It assumes an empty disk. 549The 550.Fl F 551option can be used to blank the disk. 552The new disk does not have to be the same size as the old disk as long as all 553the partitions fit, as 554.Ic restore 555will automatically adjust. 556However, the new disk must use the same sector size as the old disk. 557.\" ==== set ==== 558.It Nm Ic set Fl a Ar attribute Fl i Ar index 559.It Nm Ic set Fl l 560The 561.Ic set 562command sets various partition attributes. 563The 564.Fl l 565flag lists all available attributes. 566The 567.Fl a 568option specifies which attributes to set and may be specified more than once, 569or the attributes can be comma-separated. 570The 571.Fl i 572option specifies which entry to update. 573The possible attributes are 574.Do biosboot Dc , 575.Do bootme Dc , 576.Do bootonce Dc , 577.Do bootfailed Dc , 578.Do noblockio Dc , and 579.Do required Dc . 580The biosboot flag is used to indicate which partition should be booted 581by legacy BIOS boot code. 582See the 583.Ic biosboot 584command for more information. 585The bootme flag is used to indicate which partition should be booted 586by UEFI boot code. 587The other attributes are for compatibility with 588.Fx 589and are not currently used by 590.Nx . 591They may be used by 592.Nx 593in the future. 594.\" ==== show ==== 595.It Nm Ic show Oo Fl aglu Oc Oo Fl i Ar index Oc 596The 597.Ic show 598command displays the current partitioning on the listed devices and gives 599an overall view of the disk contents. 600With the 601.Fl g 602option the GPT partition GUID will be displayed instead of the GPT partition 603type. 604With the 605.Fl l 606option the GPT partition label will be displayed instead of the GPT partition 607type. 608With the 609.Fl u 610option the GPT partition type is displayed as an UUID instead of in a 611user friendly form. 612With the 613.Fl i 614option, all the details of a particular GPT partition will be displayed. 615The format of this display is subject to change. 616With the 617.Fl a 618option, all information for all GPT partitions (just like with 619.Fl i Ar index ) 620will be printed. 621None of the options have any effect on non-GPT partitions. 622The order of precedence for the options are: 623.Fl a , 624.Fl i , 625.Fl l , 626.Fl g , 627.Fl u . 628.\" ==== type ==== 629.It Nm Ic type Oo Fl a Oc Fl T Ar newtype 630.It Nm Ic type Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 631Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc \ 632Fl T Ar newtype 633.It Nm Ic type Fl l 634The 635.Ic type 636command allows the user to change the type of any and all partitions 637that match the selection. 638It uses the same selection options as the 639.Ic label 640command. 641See above for a description of these options. 642The 643.Fl l 644flag lists available types. 645.\" ==== unset ==== 646.It Nm Ic unset Fl a Ar attribute Fl i Ar index 647.It Nm Ic unset Fl l 648The 649.Ic unset 650command unsets various partition attributes. 651The 652.Fl l 653flag lists all available attributes. 654The 655.Fl a 656option specifies which attributes to unset and may be specified more than once. 657The 658.Fl i 659option specifies which entry to update. 660The possible attributes are 661.Do biosboot Dc , 662.Do bootme Dc , 663.Do bootonce Dc , 664.Do bootfailed Dc , 665.Do noblockio Dc , and 666.Do required Dc . 667The biosboot flag is used to indicate which partition should be booted 668by legacy BIOS boot code. 669See the 670.Ic biosboot 671command for more information. 672The other attributes are for compatibility with 673.Fx 674and are not currently used by any 675.Nx 676code. 677They may be used by 678.Nx 679code in the future. 680.El 681.Sh EXIT STATUS 682The 683.Nm 684command exits with a failure status (1) when the header command 685is used and no GPT header is found. 686This can be used to check for the existence of a GPT in shell scripts. 687.Sh EXAMPLES 688.Bd -literal 689nas# gpt show wd3 690 start size index contents 691 0 1 PMBR 692 1 3907029167 693nas# gpt create wd3 694nas# gpt show wd3 695 start size index contents 696 0 1 PMBR 697 1 1 Pri GPT header 698 2 32 Pri GPT table 699 34 3907029101 700 3907029135 32 Sec GPT table 701 3907029167 1 Sec GPT header 702nas# gpt add -s 10486224 -t swap -i 1 wd3 703nas# gpt label -i 1 -l swap_1 wd3 704partition 1 on rwd3d labeled swap_1 705nas# gpt show wd3 706 start size index contents 707 0 1 PMBR 708 1 1 Pri GPT header 709 2 32 Pri GPT table 710 34 10486224 1 GPT part - NetBSD swap 711 10486258 3896542877 712 3907029135 32 Sec GPT table 713 3907029167 1 Sec GPT header 714nas# gpt show -l wd3 715 start size index contents 716 0 1 PMBR 717 1 1 Pri GPT header 718 2 32 Pri GPT table 719 34 10486224 1 GPT part - "swap_1" 720 10486258 3896542877 721 3907029135 32 Sec GPT table 722 3907029167 1 Sec GPT header 723nas# 724.Ed 725.Pp 726Booting from GPT on an BIOS system. 727This creates a bootable partition that can be manually installed to. 728Note that 729.Xr sysinst 8 730does not yet properly support this setup. 731.Bd -literal 732xotica# gpt create wd1 733xotica# gpt add -b 1024 -l bootroot -t ffs -s 1g wd1 734/dev/rwd1: Partition 1 added: 49f48d5a-b10e-11dc-b99b-0019d1879648 1024 2097152 735xotica ~# dmesg | tail -2 736wd1: GPT GUID: 660e0630-0a3f-47c0-bc52-c88bcec79392 737dk0 at wd1: "bootroot", 2097152 blocks at 1024, type: ffs 738xotica# gpt biosboot -L bootroot wd1 739xotica# newfs dk0 740xotica# installboot /dev/rdk0 /usr/mdec/bootxx_ffsv1 741xotica# mount /dev/dk0 /mnt 742xotica# cp /usr/mdec/boot /mnt 743.Ed 744.Sh SEE ALSO 745.Xr boot 8 , 746.Xr dkctl 8 , 747.Xr fdisk 8 , 748.Xr installboot 8 , 749.Xr mount 8 , 750.Xr newfs 8 , 751.Xr swapctl 8 752.Sh HISTORY 753The 754.Nm 755utility appeared in 756.Fx 5.0 757for ia64. 758.Nm 759utility first appeared in 760.Nx 5.0 . 761.Sh BUGS 762The development of the 763.Nm 764utility is still work in progress. 765Many necessary features are missing or partially implemented. 766In practice this means that the manual page, supposed to describe these 767features, is farther removed from being complete or useful. 768As such, missing functionality is not even documented as missing. 769However, it is believed that the currently present functionality is reliable 770and stable enough that this tool can be used without bullet-proof footware if 771one thinks one does not make mistakes. 772.Pp 773It is expected that the basic usage model does not change, but it is 774possible that future versions will not be compatible in the strictest sense 775of the word. 776Also, options primarily intended for diagnostic or debug purposes may be 777removed in future versions. 778.Pp 779Another possibility is that the current usage model is accompanied by 780other interfaces to make the tool usable as a back-end. 781This all depends on demand and thus feedback. 782