1 .\" Copyright (c) 2002 Marcel Moolenaar
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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.
25 .\" $FreeBSD: src/sbin/gpt/gpt.8,v 1.17 2006/06/22 22:22:32 marcel Exp $
27 .Dd September 28, 2009
32 .Nd "GUID partition table maintenance utility"
35 .Op Ar general_options
37 .Op Ar command_options
42 utility provides the necessary functionality to manipulate GUID partition
43 tables (GPTs), but see
45 below for how and where functionality is missing.
46 GPT partitions are accessed as
48 disk slices, with same number as GPT partition,
49 127 slices per disk device are supported.
50 The basic usage model of the
52 tool follows that of the
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
59 is either a special file
60 corresponding to a disk-like device or a regular file.
61 The command is applied to each
63 listed on the command line.
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.
72 option allows the user to change the number of partitions the GPT can
74 This is used whenever a new GPT is created.
77 utility will create space for 128 partitions (or 32 sectors of 512 bytes).
83 utility to open the device for reading only.
84 Currently this option is primarily useful for the
86 command, but the intent
87 is to use it to implement dry-run behaviour.
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.
95 .Bl -tag -width indent
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
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.
118 option allows the user to specify the starting (beginning) sector number of
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.
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.
132 option allows the user to specify the size of the partition in sectors.
133 The minimum size is 1.
137 option allows the user to specify the partition type.
138 The type is given as an UUID, but
141 .Cm efi , swap , ufs , hfs , linux , dfly , hammer, hammer2
144 as aliases for the most commonly used partition types.
156 You may also specify any symbolic name in the system
161 If you don't specify a beginning sector with
163 , the new partition will be aligned to 1MiB in size and position
164 (in case of 512 byte sector sizes).
166 .It Nm Ic boot Ar device ...
169 command allows the user to create a small boot partition in a freshly
172 This command creates a small, 1GB boot partition as partition #0
173 and hacks in a special
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
180 You must add a line to
183 .Bd -literal -offset indent
184 vfs.root.mountfrom="ufs:da1s1a"
187 which point to the actual root mount.
189 Your root partition may be another GPT partition and you may use a 64 bit
190 disklabel within that partition if you desire.
194 boot manager is used, it can be manipulated with the
198 option usually needs to be set.
201 A disk setup with the
203 command may not be shared with another OS,
204 as it doesn't use a fully standard GPT.
207 Some BIOSes may not be able to deal with this hack, your mileage may vary.
209 .It Nm Ic create Oo Fl fp Oc Ar device ...
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
219 option is specified, an existing MBR is destroyed and any partitions
220 described by the MBR are lost.
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 ...
232 command allows the user to destroy an existing, possibly not empty GPT.
238 to destroy the table in a way that it can be recovered.
240 .It Nm Ic init Fl f Oo Fl B Oc Oo Fl E Oc Ar device ...
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
248 The boot slice will be dos-formatted.
249 The disklabel will be left empty and ready to edit.
251 Due to the destructive nature of this directive, the
253 option must also be specified.
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.
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
272 .Aq Fl f Ar file | Fl l Ar label
282 .Aq Fl f Ar file | Fl l Ar 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.
292 option specifies that all partitions should be labeled.
293 It is mutually exclusive with all other selection options.
297 option selects the partition that starts at the given block number.
301 option selects the partition with the given partition number.
302 Partition numbers start at 0.
306 option selects all partitions that have the given size.
307 This can cause multiple partitions to be removed.
311 option selects all partitions that have the given type.
312 The type is given as an UUID or by the aliases that the
315 This can cause multiple partitions to be removed.
321 options specify the new label to be assigned to the selected partitions.
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
329 the label is read from
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 ...
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
343 This can be overridden with the
348 option will cause unknown partitions to be ignored and any data in it
353 option prevents migrating
355 disk labels into GPT partitions by creating
356 the GPT equivalent of a slice.
358 .It Nm Ic remove Oo Fl a Oc Ar device ...
370 command allows the user to remove any and all partitions that match the
372 It uses the same selection options as the
375 See above for a description of these options.
376 Partitions are removed by clearing the partition type.
377 No other information is changed.
379 .It Nm Ic show Oo Fl lu Oc Ar device ...
382 command displays the current partitioning on the listed devices and gives
383 an overall view of the disk contents.
386 option the GPT partition label will be displayed instead of the GPT partition
388 The option has no effect on non-GPT partitions.
391 option the GPT partition type is displayed as an UUID instead of in a
395 option takes precedence over the
400 .Bl -tag -width ".Pa /etc/defaults/uuids"
405 .It Pa /etc/defaults/uuids
407 and their symbolic names provided by the OS vendor.
410 and their symbolic names provided by the system administrator.
413 To install an empty GPT on
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:
421 .Dl "gpt -v show ad6"
423 To add a dummy GPT partition 0:
425 .Dl "gpt add -i0 -s16 ad6"
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,
430 .Dq dangerously dedicated
432 For GPT slice 0 has no special meaning, it is just the first slice on the disk.
434 To add a GPT partition of size approx. 100GB:
436 .Dl "gpt add -s200000000 ad6"
438 This will be GPT partition 1 as it is the first one free,
439 it will be accessible as
441 which is also printed by the command.
443 .Dq DragonFly Label64 ,
444 it will have to be set up by
447 To add GPT partition 5 with type
449 using the remaining free space:
450 .Bd -literal -offset indent
451 gpt add -i5 -t "DragonFly HAMMER" ad6
454 To print the contents of the GPT:
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
463 with GPT for booting, using the
468 Any previous data on disk installed to will be deleted.
469 .Bd -literal -offset indent
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
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
488 mount /dev/da1s0a /mnt/boot
490 cpdup / /mnt # copy each file system you need, e.g.
491 cpdup /boot /mnt/boot
493 cpdup /var/tmp /mnt/var/tmp
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"'
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.
533 The development of the
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.
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
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.
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.
561 command doesn't support
projects / dragonfly.git / blob