TraffStats HowTo

1.2.1 Installing the core version

Download the current version of TraffStats and extract the archive into a directory accessible through your webserver. e.g. /var/www/: In order to simplify the URL for the access of the webapplication you may create a link to the TraffStats-0.10.2-directory:
Change into the TraffStats-directory; all examples in this HowTo assume that your working directory is the newly created TraffStats-directory.
If you have installed an old version of TraffStats and prefer a complete new installation instead of an upgrade, you must delete the old database and user. If you prefer an upgrade, please read Upgrade.
There are 2 scripts that should help you deleting the old database and the old database-user. (Attention: do not execute the following commands if you like to do an upgrade!)
Create the database:
(Attention: do not execute the following commands if you like to do an upgrade!)
Use the commands listed below to create the database and the database-user:
Adjusting file rights
Files containing sensitive informations should be secured by assigning them restrictive user rights.
The file config/config.php should only be readable by the useraccount used by the webserver. e.g.: The file collector/collector.pl should only be read- and executable by the account running the cronjob for the collector (root). e.g.:

1.2.2 Installation of the bundle-version

Please download the Traffstats-bundle file corresponding to your PHP version and follow the instructions in the chapter Installation of the core-version and simply ignore the section concerning the installation of JpGraph and Microsoft TrueType core fonts.

1.2.3 Installation using deb-Packages

The deb-Packages have been developed for Debian etch (4.0). Tests for the distributions testing and unstable (lenny and sid) are still pending.
A experimantal repository exists. If you like to use it, please add the following line to your /etc/apt/sources.list: Please enter the following commands as root in order to import the key used for signing the packages and the repository:
List of distributed files (deb-packages):

• traffstats_0.10.2_all.deb - traffstats
• JpGraph 2.x for PHP5
  • libphp-jpgraph2_2.3-1_all.deb
  • libphp-jpgraph2-examples_2.3-1_all.deb
  • libphp-jpgraph2-doc_2.3-1_all.deb
• JpGraph 1.x for PHP4
  • libphp-jpgraph1_1.22-3_all.deb
  • libphp-jpgraph1-examples_1.22-3_all.deb

In order to install TraffStats for PHP5 you must download traffstats_0.10.2_all.deb and libphp-jpgraph2_2.3-1_all.deb.
Then first install all required packages: Install JpGraph: If you prefer using the repository: Finally install TraffStats: or via the repository:
The procedure for PHP4 would be similar:
Download the required files: traffstats_0.10.2_all.deb and libphp-jpgraph1_1.22-3_all.deb.
Then first install all required packages: Install JpGraph: If you prefer using the repository: Finally install TraffStats: or via the repository:
During the installation of the TraffStats package you can let the install routines automatical create the required databases and perform the necessary configuration of the web server. If you should choose this comfortable way, you can continue right after the installation with the First login.

1.3.1 Upgrade of an existing installation : version 0.4 - 0.6

Since the release of TraffStats-0.6 contains many new features, this implied unfortunately also a fundamental change of the database structure.
This circumstance makes an update difficult!
If you my miss data already collected using version 0.4, a new installation is recommended!
If you should decide for an upgrade, there are 2 possibilities:

1. backup of the old collected stats, a complete new installation, restore of the backup followed by a reconfiguration of the hosts and interfaces.
   This procedure has the disadvantage that all useraccounts are lost, but the database structure is completely rebuilt.
   Proceed as follows:
   1. deactivate the cron-job for the collector.
   2. backup the data for hosts, interfaces and the collected stats:
      mysqldump -u root -p -n -t -Q --compact -c traffstats host interface stats -r /tmp/ts-back.sql;
   3. Logout from the webapplication / webinterface.
   4. Delete all old files and follow the instructions for a complete new Installation of TraffStats inclusively the instruction for the deletion of the old database and database-user!
   5. After a successful new installation restore the saved data:
      mysql -u root -p traffstats < /tmp/ts-back.sql;
   6. Login into the webinterface.
      First you should adapt the settings for each interface to the new structure.
      As assistance it recommends to perform a comparison of the settings database / SNMP.
      Subsequently you must perform a reconfiguration of all hosts. Please read Host configuration For each host you should adjust the settings for the "display name" aggregation for hosts and interfaces and define the "consistency checkfields" or disable the "consistency checks" performed by the collector.
   7. Perform a test run of the collector:
      ./collector/collector.pl;
      If this performs without errors, you can proceed by configuring / enabling the cronjob for the collector (see: Set up a cron-job for the collector-script).
