

       NetSaint Easy Administration Tool (NEAT) Version 4.8
               by jason blakey - jblakey@frogboy.net

                      October 1, 2001





Overview
--------

NEAT is a Perl CGI script which allows for configuration / managment
of that great monitoring application,  NetSaint (by Ethan Galstad).  Using this
CGI script written in Perl 5 you can create, modify, and delete entity
instances such as hosts, hostgroups, commands, etc.

NOTE: i've included entity definitions for both NetSaint versions .0.0.6 and
.0.0.7b3 - choose the right one for your intstallation, and specify it in
your neat4.options file.


Features
--------

NEAT has a lot of features and more are on the way.  Currently, the feature
list includes:

*  Perl CGI script.  Does NOT require a database backend.
*  Presents a heirarchical view of the NetSaint configuration.
*  Access check for httpd authenticated users.
*  Can log modification history (with httpd username if available).
*  Can be used to maintain multiple configuration files.
*  Optional verification of NetSaint configuration using the '-v' command
*  User-configurable input verification.
*  User-configurable entity definitions.
*  User-configurable deletion schemes.


Contents
---------

The NEAT package consists of the following parts:

neat.cgi             The main script.
neat4.options        Options which need to be set for NEAT to properly run.
deletion_rules       Rules defining how to delete each entity type.
ver_tags             Input verification tags.
0.6_entity_defs      The entity definitions for NetSaint version 0.0.6
0.7_entity_defs      The entity definitions for NetSaint version 0.0.7
GPL                  The GNU public license.
adminbar.gif         A small graphic which can be used to make a link to
                     NEAT in your NetSaint side.html page.


Installing NEAT
---------------

To install NEAT, you need to perform the following steps:

1.  Move your neat.cgi file to your NetSaint /sbin directory, usually
    /usr/local/netsaint/sbin.

2.  Make neat.cgi executable by your web daemon.  Usually 'chmod a+x neat.cgi'

3.  Edit the line near the top of neat.cgi that looks like this:

$OPTIONS = "/usr/local/netsaint/neat4/neat4.options"; 

    and change this to the proper location of your neat4.options file.

4.	Check to make sure your perl executable lives at /usr/bin/perl.  If
	not, you will have to change the first line of neat.cgi to point
	to where Perl lives on your system.

5.  Edit your neat4.options file, setting each option as need be.
    (This will be discussed in detail later in this document)
	DO NOT SKIP THIS STEP - you need to verify/change almost
	every option in neat4.options.

6.  Make sure that your NetSaint hostfile(s) is/are writable by the
    userid/group that your web server runs as.  I usually put "nobody" in the 
    netsaint group, and then do a 'chmod g+w hosts.cfg', but it's up to you.

6.  Try running NEAT by going to the proper URL... usually

http://yourbox/cgi-bin/netsaint/neat.cgi

    This will depend on how/where YOUR NetSaint is installed, of course.


The Options File
------------------

The neat4.options file sets a number of very important options.  They are
described in gut-wrenching detail below (please see the included neat4.options
file for examples):

$ENTITY_DEFS        This option points to where your entity definition file
                    lives.

$DEL_RULES          This option points to where your entity deletion rules
                    file lives.

$VER_TAGS           This options points (suprise) to where your input
                    verification tags file lives.

@CONFIGS            This array lists your entity configuration files.   NEAT 
                    should know about ALL your entity instances (all commands,
                    hosts, hostgroups, contacts, contactgroups, etc) or
                    strange things may happen.

$CGIPATH            This option defines the path to your netsaint cgi-bin
                    directory, relative to your web servers point of view.

$COLOR1
$COLOR2
$TEXTCOLOR1
$TEXTCOLOR2         These options define the color-scheme for NEAT. Each can
                    be either hex or RGB values.


@REMOTE_USERS      If this array is defined, it lists which httpd
                   authenticated users are allowed to access NEAT. If you 
                   don't wish to use this feature, comment this line out with
                   a #.

$VERIFY_COMMAND    If this option is defined, NEAT will attempt to run
                   this command before it lets the user restart NetSaint.
                   This is to prevent restarting NetSaint when there are
                   issues with the configuration files. If you don't wish
                   to be able to restart Netsaint through NEAT, comment
                   out this line.

                   NOTE: this option relies on having check_external_commands
                   enabled in your netsaint.cfg file.  If you choose NOT
                   to enable that option, you can't enable this option - 
                   so comment this line our in your neat4.options file.

$MOD_LOGFILE       If this option is defined, NEAT will log the date/time/
                   httpd username (if available)/action to a logfile.  Make
                   sure that this logfile is writable by your httpd uid/gid.

@HNC
@SNC              These arrays are refered to from the entity_defs file, and
                  specify choices for host notification commands and 
                  service notification commands.  Much more on this later.


The Entity Definitions File
---------------------------

This file is the heart of NEAT.  It defines the fields that make up
each entity type in NetSaint.  Because of this, this file is VERY delicate.  Any
errors in this file can cause VERY strange things to start happening.

Now, i'm not trying to say don't mess with this file - feel free to change
things to suite your own needs.  I'm only saying if you don't understand this
file, DON'T CHANGE IT.  The only exception might be the DEFAULT VALUE field,
which you can muck with as you like.

