
		Sneep User Guide 


	sneep_UserGuide.txt  06/16/05 23:35:19

Sneep (Serial Number in EEProm) provides persistent storage of the
Chassis Serial Number for virtually all Sun platforms. Additionally,
sneep can provide persistent storage for a variety of user-defined data
such as asset tag, service contract, etc.

Sneep is delivered as the Solaris package SUNWsneep, and is available 
to the public for download from 
	BigAdmin	http://www.bigadmin.com 
	(and possibly)
	SunSolve	http://sunsolve.sun.com

The download site internal to Sun is 
	Field Customer Advocacy
	http://webhome.central/fca-eng/solutions/sneep


LICENSING

	Use of sneep is subject to a license acceptance. If you did not
download sneep yourself, or have for any other reason not viewed and
accepted the license for sneep, please review the sneep license file
before installing or using sneep.  The sneep license can be found in
the SUNWsneep package:

	SUNWsneep/Docs/sneep_LICENSE.txt 

Installation or use of sneep implicitly accepts the terms of the license. 
You should know what you have accepted.





INSTALLATION AND REMOVAL OF SNEEP

	Sneep is delivered as a Solaris package, installed using 
"pkgadd" and removed using "pkgrm" .  Installation and removal of sneep
has been made as simple as possible, and can be completely
non-interactive.  No "admin" or "response" file is necessary.

	$ pkgrm  -n SUNWsneep
	$ pkgadd -n -d directory SUNWsneep 



If you require access to sneep without specifying the full path
	/opt/SUNWsneep/bin
you may use the "add_sneep_to_bin" utility supplied to configure 
and register another path to sneep.

	$ add_sneep_to_bin/add_sneep_to_bin [directory]

By default, a link to sneep is placed in /usr/sbin .
If the sneep package is removed, the link will also be removed.



If you have "explorer" installed, install the sneep plugin for explorer

	$ /opt/SUNWsneep/bin/install_explorer_plugin

For more information, refer to Docs/INSTALL_sneep.txt , and to
Appendix B "The Explorer Plugin" .


If the sneep package is removed from the system, any sneep data such as
Chassis Serial Number remains unless you deliberately remove it, and it
continues to provide value.  It is included in any "explorer" outputs,
and is available to the administrator from the EEPROM "nvramrc"
variable in OBP and Solaris.




SNEEP DATA SOURCES AND FORMATS

	Sneep maintains the Chassis Serial Number (CSN) and other 
user data in several places, including system EEPROM, a backup file,
and the "explorer" and "CST" configuration files.

See Appendix A: "Sneep Data Sources", for detailed information 
on where sneep will search for and save information,
and for the uses and limitations of those data sources.


SNEEP MANUAL PAGE

	For concise, detailed usage, read the sneep man page using the 
Unix man(1) command.  The following command will obtain the man page 
from the default installation location:

	$ man -M /opt/SUNWsneep/man sneep


OTHER UTILITIES REFERENCED:	EXPLORER AND CST

	"explorer" refers to the Sun Explorer tool for capturing 
largely static system configuration information. It is delivered as the
packages SUNWexplo and SUNWexplu, and is available from SunSolve at
http://sunsolve.sun.com . Sun recommends that explorer be installed on
every system and domain. It should be run on a regular schedule, and
if possible, the output should be transmitted to Sun. 
For detail on transmitting explorer output to Sun, see
	explorer documentation 
	sunsolve.sun.com/explorer
	www.sun.com/service/support/srs/netconnect

	"CST" refers to the Sun Configuration Service Tracker tool for
capturing and tracking system configuration changes and service events,
and maintaining the history of a system. CST also detects and maintains
the history and causes for system outage events, for reporting system
availability.  It is delivered as the packages SUNWcstu and SUNWcstv,
and is available from the Sun Download Center at http://www.sun.com .





SNEEP DATA TAGS

	Every data item stored by sneep has a name, which is specified by 
a "tag" .  Tags are arbitrary user-defined strings: case sensitive
and alpha-numeric. A few special characters are allowed:
	@ # _ + = -

Tags are specified on the sneep command line by using the option "-t"
followed by one or more comma-separated tags.

