1.\" Copyright (c) 2004 2.\" David E. O'Brien. All rights reserved. 3.\" Copyright (c) 2004, 2005 4.\" Joerg Wunsch. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd March 30, 2005 30.Dt SUNLABEL 8 31.Os 32.Sh NAME 33.Nm sunlabel 34.Nd read and write disk pack label suitable for Sun's OpenBoot PROM 35.Sh SYNOPSIS 36.Nm 37.Op Fl r 38.Op Fl c No \&| Fl h 39.Ar disk 40.Nm 41.Fl B 42.Op Fl b Ar boot1 43.Op Fl n 44.Ar disk 45.Nm 46.Fl R 47.Op Fl B Op Fl b Ar boot1 48.Op Fl r 49.Op Fl n 50.Op Fl c 51.Ar disk protofile 52.Nm 53.Fl e 54.Op Fl B Op Fl b Ar boot1 55.Op Fl r 56.Op Fl n 57.Op Fl c 58.Ar disk 59.Nm 60.Fl w 61.Op Fl B Op Fl b Ar boot1 62.Op Fl r 63.Op Fl n 64.Op Fl c 65.Ar disk type 66.Sh DESCRIPTION 67The 68.Nm 69utility 70installs, examines or modifies the 71.Em Sun OpenBoot PROM 72label on a disk. 73In addition, 74.Nm 75can install bootstrap code. 76.Ss Introduction 77The label occupies the first sector (i.e., 512 bytes) of each disk. 78It starts with a textual description which by convention also mentions 79the disk geometry in textual form (number of cylinders, alternate 80cylinders, heads, and sectors per track), optionally followed by a 81table of SVR4-compatible VTOC tags and flags per partition, followed 82by the partition table itself. 83Finally, a checksum is recorded to ensure the label has not been 84tampered with. 85.Pp 86The 87.Em Sun OpenBoot PROM 88label allows for 8 disk partitions. 89The partition table lists the starting cylinder of the partition, 90plus the size of the partition in 512-byte sectors. 91Thus, partitions in the 92.Em Sun OpenBoot PROM 93must always start at a cylinder boundary (for whatever geometry 94emulation has been chosen). 95.Pp 96The optional SVR4-compatible VTOC tag and flags table is not used 97by the 98.Fx 99kernel. 100It is maintained solely for compatibility with the 101.Tn Solaris 102operating system that might share disks with 103.Fx 104on the same hardware platform. 105.Pp 106The 107.Em Sun OpenBoot PROM 108label is natively understood by the underlying hardware, which can 109bootstrap from a single partition entry, as opposed to the very first 110block(s) of the entire disk as on many other hardware platforms. 111.Pp 112Note that the hardware platform mandates that two cylinders are set 113aside as 114.Em alternate cylinders 115which are not available to user programs (and not even through the 116.Dq Li backup 117partition). 118.Ss Options 119Options are listed in alphabetical order here. 120Note that only those option combinations listed under 121.Sx SYNOPSIS 122are allowable. 123.Bl -tag -width ".Fl b Ar bootpath" 124.It Fl b Ar bootpath 125Specify that 126.Ar bootpath 127is to be used as the boot image, rather than the default of 128.Pa /boot/boot1 . 129.It Fl B 130Install bootstrap code onto the disk. 131Note that since the underlying hardware platform bootstraps from 132partitions, not disks, this operation is only useful if there is 133a partition starting at offset 0. 134.It Fl c 135Use cylinders for partition size display rather than 136(512-byte) sectors. 137This also changes the default interpretation of the partition 138size entries when editing the label, or reading from a prototype 139file. 140Thus, prototype files are only compatible when both, obtaining 141the file and re-installing it is done using the same 142.Fl c 143option setting. 144.It Fl e 145Enter edit mode. 146See 147.Sx Edit mode 148below for a more detailed explanation. 149.It Fl h 150When displaying the label, make the partition size and offset 151values 152.Dq human readable . 153The displayed numbers will get a suffix of 154.Ql B 155for bytes, 156.Ql K 157for 1024 bytes each, 158.Ql M 159for 1048576 bytes each, or 160.Ql G 161for 1073741824 bytes each appended. 162Note that due to possible rounding errors, prototype files 163obtained using the 164.Fl h 165option are not suited for re-installing using the 166.Fl R 167option. 168.It Fl n 169No changes. 170All operations, checks etc., are performed normally, but nothing 171is written to disk. 172.It Fl r 173Obsolete option that used to indicate that the operation should 174be done directly on disk, as opposed through the respective kernel 175services. 176Ignored. 177.It Fl R 178Restore label from the prototype in 179.Ar protofile . 180A prototype file is simply the textual representation of the 181label as printed using the first form of the 182.Nm 183utility shown in the 184.Sx SYNOPSIS . 185Note that the 186.Fl c 187option used to obtain the prototype must match the option used 188when restoring the label (both present, or both absent). 189.It Fl w 190Write mode. 191Suitable to write an initial label to disk. 192The 193.Ar type 194argument used to be an entry into a table of predefined labels, 195but this functionality is not supported by 196.Nm . 197Instead, the only allowable 198.Ar type 199argument is the string 200.Dq Li auto , 201indicating that an automatically created label should be written 202to disk. 203This automatism will try to create an initial label that fits as 204best as possible into the available disk capacity. 205.El 206.Pp 207If neither of the 208.Fl e , R , 209or 210.Fl w 211options are present, the existing label for 212.Ar disk 213will be printed to standard output. 214.Pp 215The 216.Ar disk 217argument 218must be given as a plain disk name, without any leading 219.Pa /dev/ . 220.Ss Edit mode 221In edit mode, the existing label from 222.Ar disk 223will be read, and put into a template file. 224The command referenced by the 225.Ev EDITOR 226environmental variable will be started to allow the user 227to edit the label. 228The label is then checked and examined for any errors. 229If no errors have been found, the new label is written to disk. 230If there were any errors, a message is printed to standard 231error output, and the user is given the opportunity to edit 232the template file again. 233If accepted, editing starts over. 234If declined, no changes will 235be written to disk. 236.Pp 237The label presented for editing is the same as the standard 238printout, with some added hints about the possible options to 239specify the sector size and starting cylinder. 240The following areas in the template can be edited: 241.Bl -tag -width indent 242.It Sy Textual label, geometry emulation 243The line 244.D1 Li text: Ar XXXX Li cyl Ar CC Li alt 2 hd Ar HH Li sec Ar SS 245represents the label text. 246It must be retained exactly in the form shown. 247The editable text 248.Ar XXXX 249is a simple (non-whitespace) text describing the disk. 250By convention, this text mentions the approximate size of the 251disk, as in 252.Dq Li SUN9.0G 253for a 9 GB disk shipped by Sun. 254.Pp 255The values 256.Ar CC , 257.Ar HH , 258and 259.Ar SS 260describe the number of cylinders, heads (tracks per 261cylinder), and sectors per track respectively. 262They might be modified to change the geometry emulation. 263Each number must be between 1 and 65535. 264The product 265.D1 Em (CC + 2) * HH * SS 266must be less than or equal to the total number of sectors of the 267disk (which is given as a hint in a comment field). 268.It Sy Volume name 269The volume name (if present) is introduced by the string 270.Dq "volume name:" . 271It can be up to 8 characters long, and might be useful to distinguish 272different disks in a system. 273Note that volume names require the VTOC elements to be present, so 274any of the VTOC constraints described below need to be obeyed as well 275if a volume name is to be set. 276Setting an empty volume name will delete it from the label. 277.It Sy Partition entries 278Partition entries start with a letter from 279.Ql a 280through 281.Ql h , 282immediately followed by a colon, followed by the size of this 283partition, and the starting cylinder of the partition. 284The unit of the size field defaults to sectors, or to cylinders 285if the 286.Fl c 287option is in effect. 288Alternatively, a different unit may be specified by appending 289.Ql s 290for (512-byte) sectors, 291.Ql c 292for cylinders, 293.Ql k 294for kilobytes, 295.Ql m 296for megabytes, or 297.Ql g 298for gigabytes. 299The last partition entry may specify the size as 300.Ql * 301to indicate that this entry should consume the rest of disk not 302consumed by any other partition so far. 303.Pp 304The start of partition is always taken as a cylinder number (starting 305at 0) since this is what the underlying hardware uses. 306Alternatively, specifying it as 307.Ql * 308will make the computation automatically chose the nearest possible 309cylinder boundary. 310.Pp 311Partition 312.Ql c 313must always be present, must start at 0, and must cover the entire 314disk (without considering the alternate cylinders though). 315.Pp 316Optionally, each partition entry may be followed by an SVR4-compatible 317VTOC tag name, and a flag description. 318The following VTOC tag names are known: 319.Bl -column -offset indent ".Li unassigned" ".Sy value" ".Sy comment" 320.It Sy name Ta Sy value Ta Sy comment 321.It Li unassigned Ta No 0x00 Ta \& 322.It Li boot Ta No 0x01 Ta \& 323.It Li root Ta No 0x02 Ta \& 324.It Li swap Ta No 0x03 Ta \& 325.It Li usr Ta No 0x04 Ta \& 326.It Li backup Ta No 0x05 Ta c partition, entire disk 327.It Li stand Ta No 0x06 Ta \& 328.It Li var Ta No 0x07 Ta \& 329.It Li home Ta No 0x08 Ta \& 330.It Li altsctr Ta No 0x09 Ta alternate sector partition 331.It Li cache Ta No 0x0a Ta Solaris cachefs partition 332.It Li VxVM_pub Ta No 0x0e Ta VxVM public region 333.It Li VxVM_priv Ta No 0x0f Ta VxVM private region 334.El 335.Pp 336The following VTOC flags are known: 337.Bl -column -offset indent ".Sy name" ".Sy value" ".Sy comment" 338.It Sy name Ta Sy value Ta Sy comment 339.It Li wm Ta No 0x00 Ta read/write, mountable 340.It Li wu Ta No 0x01 Ta read/write, unmountable 341.It Li rm Ta No 0x10 Ta read/only, mountable 342.It Li ru Ta No 0x11 Ta read/only, unmountable 343.El 344.Pp 345Optionally, both the tag and/or the flag name may be specified 346numerically, using standard 347.Ql C 348numerical notation (prefix 349.Ql 0x 350for hexadecimal numbers, 351.Ql 0 352for octal numbers). 353If the flag field is omitted, it defaults to 354.Ql wm . 355If the tag field is also omitted, it defaults to 356.Dq Li unassigned . 357If none of the partitions lists any VTOC tag/flags, no 358SVR4-compatible VTOC elements will be written to disk. 359If VTOC-style elements are present, partition 360.Ql c 361must be marked as 362.Dq Li backup 363(and should be marked 364.Ql wu ) . 365.El 366.Pp 367When checking the label, partition 368.Ql c 369is checked for presence, and for the mentioned restrictions. 370All other partitions are checked for possible overlaps, as 371well as for not extending past the end of unit. 372If VTOC-style elements are present, overlaps of unmountable 373partitions against other partitions will be warned still but 374do not cause a rejection of the label. 375That way, 376.Em encapsulated disks 377of volume management software are acceptable as long as the 378volume management partitions are clearly marked as unmountable. 379.Pp 380Any other fields in the label template are informational only, 381and will not be parsed when reading the label. 382.Pp 383Note that when changing the geometry emulation by editing the 384textual description line, all partition entries will be 385considered based on the new geometry emulation. 386.Sh ENVIRONMENT 387.Bl -tag -width ".Ev EDITOR" -compact 388.It Ev EDITOR 389Name of the command to edit the template file in edit-mode. 390Defaults to 391.Xr vi 1 . 392.El 393.Sh FILES 394.Bl -tag -width ".Pa /boot/boot1" -compact 395.It Pa /boot/boot1 396Default boot image. 397.El 398.Sh SEE ALSO 399.Xr vi 1 , 400.Xr geom 4 , 401.Xr bsdlabel 8 402.Sh HISTORY 403The 404.Nm 405utility appeared in 406.Fx 5.1 . 407.Sh AUTHORS 408The 409.Nm 410utility was written by 411.An Jake Burkholder , 412modeling it after the 413.Xr bsdlabel 8 414command available on other architectures. 415.Pp 416.An -nosplit 417This man page was initially written by 418.An David O'Brien , 419and later substantially updated by 420.An J\(:org Wunsch . 421.Sh BUGS 422Installing bootstrap code onto an entire disk is merely pointless. 423.Nm 424should rather support installing bootstrap code into a partition 425instead. 426.Pp 427The 428.Dq auto 429layout algorithm could be smarter. 430By now, it tends to emulate fairly large cylinders which due to 431the two reserved alternate cylinders causes a fair amount of 432wasted disk space. 433