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