WWWWWW

Current Directory: /usr/share/doc/mrtg/contrib/whodo
Viewing File: /usr/share/doc/mrtg/contrib/whodo/README
WHODO

This is Whodo 1.11.

Whodo is a set of Perl scripts to analyse IP accounting data from a cisco 
router. The stats for each traffic source are fed into mrtg. Whodo also 
generates pie graphs showing traffic split by source or destination.


HOW TO

1. Put the scripts in the appropriate directories. There are 3 sets of files in 
whodo.
(i) Whodo/gifgraph contains a perl module written by Martien Verbruggen. 
I've made some changes to it so it does what I need. However I haven't 
been able to contact Martien & get them included in his distribution. GIFgraph
is used by �pie.pl�. You'll need to copy this to wherever you put 
your Perl modules. Note that gifgraph uses another module GD.pm. GD is 
available in/for the standard Perl distribution and ActivePerl. However if 
you use Perl for Win32, you are on your own.
(ii) Whodo/wwwscripts contains 2 CGI script. Put them wherever your CGI 
scripts live.
(iii) Whodo/* contains everything else. I keep this stuff under 
mrtg/contrib/whodo.

You'll also need the module SNMP_Session. If you don't have it, get it from
ftp://ftp.switch.ch/software/sources/network/snmp/perl/

2. Start IP accounting on the router. If you don't know what you are doing 
here, tread carefully � you can bring the router to its knees.

The community string that you will supply in the next step, for the $HOST
variable, must have READ-WRITE access to the router.  COLLECT.PL clears
the accounting list (SNMPSET) once the data is collected to not be double
counted and surely to keep reduce the memory requirements on the router.
To do this at the (config) prompt type : snmp-server community (your
community name) RW.  DO NOT do it to the community public, this will
leave your router open to attack.

3. You'll need to customise some constants at the start of collect.pl. You'll
need to change $HOST & $SOURCEDIR. $LOGPATH isn't relevant until step 6 
but you should set it up now. $BIGBYTES you'll probably need to keep 
tweaking. Basically, any source that generates more than $BIGBYTES 
between polls will get its own MRTG graph for ever more. Sources that 
never generate this much traffic will be grouped together as 
�Miscellaneous�.

$LOGPATH also occurs in pie.pl & makeanalyse.pl

4. You'll want to create a networks file � such as the standard �networks� file 
found in C:\winnt\system32\drivers\etc or /etc/networks. Collect.pl scans the 
file including comments following a normal line of data. The file is used to map
destination addresses to network names. Which makes the output (see step 6) much
more user friendly.

The file has a second function. If a trailing comment includes a �/� followed 
by a number, this is taken as the classless representation of the subnet mask 
size. If not, the network/subnet is assumed to be Class C.

A sample networks file is included.

5. Set collect.pl up to run periodically. I run it every 30 minutes with 
something like:

collect.pl -a c:\perl\mrtg\contrib\whodo\sources.cfg -n \
c:\winnt\system32\drivers\etc\networks
mrtg c:\perl\mrtg\contrib\whodo\sources.cfg

I've included a vestigial �sources.cfg�. You can use it to get you started.
Collect.pl maintains the file automatically.

You should now be getting mrtg graphs showing traffic generated by your 
traffic sources over time. Bask in it for a day.

6. collect.pl generates a new log/csv file every time it runs. By now you are 
probably up to your armpits in these files. I've included a script 
(summarise.pl) that I run every night to condense the day's log files into a 
single file. It doesn't need any arguments to run. However it does include a 
constant ($LOGPATH) that you'll need to change. Try running it.

7. So now you want to generate pie graphs breaking down traffic by source 
or destination? OK. You'll need to run makeanalyse.pl. It generates an 
HTML page that is used to generate the graphs. For example:
perl c:\perl\mrtg\contrib\whodo\makeanalyse.pl >d:\www\analyse.html

The page generated contains drop down lists containing the current sources 
and destinations. Since these will change over time, I run makeanalyse 
every night.

8. What's that? You want a more flexible way of mapping source addresses 
to text? You'd like to group multiple addresses under the same name? You 
want to use a name other than that in DNS?

OK. Create a file with two columns � the address and then name you want. 
In place of an address, you can use regular expressions. Thus the line 
�203.167.223.13[456]  Exchange� maps addresses 203.167.223.134, 
203.167.223.135 and 203.167.223.136 to the name �Exchange�. Note that the 
character �.� has its literal meaning � it is not a metacharacter.

If a source address does not appear in the sources file, it will be looked up 
with a normal reverse lookup. If that fails, the address is used. A sample 
sources file is included.

To make use of a sources file, change the command running collect.pl to 
something like:
collect.pl -a c:\perl\mrtg\contrib\whodo\sources.cfg -n \
c:\winnt\system32\drivers\etc\networks-s c:\perl\mrtg\contrib\whodo\sources

Mind you, if you'd had any sense you would have done this before step 5.


VOODOO

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 TOO

Tobi has agreed to include this set of scripts in the mrtg distribution. So, if 
you make any improvements or bug fixes, please provide them to him. But 
please be aware that he can't support the scripts himself.



Tony Farr
24/3/99
F1l3 Manager