The default tag is "ChassisSerialNumber", so that when manipulating
the CSN, the tag does not have to be specified.  However, you may do so
if you wish.

There are a few reserved tags. Most are associated with the 
Chassis Serial Number. The tag reserved for Chassis Serial Number is
	ChassisSerialNumber  

These additional tags are equivalent and interchangeable aliases 
for ChassisSerialNumber:
	serial  CSN   csn

There are times when it is useful or necessary to specify a tag for
the Chassis Serial Number. You may find the aliases above to be easier
to use.


There are also pseudo-tags for retrieval of Operating System data:

	hostname	hostid





STORAGE AND RETRIEVAL OF THE CHASSIS SERIAL NUMBER

	This section describes the most basic use of sneep, as it 
would be used to set the serial number on a machine which has no
previous serial information available. If your machine already has a
source for serial number data which sneep can access, see the section
on "Using Sneep to Recover Existing Data" .

		**************
Remember that even if sneep finds a serial number on your system in any of
the secondary sneep data sources, it is NOT stored in EEPROM until
sneep is used to set the serial number.  This also stores it in in the
backup file /etc/default/SUNWsneep in case the eeprom defaults are
restored, or the eeprom is replaced.  
		**************

	# make certain that sneep cannot find any (possibly incorrect)
	# serial number data from any of the data sources

	$ /opt/SUNWsneep/bin/sneep -a
		ChassisSerialNumber from default value :
	unknown
	$

	# If the result above is not "unknown", sneep has found
	# some serial data, and has identified the source.
	# If you wish to ignore it, proceed with this example.
	# If you wish to preserve and restore it, see the section
	# on using sneep to recover existing data.


	# ( Obtain Chassis Serial from physical label or other documentation)
	# Set Chassis Serial Number with "setting" option -s
	#	Until you perform this step, the serial number
	#	is NOT stored in eeprom, and is easily lost or overwritten.

	$ /opt/SUNWsneep/bin/sneep -s 126h2Aa4
	$


Now that this step is completed, the serial number will be printed
whenever the system is booting if the eeprom variable "use-nvramrc?"
is set to "true" .
However, it is not necessary for "use-nvramrc?" to be set to "true"
for sneep to save and retrieve the serial number. On a Solaris x86 system,
the "use-nvramrc?" variable may not even exist.

	# If you wish, determine the value of "use-nvramrc?"
	$ /usr/sbin/eeprom use-nvramrc?
	use-nvramrc?=true
	$


	# Retrieve serial in simplest form, using default sneep behavior
	#  Note conversion of mixed-case input (above) to upper case standard.

	$ /opt/SUNWsneep/bin/sneep
	126H2AA4
	$


VERIFICATION OF SERIAL DATA IN DATA SOURCES


	# 	Report on all data sources using option -a .
	#	After the serial has been set, several data sources 
	#	may be available. This will vary depending on the
	#	software installed on the system.

	$ /opt/SUNWsneep/bin/sneep -a
	    ChassisSerialNumber from eeprom :
	126H2AA4
	    ChassisSerialNumber from backup : /etc/default/SUNWsneep :
	126H2AA4
	    ChassisSerialNumber from explorer :
	126H2AA4
	    ChassisSerialNumber from cst :
	126H2AA4
	$


	# Locate Serial data in EEPROM. 
	# Note that serial is associated with a specific "tag" : 
	#	ChassisSerialNumber.   This tag is reserved.
	$ /usr/sbin/eeprom nvramrc | grep  Serial
	nvramrc=." ChassisSerialNumber 126H2AA4 " cr
	$


	# verify that serial is present in explorer configuration
	$ grep EXP_SER /etc/opt/SUNWexplo/default/explorer
	EXP_SERIAL_809f5be8="126H2AA4"
	$


	# verify that serial is present in CST user data
	$ grep erial /var/opt/SUNWcst/user_data
	Serial # of System      126H2AA4
	$


        # verify that sneep has sent a Serial event on the CST agent:
	$ grep "<CSN>" /var/opt/SUNWcst/cst_history
                <CSN>126H2AA4</CSN>
        # (there will be one of these for each time an event was sent)


	# verify that serial is present in the backup file
	$ grep erial /etc/default/SUNWsneep	# SUNWsneep is the backup file
	ChassisSerialNumber     126H2AA4
	$





