v2.15                How to Install routers.cgi script
                     ---------------------------------

Before Starting
---------------
First, you need to make sure you have the following installed:
	MRTG
	RRDTool (v1.0.39 or later).  Install perl modules under site-perl.
	Perl (V5 or better).  If under NT, make sure you have configured any
	    necessary extension associations and so on.
	Perl CGI libraries (many installs, eg ActivePerl, have this as standard)
	Perl File::Basename library (this is probably standard)
	Perl Text::ParseWords library (this is probably standard)
	Perl Net::SNMP library (only if you want to use Routing Table extensions)
	Perl GD library (if you want to use the compact summary screen) with
        the necessary gd support libraries ( see http://www.boutell.com/gd/ )
	Perl Time::Zone library (not required, but used if you have it.  If
     using multiple timezones under Windows then you really need it)
	A web server (duh).  If using Apache, you need mod_expires

You probably already have most of these, if you have already installed MRTG 
and RRDTool.

Before using mod_perl or speedycgi, check out the sections in the PROBLEMS
and HOWTO documentation!

Make sure you have the latest version of routers.cgi.  Check on
http://www.steveshipway.org/software/ 

Next, you need to make sure of the following:

* All MRTG .conf files to be handled by routers.cgi have the 'UseRRDTool' or
  'Logformat: rrdtool' option set, and their databases are in RRDTool format.
* Each MRTG .conf file deals with a different router. (Not necessary, but
  advised)

The last will be correct if you created your .conf files using the
cfgmaker command that comes with MRTG.  I suggest you use the cfgmaker
command with the '--descint --ifdesc=descr' options set.

Fast Install
------------
If you have a faily generic system, running NT or some flavour of UNIX, 
probably with either IIS or Apache, then you can use the install script.
In fact, unless you have a very unusual setup, you can probably use this 
script.
Just run:
	perl install.pl
and this should ask you a few questions, giving sensible defaults most of the
time.  Unless you have a customised system, this should install it for you!

If you cannot use install.pl, or you prefer to do it by hand, then read on.

If you have not yet created your MRTG .cfg files, you may wish to use the
script buildwan.pl in the extras directory -- it creates all necessary .cfg
files for your entire WAN.

Also, see the section at the bottom about running targetnames.pl

Use of routers.cgi under Windows NT
-----------------------------------
I have now tested this with Apache and ActivePerl.  However, there are a few
caveats.  The script relies on the .htaccess file to force the expiry of
old graphs.  If you are using Apache under NT this is still OK, but IIS
does not use the htaccess file.  You need to ensure that the graphs directory
is either set for the appropriate expiry times, or set to NEVER CACHE.
After taking a look, it appears that in IIS you can only set expiry times for
an entire directory at once.  So, set the graphs directory to expire in
5 MINUTES.

Installing routers2.cgi (not using install.pl)
----------------------------------------------

You will need to modify the '#!/usr/local/bin/perl' on the first line of the
scripts to reflect the correct location of your perl executable (the install
script does this for you).

Dont forget to install the RRDs perl libraries!

Remember that while NT uses backstrokes '\' as path separators, URLs use
forward strokes '/'.  So, when editing the routers2.conf file, make sure you
use the correct strokes when defining URL paths and filename paths.

People using ActivePerl should look in the documentation to find out how to
set up their web server to run Perl CGI scripts.  This can be found at:
http://velocity.activestate.com/docs/ActivePerl/faq/Windows/ActivePerl-Winfaq6.html

Most of these instructions are UNIX-centric.  Windows NT people should make the
appropriate changes for directory paths, permissions, and so on.  You will
obviously need the Windows version of Perl installed and made CGI-able.  The
same applies to people with Macs or any other more obscure OS.

Timezone support under Windows is minimal, due to limitations of the O/S that
are compiled into RRDTool.  Under windows, you cannot have a different 
timezone for each target.  If this is a problem, then stick with MRTG (the
compiler used for MRTG does not have the problems that RRDTool does).  This
may well be corrected in a later version of RRDTool - so get the latest version!

Creating Directories
--------------------
Now you need to decide where to put the files.  The directories you will
need are as follows:

CGI-BIN DIRECTORY: This is where the routers.cgi file goes, with read and
  execute permission.  This directory should be visible to your web browser
  with exec-cgi flag set. ( 'Script' flag in IIS )

ICONS DIRECTORY: This is where all the .gif files are put.  This directory
  should be visible to your web browser.  Make a note of the directory's URL
  This should not be under the CGI-BIN directory.  Usually called /rrdicons
  or similar.

GRAPHS DIRECTORY:  This is the work directory for the graphs.  It needs to 
  be writeable to the httpd UID, and otherwise empty.  The htaccess file should
  be placed in here.  This directory also needs to be visible to your web
  browser.  Make a note of the URL of the directory, and its path in the 
  filesystem.  Note that under some web servers you do not have the htaccess
  file - you should do whatever is equivalent on your server.  Also, Apache
  needs to have the mod_expires module installed to use htaccess. IIS users
  should set the directory to expire in 5 MINUTES.
  This should not be under the CGI-BIN directory.

DATABASE DIRECTORY: Where the RRDTool .rrd databases are kept.  This should
  already exist.  It should not be under your web server root.

MRTG CONF DIRECTORY:  Where the MRTG .conf files are kept.  This should
  already exist.  It should not be under your web server root.

Configuring the perl script
---------------------------
This is now done via a separate configuration file.  You should modify the 
script so that it knows where the conf file is (the line is clearly marked
at the beginning of the .pl file), and (if necessary) modify the path of
the perl executable in the first line of the script. ( $CONFFILE = "...." )

The conf file should have at least 2 sections, [web] and [routers.cgi].  The
first needs an entry 'backurl' to define where the 'Main Menu' button takes us.
The other section defines all the other options that used to be hardcoded into
the script.

A third section, [routerdesc], is now DEPRECATED.  Don't use it unless you
have to.

A fourth section, [targetnames]  is optional and allows you to override the 
default short description for the routers and interfaces.  You key this
section with either the MRTG .conf file name, or the interface target name.

The short description for a router is taken as:
	: The entry for the MRTG .conf file in the [targetnames] section
	: The entry in the [routerdesc] section, or
	: The 'ShortDesc[_]: ....' entry in the mrtg.conf files, or
	: The first word in the 'Title[..]: ...' line in the mrtg.conf files
      (this is also the key used to uniquely identify the router in
	  the [routerdesc] section)

A fifth section, [targettitles] is optional and allows you to give the 'long'
description for each interface.  This corresponds directly to the Title[]
directive in the MRTG files.  If you made your MRTG config files using
cfgmaker with the --descint option, you may not need do do anything here.

See the example routers2.conf file, and the README file for more information.

You now need to put this configuration file somewhere - I suggest in
/usr/local/etc - and then modify the script routers.cgi so that it knows
where to find this file.  The line to modify is clearly indicated at the
start of the script.  As shipped, it is configured to be kept in the file 
/usr/local/etc/webdev.conf

targetnames.pl
--------------
This is a script to automatically build the [targetnames] section of your
routers2.conf.  AFTER configuring the routers2.conf file, you can run this
using the command
	perl targetnames.pl routers2.conf > targetnames.conf
changing 'routers2.conf' to be the full pathname of wherever you have installed
your routers2.conf file.  If you used the install.pl script, this will probably
be in the same directory as your .rrd files.
This command will use SNMP to query your routers, and will output on STDOUT
into targetnames.conf the necessary configuration directives which you can edit
and add in to your routers2.conf file.
The script looks in SNMP for the interface names and descriptions (if they are
available) and formats them for the routers2.conf file.

Installing the files
--------------------
Copy the routers.cgi file to the CGI-BIN directory, permission 555 (read
and execute).  If it is called routers.cgi.pl in the package then rename 
it to routers.cgi (UNIX, Apache) or routers.pl (NT with IIS)

Copy the htaccess file to the GRAPHS directory as .htaccess, permission 444.
This is not necessary if your web server does not use htaccess files - you 
should do the equivalent for your server.  Apache may need mod_expires 
activated for htaccess to work, and AllowOverride set for the GRAPHS directory.

Copy the *.gif files to the ICONS directory.

Testing the script
------------------
It should now work!  Point your browser at the routers.cgi file, and see
what you get.  Note that you MUST have javascript enabled on your browser
for the pages to function correctly, and you need cookies enabled if you
want to use the personal preferences page.

routingtables.cgi
-----------------
You may wish to use the experimental Routing Tables extension.  To use this,
you must do the following:
* Install Net::SNMP
* Install the routingtables.cgi script in your CGI bin.
* Uncomment the 'routingtableurl' directive in the routers2.conf
This will result in a new link appearing on the 'info' page for each router,
allowing you to view the current routing table on the router in question.
Note that this may have problems with NT servers, particularly when used with
IIS as the web server.
The link will be hidden in the event that it cannot work out the necessary
information.
Also, your community strings will appear in your browser history.  If this is
a security concern to you, then do not enable this feature.  If you do enable
it, then make sure your community strings are READ ONLY and preferably 
restricted to just the IP address of this monitoring server.

Contacting me
-------------
Try one of the following:
web: http://www.steveshipway.org/software (main site)
     http://www.shipway.org.uk/software (popup ads - yeuchk)
email: steve@steveshipway.org (preferred), s.shipway@auckland.ac.nz (work), 
	steve@shipway.org.uk (last chance)
mailing list: http://www.steveshipway.org/mailman/listinfo/support_steveshipway.org
forum: http://www.steveshipway.org/forum/index.php
Yahoo IM: steveshipway
ICQ: #210588157
AIM: shipwaysteve
MSN: s.shipway@auckland.ac.nz
Please don't telephone me, unless you want to offer me money :-)

Thanking me
-----------
Encourage development by sending me something from my Amazon Wishlist
http://www.amazon.co.uk/exec/obidos/registry/3S0PX0NTU8KDC
Details on http://www.steveshipway.org/software/wishlist.html

People who send me something have their names added to the Information page,
and also get a warm, fuzzy feeling deep within from having given something
back...

-Steve