2. Upgrading the database structure
   This variant has the advantage of preserving all data, however small deviations in the database structure will remain compared with a new installation.
   Proceed as follows:
   1. deactivate the cron-job for the collector.
   2. Logout from the webapplication / webinterface!
   3. Delete all old files and follow the instructions for a complete new Installation of TraffStats excluding the instruction for the deletion AND creation of the database and database-user!
   4. After a successful new installation please apply the update-script:
      mysql -u root -p traffstats < sql/update-v0.4.sql;
   5. Login into the webinterface.
      First you should adapt the settings for each interface to the new structure.
      As assistance it recommends to perform a comparison of the settings database / SNMP.
      Subsequently you must perform a reconfiguration of all hosts. Please read Host configuration For each host you should adjust the settings for the "display name" aggregation for hosts and interfaces and define the "consistency checkfields" or disable the "consistency checks" performed by the collector.
   6. Perform a test run of the collector:
      ./collector/collector.pl;
      If this performs without errors, you can proceed by configuring / enabling the cronjob for the collector (see: Set up a cron-job for the collector-script).

1.3.2 1.3.2 Upgrade of an existing installation : version 0.6/0.7 - 0.8

In order to fix an error in the database structure in version 0.6 and 0.7, apply the update-script:

1.3.3 Upgrade of an existing installation : version 0.8/0.9.x - 0.10.0

Implementation of new features requires an adaptation of the database structure. If you perform the upgrade using debian packages and you choosed to use dbconfig the required changes will be applied automatically. Otherwise you will have to perform the following steps:

1. logout from TraffStats
2. apply the update-script:
   mysql -u root -p traffstats < sql/update-v0.9.1.sql;

In order to fix an error caused by versions smaller equal 0.9.1 of the collector-script you can execute the script collector/fixSysUpTime.pl. Caution: the execution of the script can take some time and may cause high CPU load!

1.3.4 Upgrade of an existing installation : version 0.10.0/0.10.1 - 0.10.2

Implementation of new right requires an adaptation of the database structure. If you perform the upgrade using debian packages and you choosed to use dbconfig the required changes will be applied automatically. Otherwise you will have to perform the following steps:

1. logout from TraffStats
2. apply the update-script:
   mysql -u root -p traffstats < sql/update-v0.10.1.sql;

1.3.5 Upgrade of an existing installation : version 0.10.2 - 0.11.0

Implementing different configurable layouts requires an adaptation of the database structure. If you perform the upgrade using debian packages and you choosed to use dbconfig the required changes will be applied automatically. Otherwise you will have to perform the following steps:

1. logout from TraffStats
2. apply the update-script:
   mysql -u root -p traffstats < sql/update-v0.10.2.sql;

1.3.6 Upgrade of an existing installation : version 0.11.0 - 0.11.1

Implementing new features requires an adaptation of the database structure. If you perform the upgrade using debian packages and you choosed to use dbconfig the required changes will be applied automatically. Otherwise you will have to perform the following steps:

1. logout from TraffStats
2. apply the update-script:
   mysql -u root -p traffstats < sql/update-v0.11.0.sql;

Please read the chapter: 1.2.1.2 Additional Software - Microsoft TrueType core fonts

1.4.1 Set up a cron-job for the collector-script

In order to perform data acquisitions in regular intervals, you should configure a cron-job for the collector-script.
Create a file /etc/cron.d/traffstats with the following content: You may replace the list 5,15,25,35,45,55 with */10 in order to run the collector every ten minutes.
You may adapt the execution frequency, e.g.: */5 in order to execute the job every 5 minutes or */15 for "quarter of an hour" steps. (see: Timing the execution of the collector)
In order to make changes to the cronfile /etc/cron.d/traffstats take effect, you must reload crond:

1.4.2 First login

