Munin contributed plugins

#!/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)