Documentation for NetSaint Easy Administration Tool (NEAT) Version 3.0
                                  by
                             jason blakey
                          jblakey@frogboy.net
                            August 14, 2000

Overview
----------

- NEAT provides a web-based administration tool for NetSaint Version 0.0.6b4
NOTE: This version of NEAT works ONLY with NetSaint version 0.0.6b4.  Use NEAT
version 2.5 with NetSaint version .0.0.5.

- NEAT now relies on the NetSaint built-in command system to restart NetSaint.
  Thus, there is no restart_netsaint.cgi script anymore.

- NEAT is written entirely in Perl5.

- NEAT does not use JAVA in any way, shape, or form.

- NEAT is distributed under the GNU Public License - see the disclaimer
  at the bottom of this document.

Installation
-------------

Step 1:
To install, place the following scripts inside your netsaint installations
sbin directory:

admin.cgi
display_entry.cgi
write_entry.cgi

Step 2:
Each one of these scripts has a section that looks like this at the start:

########################### CONFIGURATION #################################
$CONFIG = "/usr/local/netsaint/neat.options";
###########################################################################

This line MUST point to where your neat.options file is.  Your neat.options
file defines many things - please see the neat.options file included with
this distribution for a working configuration (my configuration).

Step 3:
Each script starts with a line that looks like 
#!/usr/bin/perl

If your perl does not live in /usr/bin, you will have to
1.  Change the first line in each script to point to where your perl lives

                            or

2.  Create a soft link from where your perl actually lives to /usr/bin/perl
    example:   ln -s /usr/local/bin/perl /usr/bin/perl
    This of course assumes you can write to the /usr/bin directory (which 
	is something only root should be able to do.)

Step 4:
Make sure that the hosts.cfg file is writable by your web server user.  E.g., my
httpd runs as nobody - so i have added nobody to the netsaint group, and 
made the hosts.cfg file group netsaint, and group writable.  Perhaps a 'ls -l'
will make this clearer.
$ ls -l
total 18
-rw-rw----   1 netsaint netsaint    11589 Mar  9 14:10 hosts.cfg
-rw-r--r--   1 netsaint netsaint     5341 Feb  2 09:03 netsaint.cfg   
$

Step5: 
That's it!  Point a browser to http://your-host/your-netsaint-cgi-bin-dir/admin.cgi
and hopefully, it should work!


Script Details
--------------

 admin.cgi
	This script reads through the hosts.cfg file, and displays currently
	defined entities.  It also present options to modify/create entities.
	NOTE: as of version 1.4, this script also keeps track of what
	entities are referenced by other entities.  An entity that is
	referenced by another entity cannot be deleted UNTIL the referencing
	entity is deleted (is this confusing?:)).

 display_entry.cgi
	This script will either accept data for a new entity, or display and
	allow you to change the details for an existing entity.

 write_entry.cgi
	This is the script which writes new entries or modifications to the
	hosts.cfg file (NOTE: the cfg file must be writable by the username
	your web server runs under).



HOW TO USE THE SYSTEM:
	These scripts are all CGI's, and as such, need to reside in a
	cgi-bin directory.  The way i do this is create a symbolic link
	from /usr/local/netsaint/sbin to /opt/apache/cgi-bin/netsaint.

	Then, to access the administrative interface, i just go to
	http://mybox/cgi-bin/netsaint/admin.cgi
	and there i am.

	NOTE: make sure the hosts.cfg file is writable by the owner of your
	apache (i'm assuming apache) process.

Thanks,
jason blakey
jblakey@playground.net
April 03 , 2000 
Updated August 04, 2000
Updated again - August 14, 2000


REVISION HISTORY
----------------

Version 1.0
January 5, 2000
Initial Release

Version 1.1
January 10, 2000 
- Fixed two bugs, one dealing with ignoring spaces in the hosts.cfg file,
  and one dealing with optional args to the check command - thanks to 
  vladimir naprstek for
  finding 'em (actually, i had known about the optional args one, but i 
  conviently forgotten about it:))

