1.\" $NetBSD: gpt.8,v 1.45 2015/12/25 12:16:03 wiz 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 December 25, 2015 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 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 c 224option allows the user to specify the filename that 225.Nm 226should read the bootcode from. 227The default is to read from 228.Pa /usr/mdec/gptmbr.bin . 229.Pp 230The 231.Fl i 232option selects the partition that should contain the primary 233bootstrap code, as installed via 234.Xr installboot 8 . 235The 236.Fl L 237option selects the partition by label. 238If there are multiple partitions with the same label, it will use the 239first one found. 240.\" ==== create ==== 241.It Nm Ic create Oo Fl fP Oc Oo Fl p Ar partitions Oc 242The 243.Ic create 244command allows the user to create a new (empty) GPT. 245By default, one cannot create a GPT when the device contains a MBR, 246however this can be overridden with the 247.Fl f 248option. 249If the 250.Fl f 251option is specified, an existing MBR is destroyed and any partitions 252described by the MBR are lost. 253.Pp 254The 255.Fl P 256option tells 257.Nm 258to create only the primary table and not the backup table. 259This option is only useful for debugging and should not be used otherwise. 260.Pp 261The 262.Fl p 263option changes the default number of partitions the GPT can 264accommodate. 265This is used whenever a new GPT is created. 266By default, the 267.Nm 268utility will create space for 128 partitions (or 32 sectors of 512 bytes). 269.\" ==== destroy ==== 270.It Nm Ic destroy Oo Fl r Oc 271The 272.Ic destroy 273command allows the user to destroy an existing, possibly not empty GPT. 274.Pp 275The 276.Fl r 277option instructs 278.Nm 279to destroy the table in a way that it can be recovered. 280.\" ==== header ==== 281.It Nm Ic header 282The 283.Ic header 284command displays size information about the media and information from the 285GPT header if it exists. 286.\" ==== label ==== 287.It Nm Ic label Oo Fl a Oc Ao Fl f Ar file | Fl l Ar label Ac 288.It Nm Ic label Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 289Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc \ 290Ao Fl f Ar file | Fl l Ar label Ac 291The 292.Ic label 293command allows the user to label any partitions that match the selection. 294At least one of the following selection options must be specified. 295.Pp 296The 297.Fl a 298option specifies that all partitions should be labeled. 299It is mutually exclusive with all other selection options. 300.Pp 301The 302.Fl b Ar blocknr 303option selects the partition that starts at the given block number. 304.Pp 305The 306.Fl i Ar index 307option selects the partition with the given partition number. 308.Pp 309The 310.Fl L Ar label 311option selects all partitions that have the given label. 312This can cause multiple partitions to be relabeled. 313.Pp 314The 315.Fl s Ar sectors 316option selects all partitions that have the given size. 317This can cause multiple partitions to be labeled. 318.Pp 319The 320.Fl t Ar type 321option selects all partitions that have the given type. 322The type is given as an UUID or by the aliases that the 323.Ic add 324command accepts. 325This can cause multiple partitions to be labeled. 326.Pp 327The 328.Fl f Ar file 329or 330.Fl l Ar label 331options specify the new label to be assigned to the selected partitions. 332The 333.Fl f Ar file 334option is used to read the label from the specified file. 335Only the first line is read from the file and the trailing newline 336character is stripped. 337If the file name is the dash or minus sign 338.Pq Fl , 339the label is read from 340the standard input. 341The 342.Fl l Ar label 343option is used to specify the label in the command line. 344The label is assumed to be encoded in UTF-8. 345.\" ==== migrate ==== 346.It Nm Ic migrate Oo Fl fs Oc Oo Fl p Ar partitions Oc 347The 348.Ic migrate 349command allows the user to migrate an MBR-based disk partitioning into a 350GPT-based partitioning. 351By default, the MBR is not migrated when it contains partitions of an unknown 352type. 353This can be overridden with the 354.Fl f 355option. 356Specifying the 357.Fl f 358option will cause unknown partitions to be ignored and any data in it 359to be lost. 360.Pp 361The 362.Fl s 363option prevents migrating 364.Bx 365disk labels into GPT partitions by creating 366the GPT equivalent of a slice. 367Note that the 368.Fl s 369option isn't applicable to 370.Nx 371partitions. 372.Pp 373The 374.Fl p 375option changes the default number of partitions the GPT can 376accommodate. 377This is used whenever a new GPT is created. 378By default, the 379.Nm 380utility will create space for 128 partitions (or 32 sectors of 512 bytes). 381.Pp 382The 383.Ic migrate 384command requires space at the beginning and the end of the device outside 385any partitions to store the GPTs. 386Space is required for the GPT header 387.Pq which takes one sector 388and the GPT partition table. 389See the 390.Fl p 391option 392for the size of the GPT partition table. 393By default, just about all devices have a minimum of 62 sectors free at the 394beginning of the device, but don't have any free space at the end. 395For the default GPT partition table size on a 512 byte sector size device, 39633 sectors at the end of the device would need to be freed. 397.\" ==== recover ==== 398.It Nm Ic recover 399The 400.Ic recover 401command tries to restore the GPT partition label from the backup 402near the end of the disk. 403It is very useful in case the primary label was deleted. 404.\" ==== remove ==== 405.It Nm Ic remove Oo Fl a Oc 406.It Nm Ic remove Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 407Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc 408The 409.Ic remove 410command allows the user to remove any and all partitions that match the 411selection. 412It uses the same selection options as the 413.Ic label 414command. 415See above for a description of these options. 416Partitions are removed by clearing the partition type. 417No other information is changed. 418.\" ==== resize ==== 419.It Nm Ic resize Fl i Ar index Oo Fl a Ar alignment Oc \ 420Oo Fl s Ar size Oc 421The 422.Ic resize 423command allows the user to resize a partition. 424The partition may be shrunk and if there is sufficient free space 425immediately after it then it may be expanded. 426The 427.Fl s 428option allows the new size to be specified, otherwise the partition will 429be increased to the maximum available size. 430If there is no suffix, or the suffix is 431.Sq s 432or 433.Sq S 434then size is in sectors, otherwise size is in bytes which must be 435a multiple of the device's sector size. 436The minimum size is 1 sector. 437If the 438.Fl a 439option is specified then the size will be adjusted to be a multiple of 440alignment if possible. 441.\" ==== resizedisk ==== 442.It Nm Ic resizedisk Oo Fl s Ar size Oc 443The 444.Ic resizedisk 445command allows the user to resize a disk. 446With GPTs, a backup copy is stored at the end of the disk. 447If the underlying medium changes size 448.Pq or is going to change size , 449then the backup copy needs to be moved to the new end of the disk, 450and the last sector available for data storage needs to be adjusted. 451This command does that. 452If the backup copy no longer exists due to the medium shrinking, then 453a new backup copy will be created using the primary copy. 454.Pp 455The 456.Fl s 457option allows the new size to be specified, otherwise the backup copy 458will automatically be placed at the current end of the disk. 459If there is no suffix, or the suffix is 460.Sq s 461or 462.Sq S 463then size is in sectors, otherwise size is in bytes which must be 464a multiple of the device's sector size. 465Using the 466.Fl s 467option allows you to move the backup copy prior to resizing the medium. 468This is primarily useful when shrinking the medium. 469.\" ==== restore ==== 470.It Nm Ic restore Oo Fl F Oc Oo Fl i Ar infile Oc 471The 472.Ic restore 473command restores a partition table that was previously saved using the 474.Ic backup 475command. 476The partition table is read from standard input or a file specified in 477the 478.Ar infile 479argument and is expected to be in the format of a plist. 480It assumes an empty disk. 481The 482.Fl F 483option can be used to blank the disk. 484The new disk does not have to be the same size as the old disk as long as all 485the partitions fit, as 486.Ic restore 487will automatically adjust. 488However, the new disk must use the same sector size as the old disk. 489.\" ==== set ==== 490.It Nm Ic set Fl a Ar attribute Fl i Ar index 491.It Nm Ic set Fl l 492The 493.Ic set 494command sets various partition attributes. 495The 496.Fl l 497flag lists all available attributes. 498The 499.Fl a 500option specifies which attributes to set and may be specified more than once, 501or the attributes can be comma-separated. 502The 503.Fl i 504option specifies which entry to update. 505The possible attributes are 506.Do biosboot Dc , 507.Do bootme Dc , 508.Do bootonce Dc , 509.Do bootfailed Dc , 510.Do noblockio Dc , and 511.Do required Dc . 512The biosboot flag is used to indicate which partition should be booted 513by legacy BIOS boot code. 514See the 515.Ic biosboot 516command for more information. 517The other attributes are for compatibility with 518.Fx 519and are not currently used by any 520.Nx 521code. 522They may be used by 523.Nx 524code in the future. 525.\" ==== show ==== 526.It Nm Ic show Oo Fl aglu Oc Oo Fl i Ar index Oc 527The 528.Ic show 529command displays the current partitioning on the listed devices and gives 530an overall view of the disk contents. 531With the 532.Fl g 533option the GPT partition GUID will be displayed instead of the GPT partition 534type. 535With the 536.Fl l 537option the GPT partition label will be displayed instead of the GPT partition 538type. 539With the 540.Fl u 541option the GPT partition type is displayed as an UUID instead of in a 542user friendly form. 543With the 544.Fl i 545option, all the details of a particular GPT partition will be displayed. 546The format of this display is subject to change. 547With the 548.Fl a 549option, all information for all GPT partitions (just like with 550.Fl i Ar index ) 551will be printed. 552None of the options have any effect on non-GPT partitions. 553The order of precedence for the options are: 554.Fl a , 555.Fl i , 556.Fl l , 557.Fl g , 558.Fl u . 559.\" ==== type ==== 560.It Nm Ic type Oo Fl a Oc Fl T Ar newtype 561.It Nm Ic type Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 562.It Nm Ic type Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 563Oo Fl L Ar label Oc Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc \ 564Fl T Ar newtype 565.It Nm Ic type Fl l 566The 567.Ic type 568command allows the user to change the type of any and all partitions 569that match the selection. 570It uses the same selection options as the 571.Ic label 572command. 573See above for a description of these options. 574The 575.Fl l 576flag lists available types. 577.\" ==== unset ==== 578.It Nm Ic unset Fl a Ar attribute Fl i Ar index 579.It Nm Ic unset Fl l 580The 581.Ic unset 582command unsets various partition attributes. 583The 584.Fl l 585flag lists all available attributes. 586The 587.Fl a 588option specifies which attributes to unset and may be specified more than once. 589The 590.Fl i 591option specifies which entry to update. 592The possible attributes are 593.Do biosboot Dc , 594.Do bootme Dc , 595.Do bootonce Dc , 596.Do bootfailed Dc , 597.Do noblockio Dc , and 598.Do required Dc . 599The biosboot flag is used to indicate which partition should be booted 600by legacy BIOS boot code. 601See the 602.Ic biosboot 603command for more information. 604The other attributes are for compatibility with 605.Fx 606and are not currently used by any 607.Nx 608code. 609They may be used by 610.Nx 611code in the future. 612.El 613.Sh EXAMPLES 614.Bd -literal 615nas# gpt show wd3 616 start size index contents 617 0 1 PMBR 618 1 3907029167 619nas# gpt create wd3 620nas# gpt show wd3 621 start size index contents 622 0 1 PMBR 623 1 1 Pri GPT header 624 2 32 Pri GPT table 625 34 3907029101 626 3907029135 32 Sec GPT table 627 3907029167 1 Sec GPT header 628nas# gpt add -s 10486224 -t swap -i 1 wd3 629nas# gpt label -i 1 -l swap_1 wd3 630parition 1 on rwd3d labeled swap_1 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 10486224 1 GPT part - NetBSD swap 637 10486258 3896542877 638 3907029135 32 Sec GPT table 639 3907029167 1 Sec GPT header 640nas# gpt show -l wd3 641 start size index contents 642 0 1 PMBR 643 1 1 Pri GPT header 644 2 32 Pri GPT table 645 34 10486224 1 GPT part - "swap_1" 646 10486258 3896542877 647 3907029135 32 Sec GPT table 648 3907029167 1 Sec GPT header 649nas# 650.Ed 651.Sh SEE ALSO 652.Xr boot 8 , 653.Xr dkctl 8 , 654.Xr fdisk 8 , 655.Xr installboot 8 , 656.Xr mount 8 , 657.Xr newfs 8 , 658.Xr swapon 8 659.Sh HISTORY 660The 661.Nm 662utility appeared in 663.Fx 5.0 664for ia64. 665.Sh BUGS 666The development of the 667.Nm 668utility is still work in progress. 669Many necessary features are missing or partially implemented. 670In practice this means that the manual page, supposed to describe these 671features, is farther removed from being complete or useful. 672As such, missing functionality is not even documented as missing. 673However, it is believed that the currently present functionality is reliable 674and stable enough that this tool can be used without bullet-proof footware if 675one thinks one does not make mistakes. 676.Pp 677It is expected that the basic usage model does not change, but it is 678possible that future versions will not be compatible in the strictest sense 679of the word. 680Also, options primarily intended for diagnostic or debug purposes may be 681removed in future versions. 682.Pp 683Another possibility is that the current usage model is accompanied by 684other interfaces to make the tool usable as a back-end. 685This all depends on demand and thus feedback. 686