IPAcco
IP
Accounting Collector and Visualizer
for Cisco Routers
Version 0.2
Installation Guide
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.
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.
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
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.
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.
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.
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.
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.
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).
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.
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.
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.