REMOVING THE CHASSIS SERIAL NUMBER FROM SNEEP

	To remove the serial number, set it using the null value "" .
This not only eliminates the value associated with the serial tag,
it removes the entry entirely from eeprom and backup, and as thoroughly
as possible from other data sources.

	$ /opt/SUNWsneep/bin/sneep
	126H2AA4
	$ /opt/SUNWsneep/bin/sneep -s ""
	$ /opt/SUNWsneep/bin/sneep 
	unknown

	$ /usr/sbin/eeprom nvramrc | grep  Serial
	$

	$ grep EXP_SER /etc/opt/SUNWexplo/default/explorer
	EXP_SERIAL_809f5be8=""







STORING AND RETRIEVING USER DATA WITH SNEEP

	Tags are used to name other data items which the user wishes to 
store along with the Chassis Serial number. One example is an Asset ID
number.

We use the "tag" option -t to specify the tag associated with the data
item; the "name" of the data .  In this case, we will use "ASSET_ID" as
the tag for the stored asset ID.

	# Check for ASSET tag in EEPROM
	#	no asset information has been previously stored
	$ /usr/sbin/eeprom | grep  ASSET_ID
	$

	# retrieve the (missing) ASSET_ID, 
	# providing a default value of "Unregistered" if it is absent.

	$ /opt/SUNWsneep/bin/sneep  -d Unregistered -t ASSET_ID
	Unregistered
	$


	# Set and retrieve a value for the ASSET tag
	# Note that no upper case conversion is done on the value,
	# as would have been done on the chassis serial number.

	$ /opt/SUNWsneep/bin/sneep  -t ASSET_ID -s Sun1234
	$ /opt/SUNWsneep/bin/sneep  -t ASSET_ID
	Sun1234


	# Data format in eeprom is identical to CSN; tag and value are different
	$ /usr/sbin/eeprom nvramrc
	nvramrc=." ChassisSerialNumber 126H2AA4 " cr
	." ASSET_ID Sun1234 " cr



RETRIEVING MULTIPLE TAGS AT THE SAME TIME : populating a spreadsheet

	Multiple tags may be retrieved at the same time. This may 
be especially useful if you need to create a summary spreadsheet of
several values from each of your systems. The hostname and hostid
pseudo-tags provide convenient access to information which is often
required in conjunction with serial data.

By collecting this data from each of your systems and combining it into
one file, you can populate a spreadsheet with accurate information
for reporting and many other purposes.

	$ /opt/SUNWsneep/bin/sneep -t hostname,hostid,csn
	Webserver1,8081439,126H2AA4

Note that any tags for which no value has been set will be replaced by
the default value of "unknown", unless you provide a different value
(or no value) by means of the option -d .

	$ /opt/SUNWsneep/bin/sneep -t hostname,hostid,LOCATION,csn,ASSET_ID
	Webserver1,8081439,unknown,126H2AA4,Sun1234

	$ /opt/SUNWsneep/bin/sneep -d "" \
				-t hostname,hostid,LOCATION,csn,ASSET_ID
	Webserver1,8081439,,126H2AA4,Sun1234



USING SNEEP TO DISPLAY EXISTING DATA WITH TAGS

	# To display all of the known sneep tags, use option -T
	$ /opt/SUNWsneep/bin/sneep -T
	ChassisSerialNumber     "126H2AA4"
	ASSETTAG        "Asset1234"
	CLUSTERWARNING  "Clustered with node ABCD and MUST use SCSI ID 3"

	# To display a particular tag or group of tags, add option -t tag
	$ /opt/SUNWsneep/bin/sneep -T -t ASSETTAG
	ASSETTAG	"Asset1234"
	




USING SNEEP TO RECOVER EXISTING DATA

	While sneep should be able to recover automatically from most data
inconsistencies at system boot time, there are times when you may wish
to get serial number information which already exists on your system,
and commit it to eeprom and to the other sneep data sources.

