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