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 September 28, 2009 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 , 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.\" ==== boot ==== 160.It Nm Ic boot Ar device ... 161The 162.Ic boot 163command allows the user to create a small boot partition in a freshly 164created GPT. 165.Pp 166This command creates a small, 1GB boot partition as partition #0 167and hacks in a special 168.Sq slice 1 169in the PMBR which aliases it. 170The PMBR is further modified to add the necessary boot code. 171You can then disklabel GPT partition #0 and mount it, placing the contents of 172.Pa /boot 173directory within. 174You must add a line to 175.Pa loader.conf , 176like 177.Bd -literal -offset indent 178vfs.root.mountfrom="ufs:da1s1a" 179.Ed 180.Pp 181which point to the actual root mount. 182.Pp 183Your root partition may be another GPT partition and you may use a 64 bit 184disklabel within that partition if you desire. 185.Pp 186The 187.Sq boot0 188boot manager is used, it can be manipulated with the 189.Xr boot0cfg 8 190command, 191.Sq packet 192option usually needs to be set. 193.Pp 194.Em NOTE! 195A disk setup with the 196.Ar boot 197command may not be shared with another OS, 198as it doesn't use a fully standard GPT. 199.Pp 200.Em WARNING! 201Some BIOSes may not be able to deal with this hack, your mileage may vary. 202.\" ==== create ==== 203.It Nm Ic create Oo Fl fp Oc Ar device ... 204The 205.Ic create 206command allows the user to create a new (empty) GPT. 207By default, one cannot create a GPT when the device contains a MBR, 208however this can be overridden with the 209.Fl f 210option. 211If the 212.Fl f 213option is specified, an existing MBR is destroyed and any partitions 214described by the MBR are lost. 215.Pp 216The 217.Fl p 218option tells 219.Nm 220to create only the primary table and not the backup table. 221This option is only useful for debugging and should not be used otherwise. 222.\" ==== destroy ==== 223.It Nm Ic destroy Oo Fl r Oc Ar device ... 224The 225.Ic destroy 226command allows the user to destroy an existing, possibly not empty GPT. 227.Pp 228The 229.Fl r 230option instructs 231.Nm 232to destroy the table in a way that it can be recovered. 233.\" ==== label ==== 234.It Xo 235.Nm 236.Ic label 237.Op Fl a 238.Aq Fl f Ar file | Fl l Ar label 239.Ar device ... 240.Xc 241.It Xo 242.Nm 243.Ic label 244.Op Fl b Ar number 245.Op Fl i Ar index 246.Op Fl s Ar count 247.Op Fl t Ar type 248.Aq Fl f Ar file | Fl l Ar label 249.Ar device ... 250.Xc 251The 252.Ic label 253command allows the user to label any partitions that match the selection. 254At least one of the following selection options must be specified. 255.Pp 256The 257.Fl a 258option specifies that all partitions should be labeled. 259It is mutually exclusive with all other selection options. 260.Pp 261The 262.Fl b Ar number 263option selects the partition that starts at the given block number. 264.Pp 265The 266.Fl i Ar index 267option selects the partition with the given partition number. 268Partition numbers start at 0. 269.Pp 270The 271.Fl s Ar count 272option selects all partitions that have the given size. 273This can cause multiple partitions to be removed. 274.Pp 275The 276.Fl t Ar type 277option selects all partitions that have the given type. 278The type is given as an UUID or by the aliases that the 279.Ic add 280command accepts. 281This can cause multiple partitions to be removed. 282.Pp 283The 284.Fl f Ar file 285or 286.Fl l Ar label 287options specify the new label to be assigned to the selected partitions. 288The 289.Fl f Ar file 290option is used to read the label from the specified file. 291Only the first line is read from the file and the trailing newline 292character is stripped. 293If the file name is the dash or minus sign 294.Pq Fl , 295the label is read from 296the standard input. 297The 298.Fl l Ar label 299option is used to specify the label in the command line. 300The label is assumed to be encoded in UTF-8. 301.\" ==== migrate ==== 302.It Nm Ic migrate Oo Fl fs Oc Ar device ... 303The 304.Ic migrate 305command allows the user to migrate an MBR-based disk partitioning into a 306GPT-based partitioning. 307By default, the MBR is not migrated when it contains partitions of an unknown 308type. 309This can be overridden with the 310.Fl f 311option. 312Specifying the 313.Fl f 314option will cause unknown partitions to be ignored and any data in it 315to be lost. 316.Pp 317The 318.Fl s 319option prevents migrating 320.Bx 321disk labels into GPT partitions by creating 322the GPT equivalent of a slice. 323.\" ==== remove ==== 324.It Nm Ic remove Oo Fl a Oc Ar device ... 325.It Xo 326.Nm 327.Ic remove 328.Op Fl b Ar number 329.Op Fl i Ar index 330.Op Fl s Ar count 331.Op Fl t Ar type 332.Ar device ... 333.Xc 334The 335.Ic remove 336command allows the user to remove any and all partitions that match the 337selection. 338It uses the same selection options as the 339.Ic label 340command. 341See above for a description of these options. 342Partitions are removed by clearing the partition type. 343No other information is changed. 344.\" ==== show ==== 345.It Nm Ic show Oo Fl lu Oc Ar device ... 346The 347.Ic show 348command displays the current partitioning on the listed devices and gives 349an overall view of the disk contents. 350With the 351.Fl l 352option the GPT partition label will be displayed instead of the GPT partition 353type. 354The option has no effect on non-GPT partitions. 355With the 356.Fl u 357option the GPT partition type is displayed as an UUID instead of in a 358user friendly form. 359The 360.Fl l 361option takes precedence over the 362.Fl u 363option. 364.El 365.Sh FILES 366.Bl -tag -width ".Pa /etc/defaults/uuids" 367.It Pa /boot/boot0 368The default 369.Sq boot0 370image. 371.It Pa /etc/defaults/uuids 372A list of UUIDs 373and their symbolic names provided by the OS vendor. 374.It Pa /etc/uuids 375A list of UUIDs 376and their symbolic names provided by the system administrator. 377.El 378.Sh EXAMPLES 379To install an empty GPT on 380.Pa ad6 : 381.Pp 382.Dl "gpt create ad6" 383.Pp 384GPT partitions are defined in number of sectors, the sector size is usually 512B, 385which is assumed in the examples below, it can be found using: 386.Pp 387.Dl "gpt -v show ad6" 388.Pp 389To add a dummy GPT partition 0: 390.Pp 391.Dl "gpt add -i0 -s16 ad6" 392.Pp 393You might want to do this to not use slice 0 for data; 394when GPT is not used on a disk, slice 0 is the compatibility slice, 395which is used for 396.Dq dangerously dedicated 397disks. 398For GPT slice 0 has no special meaning, it is just the first slice on the disk. 399.Pp 400To add a GPT partition of size approx. 100GB: 401.Pp 402.Dl "gpt add -s200000000 ad6" 403.Pp 404This will be GPT partition 1 as it is the first one free, 405it will be accessible as 406.Pa ad6s1 , 407which is also printed by the command. 408The type will be 409.Dq DragonFly Label64 , 410it will have to be set up by 411.Xr disklabel64 8 . 412.Pp 413To add GPT partition 5 with type 414.Dq DragonFly HAMMER 415using the remaining free space: 416.Bd -literal -offset indent 417gpt add -i5 -t "DragonFly HAMMER" ad6 418.Ed 419.Pp 420To print the contents of the GPT: 421.Pp 422.Dl "gpt show ad6" 423.Ss Boot Setup 424To setup a disk using GPT for booting, the steps below can be used. 425System is copied from an already installed disk, 426e.g.\& a hard disk or an install CD. 427This example will setup disk 428.Pa da1 429with GPT for booting, using the 430.Ic boot 431command. 432.Pp 433.Em WARNING! 434Any previous data on disk installed to will be deleted. 435.Bd -literal -offset indent 436gpt create -f da1 437gpt boot da1 438boot0cfg -s 2 da1 439disklabel -B -r -w da1s0 auto 440disklabel -e da1s0 # add `a: * * 4.2BSD', to add `a' partition 441 # with fstype `4.2BSD' covering whole slice 442 443gpt add da1 444disklabel64 -r -w da1s1 auto 445disklabel64 -e da1s1 # add `b: 4G * swap', to add `b' partition 446 # with fstype `swap' and size 4GB, 447 # add `a: * * HAMMER', to add `a' partition 448 # with fstype `HAMMER' covering rest of slice 449newfs_hammer -L ROOT /dev/da1s1a 450mount_hammer /dev/da1s1a /mnt 451 452newfs /dev/da1s0a 453mkdir /mnt/boot 454mount /dev/da1s0a /mnt/boot 455 456cpdup / /mnt # copy each file system you need, e.g. 457cpdup /boot /mnt/boot 458cpdup /var /mnt/var 459cpdup /var/tmp /mnt/var/tmp 460cpdup /usr /mnt/usr 461 462cd /mnt 463vi etc/fstab # add `/dev/da1s1a / hammer rw', 464 # add `/dev/da1s1b none swap sw', 465 # add `/dev/da1s0a /boot ufs rw 1 1', 466 # delete lines for file systems cpdup'ed above 467vi boot/loader.conf # add `vfs.root.mountfrom="hammer:da1s1a"' 468cd 469umount /mnt/boot 470umount /mnt 471.Ed 472.Sh COMPATIBILITY 473The GPT that 474.Nm 475manipulates is part of the EFI standard and is supported by many OSs. 476GPT uses 64 bits to store number of sectors, this supports very large disks. 477With the prevalent sector size of 512B this is 8 billion TB. 478.Sh SEE ALSO 479.Xr uuid 3 , 480.Xr disklabel64 5 , 481.Xr uuids 5 , 482.Xr boot0cfg 8 , 483.Xr disklabel 8 , 484.Xr disklabel64 8 , 485.Xr fdisk 8 , 486.Xr mount 8 , 487.Xr newfs 8 , 488.Xr newfs_hammer 8 , 489.Xr swapon 8 490.Sh HISTORY 491The 492.Nm 493utility appeared in 494.Fx 5.0 495for ia64. 496It was imported to 497.Dx 1.9 . 498.Sh BUGS 499The development of the 500.Nm 501utility is still work in progress. 502Many necessary features are missing or partially implemented. 503In practice this means that the manual page, supposed to describe these 504features, is farther removed from being complete or useful. 505As such, missing functionality is not even documented as missing. 506However, it is believed that the currently present functionality is reliable 507and stable enough that this tool can be used without bullet-proof footware if 508one thinks one does not make mistakes. 509.Pp 510It is expected that the basic usage model does not change, but it is 511possible that future versions will not be compatible in the strictest sense 512of the word. 513For example, the 514.Fl p Ar count 515option may be changed to a command option rather than a generic option. 516There are only two commands that use it so there is a chance that the natural 517tendency for people is to use it as a command option. 518Also, options primarily intended for diagnostic or debug purposes may be 519removed in future versions. 520.Pp 521Another possibility is that the current usage model is accompanied by 522other interfaces to make the tool usable as a back-end. 523This all depends on demand and thus feedback. 524.Pp 525The 526.Ic migrate 527command doesn't support 528.Dx 529partition types. 530