Skip to main content

mod_snmp

About​

This module is still under development, and by no means intended to be a complete read/write SNMP interface.

Click here to expand Table of Contents

Reserved Object Identifier (OID)​

The OID .1.3.6.1.4.1.27880 has been reserved for FreeSWITCH. The full OID tree is documented.

Available Objects​

Currently, all attributes are read-only, and are as follows:

.1.3.6.1.4.1.27880 FreeSWITCH

  • .1: core
    • .1.1: identity
      • .1.3.6.1.4.1.27880.1.1.1: FreeSWITCH version string (eg. "1.0.head (git-0cf1d54 2011-01-19 16-36-04 -0500)")
        • .1.3.6.1.4.1.27880.1.1.2: Core UUID as a string
    • .2: systemStats
      • .1.3.6.1.4.1.27880.1.2.1: FreeSWITCH uptime as SNMP TimerTicks (hundredths of seconds)
        • .1.3.6.1.4.1.27880.1.2.2: Number of sessions since FreeSWITCH was started
        • .1.3.6.1.4.1.27880.1.2.3: Currently active sessions
        • .1.3.6.1.4.1.27880.1.2.4: Maximum allowed sessions
        • .1.3.6.1.4.1.27880.1.2.5: Currently active calls
        • .1.3.6.1.4.1.27880.1.2.6: Current sessions per second
        • .1.3.6.1.4.1.27880.1.2.7: Maximum allowed sessions per second
        • .1.3.6.1.4.1.27880.1.2.8: Peak sessions per second
        • .1.3.6.1.4.1.27880.1.2.9: Peak sessions per second Last Five Minutes
        • .1.3.6.1.4.1.27880.1.2.10: Peak sessions
        • .1.3.6.1.4.1.27880.1.2.11: Peak sessions Last Five Minutes

Management information base (MIB)​

The MIB can be viewed in FishEye. Developers will do their best to maintain backwards compatibility with regards to OIDs in the MIB, however since this module is in the early stages of development, some OIDs may change. Please use the MIB and object names, rather than hard-code OIDs in your NMS (eg. MRTG, Cacti etc) configuration.

Integration with SNMP server​

The module acts as a Agent X subagent. This means it registers with your existing SNMP server to handle a specific OID, so can monitor your system and FS with a single daemon. This is a far more optimal approach than older approaches execute fs_cli to query the FreeSWITCH status via ESL.

Configuring Net-SNMP for AgentX Subagent Support​

Your main snmpd will need to run as a master agent, so that mod_snmp can connect to it as a subagent over a named socket. Using the agentXPerms, make sure that you set the permissions and ownership such that your freeswitch user will be able to read/write to it.

Note that some earlier versions of Net-SNMP did not honor the agentXPerms config directive. If you find this happening, you will need to modify your snmpd init script to manually change the permissions/ownership of the socket after snmpd has started. If this is the case you'll see "Failed to connect to the agentx master agent" in the logs and /var/agentx/master will probably be owned by root:root instead of freeswitch:daemon.

#  Run as an AgentX master agent
master          agentx

#  Listen on default named socket /var/agentx/master
#  agentXPerms  SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
agentXPerms     0755 0755 freeswitch daemon

Most default configurations of Net-SNMP only allow a restricted view of the whole tree. The systemonly view is usually defined as OIDs .1.3.6.1.2.1.1 and .1.3.6.1.2.1.25.1. If you want to allow external hosts (or even localhost) to view the entire tree, you will need to modify the security/view parameters in snmpd.conf. Near the top of your snmpd.conf you should find the following:

# rocommunity public  localhost

Uncomment that line to allow localhost to view the entire tree (including the FreeSWITCH OID). If you wish to allow external monitoring hosts, such as MRTG, Cacti etc view more than just the systemonly view, you will need to further modify the security configuration. This procedure is outside the scope of this Wiki page, and can be found described in the manpage for snmpd.conf.

Note that to monitor snmp from external hosts, you may also need to check that snmpd is binding to either 0.0.0.0 or a specified IP address. In the interests of security, many distros only bind snmpd to 127.0.0.1.

Installation Prerequisites​

You need to install "net-snmp-devel" or "net-snmp-dev" package and have "openssl-devel" (or openssl-dev) to be able to compile this module.

Debian Wheezy​

Debian is missing MIBs for SNMP. To install them, add the non-free aptitude sources to /etc/apt/sources.list

# non-free
deb http://ftp.us.debian.org/debian/ wheezy non-free
deb-src http://ftp.us.debian.org/debian/ wheezy non-free

Then install snmp-mibs-downloader

apt-get update
apt-get install snmp-mibs-downloader

Testing with snmpwalk​

If you have 'rocommunity public localhost' in your snmpd.conf you can test with snmpwalk. Walk the whole tree:

snmpwalk -v 1 -c public localhost .1.3.6.1.4.1.27880

Walk systemStats:

snmpwalk -v 1 -c public localhost .1.3.6.1.4.1.27880.1.2