contrib-munin/plugins/snmp/snmp__airport

#!/usr/bin/python
"""
Munin plugin to monitor various items of data from an Apple Airport
Express/Extreme or a Time Capsule.

v1.0 by Chris Jones <cmsj@tenshu.net>
Copyright (C) 2011 Chris Jones
This script is released under the GNU GPL v2 license.

To use this plugin, use specially named symlinks:

cd /etc/munin/plugins
ln -s /path/to/snmp__airport snmp_myairport_airport_clients
ln -s /path/to/snmp__airport snmp_myairport_airport_dhcpclients
ln -s /path/to/snmp__airport snmp_myairport_airport_rate
ln -s /path/to/snmp__airport snmp_myairport_airport_signal
ln -s /path/to/snmp__airport snmp_myairport_airport_noise

NOTE: the name 'myairport' should be a valid hostname or IP address for your
      Airport. It can be any value, but it must not include the character '_'.

Now add a virtual host entry to your munin server's munin.conf:

[myairport]
    address 123.123.123.123
    user_node_name no

(with the correct IP address, obviously)

this will create a virtual host in munin for the airport named 'myairport' and
produce graphs for:
    * number of connected wireless clients
    * number of active DHCP leases
    * rate at which clients are connected (in Mb/s)
    * signal quality of connected clients (in dB)
    * noise level of connected clients (in dB)

# Magic markers
#%# capabilities=
#%# family=contrib manual
"""
import sys
import os
try:
    import netsnmp
except ImportError:
    print """ERROR: Unable to import netsnmp.
Please install the Python bindings for libsnmp.
On Debian/Ubuntu machines this package is named 'libsnmp-python'"""
    sys.exit(-3)

DEBUG=None
CMDS=['type', 'rates', 'time', 'lastrefresh', 'signal', 'noise', 'rate', 'rx',
      'tx', 'rxerr', 'txerr']
CMD=None
DESTHOST=None
NUMCLIENTS=None
NUMDHCPCLIENTS=None
WANIFINDEX=None

def dbg(text):
    """Print some debugging text if DEBUG=1 is in our environment"""
    if DEBUG is not None:
        print "DEBUG: %s" % text

def usage():
    """Print some usage information about ourselves"""
    print __doc__

def parseName(name):
    """Examing argv[0] (i.e. the name of this script) for the hostname we should
    be talking to and the type of check we want to run. The hostname should be
    a valid, resolvable hostname, or an IP address. The command can be any of:
        * clients - number of connected wireless clients
        * signal  - dB reported by the wireless clients for signal strength
        * noise   - dB reported by the wireless clients for noise level
        * rate    - Mb/s rate the wireless clients are connected at

    The name should take the form snmp_HOSTORIP_airport_COMMAND
    """
    bits = name.split('_')
    if len(bits) >= 4:
        destHost = bits[1]
        cmd = bits[3]
        dbg("parseName split '%s' into '%s'/'%s'" % (name, destHost, cmd))
        return (destHost, cmd)
    else:
        dbg("parseName found an inconsistent name: '%s'" % name)
        return None

def tableToDict(table, num):
    """The netsnmp library returns a tuple with all of the data, it is not in any
    way formatted into rows. This function converts the data into a structured
    dictionary, with each key being the MAC address of a wireless client. The
    associated value will be a dictionary containing the information available
    about the client:
        * type        - 1 = sta, 2 = wds
        * rates       - the wireless rates available to the client
        * time        - length of time the client has been connected
        * lastrefresh - time since the client last refreshed
        * signal      - dB signal strength reported by the client (or -1)
        * noise       - dB noise level reported by the client (or -1)
        * rate        - Mb/s rate the client is connected at
        * rx          - number of packets received by the client
        * tx          - number of packets transmitted by the client
        * rxerr       - number of error packets received by the client
        * txerr       - number of error packets transmitted by the client
    """
    table = list(table)
    clients = []
    clientTable = {}

    # First get the MACs
    i = num
    while i > 0:
        data = table.pop(0)
        clients.append(data)
        clientTable[data] = {}
        dbg("tableToDict: found client '%s'" % data)
        i = i - 1

    for cmd in CMDS:
        i = 0
        while i < num:
            data = table.pop(0)
            clientTable[clients[i]][cmd] = data
            dbg("tableToDict: %s['%s'] = %s" % (clients[i], cmd, data))
            i = i + 1

    return clientTable

