# Copyright @ 2007 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A.
# All rights reserved.U.S. Government Rights - Commercial software.  Government users are subject to the
# Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements.
# Use is subject to license terms.  Sun,  Sun Microsystems,  the Sun logo and  Sun Ray are trademarks or
# registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.UNIX is a registered trademark
# in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd.
#
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software distributed
# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
# CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
# language governing permissions and limitations under the License.
#
Basic installation instructions for Simple System Monitoring Application(SSMA) software       1-June-2006
=======================================================================================

These are generic installation instructions.  For detailed installation
instructions, see the SSMA Installation and Configuration Guide.
That document is located in the docs/ directory as a PDF.

SSMA software is installed in three phases, the server installation,
client installations, and then configuring the web component.

SSMA software requires a server sized appropriately to handle a 
large amount of data being sent to it by clients.  The server must be a 
machine with at least a 400mhz CPU and will use 100mb of real memory on the 
server.  In addition, the server-side component of SSMA software 
requires 100mb of disk space for each client being monitored.  A 2gb drive 
will handle the data repository requirements for 20 clients.  The Apache web 
server is also a requirement and must be installed prior to attempting a 
SSMA installation.

While neither the server-side installation nor the client-side installation of
SSMA requires root access, the user account used to install the
software must be able to run an Apache instance as well as make crontab
entries.

     CAUTION: The user that SSMA server software will be running 
              as on a Solaris host must have a password.  If that user does 
              not have a password, then SSMA cronjobs will not run.


Upgrading from a previous SSMA/Project Canary release
=====================================================

Upgrading SSMA software has been automated by the installation
script.

First, back up the existing SSMA/Project Canary software installation including
the data directory.  Reverting to a previous version of SSMA/Project Canary 
software is difficult and a restore from backup is the easiest way to extract
all the data as data formats change between major releases of SSMA/Project Canary.

Next, copy the appropriate canary.tar file for the architecture to be upgraded
to the directory where the current installation of SSMA software
resides.

Unpack the tar file in that directory, over-writing the existing Server-Side 
installation.

Change directories to the scripts directory and run the SSMA
installation script with the '-upgrade' option as shown below:

	sunblade% cd scripts
	sunblade% ./canary_install.sh -upgrade

The SSMA installation script will examine the previous installation
and upgrade files as necessary.  There is very little interaction with the
installation script in upgrade mode.

Once the installation script finishes upgrading the SSMA
installation, clients will need to be upgraded with the new probe package.

Follow the client installation instructions at the end of this README file
for instructions on how to install the new SSMA probe software on 
clients.


Initial Installation Instructions
=================================

Copy the appropriate canary.tar file for the architecture to be installed on
to the directory in which SSMA server-side software will be 
installed and extract the contents of that tar file there.

The default installation directory is '/var/tmp/canary/canary_monitor'

That directory can be created by issuing the following command:

	% mkdir -p /var/tmp/canary/canary_monitor

Make a note of the directory that SSMA software has been extracted.
This will be known as '$CANARY_HOME' and referred to as such throughout this
installation README file.

Installation of SSMA server-side software has been automated by an
installation script.  

The installation script will keep a log in $CANARY_HOME/conf.  That log keeps
a copy of everything that the installation script did just in case there are 
problems with the installation.

The name of the log file will be of the form:

        canary_cust.config.yyyymmddhhmmss

The numbers following the name of the logfile are the date the installation
was attempted, in the form MMDDYYHHMMSS.  

This file is needed when requesting assistance from the SSMA
support team.


QUICKSTART INSTALLATION
=======================

SSMA now offers a QuickStart option to install the software
by default when the installation script is first run.

To start an installation of SSMA software, change directories to 
$CANARY_HOME/scripts and execute the canary_install.sh script:

     sunblade% cd scripts
     sunblade% ./canary_install.sh

The installation script will begin by asking if the default settings are
what should be used to do the installation:

     Simple System Application (c)2007 Sun Microsystems, Inc. All Rights Reserved.

     By default, SSMA installs with the following settings:

     SSMA server       = sunblade.sun.com
     SSMA install dir  = /var/tmp/canary/canary_monitor
     SSMA data dir     = /var/tmp/canary/canary_monitor/data
     SSMA incoming dir = /var/tmp/canary/canary_monitor/data/incoming
     Upload method       = nfs
     Client install dir  = /var/tmp/canary/probe
     Client output dir   = /tmp/.canary_probe

     Do you want to use the default settings for installation? 

To install SSMA using default installation settings, enter 'y' at 
the prompt.  If the default installation cannot be used or is unacceptable, 
enter 'n' at the prompt and the installation script will begin an interactive 
installation.

For details on the interactive installation and how to activate optional
features within SSMA , consult the SSMA Installation
and Configuration Guide.

The installation script will ask one question when using the default
installation before installing the software:

     Please enter the email address that will be receiving the SSMA
     alerts (ie. joe@mycompany.com): 

Enter the email address or mail alias where SSMA should send alerts 
to. 


Server Installation Finishing Touches
=====================================

The script then sets up all required crontab entries and starts up the SSMA
server processes and checks to ensure the installation is clean and that
gnuplot will function.

