README

TrapperKeeper
=============

Description
-----------

TrapperKeeper is a suite of tools for ingesting and displaying SNMP
traps. This is designed as a replacement for snmptrapd and to supplement
existing stateful monitoring solutions.

Normally traps are stateless in nature which makes it difficult to
monitor with a system like nagios which requires polling a source.
TrapperKeeper will store traps in an active state for a configured
amount of time before expiring. This makes it possible to poll the
service for active traps and alert off of those traps.

One example might be a humidity alert. If you cross over the humidity
threshold and it clears immediately you might not want to be paged at
3am. But if it continues to send a trap every 5 minutes while it's over
that threshold the combination of (host, oid, severity) will remain in
an active state as long as that trap's expiration duration is longer
than 5 minutes. This allows something like nagios to alarm when a single
trap remains active for greater than some period of time.

Another benefit is allowing aggregation of pages. Previously we'd just
had an e-mail to a pager per trap but now we're only paged based on the
alert interval regardless of how many traps we receive. This also allows
us to schedule downtime for a device during scheduled maintenance to
avoid trap storms.

Requirements
------------

Ubuntu
~~~~~~

.. code:: bash

    $ sudo apt-get install libmysqlclient-dev libsnmp-dev

Installation
------------

New versions will be updated to PyPI pretty regularly so it should be as
easy as:

.. code:: bash

    $ pip install trapperkeeper

Once you've created a configuration file with your database information
you can run the following to create the database schema.

.. code:: bash

    $ python -m trapperkeeper.cmds.sync_db -c /path/to/trapperkeeper.yaml

Tools
-----

trapperkeeper
~~~~~~~~~~~~~

The trapperkeeper command receives SNMP traps and handles e-mailing and
writing to the database. An example configuration file with
documentation is available `here. <conf/trapperkeeper.yaml>`__

trapdoor
~~~~~~~~

trapdoor is a webserver that provides a view into the existing traps as
well as an API for viewing the state of traps. An example configuration
file with documentation is available `here. <conf/trapdoor.yaml>`__

.. figure:: https://raw.githubusercontent.com/dropbox/trapperkeeper/master/images/trapdoor.png
   :alt: Screenshot

   Screenshot
API
^^^

/api/activetraps
''''''''''''''''

**Optional Parameters:** \* host \* oid \* severity

**Returns:**

.. code:: javascript

    [
        (<host>, <oid>, <severity>)
    ]

/api/varbinds/
''''''''''''''

**Returns:**

.. code:: javascript

    [
        {
            "notification_id": <notification_id>,
            "name": <varbind_name>,
            "pretty_value": <pretty_value>,
            "oid": <oid>,
            "value": <value>,
            "value_type": <value_type>
        }
    ]

MIB Configuration
-----------------

``trapperkeeper`` and ``trapdoor`` use the default mibs via netsnmp. You
can see the default path for your system by running
``net-snmp-config --default-mibdirs``. You can use the following
environment variables usually documented in the ``snmpcmd`` man page

    MIBS - The list of MIBs to load. Defaults to
    SNMPv2-TC:SNMPv2-MIB:IF-MIB:IP-MIB:TCP-MIB:UDP-MIB:SNMP-VACM-MIB.

    MIBDIRS - The list of directories to search for MIBs. Defaults to
    /usr/share/snmp/mibs.

For example I run both the ``trapperkeeper`` and ``trapdoor`` commands
with the following environment to add a directory to the path and load
all mibs.

``MIBS=ALL MIBDIRS=+/usr/share/mibs/local/``

TODO
----

-  Allow Custom E-mail templates for TrapperKeeper
-  cdnjs prefix for local cdnjs mirrors
-  User ACLs for resolution
-  Logging resolving user

Known Issues
------------

-  Doesn't currently support SNMPv3
-  Doesn't currently support inform
-  Certain devices have been known to send negative TimeTicks. pyasn1
   fails to handle this.