def getNumClients():
    """Returns the number of wireless clients connected to the Airport we are
    examining. This will only ever be polled via SNMP once per invocation. If
    called a second time, it will just return the first value it found. This is
    intended to be an optimisation to reduce SNMP roundtrips because this script
    should not be long-running"""
    global NUMCLIENTS
    wirelessNumberOID = '.1.3.6.1.4.1.63.501.3.2.1.0'

    # Dumbly cache this so we only look it up once.
    if NUMCLIENTS is None:
        NUMCLIENTS = int(netsnmp.snmpget(netsnmp.Varbind(wirelessNumberOID),
                                         Version=2, DestHost=DESTHOST,
                                         Community='public')[0])
        dbg("getNumClients: polled SNMP for client number")

    dbg("getNumClients: found %d clients" % NUMCLIENTS)
    return NUMCLIENTS

def getNumDHCPClients():
    """Returns the number of DHCP clients with currently active leases. This
    will only ever be polled via SNMP once per invocation. If called a second
    time, it will just return the first value it found. This is intended to be
    an optimisation to reduce SNMP roundtrips because this script should not be
    long-running"""
    global NUMDHCPCLIENTS
    dhcpNumberOID = '.1.3.6.1.4.1.63.501.3.3.1.0'

    # Dumbly cache this so we only look it up once.
    if NUMDHCPCLIENTS is None:
        NUMDHCPCLIENTS = int(netsnmp.snmpget(netsnmp.Varbind(dhcpNumberOID),
                                             Version=2, DestHost=DESTHOST,
                                             Community='public')[0])
        dbg("getNumDHCPClients: polled SNMP for dhcp client number")

    dbg("getNumDHCPClients: found %d clients" % NUMDHCPCLIENTS)
    return NUMDHCPCLIENTS

def getExternalInterface():
    """Returns the index of the WAN interface of the Airport. This will only
    ever be polled via SNMP once per invocation, per getNum*Clients(). See
    above."""
    global WANIFINDEX
    iFaceNames = '.1.3.6.1.2.1.2.2.1.2'

    if WANIFINDEX is None:
        interfaces = list(netsnmp.snmpwalk(netsnmp.Varbind(iFaceNames),
                                          Version=2, DestHost=DESTHOST,
                                          Community='public'))
        dbg("getExternalInterface: found interfaces: %s" % interfaces)
        try:
            WANIFINDEX = interfaces.index('mgi1') + 1
        except ValueError:
            print "ERROR: Unable to find WAN interface mgi1"
            print interfaces
            sys.exit(-3)

    dbg("getExternalInterface: found mgi1 at index: %d" % WANIFINDEX)
    return WANIFINDEX

def getExternalInOctets():
    """Returns the number of octets of inbound traffic on the WAN interface"""
    return getOctets('In')

def getExternalOutOctets():
    """Returns the number of octets of outbound traffic on the WAN interface"""
    return getOctets('Out')

def getOctets(direction):
    """Returns the number of octets of traffic on the WAN interface in the
    requested direction"""
    index = getExternalInterface()

    if direction == 'In':
        iFaceOctets = '.1.3.6.1.2.1.2.2.1.10.%s' % index
    else:
        iFaceOctets = '.1.3.6.1.2.1.2.2.1.16.%s' % index

    return int(netsnmp.snmpget(netsnmp.Varbind(iFaceOctets),
                               Version=2, DestHost=DESTHOST,
                               Community='public')[0])

def getWanSpeed():
    """Returns the speed of the WAN interface"""
    ifSpeed = "1.3.6.1.2.1.2.2.1.5.%s" % getExternalInterface()
    dbg("getWanSpeed: OID for WAN interface speed: %s" % ifSpeed)
    try:
        wanSpeed = int(netsnmp.snmpget(netsnmp.Varbind(ifSpeed),
                                       Version=2, DestHost=DESTHOST,
                                       Community='public')[0])
    except:
        dbg("getWanSpeed: Unable to probe for data, defaultint to 10000000")
        wanSpeed = 10000000

    return wanSpeed

