                                 
                              IPAcco
              IP Accounting Collector and Visualizer
                         for Cisco Routers
                            Version 0.2
                                 
                        Installation Guide

 1. Starting Installation
 
The  first thing you should do is to choose the distribution  file
and download it. Currently IPAcco is distributed in two forms:  as
a  gzipped  tar  archive and a zip-archive. These  two  packs  are
essentially the same, although the first form is intended for  use
with  Unix/Linux  systems and the second - for Windows.  The  both
packs contain the same files. In fact, the only difference is  the
end-of-lines style in the text file (LFs in tar.gz-pack and CR-LFs
in zip).

Next,  unpack the distribution archive to the temporary  directory
of  your  choice. Later you will move the files to  the  locations
they are intended to be (see below) but now let them be where they
are. Review the README file included with the distribution.
If  you  are installing IPAcco on the Unix-like system  with  bash
(Bourne  Again SHell, which presents in most modern  Unix's),  you
may  choose to use the supplied bash script install.bash  to  ease
the   installation  process. This script copies  IPAcco  files  to
their  destination directories and performs some additional tasks.
Alternatively you may do all these things manually.  Anyway,  some
installation  steps  cannot be automated and should  be  performed
manually. Currently there is no installation script for Windows.

All  installation  steps that can be performed automatically  with
the installation script are noted below.

The next thing you should do is to prepare your router for working
with IPAcco.


 2. Configuring the Router
 
This  includes  two steps: turning on IP accounting  and  enabling
RCMD access to the router for data collector script. Note that you
must  have an administrative access to the router to perform these
steps.
 
 2.1.     Enabling IP accounting

IP accounting should be enabled per interface:

router(config)# interface <IfType><IfNumber>
router(config-if)# ip accounting [output-packets]

Repeat   these  commands  for  each  interface  you   expect   the
interesting traffic will pass through. And remember that only  the
traffic outgoing from the interface will be accounted, whether you
entered "output-packets" keyword or not.

You  should also make sure that router's IP accounting table  will
not  be  overflowed during data collection. Cisco IOS  limits  the
number of entries this table can hold. The default value for  this
limit  is  512, which is too low for the most situations. Probably
you  will  have  to  enlarge this limit with a  command  like  the
following:

router(config)# ip accounting-threshold 10000
 

 2.2.     Enabling RCMD access

IPAcco  logger  script accesses a router using RCMD  protocol,  so
this protocol must be enabled on the router before running IPAcco.
First,   enable  RCMD  (or,  more  specifically,  "rsh"   command)
globally:

router(config)# ip rcmd rsh-enable

Next, enable RCMD access from the host you want to run a collector
script:

router(config)# ip rcmd remote-host <local-user> <host> <remote-user> enable

where <local-user> is a name under which this rcmd client will  be
visible "inside" the router (actually this doesn't matter, so  you
may  enter here any name you like); <host> is an ip-address  or  a
domain  name of the host where the collector will run and <remote-
user>  is a login name of the user on behalf of whom the collector
script  will run. The remote user name does matter, it must  be  a
real  user name of the <host> (and of course, you must have access
to this account).

If  you  specified  <host> as a domain name,  this  name  must  be
resolvable  via  DNS  and the corresponding name  server  must  be
available to the router.

Doing this way we give <remote-user> at <host> an unlimited access
to  our router. Bearing in mind that RCMD authentication mechanism
is  far from being perfectly secure, perhaps it would be wiser  to
limit  this access. If you wish to do this, your config becomes  a
little  more  complicated. First, we give this  user  some  unused
privilege  level. We use 2 in this example but your  may  use  any
unused number between 2 and 14 (inclusive).

router(config)# ip rcmd remote-host <local-user> <host> <remote-user> enable 2

Next,  we  list  all commands this user is permitted  to  execute.
Actually he needs only two ones:

router(config)# privilege exec level 2 show ip accounting checkpointed
router(config)# privilege exec level 2 clear ip accounting

But for the debugging purposes we will add one more command:

router(config)# privilege exec level 2 show ip accounting

That's  all  about  the  router.  Don't  forget  to  save  a   new
configuration to the non-volatile memory or upload a new config to
the  router  if you prefer to keep and edit configs as text  files
(like  I do). Now you should be able to issue the following  shell
command  on the <host> (being logged in as <remote-user>) and  see
an output from the router containing IP accounting data.

rsh <router.ip.or.domain.name> show ip accounting

If  you  don't  see the expected output, get back and  check  what
you've done wrong in the above procedure.


 3. Creating the database
 
IPAcco   database   should  be  created   with   an   SQL   script
"CreateDB.sql" included in the distribution. But before  executing
this script you may want to edit it, and that is why.

The  script  creates a database named "ipacco" and  all  necessary
objects  (tables  and indexes) within this database.  Finally,  it
creates  two  users:  "ipacco-web"  (password  "ipacco=web")   and
"ipacco-pump"  (password "ipacco=pump").  The  first  one  is  for
impersonating PHP scripts forming the web part of IPAcco; the last
one  is  for  impersonating the data collector script. Both  users
have  the minimum set of access rights and privileges required  to
do  their  work.  No  one  of them has administrative  rights  for
"ipacco"  database  and  no  one has  any  rights  for  any  other
database.  But nevertheless you may not want these users  to  have
the same names and passwords as their twins all over the world. If
you  do not want this, edit the script and change their names  and
passwords (they are near the end of the script).

Now  go  on and execute this script. One way to do this is to  use
the standard MySQL command-line client "mysql":

mysql -u <user-name> -p<password> < CreateDB.sql

where  <user-name> and <password> are the credentials of the  user
having   administrative  privileges  on  this  MySQL  server.   Or
alternatively  you may use MySQL Control Center  to  execute  this
script.


 4. Running the Installation Script
 
Now it's the time to run the installation script if you decided to
use  it.  If you decided not to use it, skip to the next  chapter.
Run  install.bash  and  answer the questions  it  will  ask.  Most
questions  concern the destination directories for various  IPAcco
files.

Install.bash  does not actually recognize the directory  structure
style used in your system. It simply supposes that all executables
should  be  installed to /usr/bin and /usr/sbin, all configuration
files - to the subdirectory of /etc, all php- and html-pages -  to
the subdirectory of /var/www/html and so on, as it used in Red Hat
Linux,  the  system  on  which IPAcco was  tested.  The  installer
proposes   these directories by default. Of course, if you  prefer
to  install  IPAcco to the subdirectories of the single  directory
you can enter the directory paths you prefer.


 5. Setting Up the Data Collector Script
 
The  script  that does all the work by downloading data  from  the
router  to the database and repacking data between consequent  set
of   the  tables  is  named  ipacco-datapump.tcl  and  is  located
initially in the datapump subdirectory of IPAcco distribution.  To
make this script work you should perform the following two steps.

1)   Copy or move the script to the directory you want it to  live
 assign  the  appropriate access attributes to it. The destination
 directory   could  be  /usr/sbin  or  /usr/local/ipacco/bin   for
 Unix/Linux or C:\Program Files\IPAcco for Windows. You  may  also
 create a symbolic link to this script so that the script could be
 invoked with just a file name without .tcl extension (i.e.  ln  -
 s ipacco-datapump.tcl ipacco-datapump).
 If you use the installation script it will do this for you.

