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