For the first Login using the webinterface please use the following account data:
Username: admin
Password: adminpasswd
Please change the password immediately after the first login. (see: Useradministration)

2.1.1 Usage of the "Host-Wizard"

The easiest way to add a new host with interfaces to the system is the so-called "Host-Wizard". This requires however the SNMP functions of PHP!
lease enter the required data into the host-wizard form:

• IP: IP of the network device
• SNMP community: the SNMP community (e.g.:privatecommunity)
• Port: port of the SNMP server (default: 161)

After pushing the "save"-button, the Host-Wizard tries to connect to the specified host.
If you encounter an error, verify all settings (form input and configuration of the device to be queried).
After successful inquiry of the data, the Host-Wizard build following components:

• host form (for details see Host configuration)
• Link to a external color-chooser see: HTML-Colors of the interfaces and the external color-chooser
• List of interface forms (for details see: Interface configuration)
  Each interface part includes a checkbox with the option to ignore the corresponding interface. Chose this option if you like to ignore the interface completely !
  
  The following fields are prefiled according to the SNMP entries on the network device and should be changed only in exceptional cases (use the comment field for user defined input):
  1. SNMP-Nr
  2. Interfacename
  3. MAC-Address
  4. description
  5. IP
  6. type
  7. alias
  The wizard tries to determine the setting for the field active, but this can fail in rare cases, so you should examine this setting!
  At the moment there is no reliable method to determine via php if a device is implementing 64-counters. So this option is on by default. Please adjust this setting by hand. (see: 64bit counter and SNMP-Functions of PHP)

After you configured the host and all interfaces, you may save the host and all interfaces (except the once market as to be ignored) by pushing the "save"-button.
Subsequently you can verify the configuration by performing a collector run: If the collector detects an error, you should fix this by reconfiguring the host and/or interfaces in question.

2.1.2 Add hosts and interfaces

You may add hosts and interfaces manually.
This may be useful if your PHP installation lacks SNMP support or the Host-Wizard fails.
To add a new host, please select the menu option "new Host".
Using the "list Hosts" menu option and/or the view Host page you can add interfaces to a host.

2.1.3 Host configuration

Below you can see a example of an host form:

Fields with names printed bold are required! (This applies to all forms.)
Description of the fields:

• IP: IP of the device.
• Hostname: name of the device.
• SNMP community: SNMP community used to query the device via SNMP version 2c.
• Port: port of the SNMP server on the device.
• active: Select yes / no.
  Hosts with the activee field set to no are ignored by the collector.
• collector checks consistency: Select yes / no.
  This setting affects the behaviour of the collectors during the data acquisition. If the setting is set to yes, the collector will use the fields defined as consistency checkfields to perform some comparison checks. If the collector detects a difference between the settings in the TraffStats system and the data determined via SNMP, the data acquisition for the interface in question will be aborted an a eloquent error message generated.
  (see: Error messages generated by the collector)
• consistency checkfields: multiple select.
  Select the field to compare.
  Like in the example you should select all fields in order to achieve a high warning threshold level on SNMP-Nr reassignments s or changes.
• host display name: multiple select.
  Select the fields you would like to use for the aggregation of the host identifiers.
• interface display name: multiple select.
  Select the fields you would like to use for the aggregation of the interface identifiers.
  Remark that selecting many fields will result in long interface identifiers that may exceed the visible place reserved for them!

2.1.4 Interface configuration

Below you can see an example of a interface form:

Fields with names printed bold are required! (This applies to all forms.)
Description of the fields:

• SNMP-Nr.: SNMP number of the interface.
• Interfacename: name of the interface.
• MAC-Address: MAC-Address of the interface.
• description: description of the interface.
• IP: IP of the interface. (if one assigned)
  Multiple IPs should be separated using blanks.
• type: Type of the interface.
  May be in extended form TYPEDESCR(TYPENNR) (e.g. ethernetCsmacd(6)) or may consist only of the type-number. (see: net-snmp.sourceforge.net)