2)   Copy  or move the datapump configuration file (called ipacco-
 datapump.cfg)  to  the  appropriate  directory  and  assign   the
 appropriate  access  attributes to it. The destination  directory
 could  be /etc/ipacco or /usr/local/ipacco/bin for Unix/Linux  or
 C:\Program   Files\IPAcco  for  Windows.   By   default   ipacco-
 datapump.tcl  searches for its configuration file in  /etc/ipacco
 when  running  under  Unix/Linux and in its  own  directory  when
 running under Windows.

 If you use the installation script it will do this for you.

 If  you've  placed  the configuration file  to  the  non-default
 directory  you  will  have to run the datapump  script  with  -c
 option:

 ipacco-datapump -c <actual-location>/ipacco-datapump.cfg
 
 If you've changed the database password as it was recommended in
 the  previous chapter, you must also edit the configuration file
 to  reflect this change. Open the file with any text editor  and
 replace "ipacco=pump" with the password you've assigned  to  the
 database user "ipacco-pump". Also replace the default host names
 of the database server and the router with the actual ones.

 Now  you  should be able to run the script and see how it  works.
 Enter  tclsh  ipacco-datapump.tcl command at the command  prompt.
 In  Linux/Unix systems you may enter just ipacco-datapump.tcl. In
 Windows  this  brief  form  should  also  work  provided  Tcl  is
 properly  installed, but I do not recommend to use it because  in
 this  case the interpreter would run in the separate window  that
 will  close  immediately  after the script  termination,  so  you
 probably  won't  have  time to read any  diagnostic  messages  if
 something goes wrong.

 First,  you  should  see the output of "show ip  accounting"  IOS
 command  (if you don't know how it should look, run this  command
 at  IOS  command prompt in the telnet session). Next, you  should
 see   some   messages  about  packing  the  data  through   table
 hierarchy.  If  you see something else (some error messages,  for
 example)  or  see nothing, please get back and try to  understand
 what's wrong.

 Except  -c  option mentioned above, ipacco-datapump accepts  two
 more  options.  Both make them to run continuously,  instead  of
 performing one pass and terminating. The first option,  -r  does
 exactly  this. Ipacco-datapump runs until being interrupted  and
 periodically  performs  data collecting cycles.  The  period  of
 these cycles is taken from the database (see below).

 The  second option, -d ("d" stands for "daemonize") additionally
 suppresses all console output. It does not really daemonize  the
 script,  i.e.  does not send it to the background since  current
 Tcl implementations seem to lack the mechanism to do this. So if
 you  want  to run the script in the background, you should  also
 (besides specifying -d) terminate the command line with "&"  (in
 Unix shell) or use "start" command (in Windows).