You may be performing the initial configuration of sneep on 
a machine which already has accurate serial number information in
explorer or CST, or you may be manually recovering data on a system which has
had its eeprom erased or replaced. You may have found that the eeprom or
backup sources differ from explorer or CST because of some configuration
or jumpstart error.


DATA RECOVERY AND THE PRIORITY SEARCH PATH

	The order in which sneep searches its data sources is
configurable.  By default it is ordered such that the data sources
which are more authoritative or more commonly maintained
are searched first:
	fruid:sms:eeprom:backup:explorer:cst

If another sequence is more suitable for your needs, the -P option
allows you to change the sequence. This may also be controlled by
the environment variable "SNEEPPATH" . The default priority search
path can also be stored in the sneep backup file. See the section
of Appendix A which pertains to the Backup data source for
more information on storing the default priority search path in
the backup file.


	If you find that there is conflicting data on your 
machine - for example, different data in explorer compared to CST, or
backup compared to explorer - you may want to use the priority search
path to select your preferred data source.


Remember that even if sneep finds serial number or other data 
in another data source, it is NOT stored in EEPROM or the sneep backup 
file until sneep is used to set a value for the desired tag or tags.


BASIC DATA RECOVERY EXAMPLE

	# 	Report on all data sources using option -a
	#	(in this example, explorer and CST have serial numbers
	#	 and the eeprom has never been set )
	#	The explorer data source is incorrect.

	$ /opt/SUNWsneep/bin/sneep -a
	   ChassisSerialNumber from explorer :
	M2300762
	   ChassisSerialNumber from cst :
	126H2AA4

	#	By default, sneep reports the best (first) available 
	#	data according to the priority search path.
	#	If you know the serial in CST to be more reliable,
	#	then you would not want this response from explorer,
	#	which comes before CST in the default priority search path.

	$ /opt/SUNWsneep/bin/sneep
	M2300762

	#	Report your preferred data source
	#	in this case from CST, using the option -P .
	#
	#	If this were the initial use of sneep,
	#	there would be no advantage in including the
	#	(empty) eeprom and backup in the priority list, 
	#	but we do so because this would be a
	#	Best Practice under normal circumstances, in which
	#	eeprom has been set and is probably most reliable.

	$ /opt/SUNWsneep/bin/sneep -P eeprom:backup:cst
	126H2AA4


	#	The actual data extraction from CST and recovery
	#
	#	Set the eeprom and other data sources using the
	#	data recovered from CST in an obvious way.
	#
	#	This works fairly well, except that if CST has no data,
	#	"unknown" is returned and is set in place of the
	#	serial in all data sources. Option -d will be used
	#	to change this behavior in a later example.
	
	cstval=`/opt/SUNWsneep/bin/sneep -P cst `
	/opt/SUNWsneep/bin/sneep -s $cstval


SNEEP-ASSISTED DATA RECOVERY

	Sneep can assist in data recovery by producing the actual 
commands which are needed for recovery. If these commands are piped
into another shell, recovery is automatic.

To do this, we use the "tag display" option -T with the verbose option -v .
This combination produces sneep commands as the data output format.

Our example is primarily to illustrate how one might initially set the
serial from known good CST data, the first time that sneep is used on this
system. As a defensive practice, we also show how to limit the output to
the desired tag (using -t tag), in case there are other tags available
in the eeprom or sneep backup file.   The default is to output all of
the tags and values.

As another defensive Best Practice, we specify a null default value
so that if no value is found  on our priority search path, we avoid
setting a serial number of "unknown".  In fact, we will delete any
other serial value by setting a null serial in this case.

	# Get the current serial number from CST, and use it to
	# create the command to use to set the serial number.
	$ /opt/SUNWsneep/bin/sneep -vT -P eeprom:backup:cst \
						-t serial -d ""
	/opt/SUNWsneep/bin/sneep -t "ChassisSerialNumber"  -s "126H2AA4"
	$

