sbin/geom/class/part/gpart.8

   1 .\" Copyright (c) 2007, 2008 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 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd June 24, 2010
  28 .Dt GPART 8
  29 .Os
  30 .Sh NAME
  31 .Nm gpart
  32 .Nd "control utility for the disk partitioning GEOM class"
  33 .Sh SYNOPSIS
  34 To add support for the disk partitioning GEOM class,
  35 place one or more of the following
  36 lines in your kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "options GEOM_PART_APM"
  39 .Cd "options GEOM_PART_BSD"
  40 .Cd "options GEOM_PART_GPT"
  41 .Cd "options GEOM_PART_MBR"
  42 .Cd "options GEOM_PART_PC98"
  43 .Cd "options GEOM_PART_VTOC8"
  44 .Ed
  45 .Pp
  46 The
  47 .Dv GEOM_PART_APM
  48 option adds support for the Apple Partition Map (APM)
  49 found on Apple Macintosh computers.
  50 The
  51 .Dv GEOM_PART_BSD
  52 option adds support for the traditional
  53 .Bx
  54 disklabel.
  55 The
  56 .Dv GEOM_PART_GPT
  57 option adds support for the GUID Partition Table (GPT)
  58 found on Intel Itanium computers and Intel-based Macintosh computers.
  59 The
  60 .Dv GEOM_PART_MBR
  61 option adds support for the Master Boot Record (MBR)
  62 found on PCs and used on many removable media.
  63 The
  64 .Dv GEOM_PART_PC98
  65 option adds support for the MBR variant as used on
  66 NEC PC-98 computers.
  67 The
  68 .Dv GEOM_PART_VTOC8
  69 option adds support for Sun's SMI VTOC8 label as
  70 found on computers based on
  71 .Tn SPARC64
  72 and
  73 .Tn UltraSPARC.
  74 .Pp
  75 Usage of the
  76 .Ns Nm
  77 utility:
  78 .Pp
  79 .\" ==== ADD ====
  80 .Nm
  81 .Cm add
  82 .Fl b Ar start
  83 .Fl s Ar size
  84 .Fl t Ar type
  85 .Op Fl i Ar index
  86 .Op Fl l Ar label
  87 .Op Fl f Ar flags
  88 .Ar geom
  89 .\" ==== BOOTCODE ====
  90 .Nm
  91 .Cm bootcode
  92 .Op Fl b Ar bootcode
  93 .Op Fl p Ar partcode Fl i Ar index
  94 .Op Fl f Ar flags
  95 .Ar geom
  96 .\" ==== COMMIT ====
  97 .Nm
  98 .Cm commit
  99 .Ar geom
 100 .\" ==== CREATE ====
 101 .Nm
 102 .Cm create
 103 .Fl s Ar scheme
 104 .Op Fl n Ar entries
 105 .Op Fl f Ar flags
 106 .Ar provider
 107 .\" ==== DELETE ====
 108 .Nm
 109 .Cm delete
 110 .Fl i Ar index
 111 .Op Fl f Ar flags
 112 .Ar geom
 113 .\" ==== DESTROY ====
 114 .Nm
 115 .Cm destroy
 116 .Op Fl f Ar flags
 117 .Ar geom
 118 .\" ==== MODIFY ====
 119 .Nm
 120 .Cm modify
 121 .Fl i Ar index
 122 .Op Fl l Ar label
 123 .Op Fl t Ar type
 124 .Op Fl f Ar flags
 125 .Ar geom
 126 .\" ==== RESIZE ====
 127 .Nm
 128 .Cm resize
 129 .Fl i Ar index
 130 .Op Fl s Ar size
 131 .Op Fl f Ar flags
 132 .Ar geom
 133 .\" ==== SET ====
 134 .Nm
 135 .Cm set
 136 .Fl a Ar attrib
 137 .Fl i Ar index
 138 .Op Fl f Ar flags
 139 .Ar geom
 140 .\" ==== SHOW ====
 141 .Nm
 142 .Cm show
 143 .Op Ar geom ...
 144 .\" ==== UNDO ====
 145 .Nm
 146 .Cm undo
 147 .Ar geom
 148 .\" ==== UNSET ====
 149 .Nm
 150 .Cm unset
 151 .Fl a Ar attrib
 152 .Fl i Ar index
 153 .Op Fl f Ar flags
 154 .Ar geom
 155 .\"
 156 .Sh DESCRIPTION
 157 The
 158 .Nm
 159 utility is used to partition GEOM providers, normally disks.
 160 The first argument of which is the action to be taken:
 161 .Bl -tag -width ".Cm bootcode"
 162 .\" ==== ADD ====
 163 .It Cm add
 164 Add a new partition to the partitioning scheme given by
 165 .Ar geom .
 166 The partition begins on the logical block address given by the
 167 .Fl b Ar start
 168 option.
 169 Its size is expressed in logical block numbers and given by the
 170 .Fl s Ar size
 171 option.
 172 The type of the partition is given by the
 173 .Fl t Ar type
 174 option.
 175 Partition types are discussed below in the section entitled
 176 .Sx "PARTITION TYPES" .
 177 .Pp
 178 Additional options include:
 179 .Bl -tag -width 10n
 180 .It Fl i Ar index
 181 The index in the partition table at which the new partition is to be
 182 placed.
 183 The index determines the name of the device special file used
 184 to represent the partition.
 185 .It Fl l Ar label
 186 The label attached to the partition.
 187 This option is only valid when used on partitioning schemes that support
 188 partition labels.
 189 .It Fl f Ar flags
 190 Additional operational flags.
 191 See the section entitled
 192 .Sx "OPERATIONAL FLAGS"
 193 below for a discussion
 194 about its use.
 195 .El
 196 .\" ==== BOOTCODE ====
 197 .It Cm bootcode
 198 Embed bootstrap code into the partitioning scheme's metadata on the
 199 .Ar geom
 200 (using
 201 .Fl b Ar bootcode )
 202 or write bootstrap code into a partition (using
 203 .Fl p Ar partcode
 204 and
 205 .Fl i Ar index ) .
 206 Not all partitioning schemes have embedded bootstrap code, so the
 207 .Fl b Ar bootcode
 208 option is scheme-specific in nature.
 209 For the GPT scheme, embedded bootstrap code is supported.
 210 The bootstrap code is embedded in the protective MBR rather than the GPT.
 211 The
 212 .Fl b Ar bootcode
 213 option specifies a file that contains the bootstrap code.
 214 The contents and size of the file are determined by the partitioning
 215 scheme.
 216 For the MBR scheme, it is a 512 byte file of which the first 446 bytes
 217 are installed as bootstrap code.
 218 The
 219 .Fl p Ar partcode
 220 option specifies a file that contains the bootstrap code intended to be
 221 written to a partition.
 222 For the VTOC8 scheme, it is a 8192 byte file of which the last 7680 bytes
 223 are installed as bootstrap code.
 224 The partition is specified by the
 225 .Fl i Ar index
 226 option.
 227 For the VTOC8 scheme, if the
 228 .Fl i Ar index
 229 option is omitted, the bootstrap code is written to all sufficiently large
 230 partitions.
 231 The size of the file must be smaller than the size of the partition.
 232 .Pp
 233 Additional options include:
 234 .Bl -tag -width 10n
 235 .It Fl f Ar flags
 236 Additional operational flags.
 237 See the section entitled
 238 .Sx "OPERATIONAL FLAGS"
 239 below for a discussion
 240 about its use.
 241 .El
 242 .\" ==== COMMIT ====
 243 .It Cm commit
 244 Commit any pending changes for geom
 245 .Ar geom .
 246 All actions are being committed by default and will not result in
 247 pending changes.
 248 Actions can be modified with the
 249 .Fl f Ar flags
 250 option so that they are not being committed by default.
 251 As such, they become pending.
 252 Pending changes are reflected by the geom and the
 253 .Nm
 254 utility, but they are not actually written to disk.
 255 The
 256 .Cm commit
 257 action will write any and all pending changes to disk.
 258 .\" ==== CREATE ====
 259 .It Cm create
 260 Create a new partitioning scheme on a provider given by
 261 .Ar provider .
 262 The
 263 .Fl s Ar scheme
 264 option determines the scheme to use.
 265 The kernel needs to have support for a particular scheme before
 266 that scheme can be used to partition a disk.
 267 .Pp
 268 Additional options include:
 269 .Bl -tag -width 10n
 270 .It Fl n Ar entries
 271 The number of entries in the partition table.
 272 Every partitioning scheme has a minimum and a maximum number of entries
 273 and this option allows tables to be created with the number of entries
 274 that lies anywhere between the minimum and the maximum.
 275 Some schemes have a maximum equal to the minimum and some schemes have
 276 a maximum large enough to be considered unlimited.
 277 By default, partition tables are created with the minimum number of
 278 entries.
 279 .It Fl f Ar flags
 280 Additional operational flags.
 281 See the section entitled
 282 .Sx "OPERATIONAL FLAGS"
 283 below for a discussion
 284 about its use.
 285 .El
 286 .\" ==== DELETE ====
 287 .It Cm delete
 288 Delete a partition from geom
 289 .Ar geom
 290 and further identified by the
 291 .Fl i Ar index
 292 option.
 293 The partition cannot be actively used by the kernel.
 294 .Pp
 295 Additional options include:
 296 .Bl -tag -width 10n
 297 .It Fl f Ar flags
 298 Additional operational flags.
 299 See the section entitled
 300 .Sx "OPERATIONAL FLAGS"
 301 below for a discussion
 302 about its use.
 303 .El
 304 .\" ==== DESTROY ====
 305 .It Cm destroy
 306 Destroy the partitioning scheme as implemented by geom
 307 .Ar geom .
 308 .Pp
 309 Additional options include:
 310 .Bl -tag -width 10n
 311 .It Fl f Ar flags
 312 Additional operational flags.
 313 See the section entitled
 314 .Sx "OPERATIONAL FLAGS"
 315 below for a discussion
 316 about its use.
 317 .El
 318 .\" ==== MODIFY ====
 319 .It Cm modify
 320 Modify a partition from geom
 321 .Ar geom
 322 and further identified by the
 323 .Fl i Ar index
 324 option.
 325 Only the the type and/or label of the partition can be modified.
 326 To change the type of a partition, specify the new type with the
 327 .Fl t Ar type
 328 option.
 329 To change the label of a partition, specify the new label with the
 330 .Fl l Ar label
 331 option.
 332 Not all partitioning schemes support labels and it is invalid to
 333 try to change a partition label in such cases.
 334 .Pp
 335 Additional options include:
 336 .Bl -tag -width 10n
 337 .It Fl f Ar flags
 338 Additional operational flags.
 339 See the section entitled
 340 .Sx "OPERATIONAL FLAGS"
 341 below for a discussion
 342 about its use.
 343 .El
 344 .\" ==== RESIZE ====
 345 .It Cm resize
 346 Resize a partition from geom
 347 .Ar geom
 348 and further identified by the
 349 .Fl i Ar index
 350 option.
 351 New partition size is expressed in logical block
 352 numbers and can be given by the
 353 .Fl s Ar size
 354 option.
 355 If
 356 .Fl s
 357 option is ommited then new size is automatically calculated
 358 to maximum available from given geom
 359 .Ar geom .
 360 .Pp
 361 Additional options include:
 362 .Bl -tag -width 10n
 363 .It Fl f Ar flags
 364 Additional operational flags.
 365 See the section entitled
 366 .Sx "OPERATIONAL FLAGS"
 367 below for a discussion
 368 about its use.
 369 .El
 370 .\" ==== SET ====
 371 .It Cm set
 372 Set the named attribute on the partition entry.
 373 .Pp
 374 Additional options include:
 375 .Bl -tag -width 10n
 376 .It Fl f Ar flags
 377 Additional operational flags.
 378 See the section entitled
 379 .Sx "OPERATIONAL FLAGS"
 380 below for a discussion
 381 about its use.
 382 .El
 383 .\" ==== SHOW ====
 384 .It Cm show
 385 Show the current partition information of the specified geoms
 386 or all geoms if none are specified.
 387 .\" ==== UNDO ====
 388 .It Cm undo
 389 Revert any pending changes for geom
 390 .Ar geom .
 391 This action is the opposite of the
 392 .Cm commit
 393 action and can be used to undo any changes that have not been committed.
 394 .\" ==== UNSET ====
 395 .It Cm unset
 396 Clear the named attribute on the partition entry.
 397 .Pp
 398 Additional options include:
 399 .Bl -tag -width 10n
 400 .It Fl f Ar flags
 401 Additional operational flags.
 402 See the section entitled
 403 .Sx "OPERATIONAL FLAGS"
 404 below for a discussion
 405 about its use.
 406 .El
 407 .El
 408 .\"
 409 .Sh PARTITION TYPES
 410 The
 411 .Nm
 412 utility uses symbolic names for common partition types to avoid that the
 413 user needs to know what the partitioning scheme in question is and what
 414 the actual number or identification needs to be used for a particular
 415 type.
 416 The
 417 .Nm
 418 utility also allows the user to specify scheme-specific partition types
 419 for partition types that do not have symbol names.
 420 The symbolic names currently understood are:
 421 .Bl -tag -width ".Cm freebsd-vinum"
 422 .It Cm efi
 423 The system partition for computers that use the Extensible Firmware
 424 Interface (EFI).
 425 In such cases, the GPT partitioning scheme is being used and the
 426 actual partition type for the system partition can also be specified as
 427 .Qq Li "!c12a7328-f81f-11d2-ba4b-00a0c93ec93ab" .
 428 .It Cm freebsd
 429 A
 430 .Fx
 431 partition that uses the
 432 .Bx
 433 disklabel to sub-divide the
 434 partition into file systems.
 435 This is a legacy partition type and should not be used for the APM
 436 or GPT schemes.
 437 The scheme-specific types are
 438 .Qq Li "!165"
 439 for MBR,
 440 .Qq Li "!FreeBSD"
 441 for APM, and
 442 .Qq Li "!516e7cb4-6ecf-11d6-8ff8-00022d09712b"
 443 for GPT.
 444 .It Cm freebsd-boot
 445 A
 446 .Fx
 447 partition dedicated to bootstrap code.
 448 The scheme-specific type is
 449 .Qq Li "!83bd6b9d-7f41-11dc-be0b-001560b84f0f"
 450 for GPT.
 451 .It Cm freebsd-swap
 452 A
 453 .Fx
 454 partition dedicated to swap space.
 455 The scheme-specific types are
 456 .Qq Li "!FreeBSD-swap"
 457 for APM,
 458 .Qq Li "!516e7cb5-6ecf-11d6-8ff8-00022d09712b"
 459 for GPT, and tag 0x0901 for VTOC8.
 460 .It Cm freebsd-ufs
 461 A
 462 .Fx
 463 partition that contains a UFS or UFS2 file system.
 464 The scheme-specific types are
 465 .Qq Li "!FreeBSD-UFS"
 466 for APM,
 467 .Qq Li "!516e7cb6-6ecf-11d6-8ff8-00022d09712b"
 468 for GPT, and tag 0x0902 for VTOC8.
 469 .It Cm freebsd-vinum
 470 A
 471 .Fx
 472 partition that contains a Vinum volume.
 473 The scheme-specific types are
 474 .Qq Li "!FreeBSD-Vinum"
 475 for APM,
 476 .Qq Li "!516e7cb8-6ecf-11d6-8ff8-00022d09712b"
 477 for GPT, and tag 0x0903 for VTOC8.
 478 .It Cm freebsd-zfs
 479 A
 480 .Fx
 481 partition that contains a ZFS volume.
 482 The scheme-specific types are
 483 .Qq Li "!FreeBSD-ZFS"
 484 for APM,
 485 .Qq Li "!516e7cba-6ecf-11d6-8ff8-00022d09712b"
 486 for GPT, and 0x0904 for VTOC8.
 487 .It Cm mbr
 488 A partition that is sub-partitioned by a master boot record (MBR).
 489 This type is known as
 490 .Qq Li "!024dee41-33e7-11d3-9d69-0008c781f39f"
 491 by GPT.
 492 .El
 493 .Sh OPERATIONAL FLAGS
 494 Actions other than the
 495 .Cm commit
 496 and
 497 .Cm undo
 498 actions take an optional
 499 .Fl f Ar flags
 500 option.
 501 This option is used to specify action-specific operational flags.
 502 By default, the
 503 .Nm
 504 utility defines the
 505 .Ql C
 506 flag so that the action is immediately
 507 committed.
 508 The user can specify
 509 .Dq Fl f Cm x
 510 to have the action result in a pending change that can later, with
 511 other pending changes, be committed as a single compound change with
 512 the
 513 .Cm commit
 514 action or reverted with the
 515 .Cm undo
 516 action.
 517 .Sh EXIT STATUS
 518 Exit status is 0 on success, and 1 if the command fails.
 519 .Sh EXAMPLES
 520 Create GPT scheme on
 521 .Pa ad0 .
 522 .Bd -literal -offset indent
 523 /sbin/gpart create -s GPT ad0
 524 .Ed
 525 .Pp
 526 Embed GPT bootstrap code into protective MBR.
 527 .Bd -literal -offset indent
 528 /sbin/gpart bootcode -b /boot/pmbr ad0
 529 .Ed
 530 .Pp
 531 Create a dedicated
 532 .Cm freebsd-boot
 533 partition that can boot
 534 .Fx
 535 from a
 536 .Cm freebsd-ufs
 537 partition, and install bootstrap code into it.
 538 This partition must be larger than
 539 .Pa /boot/gptboot ,
 540 or the GPT boot you are planning to write.
 541 A size of 15 blocks (7680 bytes) would be sufficient for
 542 booting from UFS but let's use 128 blocks (64 KB) here in
 543 this example, in order to reserve some space for potential
 544 future need (e.g.\& from a ZFS partition).
 545 .Bd -literal -offset indent
 546 /sbin/gpart add -b 34 -s 128 -t freebsd-boot ad0
 547 /sbin/gpart bootcode -p /boot/gptboot -i 1 ad0
 548 .Ed
 549 .Pp
 550 Create a 512MB-sized
 551 .Cm freebsd-ufs
 552 partition that would contain UFS where the system boots from.
 553 .Bd -literal -offset indent
 554 /sbin/gpart add -b 162 -s 1048576 -t freebsd-ufs ad0
 555 .Ed
 556 .Pp
 557 Create VTOC8 scheme on
 558 .Pa da0 .
 559 .Bd -literal -offset indent
 560 /sbin/gpart create -s VTOC8 da0
 561 .Ed
 562 .Pp
 563 Create a 512MB-sized
 564 .Cm freebsd-ufs
 565 partition that would contain UFS where the system boots from.
 566 .Bd -literal -offset indent
 567 /sbin/gpart add -b 0 -s 1048576 -t freebsd-ufs da0
 568 .Ed
 569 .Pp
 570 After having created all required partitions, embed bootstrap code into them.
 571 .Bd -literal -offset indent
 572 /sbin/gpart bootcode -p /boot/boot1 da0
 573 .Ed
 574 .Sh SEE ALSO
 575 .Xr geom 4 ,
 576 .Xr geom 8
 577 .Sh HISTORY
 578 The
 579 .Nm
 580 utility appeared in
 581 .Fx 7.0 .
 582 .Sh AUTHORS
 583 .An Marcel Moolenaar Aq marcel@FreeBSD.org