FreeBSD-5.3/sbin/sunlabel/sunlabel.8

.\" 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
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/sbin/sunlabel/sunlabel.8,v 1.4 2004/06/02 20:21:28 joerg Exp $
.\"
.Dd June 1, 2004
.Dt SUNLABEL 8
.Os
.Sh NAME
.Nm sunlabel
.Nd read and write disk pack label suitable for Sun's OpenBoot PROM
.Sh SYNOPSIS
.Nm
.Op Fl r
.Op Fl c No \&| Fl h
.Ar disk
.Nm
.Fl B
.Op Fl b Ar boot1
.Op Fl n
.Ar disk
.Nm
.Fl R
.Op Fl B Op Fl b Ar boot1
.Op Fl r
.Op Fl n
.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
.Em Sun OpenBoot PROM
label on a disk.
In addition,
.Nm
can install bootstrap code.
.Ss Introduction
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
.Tn 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
.Dq Li 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 Li 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 , R ,
or
.Fl w
options are present, the existing label for
.Ar disk
will be printed to standard output.
.Pp
The
.Ar disk
argument
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 given the opportunity 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:
.Bl -tag -width indent
.It Sy Textual label, geometry emulation
The line
.D1 Li text: Ar XXXX Li cyl Ar CC Li alt 2 hd Ar HH Li sec Ar SS
represents the label text.
It must be retained exactly in the form shown.
The editable text
.Ar XXXX
is a simple (non-whitespace) text describing the disk.
By convention, this text mentions the approximate size of the
disk, as in
.Dq Li SUN9.0G
for a 9 GB disk shipped by Sun.
.Pp
The values
.Ar CC ,
.Ar HH ,
and
.Ar SS
describe the number of cylinders, heads (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
.Dq Li 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
.Dq Li 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 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.