As defined in the entity defintions file, each entity is made up of variables.
And each variable is made up of fields.  There are currently 11 fields that
must be defined for each entity variable. These fields are ":" delimited.

These fields are defined as:

FNum      Name                Description
-----------------------------------------------------------------------------
0         Variable Name       Name of this variable.  This field should not 
                              contain any spaces.

1         UD or not           This field tells NEAT whether or not this
                              variable is a unique-descriptor for this
            			      entity type.  That is, NEAT will not allow
                              you to create another entity with the same
                              variable value as an existing instance, if
                              this field is set to UD.

2        MULTIPLE/SINGLE      This field tells NEAT whether this variable
                              is a list (, delimited) or a single item.

3        Nice Name            This field is the nice version of the variable
                              name.  It can contains spaces.

4        Ver Tags             What input verification tags should be applied
                              against input for this variable? These tags are
                              listed in the ver_tags file. If there are
                              multiple verifiation tags applied, they should
                              be "," delimited.

5        HTML form type       What form type should NEAT create for this
                              variable?  Valid types are TEXT, SELECT,
                              and CHECKBOX.

6        HTML options         What options should NEAT apply when displaying
                              /creating this variable? Eg. SIZE=30. 

7        Linked To            This is a little tricky.  This field can contain
                              one of two options.  (1)  the name of an array
                              defined in neat4.options, or (2) host,field 
                              descriptor.  This option allows NEAT to diplay
                              a list of pre-defined options to choose from,
                              eg. the hosts in a hostgroup, or the parent
                             of a host.

8       Extra Fields Delim    This field defines (if necessary) the delimiter
                              that is used when creating a multi-field field.
                              See next field.

9       Extra Fields          This one is also a little tricky.  This field
                              allows the user to define a list of fields,
                              which are displayed during modification or
                              creation, which are then joined into one field
                              when output to the hostfile.  The only case in 
                              which this is currently used is in the SERVICE
                              definition.  Check it out for an example of use.
			      
10     Default Value          The Default Value for this field.  If you wish
                              to have a CHECKBOX default to being checked,
                              put CHECKED in this field.


Input Verification Tags
-------------------------

NEAT version 4.0 allows for user-configurable input verification, and this
file allows that functionality.  The format is:

TAGNAME                PerlRegex

Please see the included ver_tags file for examples.


Deletion Rules
---------------

NEAT version 4.0 also allows for user-configuration entity deletion behavior.
This behavior is defined the deletion_rules file.  Format is:

entity_type {
deletion_rule
.
.
.
}

where entity_type is one of the entity types defined in entity_definitions,
and deletion_rule follows the following format:

MODE:ENTITY_TYPE:My_Field:Your_Field

MODE           Can be either REMOVE or UNREF.  Believe these to be self-
               explanatory.

ENTITY_TYPE    What kind of entity do we apply this action to?

My_Field       When we are searching for ENTITY_TYPE instances to execute
               our MODE on, which of My_Field's do we match with Your_Field.

Your_Field     The field of the ENTITY_TYPE that we are matching on.

There can be as many rules as you like as instruction for how to delete an
entity, and they are recursive.  This is, if you set it up like this:

hostgroup {
	REMOVE:host:3:0
}

host {
	REMOVE:service:0:0
}

service {
}

Then if you delete a hostgroup, NEAT will search for an delete all hosts
in that hostgroup, and then delete all services for each of those hosts. This
configurability can be very powerful, but very dangerous.  

NOTE: you will be perfectly alright going with the default deletion_rules,
if you are feeling intimidated with all this. :)


Bug Reports / Feature Requests
-------------------------------
As always, i appreciate hearing comments/suggestions/questions, and will try
to get back to you as soon as possible.

Thanks, and happy NetSainting,

jason


jblakey@frogboy.net
June 05, 2001



Notes
------

- NEAT v4.7 does not yet handle serviceescalations. Perhaps in v4.8.
- NEAT v4.7 does not yet handle service dependencies. Perhaps in v4.8.


Contributors / Bug Reporters
 (In No Particular Order)
-----------------------------

Rene Hertell <rene@hertell.com>
Pramod John <pramod@SonicWALL.com>
Tom Lichti <Tom_Lichti@interactivemedia.com>
Hans Endresen <hendresen@sitesmith.com>
Tim Chipman <tdc@MailAndNews.com>
Tom Bertelson <tbert@abac.com>
Petroff Alexander <asp@memonet.ru>
Sean Eckton <sean@gwbeta.byu.edu>
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>
Devon Harding <DHarding@gthla.com>
Aaron McKinnon <aaron@fullerene.com>
Benjamin Cuthbert <Benjamin.Cuthbert@ft.com>
Ben Bell <bjb@deus.net>
Some other people whose email addresses i have since lost...
My Boss, Marla McDougall, for giving me the time to make it right. 
My Other Boss, Andre Barrette, same reason...:)
Other people who have reported many bugs...


Disclaimer
-----------
 
 NetSaint Easy Administration Tool
 Copyright (C) 2001  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       
