sunlabel(8)

NAME

sunlabel - read and write disk pack label suitable for Sun's

OpenBoot
PROM

SYNOPSIS

sunlabel [-r] [-c | -h] disk
sunlabel -B [-b boot1] [-n] disk
sunlabel -R [-B [-b boot1]] [-r] [-n] [-c] disk protofile
sunlabel -e [-B [-b boot1]] [-r] [-n] [-c] disk
sunlabel -w [-B [-b boot1]] [-r] [-n] [-c] disk type

DESCRIPTION

The sunlabel utility installs, examines or modifies the Sun

OpenBoot PROM
label on a disk. In addition, sunlabel can install boot

strap code.

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, alter

nate 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 en

sure the label
has not been tampered with.

The 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 Sun

OpenBoot PROM
must always start at a cylinder boundary (for whatever geom

etry emulation
has been chosen).

The optional SVR4-compatible VTOC tag and flags table is not

used by the
FreeBSD kernel. It is maintained solely for compatibilty

with the
Solaris operating system that might share disks with FreeBSD

on the same
hardware platform.

The 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.

Note that the hardware platform mandates that two cylinders

are set aside
as alternate cylinders which are not available to user pro

grams (and not
even through the ``backup'' partition).

Options

Options are listed in alphabetical order here. Note that

only those
option combinations listed under SYNOPSIS are allowable.

-b bootpath Specify that bootpath is to be used as

the boot image,

rather than the default of /boot/boot1.

-B Install bootstrap code onto the disk.

Note that since

the underlying hardware platform boot

straps from partitions, not disks, this operation is on

ly useful if
there is a partition starting at offset

0.

-c Use cylinders for partition size display

rather than

(512-byte) sectors. This also changes

the default
interpretation of the partition size en

tries when
editing the label, or reading from a pro

totype file.
Thus, prototype files are only compatible

when both,
obtaining the file and re-installing it

is done using
the same -c option setting.

-e Enter edit mode. See Edit mode below for

a more

detailed explanation.

-h When displaying the label, make the par

tition size and

offset values ``human readable''. The

displayed numbers will get a suffix of `B' for bytes,

`K' for 1024
bytes each, `M' for 1048576 bytes each,

or `G' for
1073741824 bytes each appended. Note

that due to possible rounding errors, prototype files

obtained using
the -h option are not suited for re-in

stalling using
the -R option.

-n No changes. All operations, checks etc.,

are per

formed normally, but nothing is written

to disk.

-r Obsolete option that used to indicate

that the opera

tion should be done directly on disk, as

opposed
through the respective kernel services.

Ignored.

-R Restore label from the prototype in

protofile. A pro

totype file is simply the textual repre

sentation of
the label as printed using the first form

of the
sunlabel utility shown in the SYNOPSIS.

Note that the
-c option used to obtain the prototype

must match the
option used when restoring the label

(both present, or
both absent).

-w Write mode. Suitable to write an initial

label to

disk. The type argument used to be an

entry into a
table of predefined labels, but this

functionality is
not supported by sunlabel. Instead, the

only allowable type argument is the string ``au

to'', 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.

If neither of the -e, -R, or -w options are present, the ex

isting label
for disk will be printed to standard output.

The disk argument must be given as a plain disk name, with

out any leading
/dev/.

Edit mode

In edit mode, the existing label from disk will be read, and

put into a
template file. The command referenced by the EDITOR envi

ronmental 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.

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. The following areas in the tem

plate can be
edited:

Textual label, geometry emulation

The line

text: XXXX cyl CC alt 2 hd HH sec SS

represents the label text. It must be retained ex

actly in the
form shown. The editable text XXXX is a simple

(non-whitespace)
text describing the disk. By convention, this text

mentions the
approximate size of the disk, as in ``SUN9.0G'' for

a 9 GB disk
shipped by Sun.

The values CC, HH, and SS describe the number of

cylinders, heads
(tracks per cylinder), and sectors per track respec

tively. They
might be modified to change the geometry emulation.

Each number
must be between 1 and 65535. The product

(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).

Volume name

The volume name (if present) is introduced by the

string ``volume
name:''. It can be up to 8 characters long, and

might be useful
to distinguish different disks in a system. Note

that volume
names require the VTOC elements to be present, so

any of the VTOC
constraints described below need to be obeyed as

well if a volume
name is to be set. Setting an empty volume name

will delete it
from the label.

Partition entries

Partition entries start with a letter from `a'

through `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 -c
option is in effect. Alternatively, a different

unit may be
specified by appending `s' for (512-byte) sectors,

`c' for cylinders, `k' for kilobytes, `m' for megabytes, or `g'

for gigabytes.
The last partition entry may specify the size as `*'

to indicate
that this entry should consume the rest of disk not

consumed by
any other partition so far.

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 `*' will make the

computation
automatically chose the nearest possible cylinder

boundary.

Partition `c' must always be present, must start at

0, and must
cover the entire disk (without considering the al

ternate cylinders though).

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:

name value comment
unassigned 0x00
boot 0x01
root 0x02
swap 0x03
usr 0x04
backup 0x05 c partition,

entire disk
stand 0x06
var 0x07
home 0x08
altsctr 0x09 alternate sec

tor partition
cache 0x0a Solaris cachefs

partition
VxVM_pub 0x0e VxVM public re

gion
VxVM_priv 0x0f VxVM private

region

The following VTOC flags are known:

name value comment
wm 0x00 read/write, mountable
wu 0x01 read/write, unmount

able
rm 0x10 read/only, mountable
ru 0x11 read/only, unmount

able

Optionally, both the tag and/or the flag name may be

specified
numerically, using standard `C' numerial notation

(prefix `0x'
for hexadecimal numbers, `0' for octal numbers). If

the flag
field is omitted, it defaults to `wm'. If the tag

field is also
omitted, it defaults to ``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 `c' must be marked as ``backup'' (and

should be marked
`wu').

When checking the label, partition `c' is checked for pres

ence, 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, encapsulated disks of volume

management
software are acceptable as long as the volume management

partitions are
clearly marked as unmountable.

Any other fields in the label template are informational on

ly, and will
not be parsed when reading the label.

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.

ENVIRONMENT

EDITOR Name of the command to edit the template file in

edit-mode.

Defaults to vi(1).

FILES

/boot/boot1 Default boot image.

SEE ALSO

vi(1), geom(4), bsdlabel(8)

HISTORY

The sunlabel utility appeared in FreeBSD 5.1.

AUTHORS

The sunlabel utility was written by Jake Burkholder, model

ing it after
the bsdlabel(8) command available on other architectures.

This man page was initially written by David O'Brien, and

later substantially updated by Jorg Wunsch.

BUGS

Installing bootstrap code onto an entire disk is merely

pointless.
sunlabel should rather support installing bootstrap code in

to a partition
instead.

The ``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.

BSD March 30, 2005

BSD