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