diff options
Diffstat (limited to 'sbin/sunlabel/sunlabel.8')
| -rw-r--r-- | sbin/sunlabel/sunlabel.8 | 358 |
1 files changed, 352 insertions, 6 deletions
diff --git a/sbin/sunlabel/sunlabel.8 b/sbin/sunlabel/sunlabel.8 index 4e56507..d2d2cff 100644 --- a/sbin/sunlabel/sunlabel.8 +++ b/sbin/sunlabel/sunlabel.8 @@ -1,5 +1,7 @@ .\" Copyright (c) 2004 .\" David E. O'Brien. All rights reserved. +.\" Copyright (c) 2004 +.\" Joerg Wunsch. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -24,7 +26,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 29, 2004 +.Dd June 1, 2004 .Dt SUNLABEL 8 .Os .Sh NAME @@ -33,6 +35,7 @@ .Sh SYNOPSIS .Nm .Op Fl r +.Op Fl c No \&| Fl h .Ar disk .Nm .Fl B @@ -44,35 +47,378 @@ .Op Fl B Op Fl b Ar boot1 .Op Fl r .Op Fl n -.Ar disk profile +.Op Fl c +.Ar disk protofile .Nm .Fl e .Op Fl B Op Fl b Ar boot1 .Op Fl r .Op Fl n +.Op Fl c .Ar disk .Nm .Fl w .Op Fl B Op Fl b Ar boot1 .Op Fl r .Op Fl n +.Op Fl c .Ar disk type .Sh DESCRIPTION The .Nm utility -installs, examines or modifies the bootable -.Fx -label on a disk partition. +installs, examines or modifies the +.Em Sun OpenBoot PROM +label on a disk. In addition, .Nm can install bootstrap code. +.Ss Introduction +.Pp +The label occupies the first sector (i. e. 512 bytes) of each disk. +It starts with a textual description which by convention also mentions +the disk geometry in textual form (number of cylinders, alternate +cylinders, heads, and sectors per track), optionally followed by a +table of SVR4-compatible VTOC tags and flags per partition, followed +by the partition table itself. +Finally, a checksum is recorded to ensure the label has not been +tampered with. +.Pp +The +.Em Sun OpenBoot PROM +label allows for 8 disk partitions. +The partition table lists the starting cylinder of the partition, +plus the size of the partition in 512-byte sectors. +Thus, partitions in the +.Em Sun OpenBoot PROM +must always start at a cylinder boundary (for whatever geometry +emulation has been chosen). +.Pp +The optional SVR4-compatible VTOC tag and flags table is not used +by the +.Fx +kernel. +It is maintained solely for compatibilty with the +.Em Solaris +operating system that might share disks with +.Fx +on the same hardware platform. +.Pp +The +.Em Sun OpenBoot PROM +label is natively understood by the underlying hardware, which can +bootstrap from a single partition entry, as opposed to the very first +block(s) of the entire disk as on many other hardware platforms. +.Pp +Note that the hardware platform mandates that two cylinders are set +aside as +.Em alternate cylinders +which are not available to user programs (and not even through the +.Ql backup +partition). +.Ss Options +Options are listed in alphabetical order here. +Note that only those option combinations listed under +.Sx SYNOPSIS +are allowable. +.Pp +.Bl -tag -width ".Fl b Ar bootpath" +.It Fl b Ar bootpath +Specify that +.Ar bootpath +is to be used as the boot image, rather than the default of +.Pa /boot/boot1 . +.It Fl B +Install bootstrap code onto the disk. +Note that since the underlying hardware platform bootstraps from +partitions, not disks, this operation is only useful if there is +a partition starting at offset 0. +.It Fl c +Use cylinders for partition size display rather than +(512-byte) sectors. +This also changes the default interpretation of the partition +size entries when editing the label, or reading from a prototype +file. +Thus, prototype files are only compatible when both, obtaining +the file and re-installing it is done using the same +.Fl c +option setting. +.It Fl e +Enter edit mode. +See +.Sx Edit mode +below for a more detailed explanation. +.It Fl h +When displaying the label, make the partition size and offset +values +.Dq human readable . +The displayed numbers will get a suffix of +.Ql B +for bytes, +.Ql K +for 1024 bytes each, +.Ql M +for 1048576 bytes each, or +.Ql G +for 1073741824 bytes each appended. +Note that due to possible rounding errors, prototype files +obtained using the +.Fl h +option are not suited for re-installing using the +.Fl R +option. +.It Fl n +No changes. +All operations, checks etc. are performed normally, but nothing +is written to disk. +.It Fl r +Obsolete option that used to indicate that the operation should +be done directly on disk, as opposed through the respective kernel +services. +Ignored. +.It Fl R +Restore label from the prototype in +.Ar protofile . +A prototype file is simply the textual representation of the +label as printed using the first form of the +.Nm +utility shown in the +.Sx SYNOPSIS . +Note that the +.Fl c +option used to obtain the prototype must match the option used +when restoring the label (both present, or both absent). +.It Fl w +Write mode. +Suitable to write an initial label to disk. +The +.Ar type +argument used to be an entry into a table of predefined labels, +but this functionality is not supported by +.Nm . +Instead, the only allowable +.Ar type +argument is the string +.Dq auto , +indicating that an automatically created label should be written +to disk. +This automatism will try to create an initial label that fits as +best as possible into the available disk capacity. +.El +.Pp +If neither of the +.Fl e , +.Fl R , +or +.Fl w +options is present, the existing label for +.Ar disk +will be printed to standard output. +.Pp +.Ar disk +must be given as a plain disk name, without any leading +.Pa /dev/ . +.Ss Edit mode +In edit mode, the existing label from +.Ar disk +will be read, and put into a template file. +The command referenced by the +.Ev EDITOR +environmental variable will be started to allow the user +to edit the label. +The label is then checked and examined for any errors. +If no errors have been found, the new label is written to disk. +If there were any errors, a message is printed to standard +error output, and the user is asked whether they want to edit +the template file again. +If accepted, editing starts over, if declined, no changes will +be written to disk. +.Pp +The label presented for editing is the same as the standard +printout, with some added hints about the possible options to +specify the sector size and starting cylinder. +There are two areas in the template that can be edited: +.Pp +.Bl -tag -width indent +.It Sy Textual label, geometry emulation +The line +.Dl "text: XXXX cyl CC alt 2 hd HH sec SS" +represents the label text. +It must be retained exactly in the form shown. +The editable text +.Sy XXXX +is a simple (non-whitespace) text describing the disk. +By convention, this text mentions the approximate size of the +disk, as in +.Ql SUN9.0G +for a 9 GB disk shipped by Sun. +.Pp +The values +.Sy CC , +.Sy HH , +and +.Sy SS +describe the number of cylinders, heads (aka. tracks per +cylinder), and sectors per track respectively. +They might be modified to change the geometry emulation. +Each number must be between 1 and 65535. +The product +.D1 Em (CC + 2) * HH * SS +must be less than or equal to the total number of sectors of the +disk (which is given as a hint in a comment field). +.It Sy Partition entries +Partition entries start with a letter from +.Ql a +through +.Ql h , +immediately followed by a colon, followed by the size of this +partition, and the starting cylinder of the partition. +The unit of the size field defaults to sectors, or to cylinders +if the +.Fl c +option is in effect. +Alternatively, a different unit may be specified by appending +.Ql s +for (512-byte) sectors, +.Ql c +for cylinders, +.Ql k +for kilobytes, +.Ql m +for megabytes, or +.Ql g +for gigabytes. +The last partition entry may specify the size as +.Ql \&* +to indicate that this entry should consume the rest of disk not +consumed by any other partition so far. +.Pp +The start of partition is always taken as a cylinder number (starting +at 0) since this is what the underlying hardware uses. +Alternatively, specifying it as +.Ql \&* +will make the computation automatically chose the nearest possible +cylinder boundary. +.Pp +Partition +.Ql c +must always be present, must start at 0, and must cover the entire +disk (without considering the alternate cylinders though). +.Pp +Optionally, each partition entry may be followed by an SVR4-compatible +VTOC tag name, and a flag description. +The following VTOC tag names are known: +.Bl -column -offset indent ".Li unassigned" ".Sy value" ".Sy comment" +.It Sy name Ta Sy value Ta Sy comment +.It Li unassigned Ta No 0x00 +.It Li boot Ta No 0x01 +.It Li root Ta No 0x02 +.It Li swap Ta No 0x03 +.It Li usr Ta No 0x04 +.It Li backup Ta No 0x05 Ta c partition, entire disk +.It Li stand Ta No 0x06 +.It Li var Ta No 0x07 +.It Li home Ta No 0x08 +.It Li altsctr Ta No 0x09 Ta alternate sector partition +.It Li cache Ta No 0x0a Ta Solaris cachefs partition +.It Li VxVM_pub Ta No 0x0e Ta VxVM public region +.It Li VxVM_priv Ta No 0x0f Ta VxVM private region +.El +.Pp +The following VTOC flags are known: +.Bl -column -offset indent ".Sy name" ".Sy value" ".Sy comment" +.It Sy name Ta Sy value Ta Sy comment +.It Li wm Ta No 0x00 Ta read/write, mountable +.It Li wu Ta No 0x01 Ta read/write, unmountable +.It Li rm Ta No 0x10 Ta read/only, mountable +.It Li ru Ta No 0x11 Ta read/only, unmountable +.El +.Pp +Optionally, both the tag and/or the flag name may be specified +numerically, using standard +.Ql C +numerial notation (prefix +.Ql 0x +for hexadecimal numbers, +.Ql 0 +for octal numbers). +If the flag field is omitted, it defaults to +.Ql wm . +If the tag field is also omitted, it defaults to +.Ql unassigned . +If none of the partitions lists any VTOC tag/flags, no +SVR4-compatible VTOC elements will be written to disk. +If VTOC-style elements are present, partition +.Ql c +must be marked as +.Ql backup +(and should be marked +.Ql wu ) . +.El +.Pp +When checking the label, partition +.Ql c +is checked for presence, and for the mentioned restrictions. +All other partitions are checked for possible overlaps, as +well as for not extending past the end of unit. +If VTOC-style elements are present, overlaps of unmountable +partitions against other partitions will be warned still but +do not cause a rejection of the label. +That way, +.Em encapsulated disks +of volume management software are acceptable as long as the +volume management partitions are clearly marked as unmountable. +.Pp +Any other fields in the label template are informational only, +and will not be parsed when reading the label. +.Pp +Note that when changing the geometry emulation by editing the +textual description line, all partition entries will be +considered based on the new geometry emulation. +.Sh ENVIRONMENT +.Bl -tag -width ".Ev EDITOR" -compact +.It Ev EDITOR +Name of the command to edit the template file in edit-mode. +Defaults to +.Xr vi 1 . +.El .Sh FILES .Bl -tag -width ".Pa /boot/boot1" -compact .It Pa /boot/boot1 Default boot image. .El .Sh SEE ALSO +.Xr vi 1 , .Xr geom 4 , -.Xr disktab 5 , .Xr bsdlabel 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 5.1 . +.Sh AUTHORS +The +.Nm +utility was written by +.An Jake Burkholder , +modeling it after the +.Xr bsdlabel 8 +command available on other architectures. +.Pp +.An -nosplit +This man page was initially written by +.An David O'Brien , +and later substantially updated by +.An J\(:org Wunsch . +.Sh BUGS +Installing bootstrap code onto an entire disk is merely pointless. +.Nm +should rather support installing bootstrap code into a partition +instead. +.Pp +The +.Dq auto +layout algorithm could be smarter. +By now, it tends to emulate fairly large cylinders which due to +the two reserved alternate cylinders causes a fair amount of +wasted disk space. |
