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