1.\" $NetBSD: disklabel.8,v 1.39 2002/02/08 01:30:43 ross Exp $ 2.\" 3.\" Copyright (c) 1987, 1988, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Symmetric Computer Systems. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the University of 20.\" California, Berkeley and its contributors. 21.\" 4. Neither the name of the University nor the names of its contributors 22.\" may be used to endorse or promote products derived from this software 23.\" without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 29.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35.\" SUCH DAMAGE. 36.\" 37.\" @(#)disklabel.8 8.2 (Berkeley) 4/19/94 38.\" 39.Dd April 19, 1994 40.Dt DISKLABEL 8 41.Os 42.Sh NAME 43.Nm disklabel 44.Nd read and write disk pack label 45.Sh SYNOPSIS 46.Nm "" 47.Op Fl rt 48.Op Fl C 49.Ar disk 50.Nm "" 51.Fl w 52.Op Fl r 53.Op Fl f Ar disktab 54.Ar disk Ar disktype 55.Oo Ar packid Oc 56.Nm "" 57.Fl e 58.Op Fl r 59.Op Fl I 60.Op Fl C 61.Ar disk 62.Nm "" 63.Fl I 64.Op Fl r 65.Op Fl C 66.Ar disk 67.Nm "" 68.Fl i 69.Op Fl I 70.Op Fl r 71.Ar disk 72.Nm "" 73.Fl R 74.Op Fl r 75.Ar disk Ar protofile 76.Nm "" 77.Op Fl NW 78.Ar disk 79.sp 80.Nm "" 81.Fl B 82.Op Fl f Ar disktab 83.Oo 84.Fl b Ar boot1 85.Op Fl s Ar boot2 86.Oc 87.Ar disk 88.Oo Ar disktype Oc 89.Nm "" 90.Fl w 91.Fl B 92.Op Fl f Ar disktab 93.Oo 94.Fl b Ar boot1 95.Op Fl s Ar boot2 96.Oc 97.Ar disk Ar disktype 98.Oo Ar packid Oc 99.Nm "" 100.Fl R 101.Fl B 102.Op Fl f Ar disktab 103.Oo 104.Fl b Ar boot1 105.Op Fl s Ar boot2 106.Oc 107.Ar disk Ar protofile 108.Oo Ar disktype Oc 109.Sh DESCRIPTION 110.Nm 111can be used to install, examine or modify the label on a disk drive or pack. 112When writing the label, it can be used 113to change the drive identification, 114the disk partitions on the drive, 115or to replace a damaged label. 116On some systems, 117.Nm 118can be used to install bootstrap code as well. 119.Pp 120There are several forms of the command that read (display), install or edit 121the label on a disk. 122Each form has an additional option, 123.Fl r , 124which causes the label to be read from or written to the disk directly, 125rather than going through the system's in-core copy of the label. 126This option may allow a label to be installed on a disk 127without kernel support for a label, such as when labels are first installed 128on a system; it must be used when first installing a label on a disk. 129Any special effects of the 130.Fl r 131flag are described with the affected commands. 132.Pp 133The read and install forms also support the 134.Fl B 135option to install bootstrap code on some platforms, 136e.g. hp300, vax, and arm32. 137The 138.Fl B 139option is not supported on all platforms. 140These variants are described later. 141.Pp 142The first form of the command (read) is used to examine the label on the named 143disk drive (e.g. sd0 or /dev/rsd0c). 144It will display all of the parameters associated with the drive 145and its partition layout. 146Unless the 147.Fl r 148flag is given, 149the kernel's in-core copy of the label is displayed; 150if the disk has no label, or the partition types on the disk are incorrect, 151the kernel may have constructed or modified the label. 152If the 153.Fl r 154flag is given, the label from the raw disk will be displayed rather 155than the in-core label. 156If the 157.Fl t 158flag is given, then the label will be formatted as a 159.Xr disktab 5 160entry. 161.Pp 162The second form of the command, with the 163.Fl w 164flag, is used to write a standard label on the designated drive. 165The required arguments to 166.Nm 167are the drive to be labelled (e.g. sd0), and 168the drive type as described in the 169.Xr disktab 5 170file. 171The drive parameters and partitions are taken from that file. 172If different disks of the same physical type are to have different 173partitions, it will be necessary to have separate disktab entries 174describing each, or to edit the label after installation as described below. 175The optional argument is a pack identification string, 176up to 16 characters long. 177The pack id must be quoted if it contains blanks. 178If the disk does not already have a label, the 179.Fl r 180flag must be used. 181In either case, the kernel's in-core label is replaced. 182.Pp 183An alternate 184.Xr disktab 5 185file may be specified with the 186.Fl f Ar disktab 187option. 188.Pp 189An existing disk label may be edited by using the 190.Fl e 191flag. 192The label is formatted and then supplied to an editor for changes. 193If no editor is specified in an 194.Ev EDITOR 195environment variable, 196.Xr vi 1 197is used. 198When the editor terminates, the formatted label is reread 199and used to rewrite the disk label. 200.Pp 201Labels can also created interactively using the 202.Fl i 203flag. 204.Pp 205The 206.Fl C 207flag causes the partition offset and size values to be displayed in 208.Aq cylinder/track/sector 209format. Note that, regardless of whether 210.Fl C 211was specified, this format is always accepted by 212.Nm 213on input with either the 214.Fl e 215or 216.Fl R 217flag. 218.Pp 219With the 220.Fl R 221flag, 222.Nm 223is capable of restoring a disk label that was formatted 224in a prior operation and saved in an ascii file. 225The prototype file used to create the label should be in the same format 226as that produced when reading or editing a label. 227Comments are delimited by 228.Ar \&# 229and newline. 230.Pp 231The 232.Fl NW 233flags for 234.Nm 235explicitly disallow and 236allow, respectively, writing of the pack label area on the selected disk. 237.Pp 238The final three forms of 239.Nm 240are used to install bootstrap code on machines where the bootstrap is part 241of the label. 242The bootstrap code is composed of one or two boot programs depending on 243the machine. 244The 245.Fl B 246option is used (on some platforms only, see above) to denote that 247bootstrap code is to be installed. 248The 249.Fl r 250flag is implied by 251.Fl B 252and never needs to be specified. 253The name of the boot program(s) to be installed can be selected in a 254variety of ways. 255First, the names can be specified explicitly via the 256.Fl b 257and 258.Fl s 259flags. 260On machines with only a single level of boot program, 261.Fl b 262is the name of that program. 263For machines with a two-level bootstrap, 264.Fl b 265indicates the primary boot program and 266.Fl s 267the secondary boot program. 268If the names are not explicitly given, standard boot programs will be used. 269The boot programs are located in 270.Pa /usr/mdec . 271The names of the programs are taken from the ``b0'' and ``b1'' parameters 272of the 273.Xr disktab 5 274entry for the disk if 275.Ar disktype 276was given and its disktab entry exists and includes those parameters. 277Otherwise, boot program names are derived from the name of the disk. 278These names are of the form 279.Pa basename Ns boot 280for the primary (or only) bootstrap, and 281.Pf boot Pa basename 282for the secondary bootstrap; 283for example, 284.Pa /usr/mdec/sdboot 285and 286.Pa /usr/mdec/bootsd 287if the disk device is 288.Em sd0 . 289.Pp 290The first of the three boot-installation forms is used to install 291bootstrap code without changing the existing label. 292It is essentially a read command with respect to the disk label 293itself and all options are related to the specification of the boot 294program as described previously. 295The final two forms are analogous to the basic write and restore versions 296except that they will install bootstrap code in addition to a new label. 297.Sh FILES 298.Bl -tag -width Pa -compact 299.It Pa /etc/disktab 300.It Pa /usr/mdec/ Ns Em xx Ns boot 301.It Pa /usr/mdec/boot Ns Em xx 302.El 303.Sh EXAMPLES 304.Dl disklabel sd0 305.Pp 306Display the in-core label for sd0 as obtained via 307.Pa /dev/rsd0c . 308.Pp 309.Dl disklabel -w -r /dev/rsd0c sd2212 foo 310.Pp 311Create a label for sd0 based on information for ``sd2212'' found in 312.Pa /etc/disktab , 313using 314.Pa foo 315as the disk pack label. 316Any existing bootstrap code will be clobbered. If you do not have an 317entry for your disk in 318.Pa /etc/disktab , 319you can use this style to put 320an initial label onto a new disk. Then dump the label to a file (using 321.Em disklabel sd0 \*[Gt] 322.Em protofile ) , 323editing the file, and replacing the label with 324.Em disklabel -R sd0 325.Em protofile . 326.Pp 327.Dl disklabel -e -r sd0 328.Pp 329Read the on-disk label for sd0, edit it and reinstall in-core as well 330as on-disk. 331Existing bootstrap code is unaffected. 332.Pp 333.Dl disklabel -e -I sd0 334.Pp 335As previous, but don't fail if there was no label on the disk yet; 336provide some default values instead. 337.Pp 338.Dl disklabel -i -I sd0 339.Pp 340As previous, only use the built-in interactive editor. 341.Pp 342.Dl disklabel -R sd0 mylabel 343.Pp 344Restore the on-disk and in-core label for sd0 from information in 345.Pa mylabel . 346Existing bootstrap code is unaffected. 347.Pp 348.Dl disklabel -B sd0 349.Pp 350Install a new bootstrap on sd0 (only for platforms which support the 351.Fl B 352option, see above). 353The boot code comes from 354.Pa /usr/mdec/sdboot 355and possibly 356.Pa /usr/mdec/bootsd . 357On-disk and in-core labels are unchanged. 358.Pp 359.Dl disklabel -w -B /dev/rsd0c -b newboot sd2212 360.Pp 361Install a new label and bootstrap (on platforms which support the 362.Fl B 363option, see above). 364The label is derived from disktab information for ``sd2212'' and 365installed both in-core and on-disk. 366The bootstrap code comes from the file 367.Pa /usr/mdec/newboot . 368.Pp 369.Dl disklabel -R -r sd0 \*[Lt]protofile\*[Gt] 370.Pp 371Install a new label and bootstrap on a disk, from a prototype label 372file. This is a good way to install a label on a previously unlabeled 373disk for which no entry appears in 374.Pa /etc/disktab , 375if you create the 376prototype file by dumping some other disk's label to a file and editing 377it appropriately (total size, partition offsets, types, etc.) 378.Sh DIAGNOSTICS 379The kernel device drivers will not allow the size of a disk partition 380to be decreased or the offset of a partition to be changed while it is open. 381Some device drivers create a label containing only a single large partition 382if a disk is unlabeled; thus, the label must be written to the ``a'' 383partition of the disk while it is open. 384This sometimes requires the desired label to be set in two steps, 385the first one creating at least one other partition, 386and the second setting the label on the new partition 387while shrinking the ``a'' partition. 388.Pp 389On some machines the bootstrap code may not fit entirely in the area 390allocated for it by some filesystems. 391As a result, it may not be possible to have filesystems on some partitions 392of a ``bootable'' disk. 393When installing bootstrap code, 394.Nm 395checks for these cases. 396If the installed boot code would overlap a partition of type FS_UNUSED 397it is marked as type FS_BOOT. 398The 399.Xr newfs 8 400utility will disallow creation of filesystems on FS_BOOT partitions. 401Conversely, if a partition has a type other than FS_UNUSED or FS_BOOT, 402.Nm 403will not install bootstrap code that overlaps it. 404.Sh SEE ALSO 405.Xr disklabel 5 , 406.Xr disktab 5 , 407.Xr fdisk 8 , 408.Xr installboot 8 , 409.Xr mbrlabel 8 410.Sh BUGS 411If the disk partition is not specified in the disk name 412(i.e. ``xy0'' instead of ``/dev/rxy0c''), 413.Nm 414will construct the full pathname of the disk and use 415the ``a'' partition on the tahoe, 416the ``d'' partition on i386 or hpcmips or arc, and 417the ``c'' partition on all others. 418.Pp 419On the sparc, sparc64, sun2 and sun3 420.Nx 421systems, the size of each partition must be a multiple of the number 422of sectors per cylinder (i.e. each partition must be an integer 423number of cylinders), or the boot ROMs will declare the label 424invalid and fail to boot the system. 425.Pp 426In addition, the 427.Fl r 428option should never be used on a sparc, sparc64, sun2 or sun3 system 429boot disk - the 430.Nx 431kernel translates the 432.Nx 433disk label into a SunOS compatible format (which is required by the 434boot PROMs) when it writes the label. Using the 435.Fl r 436causes 437.Nm 438to write directly to disk, and bypass the format translation. 439This will result in a disk label that the PROMs will not recognize, 440and that therefore cannot be booted from. 441