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