README for System Summaries ("syssumm")

$Header: /export/home/mohlerb/src/perl/syssumm/RCS/README,v 1.2 1999/06/14 22:27:15 mohlerb Exp mohlerb $

$Revision: 1.2 $

$Log: README,v $
Revision 1.2  1999/06/14 22:27:15  mohlerb
added info on how the source code is maintained and the
syssumm mailing list

Revision 1.1  1999/05/30 19:31:03  mohlerb
Initial revision


What is syssumm?
----------------

syssumm ("system summary") is intended to be an automated way to
produce system profiles of computer systems accessible on the web.
The profile would include general, hardware, network, and software
configuration information about the system in question.

The collection of the information is automated via a Perl script
which automatically e-mails it to the system with the web server
and it is automatically integrated into a set of directories, one
for each profiled system.

Information that can only be provided by humans can be integrated
into the automatically collected information easily.

The format of the web page profiles can be tailored to the needs
of local organizations.


What operating systems will syssumm produce a profile for?
----------------------------------------------------------

syssumm.pl can profile the following operating systems:

	AIX 4.X
	IRIX 5.3 through 6.5
	HP-UX 10.X and 11.X
	HP-UX 9.X (partial)
	Linux (Red Hat 5.1)
	SunOS (Solaris 2.X)


What operating systems and web servers will run the web server software?
------------------------------------------------------------------------

The web server scripts (incoming.pl and sysquery.pl) have 
been run on:

	RedHat Linux 5.2/Apache

At the present time, the web server scripts assume that
they are running on a UNIX machine with some "late" version
of sendmail.


What are the software requirements to run syssymm?
--------------------------------------------------

On the remote UNIX-based systems the only requirement is 
Perl 5.x.  No additional CPAN Perl modules are required to 
run the profiling script.  On the remote NT-based systems
you need to be running a "fresh" version of Perl from 
ActiveState.

On the web server system the only requirement is a 
sendmail-like MDA that allows the processing of messages 
through a .forward mechanism and Perl 5.x.  The web
server must support handling CGI scripts written in Perl.


What software comprises syssumm?
--------------------------------

There are 2 parts to the syssumm software.  First, there is the
software that runs on the remote systems and collects the config
information.  Second, there is the software that runs on the web
server processing incoming messages and merges the information
into the appropriate directories.

The "remote" software is composed of a Perl "driver" script called
syssumm.pl which makes calls into OS-specific Perl modules plus a 
common Perl module of utility subroutines.  In general, there is 
a Perl module for each vendor's OS.  For example, for Solaris, 
HP-UX and LINUX you would have:

	HPUX.pm
	LINUX.pm
	SunOS.pm

Only the module for the local OS running on the system is "used"
by the syssumm.pl script.  For example, if you are running the
script on a Sun box, the HPUX.pm and LINUX.pm modules are never
loaded.

When it came to extracting information about the remote system,
*keeping things simple* was valued over being extremely clever.

The "web server" software is composed of a Perl script called
incoming.pl that extracts and processes incoming e-mail messages, 
and a CGI Perl script called sysquery.pl that generates an HTML
form as well as processing the returned results of that form and
displaying a system summary.  The CGI script also generates a
web page summarizing all existing system profiles.


How does the software work (in general)?
----------------------------------------

First, the system administrator sets up the web server 
software.  He or she creates a new account on the system with 
a userid of "syssumm" on the system where the web server exists.  
The output of syssumm.pl whould be e-mailed to this account.

Next, in the home directory of the "syssumm" account, the
system administrator creates a .forward file that delivers
each incoming message to the incoming.pl script that processes 
the messages and places them in the appropriate directory 
under the web server.

The system administrator loads the "remote" software onto a
system they wish to profile and either manually runs (or sets
up cron to periodically run) the syssumm.pl script.  The "-m"
command line option specifies the e-mail address to mail the
output to (this should be "syssumm@webserver...").

Next, a pointy haired user brings up the form (generated by
sysquery.pl) and enters the name of a system which is sent 
back to the same sysquery.pl script to interpret.  If the
name equates to an existing system for which their is profile
information, then that information is formatted as HTML and
returned to the requestor's browser.

A format file is used to control the appearance of the web
page so that you can choose what fields you wish to display
in your system summaries and what order they appear.

