1.\" $NetBSD: gpt.8,v 1.50 2016/11/01 16:15:51 jdolecek 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 November 1, 2016 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.Ar command 41.Op Ar command_options 42.Ar device 43.Sh DESCRIPTION 44The 45.Nm 46utility provides the necessary functionality to manipulate GUID partition 47tables 48.Pq GPTs , 49but see 50.Sx BUGS 51below for how and where functionality is missing. 52The basic usage model of the 53.Nm 54tool follows that of the 55.Xr cvs 1 56tool. 57The general options are described in the following paragraph. 58The remaining paragraphs describe the individual commands with their options. 59Here we conclude by mentioning that a 60.Ar device 61is either a special file 62corresponding to a disk-like device or a regular file. 63The command is applied to each 64.Ar device 65listed on the command line. 66.Ss General Options 67The general options allow the user to change default settings or otherwise 68change the behaviour that is applicable to all commands. 69Not all commands use all default settings, so some general options may not 70have an effect on all commands. 71.Bl -tag -width XXXX 72.It Fl m Ar mediasize 73Override the default media size for the device (obtained 74from the kernel if possible) or defaulting to the file size for 75plain files. 76.It Fl n 77Do not update the wedge information that 78.Nm 79changed. 80You need to use the 81.Xr dkctl 8 82command manually update the device's wedge configuration if you do that. 83.It Fl r 84Open the device for reading only. 85.Nm 86Currently this option is primarily useful for the 87.Ic show 88command, but the intent is to use it to implement dry-run behaviour. 89.It Fl q 90Do not print error messages. 91This is not implemented completely yet. 92.It Fl s Ar sectorsize 93Override the default sector size for the device (obtained 94from the kernel if possible) or 95.Dv 512 96for plain files. 97.It Fl v 98Controls the verbosity level. 99The level increases with every occurrence of this option. 100There is no formalized definition of the different levels yet. 101.El 102.Ss Commands 103.Bl -tag -width indent 104.\" ==== add ==== 105.It Nm Ic add Oo Fl a Ar alignment Oc Oo Fl b Ar blocknr Oc \ 106Oo Fl i Ar index Oc Oo Fl l Ar label Oc Oo Fl s Ar size Oc \ 107Oo Fl t Ar type Oc 108The 109.Ic add 110command allows the user to add a new partition to an existing table. 111By default, it will create a UFS partition covering the first available block 112of an unused disk space. 113The command-specific options can be used to control this behaviour. 114.Pp 115The 116.Fl a Ar alignment 117option allows the user to specify an alignment for the start and size. 118The alignment may have a suffix to indicate its magnitude. 119.Nm 120will attempt to align the partition. 121.Pp 122The 123.Fl b Ar blocknr 124option allows the user to specify the starting (beginning) sector number of 125the partition. 126The minimum sector number is 1, but has to fall inside an unused region of 127disk space that is covered by the GPT. 128.Pp 129The 130.Fl i Ar index 131option allows the user to specify which (free) entry in the GPT table is to 132be used for the new partition. 133By default, the first free entry is selected. 134.Pp 135The 136.Fl l Ar label 137option allows the user to specify a label for the partition. 138.Pp 139The 140.Fl s Ar size 141option allows the user to specify the size of the partition. 142If there is no suffix, or the suffix is 143.Sq s 144or 145.Sq S 146then size is in sectors, otherwise size is in bytes which must be 147a multiple of the device's sector size. 148The minimum size is 1 sector. 149.Pp 150The 151.Fl t Ar type 152option allows the user to specify the partition type. 153The type is given as an UUID, but 154.Nm 155accepts 156.Bl -tag -width "windows-reserved" -compact -offset indent 157.It Cm apple 158Apple HFS 159.It Cm apple-ufs 160Apple UFS 161.It Cm bios 162BIOS Boot 163.It Cm efi 164EFI System 165.It Cm fbsd-legacy 166FreeBSD legacy 167.It Cm fbsd-swap 168FreeBSD swap 169.It Cm fbsd-ufs 170FreeBSD UFS/UFS2 171.It Cm fbsd-vinum 172FreeBSD vinum 173.It Cm fbsd-zfs 174FreeBSD ZFS 175.It Cm linux-data 176Linux data 177.It Cm linux-raid 178Linux RAID 179.It Cm linux-swap 180Linux swap 181.It Cm linux-lvm 182Linux LVM 183.It Cm windows 184Windows basic data 185.It Cm windows-reserved 186Windows reserved 187.It Cm ccd 188NetBSD ccd component 189.It Cm cgd 190NetBSD Cryptographic Disk 191.It Cm ffs 192NetBSD FFSv1/FFSv2 193.It Cm lfs 194NetBSD LFS 195.It Cm raid 196NetBSD RAIDFrame component 197.It Cm swap 198NetBSD swap 199.El 200as aliases for the most commonly used partition types. 201.\" ==== backup ==== 202.It Nm Ic backup Oo Fl o Ar outfile Oc 203The 204.Ic backup 205command dumps the MBR or (PMBR) and GPT partition tables to standard 206output or to a file specified by the 207.Ar outfile 208argument in a format to be used by the 209.Ic restore 210command. 211The format is a plist. 212It should not be modified. 213.\" ==== biosboot ==== 214.It Nm Ic biosboot Oo Fl A Oc Oo Fl c Ar bootcode Oc Oo Fl i Ar index Oc \ 215Oo Fl L Ar label Oc 216The 217.Ic biosboot 218command allows the user to configure the partition that contains the 219primary bootstrap program, used during 220.Xr boot 8 . 221.Pp 222The 223.Fl A 224options sets the PMBR partition active. 225.Pp 226The 227.Fl c 228option allows the user to specify the filename that 229.Nm 230should read the bootcode from. 231The default is to read from 232.Pa /usr/mdec/gptmbr.bin . 233.Pp 234The 235.Fl i 236option selects the partition that should contain the primary 237bootstrap code, as installed via 238.Xr installboot 8 . 239The 240.Fl L 241option selects the partition by label. 242If there are multiple partitions with the same label, it will use the 243first one found. 244.\" ==== create ==== 245.It Nm Ic create Oo Fl AfP Oc Oo Fl p Ar partitions Oc 246The 247.Ic create 248command allows the user to create a new (empty) GPT. 249By default, one cannot create a GPT when the device contains a MBR, 250however this can be overridden with the 251.Fl f 252option. 253If the 254.Fl f 255option is specified, an existing MBR is destroyed and any partitions 256described by the MBR are lost. 257.Pp 258The 259.Fl A 260options sets the PMBR partition active. 261.Pp 262The 263.Fl P 264option tells 265.Nm 266to create only the primary table and not the backup table. 267This option is only useful for debugging and should not be used otherwise. 268.Pp 269The 270.Fl p 271option changes the default number of partitions the GPT can 272accommodate. 273This is used whenever a new GPT is created. 274By default, the 275.Nm 276utility will create space for 128 partitions (or 32 sectors of 512 bytes). 277.\" ==== destroy ==== 278.It Nm Ic destroy Oo Fl r Oc 279The 280.Ic destroy 281command allows the user to destroy an existing, possibly not empty GPT. 282.Pp 283The 284.Fl r 285option instructs 286.Nm 287to destroy the table in a way that it can be recovered. 288.\" ==== header ==== 289.It Nm Ic header 290The 291.Ic header 292command displays size information about the media and information from the 293GPT header if it exists. 294.\" ==== label ==== 295.It Nm Ic label Oo Fl a Oc Ao Fl f Ar file | Fl l Ar label Ac 296.It Nm Ic label Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 297Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc \ 298Ao Fl f Ar file | Fl l Ar label Ac 299The 300.Ic label 301command allows the user to label any partitions that match the selection. 302At least one of the following selection options must be specified. 303.Pp 304The 305.Fl a 306option specifies that all partitions should be labeled. 307It is mutually exclusive with all other selection options. 308.Pp 309The 310.Fl b Ar blocknr 311option selects the partition that starts at the given block number. 312.Pp 313The 314.Fl i Ar index 315option selects the partition with the given partition number. 316.Pp 317The 318.Fl L Ar label 319option selects all partitions that have the given label. 320This can cause multiple partitions to be relabeled. 321.Pp 322The 323.Fl s Ar sectors 324option selects all partitions that have the given size. 325This can cause multiple partitions to be labeled. 326.Pp 327The 328.Fl t Ar type 329option selects all partitions that have the given type. 330The type is given as an UUID or by the aliases that the 331.Ic add 332command accepts. 333This can cause multiple partitions to be labeled. 334.Pp 335The 336.Fl f Ar file 337or 338.Fl l Ar label 339options specify the new label to be assigned to the selected partitions. 340The 341.Fl f Ar file 342option is used to read the label from the specified file. 343Only the first line is read from the file and the trailing newline 344character is stripped. 345If the file name is the dash or minus sign 346.Pq Fl , 347the label is read from 348the standard input. 349The 350.Fl l Ar label 351option is used to specify the label in the command line. 352The label is assumed to be encoded in UTF-8. 353.\" ==== migrate ==== 354.It Nm Ic migrate Oo Fl Afs Oc Oo Fl p Ar partitions Oc 355The 356.Ic migrate 357command allows the user to migrate an MBR-based disk partitioning into a 358GPT-based partitioning. 359By default, the MBR is not migrated when it contains partitions of an unknown 360type. 361This can be overridden with the 362.Fl f 363option. 364Specifying the 365.Fl f 366option will cause unknown partitions to be ignored and any data in it 367to be lost. 368.Pp 369The 370.Fl A 371options sets the PMBR partition active. 372.Pp 373The 374.Fl s 375option prevents migrating 376.Bx 377disk labels into GPT partitions by creating 378the GPT equivalent of a slice. 379Note that the 380.Fl s 381option is not applicable to 382.Nx 383partitions. 384.Pp 385The 386.Fl p 387option changes the default number of partitions the GPT can 388accommodate. 389This is used whenever a new GPT is created. 390By default, the 391.Nm 392utility will create space for 128 partitions (or 32 sectors of 512 bytes). 393.Pp 394The 395.Ic migrate 396command requires space at the beginning and the end of the device outside 397any partitions to store the GPTs. 398Space is required for the GPT header 399.Pq which takes one sector 400and the GPT partition table. 401See the 402.Fl p 403option 404for the size of the GPT partition table. 405By default, just about all devices have a minimum of 62 sectors free at the 406beginning of the device, but do not have any free space at the end. 407For the default GPT partition table size on a 512 byte sector size device, 40833 sectors at the end of the device would need to be freed. 409.\" ==== recover ==== 410.It Nm Ic recover 411The 412.Ic recover 413command tries to restore the GPT partition label from the backup 414near the end of the disk. 415It is very useful in case the primary label was deleted. 416.\" ==== remove ==== 417.It Nm Ic remove Oo Fl a Oc 418.It Nm Ic remove Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 419Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc 420The 421.Ic remove 422command allows the user to remove any and all partitions that match the 423selection. 424It uses the same selection options as the 425.Ic label 426command. 427See above for a description of these options. 428Partitions are removed by clearing the partition type. 429No other information is changed. 430.\" ==== resize ==== 431.It Nm Ic resize Fl i Ar index Oo Fl a Ar alignment Oc \ 432Oo Fl s Ar size Oc 433The 434.Ic resize 435command allows the user to resize a partition. 436The partition may be shrunk and if there is sufficient free space 437immediately after it then it may be expanded. 438The 439.Fl s 440option allows the new size to be specified, otherwise the partition will 441be increased to the maximum available size. 442If there is no suffix, or the suffix is 443.Sq s 444or 445.Sq S 446then size is in sectors, otherwise size is in bytes which must be 447a multiple of the device's sector size. 448The minimum size is 1 sector. 449If the 450.Fl a 451option is specified then the size will be adjusted to be a multiple of 452alignment if possible. 453.\" ==== resizedisk ==== 454.It Nm Ic resizedisk Oo Fl s Ar size Oc 455The 456.Ic resizedisk 457command allows the user to resize a disk. 458With GPTs, a backup copy is stored at the end of the disk. 459If the underlying medium changes size 460.Pq or is going to change size , 461then the backup copy needs to be moved to the new end of the disk, 462and the last sector available for data storage needs to be adjusted. 463This command does that. 464If the backup copy no longer exists due to the medium shrinking, then 465a new backup copy will be created using the primary copy. 466.Pp 467The 468.Fl s 469option allows the new size to be specified, otherwise the backup copy 470will automatically be placed at the current end of the disk. 471If there is no suffix, or the suffix is 472.Sq s 473or 474.Sq S 475then size is in sectors, otherwise size is in bytes which must be 476a multiple of the device's sector size. 477Using the 478.Fl s 479option allows you to move the backup copy prior to resizing the medium. 480This is primarily useful when shrinking the medium. 481.\" ==== restore ==== 482.It Nm Ic restore Oo Fl F Oc Oo Fl i Ar infile Oc 483The 484.Ic restore 485command restores a partition table that was previously saved using the 486.Ic backup 487command. 488The partition table is read from standard input or a file specified in 489the 490.Ar infile 491argument and is expected to be in the format of a plist. 492It assumes an empty disk. 493The 494.Fl F 495option can be used to blank the disk. 496The new disk does not have to be the same size as the old disk as long as all 497the partitions fit, as 498.Ic restore 499will automatically adjust. 500However, the new disk must use the same sector size as the old disk. 501.\" ==== set ==== 502.It Nm Ic set Fl a Ar attribute Fl i Ar index 503.It Nm Ic set Fl l 504The 505.Ic set 506command sets various partition attributes. 507The 508.Fl l 509flag lists all available attributes. 510The 511.Fl a 512option specifies which attributes to set and may be specified more than once, 513or the attributes can be comma-separated. 514The 515.Fl i 516option specifies which entry to update. 517The possible attributes are 518.Do biosboot Dc , 519.Do bootme Dc , 520.Do bootonce Dc , 521.Do bootfailed Dc , 522.Do noblockio Dc , and 523.Do required Dc . 524The biosboot flag is used to indicate which partition should be booted 525by legacy BIOS boot code. 526See the 527.Ic biosboot 528command for more information. 529The other attributes are for compatibility with 530.Fx 531and are not currently used by any 532.Nx 533code. 534They may be used by 535.Nx 536code in the future. 537.\" ==== show ==== 538.It Nm Ic show Oo Fl aglu Oc Oo Fl i Ar index Oc 539The 540.Ic show 541command displays the current partitioning on the listed devices and gives 542an overall view of the disk contents. 543With the 544.Fl g 545option the GPT partition GUID will be displayed instead of the GPT partition 546type. 547With the 548.Fl l 549option the GPT partition label will be displayed instead of the GPT partition 550type. 551With the 552.Fl u 553option the GPT partition type is displayed as an UUID instead of in a 554user friendly form. 555With the 556.Fl i 557option, all the details of a particular GPT partition will be displayed. 558The format of this display is subject to change. 559With the 560.Fl a 561option, all information for all GPT partitions (just like with 562.Fl i Ar index ) 563will be printed. 564None of the options have any effect on non-GPT partitions. 565The order of precedence for the options are: 566.Fl a , 567.Fl i , 568.Fl l , 569.Fl g , 570.Fl u . 571.\" ==== type ==== 572.It Nm Ic type Oo Fl a Oc Fl T Ar newtype 573.It Nm Ic type Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 574Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc \ 575Fl T Ar newtype 576.It Nm Ic type Fl l 577The 578.Ic type 579command allows the user to change the type of any and all partitions 580that match the selection. 581It uses the same selection options as the 582.Ic label 583command. 584See above for a description of these options. 585The 586.Fl l 587flag lists available types. 588.\" ==== unset ==== 589.It Nm Ic unset Fl a Ar attribute Fl i Ar index 590.It Nm Ic unset Fl l 591The 592.Ic unset 593command unsets various partition attributes. 594The 595.Fl l 596flag lists all available attributes. 597The 598.Fl a 599option specifies which attributes to unset and may be specified more than once. 600The 601.Fl i 602option specifies which entry to update. 603The possible attributes are 604.Do biosboot Dc , 605.Do bootme Dc , 606.Do bootonce Dc , 607.Do bootfailed Dc , 608.Do noblockio Dc , and 609.Do required Dc . 610The biosboot flag is used to indicate which partition should be booted 611by legacy BIOS boot code. 612See the 613.Ic biosboot 614command for more information. 615The other attributes are for compatibility with 616.Fx 617and are not currently used by any 618.Nx 619code. 620They may be used by 621.Nx 622code in the future. 623.El 624.Sh EXAMPLES 625.Bd -literal 626nas# gpt show wd3 627 start size index contents 628 0 1 PMBR 629 1 3907029167 630nas# gpt create wd3 631nas# gpt show wd3 632 start size index contents 633 0 1 PMBR 634 1 1 Pri GPT header 635 2 32 Pri GPT table 636 34 3907029101 637 3907029135 32 Sec GPT table 638 3907029167 1 Sec GPT header 639nas# gpt add -s 10486224 -t swap -i 1 wd3 640nas# gpt label -i 1 -l swap_1 wd3 641parition 1 on rwd3d labeled swap_1 642nas# gpt show wd3 643 start size index contents 644 0 1 PMBR 645 1 1 Pri GPT header 646 2 32 Pri GPT table 647 34 10486224 1 GPT part - NetBSD swap 648 10486258 3896542877 649 3907029135 32 Sec GPT table 650 3907029167 1 Sec GPT header 651nas# gpt show -l wd3 652 start size index contents 653 0 1 PMBR 654 1 1 Pri GPT header 655 2 32 Pri GPT table 656 34 10486224 1 GPT part - "swap_1" 657 10486258 3896542877 658 3907029135 32 Sec GPT table 659 3907029167 1 Sec GPT header 660nas# 661.Ed 662.Sh SEE ALSO 663.Xr boot 8 , 664.Xr dkctl 8 , 665.Xr fdisk 8 , 666.Xr installboot 8 , 667.Xr mount 8 , 668.Xr newfs 8 , 669.Xr swapon 8 670.Sh HISTORY 671The 672.Nm 673utility appeared in 674.Fx 5.0 675for ia64. 676.Nm 677utility first appeared in 678.Nx 5.0 . 679.Sh BUGS 680The development of the 681.Nm 682utility is still work in progress. 683Many necessary features are missing or partially implemented. 684In practice this means that the manual page, supposed to describe these 685features, is farther removed from being complete or useful. 686As such, missing functionality is not even documented as missing. 687However, it is believed that the currently present functionality is reliable 688and stable enough that this tool can be used without bullet-proof footware if 689one thinks one does not make mistakes. 690.Pp 691It is expected that the basic usage model does not change, but it is 692possible that future versions will not be compatible in the strictest sense 693of the word. 694Also, options primarily intended for diagnostic or debug purposes may be 695removed in future versions. 696.Pp 697Another possibility is that the current usage model is accompanied by 698other interfaces to make the tool usable as a back-end. 699This all depends on demand and thus feedback. 700