1.\" $NetBSD: disklabel.8,v 1.42 2002/10/21 15:54:51 rtr 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 December 14, 2001 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 I 65.Op Fl r 66.Ar disk 67.Nm "" 68.Fl R 69.Op Fl r 70.Ar disk Ar protofile 71.Nm "" 72.Op Fl NW 73.Ar disk 74.sp 75.Nm "" 76.Fl B 77.Op Fl f Ar disktab 78.Oo 79.Fl b Ar boot1 80.Op Fl s Ar boot2 81.Oc 82.Ar disk 83.Oo Ar disktype Oc 84.Nm "" 85.Fl w 86.Fl B 87.Op Fl f Ar disktab 88.Oo 89.Fl b Ar boot1 90.Op Fl s Ar boot2 91.Oc 92.Ar disk Ar disktype 93.Oo Ar packid Oc 94.Nm "" 95.Fl R 96.Fl B 97.Op Fl f Ar disktab 98.Oo 99.Fl b Ar boot1 100.Op Fl s Ar boot2 101.Oc 102.Ar disk Ar protofile 103.Oo Ar disktype Oc 104.Sh DESCRIPTION 105.Nm 106can be used to install, examine or modify the label on a disk drive or pack. 107When writing the label, it can be used 108to change the drive identification, 109the disk partitions on the drive, 110or to replace a damaged label. 111On some systems, 112.Nm 113can be used to install bootstrap code as well. 114.Pp 115There are several forms of the command that read (display), install or edit 116the label on a disk. 117Each form has an additional option, 118.Fl r , 119which causes the label to be read from or written to the disk directly, 120rather than going through the system's in-core copy of the label. 121This option may allow a label to be installed on a disk 122without kernel support for a label, such as when labels are first installed 123on a system; it must be used when first installing a label on a disk. 124Any special effects of the 125.Fl r 126flag are described with the affected commands. 127.Pp 128The read and install forms also support the 129.Fl B 130option to install bootstrap code on some platforms, 131e.g., hp300, vax, and arm32. 132The 133.Fl B 134option is not supported on all platforms. 135These variants are described later. 136.Pp 137The first form of the command (read) is used to examine the label on the named 138disk drive (e.g., sd0 or /dev/rsd0c). 139It will display all of the parameters associated with the drive 140and its partition layout. 141Unless the 142.Fl r 143flag is given, 144the kernel's in-core copy of the label is displayed; 145if the disk has no label, or the partition types on the disk are incorrect, 146the kernel may have constructed or modified the label. 147If the 148.Fl r 149flag is given, the label from the raw disk will be displayed rather 150than the in-core label. 151If the 152.Fl t 153flag is given, then the label will be formatted as a 154.Xr disktab 5 155entry. 156.Pp 157The second form of the command, with the 158.Fl w 159flag, is used to write a standard label on the designated drive. 160The required arguments to 161.Nm 162are the drive to be labelled (e.g. sd0), and 163the drive type as described in the 164.Xr disktab 5 165file. 166The drive parameters and partitions are taken from that file. 167If different disks of the same physical type are to have different 168partitions, it will be necessary to have separate disktab entries 169describing each, or to edit the label after installation as described below. 170The optional argument is a pack identification string, 171up to 16 characters long. 172The pack id must be quoted if it contains blanks. 173If the disk does not already have a label, the 174.Fl r 175flag must be used. 176In either case, the kernel's in-core label is replaced. 177.Pp 178An alternate 179.Xr disktab 5 180file may be specified with the 181.Fl f Ar disktab 182option. 183.Pp 184An existing disk label may be edited by using the 185.Fl e 186flag. 187The label is formatted and then supplied to an editor for changes. 188If no editor is specified in an 189.Ev EDITOR 190environment variable, 191.Xr vi 1 192is used. 193When the editor terminates, the formatted label is reread 194and used to rewrite the disk label. 195.Pp 196Labels can also created interactively using the 197.Fl i 198flag. 199.Pp 200The 201.Fl C 202flag causes the partition offset and size values to be displayed in 203.Aq cylinder/track/sector 204format. 205Note that, regardless of whether 206.Fl C 207was specified, this format is always accepted by 208.Nm 209on input with either the 210.Fl e 211or 212.Fl R 213flag. 214.Pp 215With the 216.Fl R 217flag, 218.Nm 219is capable of restoring a disk label that was formatted 220in a prior operation and saved in an ascii file. 221The prototype file used to create the label should be in the same format 222as that produced when reading or editing a label. 223Comments are delimited by 224.Ar \&# 225and newline. 226.Pp 227The 228.Fl NW 229flags for 230.Nm 231explicitly disallow and 232allow, respectively, writing of the pack label area on the selected disk. 233.Pp 234The final three forms of 235.Nm 236are used to install bootstrap code on machines where the bootstrap is part 237of the label. 238The bootstrap code is composed of one or two boot programs depending on 239the machine. 240The 241.Fl B 242option is used (on some platforms only, see above) to denote that 243bootstrap code is to be installed. 244The 245.Fl r 246flag is implied by 247.Fl B 248and never needs to be specified. 249The name of the boot program(s) to be installed can be selected in a 250variety of ways. 251First, the names can be specified explicitly via the 252.Fl b 253and 254.Fl s 255flags. 256On machines with only a single level of boot program, 257.Fl b 258is the name of that program. 259For machines with a two-level bootstrap, 260.Fl b 261indicates the primary boot program and 262.Fl s 263the secondary boot program. 264If the names are not explicitly given, standard boot programs will be used. 265The boot programs are located in 266.Pa /usr/mdec . 267The names of the programs are taken from the 268.Dq b0 269and 270.Dq b1 271parameters of the 272.Xr disktab 5 273entry for the disk if 274.Ar disktype 275was given and its disktab entry exists and includes those parameters. 276Otherwise, boot program names are derived from the name of the disk. 277These names are of the form 278.Pa basename Ns boot 279for the primary (or only) bootstrap, and 280.Pf boot Pa basename 281for the secondary bootstrap; 282for example, 283.Pa /usr/mdec/sdboot 284and 285.Pa /usr/mdec/bootsd 286if the disk device is 287.Em sd0 . 288.Pp 289The first of the three boot-installation forms is used to install 290bootstrap code without changing the existing label. 291It is essentially a read command with respect to the disk label 292itself and all options are related to the specification of the boot 293program as described previously. 294The final two forms are analogous to the basic write and restore versions 295except that they will install bootstrap code in addition to a new label. 296.Sh FILES 297.Bl -tag -width /usr/mdec/xxboot -compact 298.It Pa /etc/disktab 299.It Pa /usr/mdec/ Ns Em xx Ns boot 300.It Pa /usr/mdec/boot Ns Em xx 301.El 302.Sh EXAMPLES 303.Dl disklabel sd0 304.Pp 305Display the in-core label for sd0 as obtained via 306.Pa /dev/rsd0c . 307.Pp 308.Dl disklabel -w -r /dev/rsd0c sd2212 foo 309.Pp 310Create a label for sd0 based on information for 311.Dq sd2212 312found in 313.Pa /etc/disktab , 314using 315.Pa foo 316as the disk pack label. 317Any existing bootstrap code will be clobbered. 318If you do not have an entry for your disk in 319.Pa /etc/disktab , 320you can use this style to put 321an initial label onto a new disk. 322Then dump the label to a file (using 323.Em disklabel sd0 \*[Gt] 324.Em protofile ) , 325editing the file, and replacing the label with 326.Em disklabel -R sd0 327.Em protofile . 328.Pp 329.Dl disklabel -e -r sd0 330.Pp 331Read the on-disk label for sd0, edit it and reinstall in-core as well 332as on-disk. 333Existing bootstrap code is unaffected. 334.Pp 335.Dl disklabel -e -I sd0 336.Pp 337As previous, but don't fail if there was no label on the disk yet; 338provide some default values instead. 339.Pp 340.Dl disklabel -i -I sd0 341.Pp 342As previous, only use the built-in interactive editor. 343.Pp 344.Dl disklabel -R sd0 mylabel 345.Pp 346Restore the on-disk and in-core label for sd0 from information in 347.Pa mylabel . 348Existing bootstrap code is unaffected. 349.Pp 350.Dl disklabel -B sd0 351.Pp 352Install a new bootstrap on sd0 (only for platforms which support the 353.Fl B 354option, see above). 355The boot code comes from 356.Pa /usr/mdec/sdboot 357and possibly 358.Pa /usr/mdec/bootsd . 359On-disk and in-core labels are unchanged. 360.Pp 361.Dl disklabel -w -B /dev/rsd0c -b newboot sd2212 362.Pp 363Install a new label and bootstrap (on platforms which support the 364.Fl B 365option, see above). 366The label is derived from disktab information for 367.Dq sd2212 368and installed both in-core and on-disk. 369The bootstrap code comes from the file 370.Pa /usr/mdec/newboot . 371.Pp 372.Dl disklabel -R -r sd0 \*[Lt]protofile\*[Gt] 373.Pp 374Install a new label and bootstrap on a disk, from a prototype label 375file. 376This is a good way to install a label on a previously unlabeled 377disk for which no entry appears in 378.Pa /etc/disktab , 379if you create the 380prototype file by dumping some other disk's label to a file and editing 381it appropriately (total size, partition offsets, types, etc.) 382.Sh DIAGNOSTICS 383The kernel device drivers will not allow the size of a disk partition 384to be decreased or the offset of a partition to be changed while it is open. 385Some device drivers create a label containing only a single large partition 386if a disk is unlabeled; thus, the label must be written to the 387.Dq a 388partition of the disk while it is open. 389This sometimes requires the desired label to be set in two steps, 390the first one creating at least one other partition, 391and the second setting the label on the new partition 392while shrinking the 393.Dq a 394partition. 395.Pp 396On some machines the bootstrap code may not fit entirely in the area 397allocated for it by some filesystems. 398As a result, it may not be possible to have filesystems on some partitions 399of a 400.Dq bootable 401disk. 402When installing bootstrap code, 403.Nm 404checks for these cases. 405If the installed boot code would overlap a partition of type FS_UNUSED 406it is marked as type FS_BOOT. 407The 408.Xr newfs 8 409utility will disallow creation of filesystems on FS_BOOT partitions. 410Conversely, if a partition has a type other than FS_UNUSED or FS_BOOT, 411.Nm 412will not install bootstrap code that overlaps it. 413.Sh SEE ALSO 414.Xr disklabel 5 , 415.Xr disktab 5 , 416.Xr fdisk 8 , 417.Xr installboot 8 , 418.Xr mbrlabel 8 419.Sh BUGS 420If the disk partition is not specified in the disk name 421(i.e., 422.Dq xy0 423instead of 424.Dq /dev/rxy0c ) , 425.Nm 426will construct the full pathname of the disk and use the 427.Dq d 428partition on i386, hpcmips, or arc, and the 429.Dq c 430partition on all others. 431.Pp 432On the sparc, sparc64, sun2, and sun3 433.Nx 434systems, the size of each partition must be a multiple of the number 435of sectors per cylinder (i.e., each partition must be an integer 436number of cylinders), or the boot ROMs will declare the label 437invalid and fail to boot the system. 438.Pp 439In addition, the 440.Fl r 441option should never be used on a sparc, sparc64, sun2 or sun3 system 442boot disk - the 443.Nx 444kernel translates the 445.Nx 446disk label into a SunOS compatible format (which is required by the 447boot PROMs) when it writes the label. 448Using the 449.Fl r 450flag causes 451.Nm 452to write directly to disk, and bypass the format translation. 453This will result in a disk label that the PROMs will not recognize, 454and that therefore cannot be booted from. 455