If we take the command produced in the previous example, and send 
the output through a pipe to another shell, we retrieve and set the
serial number in one command.  If the shell which receives the command
is called with the "trace" (-x) option, we can see the sneep "set" command
being executed, preceded by the "+" which indicates a command being
executed and traced.

	$ /opt/SUNWsneep/bin/sneep -vT -P eeprom:backup:cst \
						-t serial -d "" | sh -x
	+ /opt/SUNWsneep/bin/sneep -t ChassisSerialNumber  -s 126H2AA4
	$




DELETING OR REMOVING USER DATA
	

	Just as the serial number can be erased by setting it with
a null value, any other tag can be removed in the same way. 
The tag and value are removed entirely from eeprom and backup, 
which are the only data sources in which user data is stored.


	$ /usr/sbin/eeprom nvramrc
	nvramrc=." ChassisSerialNumber 126H2AA4 " cr
	." ASSET_ID Sun1234 " cr

	$ /opt/SUNWsneep/bin/sneep  -t ASSET_ID -s ""
	$ /opt/SUNWsneep/bin/sneep  -t ASSET_ID
	unknown

	$ /usr/sbin/eeprom nvramrc 
	nvramrc=." ChassisSerialNumber 126H2AA4 " cr

For erasing multiple values, the option -e is provided. It is used only
in conjunction with -T and -v, and this combination causes sneep to
output the necessary sneep commands to erase the selected tags and values.
By default, this is done for all tags and values, but option -t can be used to
limit this to a subset of tags.

	$ /opt/SUNWsneep/bin/sneep -Tve
	/opt/SUNWsneep/bin/sneep -t "ChassisSerialNumber"   -s ""
	/opt/SUNWsneep/bin/sneep -t "ASSETTAG"   -s ""
	/opt/SUNWsneep/bin/sneep -t "CLUSTERWARNING"   -s ""
	$

Piping these commands to a shell will result in the complete
removal of the tags and values from sneep.

	$ /opt/SUNWsneep/bin/sneep -Tve | sh
	$ /opt/SUNWsneep/bin/sneep
	unknown
	$




SNEEP DATA CONSISTENCY CHECK AND REPAIR AT SYSTEM REBOOT

	When the SUNWsneep package is installed, it automatically creates
symbolic links in /etc/init.d and /etc/rc2.d so that sneep will be
invoked as a system startup script every time the system is booted.

When sneep is invoked at boot time with the command line argument
"start" , it checks for valid and consistent serial number data in the
eeprom and other data sources. Whenever possible, it automatically
corrects the inconsistency.
There are two primary scenarios: loss of eeprom data, and the presence of
incorrect configuration files on the system (e.g. from jumpstart).

	Loss of eeprom data:

This typically occurs when the eeprom has been replaced or has be
reset to defaults. No tags are available from eeprom, but the system
disk contains a valid sneep backup file.

If the serial number is NOT found in the eeprom, but it is found in the
backup file, and if the backup file was created on the current system,
then all of the tags found in the backup file will automatically be
restored to the eeprom.  This provides automatic recovery from eeprom
reset or replacement.  Any tags already in eeprom which do not appear
in the backup file are unchanged; in the case of eeprom reset or
replacement there will be none.
Inconsistencies and repairs are logged in the system log.
If the backup file is from a different system, no recovery is attempted.

	Missing or incorrect sneep backup, or other configuration files:

This typically occurs when a system is created from a standard image
which includes sneep, explorer, or CST configuration from a different
system. It also commonly occurs when explorer has been updated and the
configuration has not been preserved. If tags have been previously set
in the eeprom, then those settings can be recovered from eeprom and
used to replace the incorrect data.

If the serial number exists in the eeprom and any other data source
is inconsistent with it, sneep will attempt to update all of the
applicable data sources using all of the tags stored in the eeprom and
backup.  If the explorer or CST configuration files are missing, but
the corresponding package is installed, sneep will create the files
and populate them with the serial number.

Inconsistencies and repairs are logged in the system log.


All of the sneep tags found in eeprom and backup are recovered, so any tags
previously found only in the backup will be placed in the eeprom also. 
In a properly configured system, there will be no tags of this kind,
but if the backup file came from another system, new tags might be
entered into the eeprom. A special warning is logged in this case.

