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