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