The existing sysquery.pl script is intended to be an example
of how to query and retrieve system profiles since it will 
obviously not look like your local web pages.


What does the data look like generated by the remote scripts?
-------------------------------------------------------------

The information generated by syssumm.pl and processed by
incoming.pl is a basic ASCII flatfile.  Each line is
self-sufficient and is composed of:

	category:sub-category:value

The following categories have been "hard-coded" into the
script that creates the output:

	General
	Hardware
	Network
	Software
	Comment

Within each category are sub-categories.  For example, within
the General category, you'll find

	NodeName
	Organization
	Vendor
	Model
	...

Some of the sub-categories are "indexed".  For example, the
sub-categories for disks and tapes look like:

	Disks-0
	Disks-1
	Disks-2
	...
	Tapes-0
	Tapes-1
	...

Each line represents an individual device.

Entries in the Comment category are optional.  They would be 
things like "Run as root to get more information".

This is what the actual lines would like for a hypothetical
system:

	General:NodeName:dino
	General:Organization:PROTECTED
	General:Vendor:Dell
	General:Model:Geewhiz
	General:HostId:12345678
	...

Note that certain lines contain the value "PROTECTED".  These
fields signify that this information cannot really be figured
out by a stupid Perl script and really need the omniscience of
a human system administrator.

If a system has been profiled in the past and an updated profile
is sent to the web server system, PROTECTED fields will not
overwrite prior contents.  This is especially effective when
the system administrator has gone in and provided the information
that the Perl script couldn't figure out.  This feature protects
the work that they've done so that they don't need to fill in
those fields again.

Note that when the the incoming.pl script processes PROTECTED
fields (especially for the first time), it changes "PROTECTED"
to "To be provided." (to make things more readable).


Multi-line values and Extensibility
-----------------------------------

The system is extensible (in the sense that you can add 
fields to the profile).  When incoming.pl merges a new
profile into an old one, non-PROTECTED fields "overwrite"
existing fields, existing PROTECTED fields are unchanged,
and new PROTECTED fields are installed in the profile as
"To be provided".  As long as you add them to the format 
file that controls the CGI/HTML output, they will appear 
in any system profiles requested after that point.

PROTECTED fields are allowed to be a "pointer" to a file rather
than a single line of text.  In fact, if the value begins with 
a '.' (period) or '/' (forward slash) (indicating a relative or 
absolute path, respectively), and if that file exists, then it 
will include the contents of the file in place of the value.


How is the syssumm software installed?
--------------------------------------

[See another file in this directory called INSTALL.]


How can the system be extended for computer/models not yet covered?
-------------------------------------------------------------------

There is a group of people known generically as the "syssumm
Development Team".  These people responded in e-mail to the
original author (Bruce Mohler) after reading an article in the
April 1999 :login; describing the software.  The team members
have taken the software far beyond its state as described in
the article.

The members of the "syssumm Development Team" are listed in
the file DEVELOPERS in this directory (which is a sym link to
the list of subscribers used by majordomo to maintain a mailing
list).


How do the Development Team communicate?
----------------------------------------

Bruce Mohler maintains a majordomo mailing list at 
syssumm@troodon.saic.com.  People expressing interest in syssumm
are automatically added to the list, but anyone can, for any reason,
unsubscribe from the mailing list.

In addition, there is a second mailing list called 
syssumm-bugs@troodon.saic.com.  Only those members of the first
list who have actually contributed code are members of this 
list.  After the first contribution, they are automatically
added.  All bug reports go to the active developers.  Anyone on 
this list can, for any reason, unsubscribe from the mailing list.


How is the Source maintained?
-----------------------------

The "master" source tree is maintained by Bruce Mohler.

Periodically, the source tree is tar'd and gzip'd and e-mailed
to the "syssumm Development Team".  As the members extend the
code, they check it in on their system and e-mail a patch-format
diff file to Bruce Mohler who is the maintainer of the master
source tree.

If at a certain point the source tree gets too large to e-mail
or the Development Team gets tired of the weekly source releases,
we'll convert to CVS.


Automatic Profiling at System Boot
----------------------------------

Some system administrators would like their systems to be 
profiled automatically every time the system is booted up.

There is a sub-directory called "startup" in the top level
directory of the source tree with sub-directories for each
operating system for which an rc file exists.  Thanks to
Frank Crawford for starting this.