This is preferable to the alternatives:
	- Avoiding recovery in a common scenario.
	- Having inconsistent data between eeprom and the backup file.
	- Data Loss as a result of removing tags from the backup file





THE ALTERNATE INTERFACE: SETCSN and SHOWPLATFORM

	Sneep was originally written to implement a new command line API
for setting and retrieving Chassis Serial Number which first appeared in
System Management Services (SMS) 1.4 .   The hope was that the same
standardized commands could be used on all platforms to manage the serial 
number. However, SMS requires that a particular user run the commands, and
does not locate them in a directory on the standard search path.

For these reasons, the SMS command emulation in sneep cannot easily
fulfill the initial intent, and its use is no longer encouraged.
The native sneep interface has proven to be more flexible and
better-suited to automation of asset management tasks.

The SMS emulation is presented here for reference.


	# Set and retrieve serial number

	$ /opt/SUNWsneep/bin/setcsn -c  126h2Aa4

	$ /opt/SUNWsneep/bin/showplatform -p csn
	     CSN:
	     ====
	     Chassis Serial Number: 126H2AA4


	# Verify that it appears in eeprom

	$ /usr/sbin/eeprom nvramrc | grep  Serial
	nvramrc=." ChassisSerialNumber 126H2AA4 " cr


	# Remove serial number and verify

	$ /opt/SUNWsneep/bin/setcsn -c  ""
	$ /opt/SUNWsneep/bin/showplatform -p csn
	     CSN:
	     ====
	     Chassis Serial Number: Unknown
	$






APPENDIX A	Sneep Data Sources

Sneep obtains information from several sources, and stores information
in several locations. Most of these data sources are only used for
serial number data, but some can also contain user-defined data.  By
default, sneep searches these data sources in a sequence which ensures
that the most authoritative data is found first.  The default sequence
is "fruid:sms:eeprom:backup:explorer:cst" .  By use of the command line
option "P", this sequence can be changed, or constrained to a subset of
the available sources.



The System EEPROM data source : "eeprom"

	The primary storage for sneep data is the system EEPROM
maintained by Open Boot Prom (OBP).  On all SPARC systems, the EEPROM
is persistent, and the contents are maintained independent of any disk
storage on that domain. This makes sneep data such as Chassis Serial
Number impervious to disk replacement, system software upgrade, data
restoration from backup, redeployment by means of flash archive, etc.,
etc.

Solaris x86 (PC) platforms do not have the same system EEPROM which the
SPARC platforms have. In Solaris x86, EEPROM is simulated using a file
in the boot filesystem, so users of sneep must be aware that sneep data
is not completely persistent on the x86 platform.  If the boot disk is
replaced, or if its contents are completely replaced, any sneep data
found may not be the data which was last stored on that system.  While
this eliminates a very desirable characteristic of sneep data, it does
not eliminate the value of using sneep on x86.  
Under normal circumstances, the value and use of sneep is
undiminished.  Extra care should be taken to restore the appropriate
data if the disk contents are ever replaced entirely. More information
is provided in a later section on the sneep backup file.

The contents of the eeprom are included by default in the output of
the Sun Service "explorer" tool. Explorer files delivered to Sun from
systems using sneep will provide this important serial number data
automatically. Explorer data can be used in a variety of proactive analysis
tools, which will have the system serial number available for correlation
with service history and other data.

On Solaris x86, if the disk contents are replaced entirely and as a result,
the simulated eeprom is lost, an explorer file from the system can be used
to recover the sneep data from the sneep backup file described later.


EEPROM data format

	In the EEPROM, sneep uses specially formatted entries in the OBP
"nvramrc" variable. This variable is intended for storage of directives
understood by OBP - such as device aliases - and for programs in the
OBP programming language, FORTH. The data manipulated by sneep is stored in
"print" commands in the FORTH language. This ensures that they are
entirely legitimate and cannot have any undesirable side effects, as
some other approaches might. The FORTH print command is <.">string<">

The entry for the Chassis Serial Number (CSN) has this form:
	." ChassisSerialNumber <CSNvalue> " cr
where <ChassisSerialNumber> is the "tag" reserved for the serial number, 
and <CSNvalue> would be replaced by a legitimate Chassis Serial Number.

