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