• alias: alias of the interface.
• comment: users comment
• color: HTML-color for the diagrams. e.g.: #ee0000 (see: HTML-Colors of the interfaces and the external color-chooser)
• invert in/out: Select yes / no.
  Invert the viewpoint of the TraffStats-System on the traffic-direction.
  Please consider that changing this setting after the start of the data collection will result in wrong calculations! If it a change can not be avoided, proceed please as follows:

  1. deactivate the corresponding host
  2. make the appropriate changes at the interface configuration
  3. restart the network device!
  4. activate the corresponding host
• use 64bit counter: Select yes / no.
  Configures the usage of the new and better 64bit counter for the traffic calculation. The usage of the 64bit counter should only be deactivated if the device is not implementing 64-counters. If a device is marked as 64-counters-capable but is not implementing 64-counters, the collector will generate an error message. (see: 64bit counter)
• active: Select yes / no.
  Interfaces with the active field set to no are ignored by the collector.
• default: Select yes / no.
  If this is set to yes, the interface will be displayed in the initial statistic view.

2.1.5 Host - compare settings database / SNMP

If the collector detects an inconsistency in the current configuration an error message will be generated. (see: Error messages generated by the collector)
Example: As assistance for the recovery of the error TraffStats offers the possibility to perform a comparison of the settings stored in the TraffStats-System (database) vs. setting that can be queried via SNMP from the device. This feature requires the SNMP-extensions for PHP!
Similar to the page of the "Host-Wizard" a list of all Interfaces of the host is generated. As assistance a comparison of the values available via SNMP is provided, including hints to the deviations detected and the possibility to save new interfaces.

Please read the section SNMP-Number
After saving the changes you should test if the collector performs a clean run. Repeat the procedure if necessary.

2.2.1 Useradministration


User-/Admin-Accounts have following configurable settings:

• language: choose the language for the TraffStats-System.
• login: login / username for the account.
• name: name of the user.
• firstname: firstname of the user.
• enabled: select yes / no.
  disabled accounts can not log in!
• administrative rights: multiple selections possible.
  see: Assignment of administrative rights

2.2.2 Assignment of administrative rights

To each user-/admin-account you may assign different rights:

• SUPERADMIN: user with this right degree have the following authorizations:
  • create, change and delete user-/admin-accounts
  • assign and revoke administrative rights to other users
  • create, edit and delete hosts and interfaces
• HOSTADMIN: user with this right degree have the following authorizations:
  • create, edit and delete hosts and interfaces

Users without one of the administrative rights may only view statistics.

3.2.1 Configuration and interpretation of the statistics


The configuration and display elements for the statistic evaluation can be divided into 3 ranges:

1. host/interface selection:
   Selected host/interfaces will be displayed in the statistical evaluation.
2. configurations elements for the representation period
   These controls define the representation period.
   For average computations you can enter to starting and end time point. Using the links >> and << you may jump an appropriate time period forward or back.
   Pressing the button "display statistics" will generate a statistic evaluation according to the configuration.
3. configurations elements for loading or saving views / configurations Using this configuration elements you can load previously saved views / configurations or save your current settings.
   A view / configurations stores following settings:
   • selected host/interfaces
   • their distribution on the multiple-choice container for the graphical representation
   • ettings of the presentation selection per container for the graphical representation
4. statistics tables
   For each selected host/interface a separate table will be displayed.

3.2.2 Configuration and interpretation of the diagrams


The configuration elements for the graphical evaluation and diagram composition can be divided into 3 groups:

1. 3 select container
   This container may contain in each case lists (none to several elements) of host/interfaces.
2. below each container 2 buttons per container
   Using these buttons you can shift the elements selected from one container into another container.
3. below a presentation selection per container
   These elements configure if and how the host/interface combinations of the corresponding container will be integrated into the diagram.
   There are the following configurable options:
   • side by side: the elements of the container are represented next to each other
   • side by side inverted: the elements of the container are represented next to each other, however the values for in and out are exchanged
   • sum up: the elements of the container are represented one above the other and the values will be added
   • sum up inverted: the elements of the container are represented one above the other and the values will be added, however the values for in and out are exchanged
   • ignore: the elements of the container will not be displayed in the diagram

By clicking on the button labelled "show graphic evaluation" a new window containing the diagram will pop up. (If the window should remain empty, please examine the installation of JpGraph and PHP-SNMP!)