1.\" $NetBSD: gpt.8,v 1.48 2016/06/09 19:04:43 christos 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 June 9, 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 77Don't 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 90Don't 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 isn't 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 don't 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 \ 574.It Nm Ic type Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 575Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc \ 576Fl T Ar newtype 577.It Nm Ic type Fl l 578The 579.Ic type 580command allows the user to change the type of any and all partitions 581that match the selection. 582It uses the same selection options as the 583.Ic label 584command. 585See above for a description of these options. 586The 587.Fl l 588flag lists available types. 589.\" ==== unset ==== 590.It Nm Ic unset Fl a Ar attribute Fl i Ar index 591.It Nm Ic unset Fl l 592The 593.Ic unset 594command unsets various partition attributes. 595The 596.Fl l 597flag lists all available attributes. 598The 599.Fl a 600option specifies which attributes to unset and may be specified more than once. 601The 602.Fl i 603option specifies which entry to update. 604The possible attributes are 605.Do biosboot Dc , 606.Do bootme Dc , 607.Do bootonce Dc , 608.Do bootfailed Dc , 609.Do noblockio Dc , and 610.Do required Dc . 611The biosboot flag is used to indicate which partition should be booted 612by legacy BIOS boot code. 613See the 614.Ic biosboot 615command for more information. 616The other attributes are for compatibility with 617.Fx 618and are not currently used by any 619.Nx 620code. 621They may be used by 622.Nx 623code in the future. 624.El 625.Sh EXAMPLES 626.Bd -literal 627nas# gpt show wd3 628 start size index contents 629 0 1 PMBR 630 1 3907029167 631nas# gpt create wd3 632nas# gpt show wd3 633 start size index contents 634 0 1 PMBR 635 1 1 Pri GPT header 636 2 32 Pri GPT table 637 34 3907029101 638 3907029135 32 Sec GPT table 639 3907029167 1 Sec GPT header 640nas# gpt add -s 10486224 -t swap -i 1 wd3 641nas# gpt label -i 1 -l swap_1 wd3 642parition 1 on rwd3d labeled swap_1 643nas# gpt show wd3 644 start size index contents 645 0 1 PMBR 646 1 1 Pri GPT header 647 2 32 Pri GPT table 648 34 10486224 1 GPT part - NetBSD swap 649 10486258 3896542877 650 3907029135 32 Sec GPT table 651 3907029167 1 Sec GPT header 652nas# gpt show -l wd3 653 start size index contents 654 0 1 PMBR 655 1 1 Pri GPT header 656 2 32 Pri GPT table 657 34 10486224 1 GPT part - "swap_1" 658 10486258 3896542877 659 3907029135 32 Sec GPT table 660 3907029167 1 Sec GPT header 661nas# 662.Ed 663.Sh SEE ALSO 664.Xr boot 8 , 665.Xr dkctl 8 , 666.Xr fdisk 8 , 667.Xr installboot 8 , 668.Xr mount 8 , 669.Xr newfs 8 , 670.Xr swapon 8 671.Sh HISTORY 672The 673.Nm 674utility appeared in 675.Fx 5.0 676for ia64. 677.Sh BUGS 678The development of the 679.Nm 680utility is still work in progress. 681Many necessary features are missing or partially implemented. 682In practice this means that the manual page, supposed to describe these 683features, is farther removed from being complete or useful. 684As such, missing functionality is not even documented as missing. 685However, it is believed that the currently present functionality is reliable 686and stable enough that this tool can be used without bullet-proof footware if 687one thinks one does not make mistakes. 688.Pp 689It is expected that the basic usage model does not change, but it is 690possible that future versions will not be compatible in the strictest sense 691of the word. 692Also, options primarily intended for diagnostic or debug purposes may be 693removed in future versions. 694.Pp 695Another possibility is that the current usage model is accompanied by 696other interfaces to make the tool usable as a back-end. 697This all depends on demand and thus feedback. 698