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