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