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 bootstrap 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, 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.

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 geometry 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 compatibility 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 programs (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 bootstraps from partitions, not disks, this operation is only 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 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 -c option setting.

-e  Enter edit mode. See Edit mode below for a more detailed explanation.

-h  When displaying the label, make the partition 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-installing using the -R option.

-n  No changes. All operations, checks etc., are performed normally, but nothing is written to disk.

-r  Obsolete option that used to indicate that the operation should be done directly on disk, as opposed through the respective kernel services. Ignored.

-R  Restore label from the prototype in protofile. A prototype file is simply the textual representation 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 “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.

If neither of the -e, -R, or -w options are present, the existing label for disk will be printed to standard output.

The disk argument must be given as a plain disk name, without 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 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.

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 template 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 exactly 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 respectively. 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 alternate 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 sector partition
    cache | 0x0a | Solaris cachefs partition
    VxVM_pub | 0x0e | VxVM public region
    VxVM_priv | 0x0f | VxVM private region

    The following VTOC flags are known:
    name | value | comment
    wm | 0x00 | read/write, mountable
    wu | 0x01 | read/write, unmountable
    rm | 0x10 | read/only, mountable
    ru | 0x11 | read/only, unmountable

    Optionally, both the tag and/or the flag name may be specified numerically, using standard ‘C’ numerical 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 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, 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 only, 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, modeling it after the bsdlabel(8) command available on other architectures.

-nosplit This man page was initially written by David O'Brien, and later substantially updated by Jörg Wunsch.

BUGS
Installing bootstrap code onto an entire disk is merely pointless. sunlabel should rather support installing bootstrap code into 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.