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 March 15, 2003
  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 instructs
 109 .Nm
 110 to use the layout suitable for the specified machine.
 111 .Ss Reading the Disk Label
 112 To examine the label on a disk drive, use
 113 .Nm
 114 without options:
 115 .Pp
 116 .Nm
 117 .Op Fl A
 118 .Op Fl m Ar machine
 119 .Ar disk
 120 .Pp
 121 .Ar disk
 122 represents the disk in question, and may be in the form
 123 .Pa da0
 124 or
 125 .Pa /dev/da0 .
 126 It will display the partition layout.
 127 .Ss Writing a Standard Label
 128 To write a standard label, use the form
 129 .Pp
 130 .Nm
 131 .Fl w
 132 .Op Fl \&An
 133 .Op Fl m Ar machine
 134 .Ar disk
 135 .Op Ar type
 136 .Pp
 137 If the drive type is specified, the entry of that name in the
 138 .Xr disktab 5
 139 file is used; otherwise a default layout is used.
 140 .Ss Editing an Existing Disk Label
 141 To edit an existing disk label, use the form
 142 .Pp
 143 .Nm
 144 .Fl e
 145 .Op Fl \&An
 146 .Op Fl m Ar machine
 147 .Ar disk
 148 .Pp
 149 This command opens the disk label in the default editor, and when the editor
 150 exits, the label is validated and if OK written to disk.
 151 .Ss Restoring a Disk Label From a File
 152 To restore a disk label from a file, use the form
 153 .Pp
 154 .Nm
 155 .Fl R
 156 .Op Fl \&An
 157 .Op Fl m Ar machine
 158 .Ar disk protofile
 159 .Pp
 160 .Nm
 161 is capable of restoring a disk label that was previously saved in a file in
 162 .Tn ASCII
 163 format.
 164 The prototype file used to create the label should be in the same format as that
 165 produced when reading or editing a label.
 166 Comments are delimited by
 167 .Ql #
 168 and newline.
 169 .Ss Installing Bootstraps
 170 If the
 171 .Fl B
 172 argument is specified, bootstrap code will be read from the file
 173 .Pa /boot/boot
 174 and written to the disk.
 175 The
 176 .Fl b Ar boot
 177 argument allows a different file to be used.
 178 .Sh FILES
 179 .Bl -tag -width ".Pa /etc/disktab" -compact
 180 .It Pa /boot/boot
 181 Default boot image.
 182 .It Pa /etc/disktab
 183 Disk description file.
 184 .El
 185 .Sh SAVED FILE FORMAT
 186 The
 187 .Nm
 188 utility
 189 uses an
 190 .Tn ASCII
 191 version of the label when examining, editing, or restoring a disk
 192 label.
 193 The format is:
 194 .Bd -literal -offset 4n
 195
 196 8 partitions:
 197 #        size   offset    fstype   [fsize bsize bps/cpg]
 198   a:    81920        0    4.2BSD     1024  8192    16
 199   b:   160000    81920      swap
 200   c:  1173930        0    unused        0     0         # "raw" part, don't edit
 201 .Ed
 202 .Pp
 203 If the
 204 .Fl A
 205 option is specified, the format is:
 206 .Bd -literal -offset 4n
 207 # /dev/da1c:
 208 type: SCSI
 209 disk: da0s1
 210 label:
 211 flags:
 212 bytes/sector: 512
 213 sectors/track: 51
 214 tracks/cylinder: 19
 215 sectors/cylinder: 969
 216 cylinders: 1211
 217 sectors/unit: 1173930
 218 rpm: 3600
 219 interleave: 1
 220 trackskew: 0
 221 cylinderskew: 0
 222 headswitch: 0           # milliseconds
 223 track-to-track seek: 0  # milliseconds
 224 drivedata: 0
 225
 226 8 partitions:
 227 #        size   offset    fstype   [fsize bsize bps/cpg]
 228   a:    81920        0    4.2BSD     1024  8192    16
 229   b:   160000    81920      swap
 230   c:  1173930        0    unused        0     0         # "raw" part, don't edit
 231 .Ed
 232 .Pp
 233 Lines starting with a
 234 .Ql #
 235 mark are comments.
 236 .Pp
 237 The partition table can have up to 8 entries.
 238 It contains the following information:
 239 .Bl -tag -width indent
 240 .It Ar #
 241 The partition identifier is a single letter in the range
 242 .Ql a
 243 to
 244 .Ql h .
 245 By convention, partition
 246 .Ql c
 247 is reserved to describe the entire disk.
 248 .It Ar size
 249 The size of the partition in sectors,
 250 .Cm K
 251 (kilobytes - 1024),
 252 .Cm M
 253 (megabytes - 1024*1024),
 254 .Cm G
 255 (gigabytes - 1024*1024*1024),
 256 .Cm %
 257 (percentage of free space
 258 .Em after
 259 removing any fixed-size partitions other than partition
 260 .Ql c ) ,
 261 or
 262 .Cm *
 263 (all remaining free space
 264 .Em after
 265 fixed-size and percentage partitions).
 266 For partition
 267 .Ql c ,
 268 a size of
 269 .Cm *
 270 indicates the entire disk.
 271 Lowercase versions of
 272 .Cm K , M ,
 273 and
 274 .Cm G
 275 are allowed.
 276 Size and type should be specified without any spaces between them.
 277 .Pp
 278 Example: 2097152, 1G, 1024M and 1048576K are all the same size
 279 (assuming 512-byte sectors).
 280 .It Ar offset
 281 The offset of the start of the partition from the beginning of the
 282 drive in sectors, or
 283 .Cm *
 284 to have
 285 .Nm
 286 calculate the correct offset to use (the end of the previous partition plus
 287 one, ignoring partition
 288 .Ql c .
 289 For partition
 290 .Ql c ,
 291 .Cm *
 292 will be interpreted as an offset of 0.
 293 .It Ar fstype
 294 Describes the purpose of the partition.
 295 The example shows all currently used partition types.
 296 For
 297 .Tn UFS
 298 file systems and
 299 .Xr ccd 4
 300 partitions, use type
 301 .Cm 4.2BSD .
 302 For Vinum drives, use type
 303 .Cm vinum .
 304 Other common types are
 305 .Cm swap
 306 and
 307 .Cm unused .
 308 By convention, partition
 309 .Ql c
 310 represents the entire slice and should be of type
 311 .Cm unused ,
 312 though
 313 .Nm
 314 does not enforce this convention.
 315 The
 316 .Nm
 317 utility
 318 also knows about a number of other partition types,
 319 none of which are in current use.
 320 (See the definitions starting with
 321 .Dv FS_UNUSED
 322 in
 323 .In sys/disklabel.h
 324 for more details.)
 325 .It Ar fsize
 326 For
 327 .Cm 4.2BSD
 328 and
 329 .Tn LFS
 330 file systems only, the fragment size.
 331 Defaults to 1024 for partitions smaller than 1GB,
 332 4096 for partitions 1GB or larger.
 333 .It Ar bsize
 334 For
 335 .Cm 4.2BSD
 336 and
 337 .Tn LFS
 338 file systems only, the block size.
 339 Defaults to 8192 for partitions smaller than 1GB,
 340 16384 for partitions 1GB or larger.
 341 .It Ar bps/cpg
 342 For
 343 .Cm 4.2BSD
 344 file systems, the number of cylinders in a cylinder group.
 345 For
 346 .Tn LFS
 347 file systems, the segment shift value.
 348 Defaults to 16 for partitions smaller than 1GB,
 349 64 for partitions 1GB or larger.
 350 .El
 351 .Sh EXAMPLES
 352 .Dl "bsdlabel da0s1"
 353 .Pp
 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 > savedlabel"
 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 -w /dev/da0s1"
 370 .Pp
 371 Create a label for
 372 .Pa da0s1 .
 373 .Pp
 374 .Dl "bsdlabel -e da0s1"
 375 .Pp
 376 Read the label for
 377 .Pa da0s1 ,
 378 edit it, and install the result.
 379 .Pp
 380 .Dl "bsdlabel -e -n 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 -w 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 -R da0s1 savedlabel"
 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 -n da0s1 label_layout"
 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 -B da0s1"
 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 -w -B -b newboot /dev/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 .Bd -literal -offset indent
 432 dd if=/dev/zero of=/dev/da0 bs=512 count=32
 433 fdisk -BI da0
 434 dd if=/dev/zero of=/dev/da0s1 bs=512 count=32
 435 bsdlabel -w -B da0s1
 436 bsdlabel -e da0s1
 437 .Ed
 438 .Pp
 439 Completely wipe any prior information on the disk, creating a new bootable
 440 disk with a
 441 .Tn DOS
 442 partition table containing one slice, covering the whole disk.
 443 Initialize the label on this slice,
 444 then edit it.
 445 The
 446 .Xr dd 1
 447 commands are optional, but may be necessary for some
 448 .Tn BIOS Ns es
 449 to properly
 450 recognize the disk.
 451 .Pp
 452 This is an example disk label that uses some of the new partition size types
 453 such as
 454 .Cm % , M , G ,
 455 and
 456 .Cm * ,
 457 which could be used as a source file for
 458 .Dq Li "bsdlabel -R ad0s1c new_label_file" :
 459 .Bd -literal -offset 4n
 460 # /dev/ad0s1c:
 461
 462 8 partitions:
 463 #        size   offset    fstype   [fsize bsize bps/cpg]
 464   a:   400M        0    4.2BSD     4096 16384    75     # (Cyl.    0 - 812*)
 465   b:     1G        *      swap
 466   c:      *        *    unused
 467   e: 204800        *    4.2BSD
 468   f:     5g        *    4.2BSD
 469   g:      *        *    4.2BSD
 470 .Ed
 471 .Sh DIAGNOSTICS
 472 The kernel device drivers will not allow the size of a disk partition
 473 to be decreased or the offset of a partition to be changed while it is open.
 474 .Sh COMPATIBILITY
 475 Due to the use of an
 476 .Vt u_int32_t
 477 to store the number of sectors,
 478 .Bx
 479 labels are restricted to a maximum of 2^32-1 sectors.
 480 This usually means 2TB of disk space.
 481 Larger disks should be partitioned using another method such as
 482 .Xr gpt 8 .
 483 .Pp
 484 The various
 485 .Bx Ns s
 486 all use slightly different versions of
 487 .Bx
 488 labels and
 489 are not generally compatible.
 490 .Sh SEE ALSO
 491 .Xr ccd 4 ,
 492 .Xr geom 4 ,
 493 .Xr md 4 ,
 494 .\" Xr bsdlabel 5 ,
 495 .Xr disktab 5 ,
 496 .Xr boot0cfg 8 ,
 497 .Xr fdisk 8 ,
 498 .Xr gpt 8