def getData():
    """Returns a dictionary populated with all of the wireless clients and their
    metadata"""
    wirelessClientTableOID = '.1.3.6.1.4.1.63.501.3.2.2.1'

    numClients = getNumClients()

    if numClients == 0:
        # FIXME: what's actually the correct munin plugin behaviour if there is no
        # data to be presented?
        dbg("getData: 0 clients found, exiting")
        sys.exit(0)

    dbg("getData: polling SNMP for client table")
    clientTable = netsnmp.snmpwalk(netsnmp.Varbind(wirelessClientTableOID),
                                   Version=2, DestHost=DESTHOST,
                                   Community='public')
    clients = tableToDict(clientTable, numClients)

    return clients

def main(clients=None):
    """This function fetches metadata about wireless clients if needed, then
    displays whatever values have been requested"""
    if clients is None and CMD not in ['clients', 'dhcpclients', 'wanTraffic']:
        clients = getData()

    if CMD == 'clients':
        print "clients.value %s" % getNumClients()
    elif CMD == 'dhcpclients':
        print "dhcpclients.value %s" % getNumDHCPClients()
    elif CMD == 'wanTraffic':
        print "recv.value %s" % getExternalInOctets()
        print "send.value %s" % getExternalOutOctets()
    else:
        for client in clients:
            print "MAC_%s.value %s" % (client, clients[client][CMD])

if __name__ == '__main__':
    clients = None
    if os.getenv('DEBUG') == '1':
        DEBUG = True
        netsnmp.verbose = 1
    else:
        netsnmp.verbose = 0

    BITS = parseName(sys.argv[0])
    if BITS is None:
        usage()
        sys.exit(0)
    else:
        DESTHOST = BITS[0]
        CMD = BITS[1]

    if len(sys.argv) > 1:
        if sys.argv[1] == 'config':
            print """
graph_category network
host_name %s""" % DESTHOST

            if CMD == 'signal':
                print """graph_args -l 0 --lower-limit -100 --upper-limit 0
graph_title Wireless client signal
graph_scale no
graph_vlabel dBm Signal"""
            elif CMD == 'noise':
                print """graph_args -l 0 --lower-limit -100 --upper-limit 0
graph_title Wireless client noise
graph_scale no
graph_vlabel dBm Noise"""
            elif CMD == 'rate':
                print """graph_args -l 0 --lower-limit 0 --upper-limit 500
graph_title Wireless client WiFi rate
graph_scale no
graph_vlabel WiFi Rate"""
            elif CMD == 'clients':
                print """graph_title Number of connected clients
graph_args --base 1000 -l 0
graph_vlabel number of wireless clients
graph_info This graph shows the number of wireless clients connected
clients.label clients
clients.draw LINE2
clients.info The number of clients."""
            elif CMD == 'dhcpclients':
                print """graph_title Number of active DHCP leases
graph_args --base 1000 -l 0
graph_vlabel number of DHCP clients
graph_info This graph shows the number of active DHCP leases
dhcpclients.label leases
dhcpclients.draw LINE2
dhcpclients.info The number of leases."""
            elif CMD == 'wanTraffic':
                speed = getWanSpeed()
                print """graph_title WAN interface traffic
graph_order recv send
graph_args --base 1000
graph_vlabel bits in (-) / out (+) per ${graph_period}
graph_category network
graph_info This graph shows traffic for the mgi1 network interface
send.info Bits sent/received by this interface.
recv.label recv
recv.type DERIVE
recv.graph no
recv.cdef recv,8,*
recv.max %s
recv.min 0
send.label bps
send.type DERIVE
send.negative recv
send.cdef send,8,*
send.max %s
send.min 0""" % (speed, speed)
            else:
                print "Unknown command: %s" % CMD
                sys.exit(-2)

            if CMD in ['clients', 'dhcpclients', 'wanTraffic']:
                # This is static, so we sent the .label data above
                pass
            else:
                clients = getData()
                for client in clients:
                    print "MAC_%s.label %s" % (client, client)

            sys.exit(0)
    else:
        main(clients)