1.\" $OpenBSD: disklabel.8,v 1.41 2001/08/07 01:46:12 millert Exp $ 2.\" $NetBSD: disklabel.8,v 1.9 1995/03/18 14:54:38 cgd Exp $ 3.\" 4.\" Copyright (c) 1987, 1988, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" Symmetric Computer Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)disklabel.8 8.2 (Berkeley) 4/19/94 39.\" 40.Dd October 27, 1997 41.Dt DISKLABEL 8 42.Os 43.Sh NAME 44.Nm disklabel 45.Nd read and write disk pack label 46.Sh SYNOPSIS 47.Nm disklabel 48.Op Fl n 49.Op Fl cd Li \&| Fl r 50.Op Fl t 51.Op Fl v 52.Ar disk 53.Nm disklabel 54.Fl w 55.Op Fl n 56.Op Fl cd Li \&| Fl r 57.Op Fl v 58.Ar disk Ar disktype 59.Oo Ar packid Oc 60.Nm disklabel 61.Fl e 62.Op Fl n 63.Op Fl cd Li \&| Fl r 64.Op Fl v 65.Ar disk 66.Nm disklabel 67.Fl E 68.Op Fl f Ar tempfile 69.Op Fl n 70.Op Fl cd Li \&| Fl r 71.Op Fl v 72.Ar disk 73.Nm disklabel 74.Fl R 75.Op Fl r 76.Op Fl n 77.Op Fl v 78.Ar disk Ar protofile 79.Nm disklabel 80.Op Fl NW 81.Op Fl n 82.Op Fl v 83.Ar disk 84.Pp 85.Nm disklabel 86.Fl B 87.Op Fl n 88.Op Fl v 89.Oo 90.Fl b Ar boot1 91.Op Fl s Ar boot2 92.Oc 93.Ar disk 94.Oo Ar disktype Oc 95.Nm disklabel 96.Fl w 97.Fl B 98.Op Fl n 99.Op Fl v 100.Oo 101.Fl b Ar boot1 102.Op Fl s Ar boot2 103.Oc 104.Ar disk Ar disktype 105.Oo Ar packid Oc 106.Nm disklabel 107.Fl R 108.Fl B 109.Op Fl n 110.Op Fl v 111.Oo 112.Fl b Ar boot1 113.Op Fl s Ar boot2 114.Oc 115.Ar disk Ar protofile 116.Oo Ar disktype Oc 117.Sh DESCRIPTION 118The 119.Nm 120utility can be used to install, examine, or modify the label on a disk drive or 121pack. 122The disk label contains information about disk characteristics (size, 123type, etc.) and the partition layout, stored on the disk 124itself. 125It is used by the operating system to optimize disk I/O and 126locate the filesystems resident on the disk. 127.Pp 128The options are as follows: 129.Bl -tag -width Ds 130.It Fl n 131Make no permanent changes to the disklabel (useful for debugging 132purposes). 133.It Fl v 134Print additional information during operation (verbose mode). 135.It Fl r 136Causes the label to be read from or written to the disk directly, 137rather than going through the system's in-core copy of the label. 138This option may allow a label to be installed on a disk without kernel 139support for a label, such as when labels are first installed on a 140system. 141This flag does not work on a number of architectures, thus it is 142not considered the right way to put a new label on a disk. 143Its use is discouraged. 144.It Fl B 145Install bootstrap code. 146The 147.Fl r 148flag is implied by 149.Fl B 150and never needs to be specified. 151.It Fl b 152Specify the single level boot program, or the primary boot program, 153depending on the system boot architecture (single or two-level). 154.It Fl s 155On machines with a two-level bootstrap (such as i386-based systems), 156specify the secondary boot program. 157.It Fl d 158Use the 159.Em default 160label. 161This ignores any existing 162.Ox 163partitions on the disk. 164Note that this option will only work for disks 165that are capable of reporting their geometry, such as SCSI, IDE, and ESDI. 166May not be used in conjunction with the 167.Fl r 168flag. 169.It Fl c 170Clear the system's in-core copy of the label and update it based on 171the on-disk label. 172May not be used in conjunction with the 173.Fl r 174flag. 175.It Fl f Ar tempfile 176Write entries to 177.Ar tempfile 178in 179.Xr fstab 5 180format for any partitions for which mount point information has been 181specified. 182The 183.Fl f 184flag is only valid when used in conjunction with the 185.Fl E 186flag. 187If 188.Ar tempfile 189already exists, it will be overwritten. 190.It Fl t 191Format the label as a 192.Xr disktab 5 193entry. 194.It Fl w 195Write a standard label on the designated drive. 196.It Fl e 197Edit an existing disk label using the editor specified in the 198.Ev EDITOR 199environment variable, or 200.Xr vi 1 201if none is specified. 202.It Fl E 203Use a simple initial label editor, using the command-driven built-in 204editor described below. 205.It Fl R 206Restore a disk label that was formatted in a prior operation and 207saved in an 208.Tn ASCII 209file. 210.It Fl N 211Disallow writing of the pack label area on the selected disk. 212.It Fl W 213Allow writing of the pack label area on the selected disk. 214.El 215.Pp 216The first form of the command (read) is used to examine the label on 217the named disk drive (e.g., sd0 or 218.Pa /dev/rsd0c Ns ). 219It will display all of the parameters associated with the drive 220and its partition layout. 221Unless the 222.Fl r 223flag is given, the kernel's in-core copy of the label is displayed; if 224the disk has no label, or the partition types on the disk are 225incorrect, the kernel may have constructed or modified the label. 226.Pp 227The second form of the command (write) is used to write a standard 228label on the designated drive. 229The drive parameters and partitions are taken from that file. 230If different disks of the same physical type are 231to have different partitions, it will be necessary to have separate 232disktab entries describing each, or to edit the label after 233installation as described below. 234The optional argument is a pack 235identification string, up to 16 characters long. 236The pack ID must be quoted if it contains blanks. 237If the 238.Fl r 239flag is given, the disk sectors containing the label and bootstrap 240will be written directly. 241A side-effect of this is that any existing 242bootstrap code will be overwritten and the disk rendered unbootable. 243If 244.Fl r 245is not specified, the existing label will be updated via the in-core 246copy and any bootstrap code will be unaffected. 247If the disk does not already have a label, the 248.Fl r 249flag must be used. 250In either case, the kernel's in-core label is replaced. 251.Pp 252In the third form of the command (edit), the label is read from the 253in-core kernel copy, or directly from the disk if the 254.Fl r 255flag is also given. 256The label is formatted and then supplied to an editor for changes. 257If no editor is specified in an 258.Ev EDITOR 259environment variable, 260.Xr vi 1 261is used. 262When the editor terminates, the formatted label is reread and 263used to rewrite the disk label. 264Existing bootstrap code is unchanged regardless of whether 265.Fl r 266was specified. 267.Pp 268The initial label editor mode is only intended for new disks as it 269will move partitions around as necessary to maintain a contiguous pool 270of free blocks. 271Some commands or prompts take an optional unit. 272Available units are 273.Sq b 274for bytes, 275.Sq c 276for cylinders, 277.Sq k 278for kilobytes, 279.Sq m 280for megabytes, 281and 282.Sq g 283for gigabytes. 284Quantities will be rounded to the nearest 285cylinder when units are specified for sizes (or offsets). 286Commands may be aborted by entering 287.Ql ^D 288(Control-D). 289Entering 290.Ql ^D 291at the main 292.Ql > 293prompt will exit the editor. 294At prompts that request a size, 295.Ql * 296may be entered to indicate the rest of the available space. 297The editor commands are as follows: 298.Bl -tag -width "p [unit] " 299.It ? Op command 300Display help message with all available commands. 301You may specify a 302.Em command 303for which to get more detailed help. 304There is also (simple) context-sensitive help available at most prompts. 305.It M 306Display this manual page. 307.It u 308Undo (or redo) last change. 309Entering 310.Em u 311once will undo your last change. 312Entering it again will restore the change. 313.It p Op unit 314Print the current disk label. 315If a 316.Em unit 317is given, the size and offsets are displayed in terms of the 318specified unit. 319.It e 320Edit drive parameters. 321This option is used to set the following 322parameters: sectors/track, tracks/cylinder, sectors/cylinder, 323number of cylinders on the disk, total sectors on the disk, rpm, 324interleave, disk type, and a descriptive label string. 325.It b 326Set OpenBSD disk boundaries. 327This option tells 328.Nm 329which parts of the disk it is allowed to modify. 330This option is 331probably only useful for ports with fdisk partition tables where the 332ending sector in the MBR is incorrect. 333The user may enter 334.Ql * 335at the 336.Dq Size 337prompt to indicate the entire size of the disk (minus 338the starting sector). 339This is useful for disks larger than 8 340gigabytes where the fdisk partition table is incapable of storing 341the real size. 342.It r 343Recalculate free space. 344This option should really not be necessary under normal circumstances. 345.It a Op part 346Add new partition. 347This option adds a new BSD partition. 348If no partition letter is specified (a-p), the user will be prompted for 349one. 350.It c Op part 351Change the size of an existing partition. 352If no partition is specified, the user will be prompted for one. 353The new size may be 354in terms of the aforementioned units and may also be prefixed with 355.Ql + 356or 357.Ql - 358to change the size by a relative amount. 359.It d Op part 360Delete an existing partition (or 361.Ql * 362to delete all partitions). 363If no partition is specified, the user will be prompted for one. 364You may not delete the 365.Ql c 366partition. 367.It g Op d|b|u 368Set disk geometry based on what the 369.Em disk , 370.Em BIOS , 371or 372.Em user 373thinks (the 374.Em user 375geometry is simply what the label said before 376.Nm 377made any changes). 378.It D 379Sets the disk label to the default values as reported by the kernel. 380This similates the case where there is no disk label. 381.It m Op part 382Modify parameters for an existing partition. 383If no partition is specified, the user will be prompted for one. 384This option allows 385the user to change the filesystem type, starting offset, partition 386size, block fragment size, block size, and cylinders per group for 387the specified partition (not all parameters are configurable for 388non-BSD partitions). 389.It n Op part 390Name the mount point for an existing partition. 391If no partition is specified, the user will be prompted for one. 392This option is only valid if 393.Nm 394was invoked with the 395.Fl f 396flag. 397.It s Op path 398Save the label to a file in 399.Tn ASCII 400format (suitable for loading via 401the 402.Fl R 403option). 404If no path is specified, the user will be prompted for one. 405.It w 406Write the label to disk. 407This option will commit any changes to the on-disk label. 408.It q 409Quit the editor. 410If any changes have been made, the user will be 411asked whether or not to save the changes to the on-disk label. 412.It x 413Exit the editor without saving any changes to the label. 414.It X 415Toggle 416.Dq expert mode . 417By default, some settings are reserved for experts only (such as the 418block and fragment size on ffs partitions). 419.It z 420Zeroes out the existing partition table, leaving only the 421.Dq c 422partition. The drive parameters are not changed. 423.El 424.Pp 425In the restore form of the command, the prototype file used to create 426the label should be in the same format as that produced when reading 427or editing a label. 428Comments are delimited by 429.Ar \&# 430and newline. 431As with 432.Fl w , 433any existing bootstrap code will be clobbered if 434.Fl r 435is specified and will be unaffected otherwise. 436.Pp 437The final three forms of 438.Nm 439are used to install bootstrap code on machines where the bootstrap is 440part of the label. 441The bootstrap code is comprised of one or two boot 442programs depending on the machine. 443.Pp 444When installing bootstrap code with the 445.Fl B 446flag, if the names are not explicitly given, standard boot programs 447will be used. 448The boot programs are located in 449.Pa /usr/mdec . 450The names of the programs are taken from the 451.Dq b0 452and 453.Dq b1 454parameters of the 455.Xr disktab 5 456entry for the disk if 457.Ar disktype 458was given and its disktab entry exists and includes those parameters. 459Otherwise, boot program names are derived from the name of the 460disk. 461These names are of the form 462.Pa basename Ns boot 463for the primary (or only) bootstrap, and 464.Pf boot Pa basename 465for the secondary bootstrap; for example, 466.Pa /usr/mdec/sdboot 467and 468.Pa /usr/mdec/bootsd 469if the disk device is 470.Em sd0 . 471.Pp 472The first of the three boot-installation forms is used to install 473bootstrap code without changing the existing label. 474It is essentially 475a read command with respect to the disk label itself and all options 476are related to the specification of the boot program as described 477previously. 478The final two forms are analogous to the basic write and 479restore versions except that they will install bootstrap code in 480addition to a new label. 481.Pp 482Note that when a disk has no real BSD disklabel the kernel creates a 483default label so that the disk can be used. 484This default label will include other partitions found on the disk if 485they are supported on your architechture. 486For example, on systems that support 487.Xr fdisk 8 488partitions the default label will also include DOS and Linux partitions. 489However, these entries are not dynamic, they are fixed at the time 490.Nm 491is run. 492That means that subsequent changes that affect non-OpenBSD 493partitions will not be present in the default label, though you 494may update them by hand. 495To see the default label, run 496.Nm 497with the 498.Fl d 499flag. 500You can then run 501.Nm 502with the 503.Fl e 504flag and paste any entries you want from the default label into the real 505one. 506.Sh EXAMPLES 507.Dl disklabel sd0 508.Pp 509Display the in-core label for sd0 as obtained via 510.Pa /dev/rsd0c . 511.Pp 512.Dl disklabel -w -r /dev/rsd0c sd2212 foo 513.Pp 514Create a label for sd0 based on information for 515.Dq sd2212 516found in 517.Pa /etc/disktab . 518Any existing bootstrap code will be clobbered. 519(Normally you do not want to use the 520.Fl r 521flag though.) 522.Pp 523.Dl disklabel -e -r sd0 524.Pp 525Read the on-disk label for sd0, edit it and reinstall in-core as 526well as on-disk. 527(Normally you do not want to use the 528.Fl r 529flag 530though.) 531Existing bootstrap code is unaffected. 532.Pp 533.Dl disklabel -R sd0 mylabel 534.Pp 535Restore the on-disk and in-core label for sd0 from information in 536.Pa mylabel . 537Existing bootstrap code is unaffected. 538.Pp 539.Dl disklabel -B sd0 540.Pp 541Install a new bootstrap on sd0. 542The boot code comes from 543.Pa /usr/mdec/sdboot 544and possibly 545.Pa /usr/mdec/bootsd . 546On-disk and in-core labels are unchanged, but on some systems other 547information may be destroyed. 548Use with care. 549.Pp 550.Dl disklabel -w -B /dev/rsd0c -b newboot sd2212 551.Pp 552Install a new label and bootstrap. 553The label is derived from disktab information for 554.Dq sd2212 555and installed both in-core and 556on-disk. 557The bootstrap code comes from the file 558.Pa /usr/mdec/newboot . 559.Sh FILES 560.Bl -tag -width Pa -compact 561.It Pa /etc/disktab 562.It Pa /usr/mdec/ Ns Em xx Ns boot 563.It Pa /usr/mdec/boot Ns Em xx 564.El 565.Sh SEE ALSO 566.Xr disklabel 5 , 567.Xr disktab 5 , 568.Xr scan_ffs 5 569.Sh DIAGNOSTICS 570The kernel device drivers will not allow the size of a disk partition 571to be decreased or the offset of a partition to be changed while 572it is open. 573Some device drivers create a label containing only a 574single large partition if a disk is unlabeled; thus, the label must 575be written to the 576.Sq a 577partition of the disk while it is open. 578This sometimes requires the desired label to be set in two steps, 579the first one creating at least one other partition, and the second 580setting the label on the new partition while shrinking the 581.Sq a 582partition. 583.Pp 584On some machines the bootstrap code may not fit entirely in the 585area allocated for it by some filesystems. 586As a result, it may 587not be possible to have filesystems on some partitions of a 588.Dq bootable 589disk. 590When installing bootstrap code, 591.Nm 592checks for these cases. 593If the installed boot code would overlap a partition of type 594.Dv FS_UNUSED 595it is marked as type 596.Dv FS_BOOT . 597The 598.Xr newfs 8 599utility will disallow creation of filesystems on 600.Dv FS_BOOT 601partitions. 602Conversely, if a partition has a type other than 603.Dv FS_UNUSED 604or 605.Dv FS_BOOT , 606.Nm 607will not install bootstrap code that overlaps it. 608.Sh NOTES 609On i386 machines, 610.Xr installboot 8 611is normally used to install boot code. 612The 613.Fl B 614option to 615.Nm 616can still be used to install old style boot code, 617but this usage is deprecated. 618.Pp 619On some machines, such as the sparc and amiga, partition tables 620may not exhibit the full functionality that is described above. 621.Sh BUGS 622When a disk name is given without a full pathname, the constructed 623device name uses the 624.Sq a 625partition on the tahoe, the 626.Sq c 627partition on all others. 628In 629.Fl E 630mode, 631.Nm 632is far too quick to shuffle partitions around; it should keep a 633free block list and only move partitions around with the user's 634permission. 635Also, in 636.Fl E 637mode, partitions outside the OpenBSD portion of the disk should 638be changeable. 639