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 $
26 .\" $DragonFly: src/sbin/gpt/gpt.8,v 1.9 2008/08/28 21:12:44 thomas Exp $
33 .Nd "GUID partition table maintenance utility"
36 .Op Ar general_options
38 .Op Ar command_options
43 utility provides the necessary functionality to manipulate GUID partition
44 tables (GPTs), but see
46 below for how and where functionality is missing.
47 GPT partitions are accessed as
49 disk slices, with same number as GPT partition,
50 32 slices per disk device are supported.
51 The basic usage model of the
53 tool follows that of the
56 The general options are described in the following paragraph.
57 The remaining paragraphs describe the individual commands with their options.
58 Here we conclude by mentioning that a
60 is either a special file
61 corresponding to a disk-like device or a regular file.
62 The command is applied to each
64 listed on the command line.
66 The general options allow the user to change default settings or otherwise
67 change the behaviour that is applicable to all commands.
68 Not all commands use all default settings, so some general options may not
69 have an effect on all commands.
73 option allows the user to change the number of partitions the GPT can
75 This is used whenever a new GPT is created.
78 utility will create space for 128 partitions (or 32 sectors of 512 bytes).
84 utility to open the device for reading only.
85 Currently this option is primarily useful for the
87 command, but the intent
88 is to use it to implement dry-run behaviour.
92 option controls the verbosity level.
93 The level increases with every occurrence of this option.
94 There is no formalized definition of the different levels yet.
96 .Bl -tag -width indent
109 command allows the user to add a new partition to an existing table,
110 the name of the disk slice for the added partition is printed.
111 By default, it will create a
113 partition covering the first available block
114 of an unused disk space.
115 The command-specific options can be used to control this behaviour.
119 option allows the user to specify the starting (beginning) sector number of
121 The minimum sector number is 1, but has to fall inside an unused region of
122 disk space that is covered by the GPT.
126 option allows the user to specify which (free) entry in the GPT table is to
127 be used for the new partition.
128 By default, the first free entry is selected.
129 Entries start at index 0 representing partition 0 of the GPT.
133 option allows the user to specify the size of the partition in sectors.
134 The minimum size is 1.
138 option allows the user to specify the partition type.
139 The type is given as an UUID, but
142 .Cm efi , swap , ufs , hfs , linux , dfly ,
145 as aliases for the most commonly used partition types.
157 You may also specify any symbolic name in the system
161 .It Nm Ic boot Ar device ...
164 command allows the user to create a small boot partition in a freshly
167 This command creates a small, 256MB boot partition as partition #0
168 and hacks in a special
170 in the PMBR which aliases it.
171 The PMBR is further modified to add the necessary boot code.
172 You can then disklabel GPT partition #0 and mount it, placing the boot
173 directory and kernel within.
174 The boot directory must be a sub-directory, e.g.\&
179 .Dq vfs.root.mountfrom="filesystem:device"
181 .Pa /mnt/boot/loader.conf
182 to point to the actual root mount.
186 Your root partition may be another GPT partition and you may use a 64 bit
187 disklabel within that partition if you desire.
188 Note that the boot partition must use a 32 bit disklabel.
192 boot manager is used, it can be manipulated with the
196 option usually needs to be set.
199 A disk setup with the
201 command can't be shared with another OS as it doesn't use a fully standard GPT.
204 Some BIOSes may not be able to deal with this hack, your mileage may vary.
206 .It Nm Ic create Oo Fl fp Oc Ar device ...
209 command allows the user to create a new (empty) GPT.
210 By default, one cannot create a GPT when the device contains a MBR,
211 however this can be overridden with the
216 option is specified, an existing MBR is destroyed and any partitions
217 described by the MBR are lost.
223 to create only the primary table and not the backup table.
224 This 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 ...
229 command allows the user to destroy an existing, possibly not empty GPT.
235 to destroy the table in a way that it can be recovered.
241 .Aq Fl f Ar file | Fl l Ar label
251 .Aq Fl f Ar file | Fl l Ar label
256 command allows the user to label any partitions that match the selection.
257 At least one of the following selection options must be specified.
261 option specifies that all partitions should be labeled.
262 It is mutually exclusive with all other selection options.
266 option selects the partition that starts at the given block number.
270 option selects the partition with the given partition number.
271 Partition numbers start at 0.
275 option selects all partitions that have the given size.
276 This can cause multiple partitions to be removed.
280 option selects all partitions that have the given type.
281 The type is given as an UUID or by the aliases that the
284 This can cause multiple partitions to be removed.
290 options specify the new label to be assigned to the selected partitions.
293 option is used to read the label from the specified file.
294 Only the first line is read from the file and the trailing newline
295 character is stripped.
296 If the file name is the dash or minus sign
298 the label is read from
302 option is used to specify the label in the command line.
303 The label is assumed to be encoded in UTF-8.
304 .\" ==== migrate ====
305 .It Nm Ic migrate Oo Fl fs Oc Ar device ...
308 command allows the user to migrate an MBR-based disk partitioning into a
309 GPT-based partitioning.
310 By default, the MBR is not migrated when it contains partitions of an unknown
312 This can be overridden with the
317 option will cause unknown partitions to be ignored and any data in it
322 option prevents migrating
324 disk labels into GPT partitions by creating
325 the GPT equivalent of a slice.
327 .It Nm Ic remove Oo Fl a Oc Ar device ...
339 command allows the user to remove any and all partitions that match the
341 It uses the same selection options as the
344 See above for a description of these options.
345 Partitions are removed by clearing the partition type.
346 No other information is changed.
348 .It Nm Ic show Oo Fl lu Oc Ar device ...
351 command displays the current partitioning on the listed devices and gives
352 an overall view of the disk contents.
355 option the GPT partition label will be displayed instead of the GPT partition
357 The option has no effect on non-GPT partitions.
360 option the GPT partition type is displayed as an UUID instead of in a
364 option takes precedence over the
369 .Bl -tag -width ".Pa /etc/defaults/uuids"
374 .It Pa /etc/defaults/uuids
376 and their symbolic names provided by the OS vendor.
379 and their symbolic names provided by the system administrator.
382 To install an empty GPT on
387 GPT partitions are defined in number of sectors, the sector size is usually 512B,
388 which is assumed in the examples below, it can be found using:
390 .Dl "gpt -v show ad6"
392 To add a dummy GPT partition 0:
394 .Dl "gpt add -i0 -s1 ad6"
396 You might want to do this to not use slice 0 for data;
397 when GPT is not used on a disk, slice 0 is the compatibility slice,
399 .Dq dangerously dedicated
401 For GPT slice 0 has no special meaning, it is just the first slice on the disk.
403 To add a GPT partition of size approx. 100GB:
405 .Dl "gpt add -s200000000 ad6"
407 This will be GPT partition 1 as it is the first one free,
408 it will be accessible as
410 which is also printed by the command.
412 .Dq DragonFly Label64 ,
413 it will have to be set up by
416 To add GPT partition 5 with type
418 using the remaining free space:
419 .Bd -literal -offset indent
420 gpt add -i5 -t "DragonFly HAMMER" ad6
423 To print the contents of the GPT:
427 To setup a disk using GPT for booting, the steps below can be used.
428 System is copied from an already installed disk,
429 e.g.\& a hard disk or an install CD.
430 This example will setup disk
432 with GPT for booting, using the
437 Any previous data on disk installed to will be deleted.
438 .Bd -literal -offset indent
441 boot0cfg -s 2 -o packet da8
442 disklabel -B -r -w da8s0 auto
443 disklabel -e da8s0 # add `a' partition with fstype `4.2BSD' covering whole slice
446 disklabel64 -r -w da8s1 auto
447 disklabel64 -e da8s1 # add `b' partition with fstype `swap' and size 4GB,
448 # add `a' partition with fstype `HAMMER' covering rest of slice
449 newfs_hammer -L root /dev/da8s1a
450 mount_hammer /dev/da8s1a /mnt
451 cpdup / /mnt # copy each file system you need, e.g.
457 mount /dev/da8s0a /mnt/boot-fs
459 vi 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
463 chflags noschg kernel
464 mv boot kernel modules kernel.old modules.old boot-fs
465 chflags schg boot-fs/kernel
468 vi boot/loader.conf # add `vfs.root.mountfrom="hammer:da8s1a"'
475 When installing a new kernel, it needs to be installed to
479 command below can be used:
481 .Dl "make installkernel DESTDIR=/boot-fs"
485 manipulates is part of the EFI standard and is supported by many OSs.
486 GPT uses 64 bits to store number of sectors, this supports very large disks.
487 With the prevalent sector size of 512B this is 8 billion TB.
510 The development of the
512 utility is still work in progress.
513 Many necessary features are missing or partially implemented.
514 In practice this means that the manual page, supposed to describe these
515 features, is farther removed from being complete or useful.
516 As such, missing functionality is not even documented as missing.
517 However, it is believed that the currently present functionality is reliable
518 and stable enough that this tool can be used without bullet-proof footware if
519 one thinks one does not make mistakes.
521 It is expected that the basic usage model does not change, but it is
522 possible that future versions will not be compatible in the strictest sense
526 option may be changed to a command option rather than a generic option.
527 There are only two commands that use it so there is a chance that the natural
528 tendency for people is to use it as a command option.
529 Also, options primarily intended for diagnostic or debug purposes may be
530 removed in future versions.
532 Another possibility is that the current usage model is accompanied by
533 other interfaces to make the tool usable as a back-end.
534 This all depends on demand and thus feedback.
538 command doesn't support
projects / dragonfly.git / blob