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 December 29, 2006
  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 , pc98 ,
 113 and
 114 .Cm alpha .
 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 a default layout is used.
 147 .Ss Editing an Existing Disk Label
 148 To edit an existing disk label, use the form
 149 .Pp
 150 .Nm
 151 .Fl e
 152 .Op Fl \&An
 153 .Op Fl m Ar machine
 154 .Ar disk
 155 .Pp
 156 This command opens the disk label in the default editor, and when the editor
 157 exits, the label is validated and if OK written to disk.
 158 .Ss Restoring a Disk Label From a File
 159 To restore a disk label from a file, use the form
 160 .Pp
 161 .Nm
 162 .Fl R
 163 .Op Fl \&An
 164 .Op Fl m Ar machine
 165 .Ar disk protofile
 166 .Pp
 167 The
 168 .Nm
 169 utility
 170 is capable of restoring a disk label that was previously saved in a file in
 171 .Tn ASCII
 172 format.
 173 The prototype file used to create the label should be in the same format as that
 174 produced when reading or editing a label.
 175 Comments are delimited by
 176 .Ql #
 177 and newline.
 178 .Ss Installing Bootstraps
 179 If the
 180 .Fl B
 181 option is specified, bootstrap code will be read from the file
 182 .Pa /boot/boot
 183 and written to the disk.
 184 The
 185 .Fl b Ar boot
 186 option allows a different file to be used.
 187 .Sh FILES
 188 .Bl -tag -width ".Pa /etc/disktab" -compact
 189 .It Pa /boot/boot
 190 Default boot image.
 191 .It Pa /etc/disktab
 192 Disk description file.
 193 .El
 194 .Sh SAVED FILE FORMAT
 195 The
 196 .Nm
 197 utility
 198 uses an
 199 .Tn ASCII
 200 version of the label when examining, editing, or restoring a disk
 201 label.
 202 The format is:
 203 .Bd -literal -offset 4n
 204
 205 8 partitions:
 206 #        size   offset    fstype   [fsize bsize bps/cpg]
 207   a:    81920       16    4.2BSD     2048 16384  5128
 208   b:  1091994    81936      swap
 209   c:  1173930        0    unused        0     0         # "raw" part, don't edit
 210 .Ed
 211 .Pp
 212 If the
 213 .Fl A
 214 option is specified, the format is:
 215 .Bd -literal -offset 4n
 216 # /dev/da1c:
 217 type: SCSI
 218 disk: da0s1
 219 label:
 220 flags:
 221 bytes/sector: 512
 222 sectors/track: 51
 223 tracks/cylinder: 19
 224 sectors/cylinder: 969
 225 cylinders: 1211
 226 sectors/unit: 1173930
 227 rpm: 3600
 228 interleave: 1
 229 trackskew: 0
 230 cylinderskew: 0
 231 headswitch: 0           # milliseconds
 232 track-to-track seek: 0  # milliseconds
 233 drivedata: 0
 234
 235 8 partitions:
 236 #        size   offset    fstype   [fsize bsize bps/cpg]
 237   a:    81920       16    4.2BSD     1024  8192    16
 238   b:   160000    81936      swap
 239   c:  1173930        0    unused        0     0         # "raw" part, don't edit
 240 .Ed
 241 .Pp
 242 Lines starting with a
 243 .Ql #
 244 mark are comments.
 245 .Pp
 246 The partition table can have up to 8 entries.
 247 It contains the following information:
 248 .Bl -tag -width indent
 249 .It Ar #
 250 The partition identifier is a single letter in the range
 251 .Ql a
 252 to
 253 .Ql h .
 254 By convention, partition
 255 .Ql c
 256 is reserved to describe the entire disk.
 257 .It Ar size
 258 The size of the partition in sectors,
 259 .Cm K
 260 (kilobytes - 1024),
 261 .Cm M
 262 (megabytes - 1024*1024),
 263 .Cm G
 264 (gigabytes - 1024*1024*1024),
 265 .Cm %
 266 (percentage of free space
 267 .Em after
 268 removing any fixed-size partitions other than partition
 269 .Ql c ) ,
 270 or
 271 .Cm *
 272 (all remaining free space
 273 .Em after
 274 fixed-size and percentage partitions).
 275 For partition
 276 .Ql c ,
 277 a size of
 278 .Cm *
 279 indicates the entire disk.
 280 Lowercase versions of suffixes
 281 .Cm K , M ,
 282 and
 283 .Cm G
 284 are allowed.
 285 Size and suffix should be specified without any spaces between them.
 286 .Pp
 287 Example: 2097152, 1G, 1024M and 1048576K are all the same size
 288 (assuming 512-byte sectors).
 289 .It Ar offset
 290 The offset of the start of the partition from the beginning of the
 291 drive in sectors, or
 292 .Cm *
 293 to have
 294 .Nm
 295 calculate the correct offset to use (the end of the previous partition plus
 296 one, ignoring partition
 297 .Ql c ) .
 298 For partition
 299 .Ql c ,
 300 .Cm *
 301 will be interpreted as an offset of 0.
 302 The first partition should start at offset 16, because the first 16 sectors are
 303 reserved for metadata.
 304 .It Ar fstype
 305 Describes the purpose of the partition.
 306 The above example shows all currently used partition types.
 307 For
 308 .Tn UFS
 309 file systems and
 310 .Xr ccd 4
 311 partitions, use type
 312 .Cm 4.2BSD .
 313 For Vinum drives, use type
 314 .Cm vinum .
 315 Other common types are
 316 .Cm swap
 317 and
 318 .Cm unused .
 319 By convention, partition
 320 .Ql c
 321 represents the entire slice and should be of type
 322 .Cm unused ,
 323 though
 324 .Nm
 325 does not enforce this convention.
 326 The
 327 .Nm
 328 utility
 329 also knows about a number of other partition types,
 330 none of which are in current use.
 331 (See the definitions starting with
 332 .Dv FS_UNUSED
 333 in
 334 .In sys/disklabel.h
 335 for more details.)
 336 .It Ar fsize
 337 For
 338 .Cm 4.2BSD
 339 file systems only, the fragment size; see
 340 .Xr newfs 8 .
 341 .It Ar bsize
 342 For
 343 .Cm 4.2BSD
 344 file systems only, the block size; see
 345 .Xr newfs 8 .
 346 .It Ar bps/cpg
 347 For
 348 .Cm 4.2BSD
 349 file systems, the number of cylinders in a cylinder group; see
 350 .Xr newfs 8 .
 351 .El
 352 .Sh EXAMPLES
 353 Display the label for the first slice of the
 354 .Pa da0
 355 disk, as obtained via
 356 .Pa /dev/da0s1 :
 357 .Pp
 358 .Dl "bsdlabel da0s1"
 359 .Pp
 360 Save the in-core label for
 361 .Pa da0s1
 362 into the file
 363 .Pa savedlabel .
 364 This file can be used with the
 365 .Fl R
 366 option to restore the label at a later date:
 367 .Pp
 368 .Dl "bsdlabel da0s1 > savedlabel"
 369 .Pp
 370 Create a label for
 371 .Pa da0s1 :
 372 .Pp
 373 .Dl "bsdlabel -w /dev/da0s1"
 374 .Pp
 375 Read the label for
 376 .Pa da0s1 ,
 377 edit it, and install the result:
 378 .Pp
 379 .Dl "bsdlabel -e da0s1"
 380 .Pp
 381 Read the on-disk label for
 382 .Pa da0s1 ,
 383 edit it, and display what the new label would be (in sectors).
 384 It does
 385 .Em not
 386 install the new label either in-core or on-disk:
 387 .Pp
 388 .Dl "bsdlabel -e -n da0s1"
 389 .Pp
 390 Write a default label on
 391 .Pa da0s1 .
 392 Use another
 393 .Nm Fl e
 394 command to edit the
 395 partitioning and file system information:
 396 .Pp
 397 .Dl "bsdlabel -w da0s1"
 398 .Pp
 399 Restore the on-disk and in-core label for
 400 .Pa da0s1
 401 from information in
 402 .Pa savedlabel :
 403 .Pp
 404 .Dl "bsdlabel -R da0s1 savedlabel"
 405 .Pp
 406 Display what the label would be for
 407 .Pa da0s1
 408 using the partition layout in
 409 .Pa label_layout .
 410 This is useful for determining how much space would be allotted for various
 411 partitions with a labeling scheme using
 412 .Cm % Ns -based
 413 or
 414 .Cm *
 415 partition sizes:
 416 .Pp
 417 .Dl "bsdlabel -R -n da0s1 label_layout"
 418 .Pp
 419 Install a new bootstrap on
 420 .Pa da0s1 .
 421 The boot code comes from
 422 .Pa /boot/boot :
 423 .Pp
 424 .Dl "bsdlabel -B da0s1"
 425 .Pp
 426 Install a new label and bootstrap.
 427 The bootstrap code comes from the file
 428 .Pa newboot
 429 in the current working directory:
 430 .Pp
 431 .Dl "bsdlabel -w -B -b newboot /dev/da0s1"
 432 .Pp
 433 Completely wipe any prior information on the disk, creating a new bootable
 434 disk with a
 435 .Tn DOS
 436 partition table containing one slice, covering the whole disk.
 437 Initialize the label on this slice,
 438 then edit it.
 439 The
 440 .Xr dd 1
 441 commands are optional, but may be necessary for some
 442 .Tn BIOS Ns es
 443 to properly
 444 recognize the disk:
 445 .Bd -literal -offset indent
 446 dd if=/dev/zero of=/dev/da0 bs=512 count=32
 447 fdisk -BI da0
 448 dd if=/dev/zero of=/dev/da0s1 bs=512 count=32
 449 bsdlabel -w -B da0s1
 450 bsdlabel -e da0s1
 451 .Ed
 452 .Pp
 453 This is an example disk label that uses some of the new partition size types
 454 such as
 455 .Cm % , M , G ,
 456 and
 457 .Cm * ,
 458 which could be used as a source file for
 459 .Dq Li "bsdlabel -R ad0s1 new_label_file" :
 460 .Bd -literal -offset 4n
 461 # /dev/ad0s1:
 462
 463 8 partitions:
 464 #        size   offset    fstype   [fsize bsize bps/cpg]
 465   a:   400M       16    4.2BSD     4096 16384    75     # (Cyl.    0 - 812*)
 466   b:     1G        *      swap
 467   c:      *        *    unused
 468   e: 204800        *    4.2BSD
 469   f:     5g        *    4.2BSD
 470   g:      *        *    4.2BSD
 471 .Ed
 472 .Sh DIAGNOSTICS
 473 The kernel device drivers will not allow the size of a disk partition
 474 to be decreased or the offset of a partition to be changed while it is open.
 475 .Sh COMPATIBILITY
 476 Due to the use of an
 477 .Vt u_int32_t
 478 to store the number of sectors,
 479 .Bx
 480 labels are restricted to a maximum of 2^32-1 sectors.
 481 This usually means 2TB of disk space.
 482 Larger disks should be partitioned using another method such as
 483 .Xr gpt 8 .
 484 .Pp
 485 The various
 486 .Bx Ns s
 487 all use slightly different versions of
 488 .Bx
 489 labels and
 490 are not generally compatible.
 491 .Sh SEE ALSO
 492 .Xr ccd 4 ,
 493 .Xr geom 4 ,
 494 .Xr md 4 ,
 495 .\" Xr bsdlabel 5 ,
 496 .Xr disktab 5 ,
 497 .Xr boot0cfg 8 ,
 498 .Xr fdisk 8 ,
 499 .Xr gpt 8 ,
 500 .Xr newfs 8