README for grab_configs.sh, Trever Furnish, 020225.

This will hopefully provide enough information for someone who downloads
grab_configs.sh as part of a tarball to decide whether it will be useful,
install it, and get it working.

Note that you use this package at your own risk and under the terms of the
Gnu Public License - I hope it's useful, but there's no warranty whatsoever.

Also note that this is the first public packaging of this version of the
tool, so there are probably some site-specific things left in that ought to
be abstracted out - if you have any problems installing or have to make
any changes just to get it to work, please let me know so I can modify the
package to save future users the effort.  Bugfixes and updates would of course
also be greatly appreciated and if you use it at all it would be nice if you
drop me a note by email to let me know how it goes.

On to the install notes...

What's included:

This package contains one main script (grab_configs.sh) and a couple of
supporting scripts (makeindex.sh and a sample "distributor").  They're all
written in the GNU bash shell's syntax and tested only on a linux system
running redhat7.2 (although they should be easily ported to any POSIX.2
system).

Grab_configs.sh runs a series of user-provided scripts expected to dump
router or switch configurations, archives the output of those scripts,
and sends an email if there have been changes since the last time it was
run.  It also makes archive copies of each changed config in date-stamped
directories.  The script is smart enough to ignore several of the items
in cisco configs that change without human intervention (ie clock period).

Makeindex.sh optionally creates a web page with a date-organized and 
date-sorted list of the archived configs, for easier browsing.  If you
make it available from an actual web server, highly recommend restricting
access to the files - Cisco encrypted passwords can be decrypted really
quickly.

At my present employers we have several remote sites with administrators
who we want to provide this service for but who we don't want to allow
access to the whole archive of device configs from all sites.  For those
sites I use a script I called a "distributor", which just cycles through
the comparisons directory copying any files matching a list of starting
filenames into a directory just for the particular site in question.  There
should be one "distributor" script per seperate site.  A sample script
is included (distributors/lewiston) to get you started - it's generic enough
that you should only need to define some variables at the top of the
script.


How it works:

Grab_configs.sh looks in a directory (config_dumpers) for executable files
to run, running each one in sequence and storing the output of the command
in a "comparisons" directory as "scriptname.clean".  For example if there's
a file in config_dumpers named myrouter, then grab_configs.sh will run that
file and store the output in comparisons/myrouter.clean.  It will also
store a slightly modified version as "comparisons/myrouter.latest" and move
any existing .latest files to end in .previous, overwriting any existing
.previous files.  The only difference between the .clean and .latest
versions is that the .latest version has had some lines removed because
they change all the time without human intervention.  For purposes of
comparison we need to ignore those lines.

Then grab_configs.sh does a cmp of the .latest and .previous files - if
they're different, it does a diff of the two files and adds that to its
accumulated output.  When all config_dumpers have been processed, it will
mail the results to the space-seperated list of email addresses you define
in $EMAILTO at the top of the program.

Since grab_configs.sh just runs other programs to collect the device
configurations, it's pretty flexible (or useless depending on your point
of view :-).  My "config_dumpers" are usually simple expect scripts that
just telnet to the router and do a "term len 0" and a "show run".  If you
don't have expect installed, perhaps the Net::Telnet::Cisco module would
be more to your liking and there's a tool called snarf.pl which is part of
the "router audit tool" available here:

	http://www.cisecurity.org

You may also be interested in wandoc, from http://www.wandoc.com, which
does something similar to RAT - but I haven't tried the product, so this
isn't an endorsement.


Installation notes:

If you're on a redhat system with everything installed in the usual redhat
places, including expect, then you can probably just untar the package
and modify a few variables at the top of each script you want to use,
most importantly "EMAILTO" and "WORKDIR".  It's not all that consistent,
so read the scripts and set what looks good to you :-) -- I'll clean it up
as I get time.  If you don't want to run makeindex.sh, just name it
something else.  If you don't want to run a distributor, don't put one
in the distributors directory.

Note that you *will* have to remove/modify the sample config_dumper and
distributor scripts that are included, since they certainly won't be
appropriate for your site without modifications - they're samples.

You may also need to create some directories manually - there's a sample
of my current, working directory structure to assist you and I'd be happy
to hear from you if you have to create directories.  The sample directory
structure is in the file named 'tree'.


Getting help:

Please feel free to contact me for help with installing or to get added to
my personal list of "people to notify when releasing a new version".  Use
the following email address:

	grab_configs-help@wondious.com


Have fun,
Trever Furnish, grab_configs-help@wondious.com