A summary of the installation is printed as the script finishes installing
SSMA:

     SUMMARY OF SSMA INSTALLATION:

     1) DONE: Installation of SSMA server is now completed.  Batch jobs 
        are running.
     2) TBD:  Install probe.tar on each client and start canary_probe_start.sh.
     3) TBD:  Configure and start webserver on SSMA server.
     4) TBD:  Make an entry in default.cfg for each client that was started 
        in step 2.

At this point, the server is set up to recieve data from clients.

The installation script will ask for data about the installation to send
back to the SSMA support team.  This is needed when requesting
assistance.

The server-side portion of the installation will then complete and the 
installation script will exit:

	**********************************************************
	*   End of canary_install.sh.  Thanks for using SSMA     *
	**********************************************************


Upgrading Client Software
=========================

To upgrade SSMA/Project Canary client software, first, remove the existing probe
directory on each client:

	client% rm -r /var/tmp/canary/probe

Then follow the installation instructions below, just as if this was an
initial client installation.


Installing Client Software
==========================

Every client must have the SSMA Probe component installed on it,
including the SSMA server.

For each client SSMA software is to monitor, follow these 
instructions:

   1) On each client, make the directory '/var/tmp/canary/probe' as follows:
	   
         client% mkdir -p /var/tmp/canary/probe
	   
   2) Copy the 'probe.tar' package created when installing the server
      software to the client's '/var/tmp/canary/probe' directory.  By
      default, this package is found on the SSMA server as
      '/var/tmp/canary/canary_monitor/probe/probe.tar'
	   
   3) Change directories to '/var/tmp/canary/probe' and extract the 
      client software from the tar package:
   
         client% cd /var/tmp/canary/probe
         client% tar xf probe.tar
	   
   4) Change directories to the "scripts" directory and run the
      following command:
	   
	client% cd scripts
        client% sh get_client_default.cfg_entry.sh
	   
      This script will output an entry required for the SSMA
      server to properly display data.  The output from the script run
      will look like this:
	   
	***************************************************************
	* edit the file /var/tmp/canary/canary_monitor/conf/default.cfg
	* and add the following line to the end of the file
	* you might want to change "Campus" & "Geo" for your grouping, please 
	* see /var/tmp/canary/canary_monitor/conf/default.cfg for column 
	* description
	***************************************************************

	sunblade.Sun.COM        sunblade     Campus      Geo      Y

      Follow the instructions from the script run and place the line
      outputted from the 'get_client_default.cfg_entry.sh' script
      at the end of the 
      '/var/tmp/canary/canary_monitor/conf/default.cfg' file
      on the SSMA data collection server.
	   
      WARNING: SSMA software will only display data on the
               website from clients whose entries are added to this file.
               If clients are not added to this file on the data
               collection server, the server will be collecting data from 
               clients, but that data will not be displayed on the web site.
	            
   5) Start the client software as follows:
	
	client% sh canary_probe_start.sh

      The probe start script will look for any existing SSMA
      processes running, kill them, and then launch the appropriate wrapper
      script.
	   
At this point, both the SSMA server and at least one client are
configured and running.  Repeat the client installation process for as many
clients as SSMA software will be monitoring.

The SSMA server is automatically set up as a client by the 
installation script.  Simply change directories to the probe directory and
run the 'canary_probe_start.sh' script.


Configuring the Server Website
==============================

After the SSMA server software and at least one client have been
installed, the Server Website must be configured so client data can be 
displayed.  This README file assumes the Apache Web Server will be used as
it is bundled with both the Solaris and Linux Operating Systems.  

Modifying the 'httpd.conf' file is needed for the SSMA Website
to display properly.  

On Solaris, 'httpd.conf' can be found at '/etc/apache/httpd.conf'
Linux places it (sometimes) at '/etc/httpd.conf' or under the directory
that the Apache Web server has been installed.

The installation script creates an 'httpd.conf' file that is appropriate
for a SSMA installation.  It can be found under the conf/
directory on the server.

If the 'httpd.conf' file produced by the installation script cannot be used,
at the tail end of the 'httpd.conf' file, the following lines need to be
added before the Web Server is started:

   #
   # Configuration for SSMA Website
   #
   AddHandler cgi-script .cgi pl
   Alias /canary "/var/tmp/canary/canary_monitor/web/"
   <Directory "/var/tmp/canary/canary_monitor/web">
      Options +Includes +ExecCGI +Indexes +FollowSymLinks
      SetEnv LD_LIBRARY_PATH "/usr/sfw/lib:/var/tmp/canary/canary_monitor/components/lib"
      AllowOverride None
      Order allow,deny
      Allow from all
   </Directory>	

The "Alias" line which in this example reads:

   Alias /canary "/var/tmp/canary/canary_monitor/web/"

The SetEnv line which in this example reads:

   SetEnv LD_LIBRARY_PATH "/usr/sfw/lib:/var/tmp/canary/canary_monitor/components/lib"

As well as the line from this example which reads:

   <Directory "/var/tmp/canary/canary_monitor/web">

Should be changed to reflect the directory SSMA software has been
installed to.   If the default directories are used to install SSMA
software, no changes are needed.

The Apache Web server then needs to be started.
	   
Final Notes
===========

The main documentation is placed in the "docs" directory.  There, all the 
documentation needed to install, maintain, and run SSMA software 
can be found.

This software is provided for the use of Sun Microsystems, Inc.
customers.  Sun Microsystems, Inc expressly disclaims any warranty,
guarantee of fitness or suitability for any purpose, and
responsibility for the use or abuse of this software package.
It is provided as is to the public.

