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.\" $DragonFly: src/sbin/gpt/gpt.8,v 1.14 2008/10/03 21:26:28 thomas Exp $ 27.\" 28.Dd September 28, 2009 29.Os 30.Dt GPT 8 31.Sh NAME 32.Nm gpt 33.Nd "GUID partition table maintenance utility" 34.Sh SYNOPSIS 35.Nm 36.Op Ar general_options 37.Ar command 38.Op Ar command_options 39.Ar device ... 40.Sh DESCRIPTION 41The 42.Nm 43utility provides the necessary functionality to manipulate GUID partition 44tables (GPTs), but see 45.Sx BUGS 46below for how and where functionality is missing. 47GPT partitions are accessed as 48.Dx 49disk slices, with same number as GPT partition, 50127 slices per disk device are supported. 51The basic usage model of the 52.Nm 53tool follows that of the 54.Xr cvs 1 55tool. 56The general options are described in the following paragraph. 57The remaining paragraphs describe the individual commands with their options. 58Here we conclude by mentioning that a 59.Ar device 60is either a special file 61corresponding to a disk-like device or a regular file. 62The command is applied to each 63.Ar device 64listed on the command line. 65.Ss General Options 66The general options allow the user to change default settings or otherwise 67change the behaviour that is applicable to all commands. 68Not all commands use all default settings, so some general options may not 69have an effect on all commands. 70.Pp 71The 72.Fl p Ar count 73option allows the user to change the number of partitions the GPT can 74accommodate. 75This is used whenever a new GPT is created. 76By default, the 77.Nm 78utility will create space for 128 partitions (or 32 sectors of 512 bytes). 79.Pp 80The 81.Fl r 82option causes the 83.Nm 84utility to open the device for reading only. 85Currently this option is primarily useful for the 86.Ic show 87command, but the intent 88is to use it to implement dry-run behaviour. 89.Pp 90The 91.Fl v 92option controls the verbosity level. 93The level increases with every occurrence of this option. 94There is no formalized definition of the different levels yet. 95.Ss Commands 96.Bl -tag -width indent 97.\" ==== add ==== 98.It Xo 99.Nm 100.Ic add 101.Op Fl b Ar number 102.Op Fl i Ar index 103.Op Fl s Ar count 104.Op Fl t Ar type 105.Ar device ... 106.Xc 107The 108.Ic add 109command allows the user to add a new partition to an existing table, 110the name of the disk slice for the added partition is printed. 111By default, it will create a 112.Cm dfly 113partition covering the first available block 114of an unused disk space. 115The command-specific options can be used to control this behaviour. 116.Pp 117The 118.Fl b Ar number 119option allows the user to specify the starting (beginning) sector number of 120the partition. 121The minimum sector number is 1, but has to fall inside an unused region of 122disk space that is covered by the GPT. 123.Pp 124The 125.Fl i Ar index 126option allows the user to specify which (free) entry in the GPT table is to 127be used for the new partition. 128By default, the first free entry is selected. 129Entries start at index 0 representing partition 0 of the GPT. 130.Pp 131The 132.Fl s Ar count 133option allows the user to specify the size of the partition in sectors. 134The minimum size is 1. 135.Pp 136The 137.Fl t Ar type 138option allows the user to specify the partition type. 139The type is given as an UUID, but 140.Nm 141accepts 142.Cm efi , swap , ufs , hfs , linux , dfly , 143and 144.Cm windows 145as aliases for the most commonly used partition types. 146.Cm ufs 147is a 148.Fx 149UFS UUID. 150.Cm dfly 151has the alias 152.Cm dragonfly 153and is a 154.Dx 155.Xr disklabel64 5 156UUID. 157You may also specify any symbolic name in the system 158.Xr uuids 5 159files. 160.\" ==== boot ==== 161.It Nm Ic boot Ar device ... 162The 163.Ic boot 164command allows the user to create a small boot partition in a freshly 165created GPT. 166.Pp 167This command creates a small, 256MB boot partition as partition #0 168and hacks in a special 169.Sq slice 1 170in the PMBR which aliases it. 171The PMBR is further modified to add the necessary boot code. 172You can then disklabel GPT partition #0 and mount it, placing the contents of 173.Pa /boot 174directory within. 175You must add a line to 176.Pa loader.conf , 177like 178.Bd -literal -offset indent 179vfs.root.mountfrom="ufs:da1s1a" 180.Ed 181.Pp 182which point to the actual root mount. 183.Pp 184Your root partition may be another GPT partition and you may use a 64 bit 185disklabel within that partition if you desire. 186.Pp 187The 188.Sq boot0 189boot manager is used, it can be manipulated with the 190.Xr boot0cfg 8 191command, 192.Sq packet 193option usually needs to be set. 194.Pp 195.Em NOTE! 196A disk setup with the 197.Ar boot 198command may not be shared with another OS, 199as it doesn't use a fully standard GPT. 200.Pp 201.Em WARNING! 202Some BIOSes may not be able to deal with this hack, your mileage may vary. 203.\" ==== create ==== 204.It Nm Ic create Oo Fl fp Oc Ar device ... 205The 206.Ic create 207command allows the user to create a new (empty) GPT. 208By default, one cannot create a GPT when the device contains a MBR, 209however this can be overridden with the 210.Fl f 211option. 212If the 213.Fl f 214option is specified, an existing MBR is destroyed and any partitions 215described by the MBR are lost. 216.Pp 217The 218.Fl p 219option tells 220.Nm 221to create only the primary table and not the backup table. 222This option is only useful for debugging and should not be used otherwise. 223.\" ==== destroy ==== 224.It Nm Ic destroy Oo Fl r Oc Ar device ... 225The 226.Ic destroy 227command allows the user to destroy an existing, possibly not empty GPT. 228.Pp 229The 230.Fl r 231option instructs 232.Nm 233to destroy the table in a way that it can be recovered. 234.\" ==== label ==== 235.It Xo 236.Nm 237.Ic label 238.Op Fl a 239.Aq Fl f Ar file | Fl l Ar label 240.Ar device ... 241.Xc 242.It Xo 243.Nm 244.Ic label 245.Op Fl b Ar number 246.Op Fl i Ar index 247.Op Fl s Ar count 248.Op Fl t Ar type 249.Aq Fl f Ar file | Fl l Ar label 250.Ar device ... 251.Xc 252The 253.Ic label 254command allows the user to label any partitions that match the selection. 255At least one of the following selection options must be specified. 256.Pp 257The 258.Fl a 259option specifies that all partitions should be labeled. 260It is mutually exclusive with all other selection options. 261.Pp 262The 263.Fl b Ar number 264option selects the partition that starts at the given block number. 265.Pp 266The 267.Fl i Ar index 268option selects the partition with the given partition number. 269Partition numbers start at 0. 270.Pp 271The 272.Fl s Ar count 273option selects all partitions that have the given size. 274This can cause multiple partitions to be removed. 275.Pp 276The 277.Fl t Ar type 278option selects all partitions that have the given type. 279The type is given as an UUID or by the aliases that the 280.Ic add 281command accepts. 282This can cause multiple partitions to be removed. 283.Pp 284The 285.Fl f Ar file 286or 287.Fl l Ar label 288options specify the new label to be assigned to the selected partitions. 289The 290.Fl f Ar file 291option is used to read the label from the specified file. 292Only the first line is read from the file and the trailing newline 293character is stripped. 294If the file name is the dash or minus sign 295.Pq Fl , 296the label is read from 297the standard input. 298The 299.Fl l Ar label 300option is used to specify the label in the command line. 301The label is assumed to be encoded in UTF-8. 302.\" ==== migrate ==== 303.It Nm Ic migrate Oo Fl fs Oc Ar device ... 304The 305.Ic migrate 306command allows the user to migrate an MBR-based disk partitioning into a 307GPT-based partitioning. 308By default, the MBR is not migrated when it contains partitions of an unknown 309type. 310This can be overridden with the 311.Fl f 312option. 313Specifying the 314.Fl f 315option will cause unknown partitions to be ignored and any data in it 316to be lost. 317.Pp 318The 319.Fl s 320option prevents migrating 321.Bx 322disk labels into GPT partitions by creating 323the GPT equivalent of a slice. 324.\" ==== remove ==== 325.It Nm Ic remove Oo Fl a Oc Ar device ... 326.It Xo 327.Nm 328.Ic remove 329.Op Fl b Ar number 330.Op Fl i Ar index 331.Op Fl s Ar count 332.Op Fl t Ar type 333.Ar device ... 334.Xc 335The 336.Ic remove 337command allows the user to remove any and all partitions that match the 338selection. 339It uses the same selection options as the 340.Ic label 341command. 342See above for a description of these options. 343Partitions are removed by clearing the partition type. 344No other information is changed. 345.\" ==== show ==== 346.It Nm Ic show Oo Fl lu Oc Ar device ... 347The 348.Ic show 349command displays the current partitioning on the listed devices and gives 350an overall view of the disk contents. 351With the 352.Fl l 353option the GPT partition label will be displayed instead of the GPT partition 354type. 355The option has no effect on non-GPT partitions. 356With the 357.Fl u 358option the GPT partition type is displayed as an UUID instead of in a 359user friendly form. 360The 361.Fl l 362option takes precedence over the 363.Fl u 364option. 365.El 366.Sh FILES 367.Bl -tag -width ".Pa /etc/defaults/uuids" 368.It Pa /boot/boot0 369The default 370.Sq boot0 371image. 372.It Pa /etc/defaults/uuids 373A list of UUIDs 374and their symbolic names provided by the OS vendor. 375.It Pa /etc/uuids 376A list of UUIDs 377and their symbolic names provided by the system administrator. 378.El 379.Sh EXAMPLES 380To install an empty GPT on 381.Pa ad6 : 382.Pp 383.Dl "gpt create ad6" 384.Pp 385GPT partitions are defined in number of sectors, the sector size is usually 512B, 386which is assumed in the examples below, it can be found using: 387.Pp 388.Dl "gpt -v show ad6" 389.Pp 390To add a dummy GPT partition 0: 391.Pp 392.Dl "gpt add -i0 -s16 ad6" 393.Pp 394You might want to do this to not use slice 0 for data; 395when GPT is not used on a disk, slice 0 is the compatibility slice, 396which is used for 397.Dq dangerously dedicated 398disks. 399For GPT slice 0 has no special meaning, it is just the first slice on the disk. 400.Pp 401To add a GPT partition of size approx. 100GB: 402.Pp 403.Dl "gpt add -s200000000 ad6" 404.Pp 405This will be GPT partition 1 as it is the first one free, 406it will be accessible as 407.Pa ad6s1 , 408which is also printed by the command. 409The type will be 410.Dq DragonFly Label64 , 411it will have to be set up by 412.Xr disklabel64 8 . 413.Pp 414To add GPT partition 5 with type 415.Dq DragonFly HAMMER 416using the remaining free space: 417.Bd -literal -offset indent 418gpt add -i5 -t "DragonFly HAMMER" ad6 419.Ed 420.Pp 421To print the contents of the GPT: 422.Pp 423.Dl "gpt show ad6" 424.Ss Boot Setup 425To setup a disk using GPT for booting, the steps below can be used. 426System is copied from an already installed disk, 427e.g.\& a hard disk or an install CD. 428This example will setup disk 429.Pa da1 430with GPT for booting, using the 431.Ic boot 432command. 433.Pp 434.Em WARNING! 435Any previous data on disk installed to will be deleted. 436.Bd -literal -offset indent 437gpt create -f da1 438gpt boot da1 439boot0cfg -s 2 da1 440disklabel -B -r -w da1s0 auto 441disklabel -e da1s0 # add `a: * * 4.2BSD', to add `a' partition 442 # with fstype `4.2BSD' covering whole slice 443 444gpt add da1 445disklabel64 -r -w da1s1 auto 446disklabel64 -e da1s1 # add `b: 4G * swap', to add `b' partition 447 # with fstype `swap' and size 4GB, 448 # add `a: * * HAMMER', to add `a' partition 449 # with fstype `HAMMER' covering rest of slice 450newfs_hammer -L ROOT /dev/da1s1a 451mount_hammer /dev/da1s1a /mnt 452 453newfs /dev/da1s0a 454mkdir /mnt/boot 455mount /dev/da1s0a /mnt/boot 456 457cpdup / /mnt # copy each file system you need, e.g. 458cpdup /boot /mnt/boot 459cpdup /var /mnt/var 460cpdup /var/tmp /mnt/var/tmp 461cpdup /usr /mnt/usr 462 463cd /mnt 464vi etc/fstab # add `/dev/da1s1a / hammer rw', 465 # add `/dev/da1s1b none swap sw', 466 # add `/dev/da1s0a /boot ufs rw 1 1', 467 # delete lines for file systems cpdup'ed above 468vi boot/loader.conf # add `vfs.root.mountfrom="hammer:da1s1a"' 469cd 470umount /mnt/boot 471umount /mnt 472.Ed 473.Sh COMPATIBILITY 474The GPT that 475.Nm 476manipulates is part of the EFI standard and is supported by many OSs. 477GPT uses 64 bits to store number of sectors, this supports very large disks. 478With the prevalent sector size of 512B this is 8 billion TB. 479.Sh SEE ALSO 480.Xr uuid 3 , 481.Xr disklabel64 5 , 482.Xr uuids 5 , 483.Xr boot0cfg 8 , 484.Xr disklabel 8 , 485.Xr disklabel64 8 , 486.Xr fdisk 8 , 487.Xr mount 8 , 488.Xr newfs 8 , 489.Xr newfs_hammer 8 , 490.Xr swapon 8 491.Sh HISTORY 492The 493.Nm 494utility appeared in 495.Fx 5.0 496for ia64. 497It was imported to 498.Dx 1.9 . 499.Sh BUGS 500The development of the 501.Nm 502utility is still work in progress. 503Many necessary features are missing or partially implemented. 504In practice this means that the manual page, supposed to describe these 505features, is farther removed from being complete or useful. 506As such, missing functionality is not even documented as missing. 507However, it is believed that the currently present functionality is reliable 508and stable enough that this tool can be used without bullet-proof footware if 509one thinks one does not make mistakes. 510.Pp 511It is expected that the basic usage model does not change, but it is 512possible that future versions will not be compatible in the strictest sense 513of the word. 514For example, the 515.Fl p Ar count 516option may be changed to a command option rather than a generic option. 517There are only two commands that use it so there is a chance that the natural 518tendency for people is to use it as a command option. 519Also, options primarily intended for diagnostic or debug purposes may be 520removed in future versions. 521.Pp 522Another possibility is that the current usage model is accompanied by 523other interfaces to make the tool usable as a back-end. 524This all depends on demand and thus feedback. 525.Pp 526The 527.Ic migrate 528command doesn't support 529.Dx 530partition types. 531