

This is a *passive* Nagios plugin to gather the fax statistics for Asterisk systems. 
This package contains plugin versions for both the Spandsp and Digium FFA ( Fax for 
Asterisk ) modules. Since this is a *passive* plugin, it assumes that either NSCA
or NSCA-NG is being used.


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.


This plugin supports the following features:

* Is a passive plugin and can easily be run out of CRON. 
* Since it is a passive plugin, all 30 fax statistics are returned by the plugin
  at the same time, typically in about 1-2 seconds. This is obviously a better
  way to go than running the same plugin 30 times to return a single result each
  time.
* Supports both NSCA and NSCA-NG.
* Supports both the Spandsp and Digium Fax for Asterisk ( FFA ) Asterisk modules.
* Can generate optional warning and critical alerts for each of the fax statistics 
  that are reported.
* Has a Nagios server template file for each version that can be easily modified 
  to your needs. 
* By logging into the Asterisk AMI to get the fax statistics, it becomes trivial
  to query remote Asterisk servers the same way.



Setup/Installation/Customization.

(1) The get_fax_stats.pl plugin is written in PERL and requires the following CPAN
    modules to be installed: Asterisk::AMI and AnyEvent. AnyEvent is not used directly
    by the plugin, but is a dependency of Asterisk::AMI so install that one first. 
    For convenience, they are both included in the cpan sub directory.

(1) Based on the Asterisk fax module used, either spandsp or ffa, find the appropriate
    files in that sub directory.

(2) Place the get_fax_stats.pl, faxstats-lib.pl, and faxstats.ini files in whatever
    location on the Asterisk PBX that makes sense. If a remote PBX is monitored,
    then the AMI credentials need to be modified in the faxstats.ini file in the 
    section [ami]. See section (4) for more information.

(3) In the get_fax_stats.pl plugin, at the top of the file, define the full path to
    the faxstats-lib.pl file and the faxstats.ini file. No other modifications need
    to be made.

(4) The faxstats.ini file needs to be configured. First, edit the values in the [ami]
    section. To monitor a remote server, put that servers information here. Note: Make 
    sure that the remote host has the proper AMI permissions are configured on the
    remote host. Second, enter the nsca or nsca-ng information in the section [nsca].
    Third, the sections [statistics], [g.711], and [t.38] are where the warning and
    critical thresholds are optionally defined. The warning and critical thresholds
    for each statistic are independent of each other which means that a warning level
    or a critical level can be defined with the other being left emtpy. It is not
    necessary to define both warning and critical thresholds at the same time.

(5) As a convenience, a Nagios server cfg file is included as a template and includes
    all of the services that are returned by the plugin. This file may or may not be
    complete depending on your Nagios configuration, use of templates, etc. The 
    following substitutions should be made to this file: TEMPLATE, HOSTNAME, CONTACT_GROUPS,
    and SERVICEGROUPS. Feel free to disregard this step and create your own Nagios
    config file for the fax services.

(6) Create a CRON entry to run the plugin. The plugin is typically every 5 minutes, 
    but run it as often as you like. A typical entry looks like the following:

    0,5,10,15,20,25,30,35,40,45,50,55 * * * * /usr/local/nagios/libexec/get_fax_stats 

(7) That should be it. If there are any problems with this plugin, or if you want to
    see a feature added, please do not hesitate to write support@voipbusiness.us. 