For compatibility with Sun internal standards, the values for CSN are
stored in eeprom using upper case. The storage of data within print
commands prevents them from containing any embedded quotation marks or
control characters. This also restricts values to a single line, with
no embedded newlines.

The nvramrc is also available for user-defined data. The entry for a data 
item tagged "AssetNumber" with the value "AN123x" would be
	." AssetNumber AN123x " cr
Values for user-defined tags are not converted to upper case.

An OBP variable named "use-nvramrc?" controls whether or not the
nvramrc is processed when the system is reset. This variable is not
important to the storage and retrieval of sneep data, but if set to
"true", the "print" commands in the nvramrc will be executed as the
nvramrc is processed. The effect of this is to print the serial number
and any other data items on the system console when the system is
powered on or otherwise reset. This is done only if use-nvramrc?=true .




The Sneep Backup File data source : "backup" : /etc/default/SUNWsneep
	
	Sneep maintains a backup file for all the data stored by sneep.
This file can be used for data recovery in the event that the
system EEPROM is replaced or otherwise reset to default values.
This file can also be used to save settings for some sneep parameters
to override the program defaults.

On x86 platforms, the EEPROM simulation limits the contents of the 
OBP nvramrc variable to one entry, so the backup file becomes 
the only data storage for sneep data other than Chassis Serial Number.
The single entry in nvramrc is reserved for the Chassis Serial Number so
that it will be included in the eeprom data of any "explorer" output.

Solaris Zones other than the "global zone" do not have access to the
EEPROM or the eeprom command. As a result, the backup file is used as a
virtual eeprom, in much the same way as Solaris x86 uses a file as a
virtual eeprom.  For non-global zones, the backup file becomes the only
data storage for sneep data, including the Chassis Serial Number.  Each
zone can have different sneep tags, but every zone on one machine
should have the same Chassis Serial Number. If a zone loses its
configuration, the global zone still has a backup file and may have a
true eeprom.

Because of its location in the /etc/default directory, the sneep backup
file will also be included in the output of "explorer".
If both the system eeprom and the boot disk were lost, an archived
explorer file could be used to recover the sneep backup file. After this
file has been restored, sneep can immediately be used to restore 
all of the settings to eeprom.

See the section on "Recovering Existing Data" for more information.

The backup file can contain settings for the priority search path and
for the syslog facility.priority.  These settings will override the
program defaults. See the manual page for the "-P" option and the
$SNEEPPATH and the $SNEEP_SYSLOG environment variables.

To add these settings to the backup file, manually edit the file to
include lines of the form:
	sneep<space>syslog<tab><facility.priority>
	sneep<space>path<tab><ds1:ds2:...dsn>
	e.g.
		sneep syslog	local1.info
		sneep path	fruid:sms:eeprom:backup:cst:explorer

The spaces and tabs are critical and must be correct.





The explorer data source: "explorer"	/etc/opt/SUNWexplo/default/explorer

	If explorer is installed, sneep stores the chassis serial number
in the explorer configuration file, as EXP_SERIAL_<hostid>=<serialnumber>
The explorer configuration file for recent versions of explorer is
	/etc/opt/SUNWexplo/default/explorer

When explorer is fully and properly installed, this file contains the
chassis serial number and several other pieces of information. The
serial number is among the most important of these.  However,
experience has shown that in a majority of cases, this information is
missing or incorrect. There are numerous reasons for this, but it
suffices to say that maintenance of this file requires some effort. As
sneep automatically updates the EXP_SERIAL value, maintenance of the
file is somewhat simplified by using sneep to manage the serial
number.

This file serves as an additional serial number source for sneep, and
sneep serves as a way to determine when the contents of the explorer
configuration are incorrect.



The CST data source: "cst"	/var/opt/SUNWexplo/user_data

	If CST (Configuration Service Tracker) is installed, sneep stores 
the Chassis Serial Number in the user_data file entry for "Serial # of System".
	Serial # of System	<serialnumber>

This establishes a useful reference and another backup data source for
sneep.  However, CST users should be aware that changes made directly
to the user_data file on CST agent systems are not transmitted to the
CST Middleware server unless the changes are made using the CST
graphical user interface (GUI).