Version 1.2
January 11, 2000 
- Fixed (again) that bug with optional args to the check command.
  (Hopefully, this time i haven't introduced a new bug):)
  Thanks to vladimir, again:)

Version 1.3
February 1, 2000 

- fixed a bug with a fixed path to CGILIB in the admin.cgi script (Thanks to
  tony kelly for that one).
- fixed a bug with displaying a selected contactgroup in a hostgroup
  definition.
- added a check to admin.cgi and write_entry.cgi to verify the readablity and
  writability of the $HOSTS file.

Version 1.4
March 09, 2000
- many changes made / features added
- References now in place.  The admin script keeps track of how many entities
  reference each entity.  If this 'refcount' is greater than zero, that entity
  cannot be deleted.  Instead, a list of what entities reference that entity is
  displayed.
- The delete button now has a confirmation check box.
- Host creation is much simplified.  To create a host in a past, you had to:
  a.  create the host
  b.  create a service for that host
  c.  add that host to a hostgroup
  As of version 1.4,  this all takes place in one screen.
- The restart_netsaint script will now also recreate the NetSaint HTML
  files using the netsaint -h command.
- Spaces are now allowed in description fields!:)
- Many layout changes, color changes, internal fixes and some standardization.
- Many changes to the README.txt file.
- New sample sudoers and neat.option files.

Version 1.5
March 10, 2000
- now allow FQDN (full-qualified domain names) in the HOST definition

Version 1.6
March 17, 2000
- fixed a bug with host definition - ip or fqdn now works
- fixed two typos

Version 2.0
March 27, 2000
- admin.cgi is now heirarchical!  Much easier to use!
- admin.cgi completely rewritten - much cleaner (at
  least to me!:))
- Colors are now user configurable.  See the $COLOR1 and
  $COLOR2 variables in neat.options.
- Many little tweaks and pokes.

Version 2.1
April 03, 2000
- fixed a couple of typos.
- fixed a problem with admin.cgi trying to print an error
  concerning the permissions on the hosts.cfg file, and
  putting a space in it's html header - grrr...
- fixed a time period bug in service notification
- fixed a bug in hostgroup creation (if no hosts
  defined initially).

Version 2.5
August 04, 2000
- When a host is now deleted, all services linked to that host will
  be deleted as well!  Also, all references to that host will be cleaned
  up.
- When NEAT rewrites the hosts.cfg file, it is now divided into sections,
  each with a nice bold label.
- Fixed an error preventing services from notifying multiple contact groups
  when there is a problem.   i.e., services can now have multiple contact
  groups.
- Typo fixed.

Version 3.0
August 14, 2000
- Properly parses the 0.0.6b4 hosts.cfg file.
- Will no longer work with NetSaint 0.0.5 or previous.
- Some code cleanup
- Bug Fixes.

CONTRIBUTORS - BUG REPORTERS
----------------------------

Vladimir Naprstek <vladimir.naprstek@prodeco.cz>
Tony Kelly <tony@kenny.net>
Mark Schenker <marks@infostructures.com>
Tim Palmer <tim@yni.net>
Rob Wilderspin <rob@magic-moments.com>
Christopher Gurnee <gurnec@thecia.net>
Christian Steger <christian.steger@hm.inode.at>
Blair Copeland <copeland@unt.edu>
Some other people whose email addresses i have since lost...
My Boss, Marla McDougall, for giving me the time to make it right.

DISCLAIMER
-----------

NetSaint Easy Administration Tool 
Copyright (C) 2000  jason blakey

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.


CONTACT INFORMATION
-------------------

Please email comments / suggestions / bugs to:
jason blakey <jblakey@frogboy.net>

         or

jason blakey
67 Chester Crescent,
Nepean, Ontario
Canada
K2J 2J6


Thanks,
jason
jblakey@frogboy.net
