home | help
SUNLABEL(8)		     System Manager's Manual		     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-com-
     patible 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 hard-
     ware, 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 un-
		  derlying 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 interpreta-
		  tion	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 ob-
		  tained  using  the  -h option are not suited for re-installing
		  using the -R option.

     -n 	  No changes.  All operations, checks etc., are  performed  nor-
		  mally, 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  re-
		  spective 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.  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 approx-
	     imate 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', immedi-
	     ately  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  ap-
	     pending  `s'  for	(512-byte)  sectors,  `c' for cylinders, `k' for
	     kilobytes, `m' for megabytes, or `g' for gigabytes.  The last  par-
	     tition  entry may specify the size as `*' to indicate that this en-
	     try should consume the rest of disk not consumed by any other  par-
	     tition so far.

	     The start of partition is always taken as a cylinder number (start-
	     ing  at 0) since this is what the underlying hardware uses.  Alter-
	     natively, specifying it as `*' will make the computation  automati-
	     cally 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-compat-
	     ible 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 nu-
	     merically, 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 par-
     titions  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 unmount-
     able.

     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  de-
     scription	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.   De-
	     faults 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.

     This man page was initially written by David O'Brien,  and  later	substan-
     tially updated by Jorg 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.

FreeBSD 5.3			  June 1, 2004			     SUNLABEL(8)

home | help