gpt.8: Update example and note
[dragonfly.git] / sbin / gpt / gpt.8
CommitLineData
fb9cffef
MD
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 $
a668cf6a 26.\" $DragonFly: src/sbin/gpt/gpt.8,v 1.14 2008/10/03 21:26:28 thomas Exp $
fb9cffef 27.\"
51d18e64 28.Dd September 28, 2009
fb9cffef
MD
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.
68418bfc
TN
47GPT partitions are accessed as
48.Dx
b9016d53 49disk slices, with same number as GPT partition,
94f07f65 50127 slices per disk device are supported.
fb9cffef
MD
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
163ffa07 74accommodate.
fb9cffef
MD
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
68418bfc
TN
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
fb9cffef
MD
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.
71cfd094 129Entries start at index 0 representing partition 0 of the GPT.
fb9cffef
MD
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
50d00bbd 142.Cm efi , swap , ufs , hfs , linux , dfly ,
fb9cffef
MD
143and
144.Cm windows
145as aliases for the most commonly used partition types.
68418bfc
TN
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.
6148a411
MD
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
b9016d53
TN
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.
6148a411 171The PMBR is further modified to add the necessary boot code.
a668cf6a
TN
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
51d18e64 179vfs.root.mountfrom="ufs:da1s1a"
a668cf6a
TN
180.Ed
181.Pp
182which point to the actual root mount.
6148a411
MD
183.Pp
184Your root partition may be another GPT partition and you may use a 64 bit
b9016d53 185disklabel within that partition if you desire.
6148a411 186.Pp
b9016d53
TN
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
51d18e64
TN
198command may not be shared with another OS,
199as it doesn't use a fully standard GPT.
b9016d53
TN
200.Pp
201.Em WARNING!
202Some BIOSes may not be able to deal with this hack, your mileage may vary.
fb9cffef
MD
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.
71cfd094 269Partition numbers start at 0.
fb9cffef
MD
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
68418bfc
TN
366.Sh FILES
367.Bl -tag -width ".Pa /etc/defaults/uuids"
b9016d53
TN
368.It Pa /boot/boot0
369The default
370.Sq boot0
371image.
68418bfc
TN
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
a668cf6a 392.Dl "gpt add -i0 -s16 ad6"
68418bfc
TN
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"
b9016d53 424.Ss Boot Setup
6896d265
TN
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
51d18e64 429.Pa da1
6896d265
TN
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.
b9016d53 436.Bd -literal -offset indent
51d18e64
TN
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
b9016d53 443
51d18e64
TN
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
ec05e219 452
51d18e64 453newfs /dev/da1s0a
ec05e219 454mkdir /mnt/boot
51d18e64 455mount /dev/da1s0a /mnt/boot
ec05e219 456
b9016d53 457cpdup / /mnt # copy each file system you need, e.g.
ec05e219 458cpdup /boot /mnt/boot
b9016d53 459cpdup /var /mnt/var
ec05e219 460cpdup /var/tmp /mnt/var/tmp
b9016d53
TN
461cpdup /usr /mnt/usr
462
6896d265 463cd /mnt
51d18e64
TN
464vi etc/fstab # add `/dev/da1s1a / hammer rw',
465 # add `/dev/da1s1b none swap sw',
466 # add `/dev/da1s0a /boot ufs rw 1 1',
6896d265 467 # delete lines for file systems cpdup'ed above
51d18e64 468vi boot/loader.conf # add `vfs.root.mountfrom="hammer:da1s1a"'
b9016d53 469cd
ec05e219 470umount /mnt/boot
b9016d53
TN
471umount /mnt
472.Ed
68418bfc
TN
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.
fb9cffef 479.Sh SEE ALSO
68418bfc
TN
480.Xr uuid 3 ,
481.Xr disklabel64 5 ,
482.Xr uuids 5 ,
b9016d53 483.Xr boot0cfg 8 ,
68418bfc
TN
484.Xr disklabel 8 ,
485.Xr disklabel64 8 ,
fb9cffef
MD
486.Xr fdisk 8 ,
487.Xr mount 8 ,
488.Xr newfs 8 ,
68418bfc 489.Xr newfs_hammer 8 ,
fb9cffef
MD
490.Xr swapon 8
491.Sh HISTORY
492The
493.Nm
494utility appeared in
495.Fx 5.0
496for ia64.
68418bfc
TN
497It was imported to
498.Dx 1.9 .
fb9cffef
MD
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.
68418bfc
TN
525.Pp
526The
527.Ic migrate
528command doesn't support
529.Dx
530partition types.