3)   Then  you  need  to schedule this script to  run  at  regular
 intervals. Or, more precisely, you should schedule it to run every
 5  minutes. Actually you may choose any other sensible  interval,
 but its value must match to the value of the "DayViewGrid" IPAcco
 runtime  parameter,  which is stored in the  database  and  which
 defaults  to  5 minutes. Because at this moment you  cannot  edit
 runtime  parameters (unless you want to edit data tables manually
 in  MySQL  Control  Center), now you  should  better  leave  this
 parameter with its default value and set the scheduling  interval
 to the same value.

 You  can  either schedule the script with some external scheduler
 or let it schedule itself, i.e. run it in the background mode. In
 the  last  case  the script will choose the right  working  cycle
 period value automatically. I personally prefer the second way.
 If  you  prefer  the first way you may use cron under  Linux/Unix
 for  scheduling the data collector script. In Windows 2000/XP you
 may  use  the  system default task scheduler or  any  third-party
 scheduler.   If  you system uses /etc/cron.d directory  for  cron
 scripts  you  may  just  copy the provided  cron  file  from  the
 /cron.d subdirectory of the distribution directory.

 If you use the installation script it will do this for you.

 If  you  prefer  the  second  way you  should  somehow  make  the
 collector  script to run automatically at the system startup.  As
 the  system  startup  procedures vary  greatly  from  one  OS  to
 another  I  cannot  provide  a startup  script  for  IPAcco  data
 collector  suitable  for  any system. But  if  your  system  uses
 SystemV-style  initscripts the startup  script  provided  in  the
 /sysvinit  subdirectory of the distribution directory may  appear
 useful  for you. Copy it into /etc/rc.d/init.d directory and,  if
 your  system  supports  chkconfig  utility  issue  the  following
 command:

 chkconfig -add ipacco
 
 If you use the installation script it will do this for you.


 6. Deploying PHP Scripts
 
At  last, you should setup the set of server-side PHP scripts that
implement the Web-based user interface for IPAcco. How to do  this
depends  very much on the operating system and the Web-server  you
use. I will try to give you some hints but you should consult with
the documentation for your HTTP-server to get all details.

The  first  thing  you  should take into account  is  that  IPAcco
currently have not any built-in security. This means that it  does
not perform any user authentication/authorization. So, if you want
to  restrict the user access to IPAcco (and you will probably want
to  do  it),  you should use the security features  of  your  Web-
server.  Again,  I won't explain how to do this  because  this  is
rather  extensive subject and details depend greatly on  the  Web-
server.

Generally, you should create a set of the access rules determining
who  can access IPAcco and then apply these rules to the directory
containing  IPAcco PHP scripts. With Apache you create ".htaccess"
file containing access-control Apache directives. With IIS you use
Internet  Service Manager to create an IIS application  and  setup
security for IPAcco directory.

Now  you  are  ready to deploy IPAcco PHP scripts. Initially  they
reside  in  "html"  subdirectory of  the  distribution  directory.
First,  locate "SiteDefs.php" file, open it in a text  editor  and
find a line looking like this:

define("DBSERVER", "ipacco");
define("DBNAME", "ipacco");
define("DBLOGIN", "ipacco-web");
define("DBPASSWORD", "ipacco=web");

Replace   "ipacco=web"  with  the  password  you've  assigned   to
"ipacco-web"  database  user  (if you've  chosen  to  change  this
password  earlier). Again replace the default  host  name  of  the
database server with the actual one.

Next, you have to make IPAcco "html"directory available to the Web-
server.  Both  with  Apache and IIS you may choose  to  copy  this
subdirectory to the Web-server document directory or leave  it  in
place.    The    document   directory   for   IIS    usually    is
"C:\inetpub\wwwroot"  or  something  like  that;  Apache  document
directory  in Linux usually is "/var/www/html". If you  prefer  to
leave IPAcco "html" directory in place you should create a symlink
to  this  directory in the Web-server document  directory  (if  in
Linux/Unix) or create an IIS virtual subdirectory (if in Windows).
Then,  either you've copied "html" directory or left it in  place,
you should apply access permissions to this directory as described
above.

 7. What to Do Next
 
Now  that  you've done all said above you should  have  a  working
instance  of  IPAcco.  Start  a  Web-browser  and  enter  the  URL
representing IPAcco directory. When you see IPAcco's initial page,
click  on  "Help" link on the left side of this page  to  get  the
additional information about using IPAcco.
