trapperkeeper 0.6.0

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 humity
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.

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

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

::

$ pip install trapperkeeper

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

``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
:align: center
:alt: Screenshot

Screenshot
API
^^^

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

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

**Returns:** ``javascript [ (<host>, <oid>, <severity>) ]``

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

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

TODO
----

- Runtime rules language for things like blackhole and e-mail subjects.
- 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
- Doesn't support listening on IPv6
- Certain devices have been known to send negative TimeTicks. pyasn1
fails to handle this.