As it does with the explorer configuration file, sneep somewhat
simplifies the task of maintaining the Serial Number in the CST User Data. 

In an effort to improve the communication between tools and assist the
customer with maintenance of this data, whenever sneep updates the
user_data file, it also sends a special Serial event to the CST middleware.
This event can be seen in the node history, can be propagated to Sun,
and can be used on the CST Middleware server by the User Data Editor
(uded) to propagate the change between the CST Middleware and the agent
system as a legitimate User Data update.

The CST User Data is provided to the customer to record and track more
than 50 common and useful data items including asset information,
system location, contracts and contacts, and many others.  These are
exactly the kind of data items which users might store using sneep.
While sneep generally has an advantage in persistence, the user should
consider the value provided by using the CST User Data for items which
do not have to be available at the OBP level of system operation.

The User Data Editor, "uded", is a powerful tool for increasing the
value of the CST User Data by making it practical to update and
maintain the information on large groups of systems using a
command-line interface. This can be much more efficient, scalable, and
accurate than using the graphical interface.

"uded" is not a standard part of the CST distribution, but can be
obtained through your Sun Account Team from Sun Field Customer Advocacy
at webhome.central/fca-eng/solutions/uded .



The FRUID data source : "fruid"		(not fully implemented)

	Some Sun platforms provide detailed identification of all installed
Field Replaceable Units (FRUs). While the serial numbers available in this
data are normally serial numbers for the individual boards and components,
the data may someday include the overall Chassis Serial Number (CSN).
At this time, sneep is not able to locate the Chassis Serial Number in this
data source, but sneep will be updated when the CSN is generally available,
and when more is understood about the use of this data source.


The SMS data source : "sms"		(not fully implemented)

	Some Sun platforms (the E25K/E20K/15K/12K) are controlled by 
System Controllers (SC) which use SunFire System Management Services
(SMS) software.  SMS 1.4.1 and above has the capability to save and
retrieve the Chassis Serial Number (CSN) using the "setcsn" and
"showplatform" commands.  Once set using setcsn, the CSN is completely
non-volatile and even more persistent than system EEPROM. However, this
capability is provided only on the main SC, and not on the spare SC or
on the Solaris domains which are being controlled.  

As this significantly reduces the availability of the information, SMS
is not currently used as a data source by sneep. RFEs exist to make use
of SMS when sneep is run on the SC, and to attempt to retrieve this
information from the main SC when sneep is used on the domains.

As the setcsn/showplatform command lines are the only standardized Sun
interface to the Chassis Serial Number other than sneep, sneep provides
simple emulations of the relevant parts of the command line options for
these commands. This is implemented using links in the sneep "bin"
directory to the sneep executable, named "setcsn" and "showplatform"
See the section of this document on "The Alternate Interface".







APPENDIX B	The explorer Plug-In for Chassis Serial Number



As you have seen, sneep can search several sources for the best serial
data, and it is anticipated that there may be more changes in the
future. For example: the CSN may move from the nvramrc variable to its
own OBP environment variable.

Although every explorer includes sneep tags in the eeprom.out and
etc/default/SUNWsneep files, it is desirable to have the chassis serial
number stored in its own file in the explorer without regard to
where the serial number came from.

Explorer will be updated shortly to collect the serial number using
sneep.  Until that work is completed, sneep includes a script which
installs a plugin into explorer for this purpose.  To install the
plugin, simply run the script provided with sneep:

	$ /opt/SUNWsneep/bin/install_explorer_plugin
	$

The plugin is installed as
	/opt/SUNWexplo/tools/chassis_serial
and the serial is stored in the explorer file
	sysconfig/chassis_serial.out

[ These names may change when sneep support in built into explorer ]

Any time that explorer is re-installed or updated, the plugin must be
reinstalled using the command provided. This is necessary because the
explorer version must  match the version information embedded in every
plugin in order for explorer to use the plugin.  This will not be
necessary after explorer includes sneep support natively.

If the plugin is already present and configured for the currently
installed version of explorer, no change will be made to the plugin by
install_explorer_plugin .

