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)

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	parti-
     tion 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 interpre-
		  tation 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 off-
		  set 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,	proto-
		  type 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 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
		  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	prede-
		  fined	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	vari-
     able 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', imme-
	     diately followed by a colon, followed by the size of this parti-
	     tion, 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	cylin-
	     ders, `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 cylin-
	     ders though).

	     Optionally, each partition	entry may be followed by an SVR4-com-
	     patible 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 parti-
	     tions 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 possi-
     ble 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 rejec-
     tion 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.

     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 emu-
     late fairly large cylinders which due to the two reserved alternate
     cylinders causes a	fair amount of wasted disk space.

FreeBSD	10.1			March 30, 2005			  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | FILES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=sunlabel&sektion=8&manpath=FreeBSD+10.0-RELEASE>

home | help