File README.SUSE-check_asterisk_peers of Package monitoring-plugins-asterisk

Check asterisk peers monitoring plugin.

Description:

This plugin checks Asterisk peers via Asterisk CLI commands to make sure
they are in a healthy state.  Unlike other monitoring plugins, status
is obtained from the perspective of the Asterisk server -- it's a good plugin
to use for monitoring the state of your connections to providers.

Both the peer itself and registration status to a peer can be monitored,
with the option of verifying that the peer/registration is actively configured.

If any of the checked peers/registrations return a non-OK state, a critical
state is returned. If verification is being used and a peer/registration is
not verified as being in the active configuration, then the status check is
skipped for that item instead of a critical state being returned.

web site: http://exchange.nagios.org/directory/Plugins/Telephony/Asterisk/check_asterisk_peers/details

Written by Chad Phillips <chad@apartmentlines.com>
Adapted to SUSE by Martin Caj <mcaj@suse.cz>


For a machines with active appamor, there is profile :
usr.lib.nagios.plugins.check_asterisk_peers allows run the script on the machine.

Last Modified: 2013-12-10

Usage:
--------

check_asterisk_peers [--type | -t <sip|iax>] [--peers | -p <peers>] [--registrations | -r <registrations>] 
                     [--verify-peers] [--verify-registrations] [--config-file <filepaths>] [--help | -h]

The following arguments are accepted:

  --type  | -t            (Optional) The type of peer to check.  Valid values
                          are sip, iax. Defaults to sip.

  --peers | -p            (Optional) A space separated list of peers to check.
                          Use the peer name given in the configuration,
                          without the surrounding brackets.

  --registrations | -r    (Optional) A space separated list of registrations
                          to check, in the form of username@uri. For example,
                          to check the registration of peer foo to
                          somesite.com, use foo@somesite.com

  --verify-peers          (Optional) If set, peer entries are verified in
                          the configuration, and the check is skipped
                          if they are not found.

  --verify-registrations  (Optional) If set, registrations are verified in
                          the configuration, and the check is skipped
                          if they are not found.

  --config-file           (Optional) The location of the configuration file(s).
                          Use a space separated list if specifying multiple
                          files.

                          Default value is based on the --type setting:

                          sip: /etc/asterisk/sip.conf
                          iax: /etc/asterisk/iax.conf

  --help | -h             Print this help and exit.

Examples:

Check peers [foo] and [bar]:

  check_asterisk_peers -p "foo bar"

Check peers [foo] and [bar], and registration for usr baz at somesite.com,
and verify that both the peers and the registration are actively configured.

  check_asterisk_peers -p "foo bar" -r "baz@somesite.com" --verify-peers --verify-registrations

Caveats:

The verification checks will not work correctly if there is any leading or
trailing whitespace on any of the register statement lines or the peer
section headings.

This plugin does not work with Realtime.

On the Asterisk side you need to have enabled peers monitoring, otherwise
the Status is allways "Status : Unmonitored". That is done via qualify set to yes.
I recomened to set also timeout via registertimeout and registerattempts.
This same you have to do in the conf file for IAX.

Example for sip.conf:
---------------------
[mcaj]
callerid=Martin Caj <00007>
type=friend
host=dynamic
secret=the-very-secret-password
qualify=yes
registertimeout=20
registerattempts=10

Example for iax.conf:
---------------------
; Trunk between Nbg and Prague
[AST1-to-AST2]
type=friend
username=communicator
;host=remote.voip-server.company.org
host=8.8.8.8
secret=the-very-serlet-key
context=remotevoip
disallow=all
allow=alaw
trunk=yes
requirecalltoken=no
qualify=yes
registertimeout=20
registerattempts=10


This plugin calls the asterisk executable directly, so make sure that the user
executing this script has appropriate permissions!  Usually the asterisk binary
can only be run by the asterisk user or root. To grant the nagios user
permissions to execute the script, try something like the following in your
/etc/sudoers file:
  nagios ALL=(ALL) NOPASSWD: /path/to/plugins/directory/check_asterisk_peers

Then call the plugin using sudo:
  /path/to/sudo check_asterisk_peers