Monitoring Asterisk

From OpenNMS
Jump to navigation Jump to search

Monitoring Asterisk VoIP servers

Monitoring SIP Peers

This feature was written by Michael Batz.

This feature appears to be not working due to an AMI AuthenticationError login error in OpenNMS 19.0.1; this is being investigated (see the issue tracker above)

SIP peers are either local SIP devices such as phones or remote SIP trunk endpoints.

Create an Asterisk Manager Interface user

The monitoring is done using the Asterisk Manager Interface, a command-line interface to Asterisk.

Edit the file /etc/asterisk/manager.conf to add in a new AMI user named 'opennms' that will be used by OpenNMS.

vi /etc/asterisk/manager.conf

writetimeout =
secret = mysecretpwd
deny =                    ; deny all IPs by default
permit =      ; but permit connections from the OpenNMS server
read = none
write = reporting

Now edit the related OpenNMS configuration file to provide these credentials to OpenNMS.

vi /etc/opennms/ami-config.xml
<?xml version="1.0"?>
<ami-config retry="2" timeout="1500"
        username="opennms" password="mysecretpwd">

Ensure SIP devices are configured with "qualify=yes"

Asterisk needs to be configured to monitor SIP connections. Configure SIP devices and trunks with the "qualify=yes" option. Confirm monitoring is in place by running the command "sip show peers" in Asterisk. The "Status" column for the desired SIP peer should show "OK (x ms)".

Note also the SIP peer name (not the username part). This will be needed later.

Create poller monitoring objects for each SIP peer to monitor

Edit poller-configuration.xml and define each SIP peer to monitor. Usually, these will be placed in the "example1" poller package. Ihe example creates a service named "490-SIP" to monitor the SIP peer named "490" (phone extension 490, in this case). The SIP peer name must exactly match what Asterisk displays as the peer name in "sip show peers".

vi /etc/opennms/poller-configuration.xml
        <service name="490-SIP" interval="30000" user-defined="false" status="on">
           <parameter key="timeout" value="3000"/>
           <parameter key="retry" value="2"/>
           <parameter key="sip-peer" value="490" />

In the monitor section at the end of the package definition, add a matching monitor line.

    <monitor service="490-SIP" class-name="org.opennms.netmgt.asterisk.monitor.AsteriskSIPPeerMonitor"/>

Repeat the process for each SIP peer to monitor.

Restart OpenNMS for the new poller definitions to become active.

Create a provisioning requisition for the monitored Asterisk server

Now create an Asterisk server object and attach the above polling objects to it. This is done through a provisioning requisition.

GUI method

Using the OpenNMS web GUI, go to Admin > Manage Provisioning Requisitions.

  • Enter a name for this provisioning requisition in the text box in the upper-left, e.g. "Asterisk server VoIP trunk monitoring" and click "Add New Requisition"
  • In the new provisioning requisition, click "Foreign Source Definition" > "Edit"
    • Delete all the default detectors except ICMP
    • Click "Add Detector" and add a detector with a name exactly matching the poller service created above, e.g. "490-SIP". The class should be "LOOP". This is a special detector that will always detect the named service without actually checking that is present.
      • For the new detector, add a parameter "supported" with a value of "true"
      • For the new detector, add a parameter "ipMatch" with a value of the IP address of the Asterisk server, e.g.
    • Add additional detectors for each SIP peer to monitor. There should be one detector for each SIP peer defined in poller-configuration.xml.
    • Click "Done"
  • In the new provisioning requisition, click "Requisition" > "Edit"
    • Click "Add Node"
      • For the node name, enter any desired node identification string. The Asterisk server hostname is a good identification string to use. If the Asterisk server already exists as a node, make this node name a bit different to make it unique.
      • Click "Save" to save the node
      • Click "Add Interface" to add an interface. Fill in the IP address of the Asterisk server, e.g. The "SNMP Primary" field can be "N" as this interface will not be scanned using SNMP.
      • Click "Done"

Back at the main Provisioning Requisition page, click "Synchronise" for the new provisioning requisition. The requisition should now show "1 nodes defined, 1 nodes in database".

The node will now exist with the defined services of ICMP and of each desired SIP peer to monitor.

command-line method

It's easiest to create the monitoring node and the first SIP trunk detector using the web GUI, as above.

Additional SIP trunks can be added at this point by editing the provisioning definition XML file and adding additional "service" XML element sections.

In this example case, the provisioning requisition is called "FreePBXDistro01 VoIP trunk monitoring".

vi "/etc/opennms/foreign-sources/FreePBXDistro01 VoIP trunk monitoring.xml"
       <detector name="491-SIP" class="org.opennms.netmgt.provision.detector.loop.LoopDetector">
           <parameter key="supported" value="true"/>
           <parameter key="ipMatch" value=""/>

After editing the file, use the Web GUI to go to Admin > Manage Provisioning Requisitions. Click the "Symchonize" button for the "FreePBXDistro01 VoIP trunk monitoring" requisition. The additional SIP trunks will immediately be provisioned and detected. No restart of OpenNMS is needed.


  • Go to "Node List". The new node should be present. View it.
  • All expected SIP peers should have discovery events.
  • The status of the SIP peers should be green and stay at 100% if they are being detected as up.


  • Edit /etc/opennms/log4j2.xml ( prior openNMS 14) and set "<KeyValuePair key="poller" value="DEBUG" />" instead of the default WARN setting. Look in /var/log/opennms/poller.log for messages relating to the SIP peer object.

Monitoring IAX Peers