Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SUNLABEL(8)             FreeBSD System Manager's Manual            SUNLABEL(8)

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

     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

     The sunlabel utility installs, examines or modifies the Sun OpenBoot PROM
     label on a disk.  In addition, sunlabel can install bootstrap code.

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

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

   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.  There are two areas in the template that 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).

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

     EDITOR      Name of the command to edit the template file in edit-mode.
                 Defaults to vi(1).

     /boot/boot1      Default boot image.

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

     The sunlabel utility appeared in FreeBSD 5.1.

     The sunlabel utility was written by Jake Burkholder, modeling 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.

     Installing bootstrap code onto an entire disk is merely pointless.
     sunlabel should rather support installing bootstrap code into a partition

     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.

FreeBSD 11.0-PRERELEASE          June 1, 2004          FreeBSD 11.0-PRERELEASE


Want to link to this manual page? Use this URL:

home | help