sbin/bsdlabel/bsdlabel.8

   1 .\" Copyright (c) 1987, 1988, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Symmetric Computer Systems.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 4. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)disklabel.8 8.2 (Berkeley) 4/19/94
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd October 5, 2016
  35 .Dt BSDLABEL 8
  36 .Os
  37 .Sh NAME
  38 .Nm bsdlabel
  39 .Nd read and write BSD label
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl A
  43 .Ar disk | Fl f Ar file
  44 .Nm
  45 .Fl w
  46 .Op Fl \&An
  47 .Op Fl B Op Fl b Ar boot
  48 .Op Fl m Ar machine
  49 .Ar disk | Fl f Ar file
  50 .Op Ar type
  51 .Nm
  52 .Fl e
  53 .Op Fl \&An
  54 .Op Fl B Op Fl b Ar boot
  55 .Op Fl m Ar machine
  56 .Ar disk | Fl f Ar file
  57 .Nm
  58 .Fl R
  59 .Op Fl \&An
  60 .Op Fl B Op Fl b Ar boot
  61 .Op Fl m Ar machine
  62 .Op Fl f
  63 .Ar disk | Fl f Ar file
  64 .Ar protofile
  65 .Sh DESCRIPTION
  66 The
  67 .Nm
  68 utility
  69 installs, examines or modifies the
  70 .Bx
  71 label on a disk partition, or on a file containing a partition image.
  72 In addition,
  73 .Nm
  74 can install bootstrap code.
  75 .Ss Disk Device Name
  76 When specifying the device (i.e., when the
  77 .Fl f
  78 option is not used),
  79 the
  80 .Pa /dev/
  81 path prefix may be omitted;
  82 the
  83 .Nm
  84 utility will automatically prepend it.
  85 .Ss General Options
  86 The
  87 .Fl A
  88 option enables processing of the historical parts of the
  89 .Bx
  90 label.
  91 If the option is not given, suitable values are set for these fields.
  92 .Pp
  93 The
  94 .Fl f
  95 option tells
  96 .Nm
  97 that the program will operate on a file instead of a disk partition.
  98 .Pp
  99 The
 100 .Fl n
 101 option stops the
 102 .Nm
 103 program right before the disk would have been modified, and displays
 104 the result instead of writing it.
 105 .Pp
 106 The
 107 .Fl m Ar machine
 108 argument forces
 109 .Nm
 110 to use a layout suitable for a different architecture.
 111 Current valid values are
 112 .Cm i386 , amd64 , ia64 ,
 113 and
 114 .Cm pc98 .
 115 If this option is omitted,
 116 .Nm
 117 will use a layout suitable for the current machine.
 118 .Ss Reading the Disk Label
 119 To examine the label on a disk drive, use the form
 120 .Pp
 121 .Nm
 122 .Op Fl A
 123 .Op Fl m Ar machine
 124 .Ar disk
 125 .Pp
 126 .Ar disk
 127 represents the disk in question, and may be in the form
 128 .Pa da0
 129 or
 130 .Pa /dev/da0 .
 131 It will display the partition layout.
 132 .Ss Writing a Standard Label
 133 To write a standard label, use the form
 134 .Pp
 135 .Nm
 136 .Fl w
 137 .Op Fl \&An
 138 .Op Fl m Ar machine
 139 .Ar disk
 140 .Op Ar type
 141 .Pp
 142 If the drive
 143 .Ar type
 144 is specified, the entry of that name in the
 145 .Xr disktab 5
 146 file is used; otherwise, or if the type is specified as 'auto', a default
 147 layout is used.
 148 .Ss Editing an Existing Disk Label
 149 To edit an existing disk label, use the form
 150 .Pp
 151 .Nm
 152 .Fl e
 153 .Op Fl \&An
 154 .Op Fl m Ar machine
 155 .Ar disk
 156 .Pp
 157 This command opens the disk label in the default editor, and when the editor
 158 exits, the label is validated and if OK written to disk.
 159 .Ss Restoring a Disk Label From a File
 160 To restore a disk label from a file, use the form
 161 .Pp
 162 .Nm
 163 .Fl R
 164 .Op Fl \&An
 165 .Op Fl m Ar machine
 166 .Ar disk protofile
 167 .Pp
 168 The
 169 .Nm
 170 utility
 171 is capable of restoring a disk label that was previously saved in a file in
 172 .Tn ASCII
 173 format.
 174 The prototype file used to create the label should be in the same format as that
 175 produced when reading or editing a label.
 176 Comments are delimited by
 177 .Ql #
 178 and newline.
 179 .Ss Installing Bootstraps
 180 If the
 181 .Fl B
 182 option is specified, bootstrap code will be read from the file
 183 .Pa /boot/boot
 184 and written to the disk.
 185 The
 186 .Fl b Ar boot
 187 option allows a different file to be used.
 188 .Sh FILES
 189 .Bl -tag -width ".Pa /etc/disktab" -compact
 190 .It Pa /boot/boot
 191 Default boot image.
 192 .It Pa /etc/disktab
 193 Disk description file.
 194 .El
 195 .Sh SAVED FILE FORMAT
 196 The
 197 .Nm
 198 utility
 199 uses an
 200 .Tn ASCII
 201 version of the label when examining, editing, or restoring a disk
 202 label.
 203 The format is:
 204 .Bd -literal -offset 4n
 205
 206 8 partitions:
 207 #        size   offset    fstype   [fsize bsize bps/cpg]
 208   a:    81920       16    4.2BSD     2048 16384  5128
 209   b:  1091994    81936      swap
 210   c:  1173930        0    unused        0     0         # "raw" part, don't edit
 211 .Ed
 212 .Pp
 213 If the
 214 .Fl A
 215 option is specified, the format is:
 216 .Bd -literal -offset 4n
 217 # /dev/da1c:
 218 type: SCSI
 219 disk: da0s1
 220 label:
 221 flags:
 222 bytes/sector: 512
 223 sectors/track: 51
 224 tracks/cylinder: 19
 225 sectors/cylinder: 969
 226 cylinders: 1211
 227 sectors/unit: 1173930
 228 rpm: 3600
 229 interleave: 1
 230 trackskew: 0
 231 cylinderskew: 0
 232 headswitch: 0           # milliseconds
 233 track-to-track seek: 0  # milliseconds
 234 drivedata: 0
 235
 236 8 partitions:
 237 #        size   offset    fstype   [fsize bsize bps/cpg]
 238   a:    81920       16    4.2BSD     1024  8192    16
 239   b:   160000    81936      swap
 240   c:  1173930        0    unused        0     0         # "raw" part, don't edit
 241 .Ed
 242 .Pp
 243 Lines starting with a
 244 .Ql #
 245 mark are comments.
 246 .Pp
 247 The partition table can have up to 8 entries.
 248 It contains the following information:
 249 .Bl -tag -width indent
 250 .It Ar #
 251 The partition identifier is a single letter in the range
 252 .Ql a
 253 to
 254 .Ql h .
 255 By convention, partition
 256 .Ql c
 257 is reserved to describe the entire disk.
 258 .It Ar size
 259 The size of the partition in sectors,
 260 .Cm K
 261 (kilobytes - 1024),
 262 .Cm M
 263 (megabytes - 1024*1024),
 264 .Cm G
 265 (gigabytes - 1024*1024*1024),
 266 .Cm %
 267 (percentage of free space
 268 .Em after
 269 removing any fixed-size partitions other than partition
 270 .Ql c ) ,
 271 or
 272 .Cm *
 273 (all remaining free space
 274 .Em after
 275 fixed-size and percentage partitions).
 276 For partition
 277 .Ql c ,
 278 a size of
 279 .Cm *
 280 indicates the entire disk.
 281 Lowercase versions of suffixes
 282 .Cm K , M ,
 283 and
 284 .Cm G
 285 are allowed.
 286 Size and suffix should be specified without any spaces between them.
 287 .Pp
 288 Example: 2097152, 1G, 1024M and 1048576K are all the same size
 289 (assuming 512-byte sectors).
 290 .It Ar offset
 291 The offset of the start of the partition from the beginning of the
 292 drive in sectors, or
 293 .Cm *
 294 to have
 295 .Nm
 296 calculate the correct offset to use (the end of the previous partition plus
 297 one, ignoring partition
 298 .Ql c ) .
 299 For partition
 300 .Ql c ,
 301 .Cm *
 302 will be interpreted as an offset of 0.
 303 The first partition should start at offset 16, because the first 16 sectors are
 304 reserved for metadata.
 305 .It Ar fstype
 306 Describes the purpose of the partition.
 307 The above example shows all currently used partition types.
 308 For
 309 .Tn UFS
 310 file systems and
 311 .Xr ccd 4
 312 partitions, use type
 313 .Cm 4.2BSD .
 314 For Vinum drives, use type
 315 .Cm vinum .
 316 Other common types are
 317 .Cm swap
 318 and
 319 .Cm unused .
 320 By convention, partition
 321 .Ql c
 322 represents the entire slice and should be of type
 323 .Cm unused ,
 324 though
 325 .Nm
 326 does not enforce this convention.
 327 The
 328 .Nm
 329 utility
 330 also knows about a number of other partition types,
 331 none of which are in current use.
 332 (See the definitions starting with
 333 .Dv FS_UNUSED
 334 in
 335 .In sys/disklabel.h
 336 for more details.)
 337 .It Ar fsize
 338 For
 339 .Cm 4.2BSD
 340 file systems only, the fragment size; see
 341 .Xr newfs 8 .
 342 .It Ar bsize
 343 For
 344 .Cm 4.2BSD
 345 file systems only, the block size; see
 346 .Xr newfs 8 .
 347 .It Ar bps/cpg
 348 For
 349 .Cm 4.2BSD
 350 file systems, the number of cylinders in a cylinder group; see
 351 .Xr newfs 8 .
 352 .El
 353 .Sh EXAMPLES
 354 Display the label for the first slice of the
 355 .Pa da0
 356 disk, as obtained via
 357 .Pa /dev/da0s1 :
 358 .Pp
 359 .Dl "bsdlabel da0s1"
 360 .Pp
 361 Save the in-core label for
 362 .Pa da0s1
 363 into the file
 364 .Pa savedlabel .
 365 This file can be used with the
 366 .Fl R
 367 option to restore the label at a later date:
 368 .Pp
 369 .Dl "bsdlabel da0s1 > savedlabel"
 370 .Pp
 371 Create a label for
 372 .Pa da0s1 :
 373 .Pp
 374 .Dl "bsdlabel -w /dev/da0s1"
 375 .Pp
 376 Read the label for
 377 .Pa da0s1 ,
 378 edit it, and install the result:
 379 .Pp
 380 .Dl "bsdlabel -e da0s1"
 381 .Pp
 382 Read the on-disk label for
 383 .Pa da0s1 ,
 384 edit it, and display what the new label would be (in sectors).
 385 It does
 386 .Em not
 387 install the new label either in-core or on-disk:
 388 .Pp
 389 .Dl "bsdlabel -e -n da0s1"
 390 .Pp
 391 Write a default label on
 392 .Pa da0s1 .
 393 Use another
 394 .Nm Fl e
 395 command to edit the
 396 partitioning and file system information:
 397 .Pp
 398 .Dl "bsdlabel -w da0s1"
 399 .Pp
 400 Restore the on-disk and in-core label for
 401 .Pa da0s1
 402 from information in
 403 .Pa savedlabel :
 404 .Pp
 405 .Dl "bsdlabel -R da0s1 savedlabel"
 406 .Pp
 407 Display what the label would be for
 408 .Pa da0s1
 409 using the partition layout in
 410 .Pa label_layout .
 411 This is useful for determining how much space would be allotted for various
 412 partitions with a labeling scheme using
 413 .Cm % Ns -based
 414 or
 415 .Cm *
 416 partition sizes:
 417 .Pp
 418 .Dl "bsdlabel -R -n da0s1 label_layout"
 419 .Pp
 420 Install a new bootstrap on
 421 .Pa da0s1 .
 422 The boot code comes from
 423 .Pa /boot/boot :
 424 .Pp
 425 .Dl "bsdlabel -B da0s1"
 426 .Pp
 427 Install a new label and bootstrap.
 428 The bootstrap code comes from the file
 429 .Pa newboot
 430 in the current working directory:
 431 .Pp
 432 .Dl "bsdlabel -w -B -b newboot /dev/da0s1"
 433 .Pp
 434 Completely wipe any prior information on the disk, creating a new bootable
 435 disk with a
 436 .Tn DOS
 437 partition table containing one slice, covering the whole disk.
 438 Initialize the label on this slice,
 439 then edit it.
 440 The
 441 .Xr dd 1
 442 commands are optional, but may be necessary for some
 443 .Tn BIOS Ns es
 444 to properly
 445 recognize the disk:
 446 .Bd -literal -offset indent
 447 dd if=/dev/zero of=/dev/da0 bs=512 count=32
 448 gpart create -s MBR da0
 449 gpart add -t freebsd da0
 450 gpart set -a active -i 1 da0
 451 gpart bootcode -b /boot/mbr da0
 452 dd if=/dev/zero of=/dev/da0s1 bs=512 count=32
 453 bsdlabel -w -B da0s1
 454 bsdlabel -e da0s1
 455 .Ed
 456 .Pp
 457 This is an example disk label that uses some of the new partition size types
 458 such as
 459 .Cm % , M , G ,
 460 and
 461 .Cm * ,
 462 which could be used as a source file for
 463 .Dq Li "bsdlabel -R ada0s1 new_label_file" :
 464 .Bd -literal -offset 4n
 465 # /dev/ada0s1:
 466
 467 8 partitions:
 468 #        size   offset    fstype   [fsize bsize bps/cpg]
 469   a:   400M       16    4.2BSD     4096 16384    75    # (Cyl.    0 - 812*)
 470   b:     1G        *      swap
 471   c:      *        *    unused
 472   e: 204800        *    4.2BSD
 473   f:     5g        *    4.2BSD
 474   g:      *        *    4.2BSD
 475 .Ed
 476 .Sh DIAGNOSTICS
 477 The kernel device drivers will not allow the size of a disk partition
 478 to be decreased or the offset of a partition to be changed while it is open.
 479 .Sh COMPATIBILITY
 480 Due to the use of an
 481 .Vt uint32_t
 482 to store the number of sectors,
 483 .Bx
 484 labels are restricted to a maximum of 2^32-1 sectors.
 485 This usually means 2TB of disk space.
 486 Larger disks should be partitioned using another method such as
 487 .Xr gpart 8 .
 488 .Pp
 489 The various
 490 .Bx Ns s
 491 all use slightly different versions of
 492 .Bx
 493 labels and
 494 are not generally compatible.
 495 .Sh SEE ALSO
 496 .Xr ccd 4 ,
 497 .Xr geom 4 ,
 498 .Xr md 4 ,
 499 .Xr disktab 5 ,
 500 .Xr boot0cfg 8 ,
 501 .Xr gpart 8 ,
 502 .Xr newfs 8
 503 .Sh HISTORY
 504 The
 505 .Nm disklabel
 506 utility appeared in
 507 .Bx 4.3 Tahoe .