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