===== Introduction =====

This file contains instructions on how to use the snmptrapd in NAV and
how to add traphandlers to it.


===== What is the snmptrapd? =====

The snmptrapd is a program written in python designed to receive traps
sent to NAV and process them by sending them to
traphandlers. Traphandlers are independent and may be written by
whoever wants to. snmptrapd is based on the pysnmp-library and the
example on [[http://pysnmp.sourceforge.net/examples/2.x/snmptrapd.html|Python@SourceForge]]


===== Usage =====

The snmptrapd is located in the ''$NAV/bin'' directory and is started and
stopped like any other nav-process - by the use of nav start/stop
commands. The snmptrapd may be run on the commandline aswell if no
other trapdaemon is running. It then logs everything to STDOUT. If you
want to daemonize it, use the -d option.

When run, snmptrapd first binds to the port it will receive traps on
(default 162) as root, and then switches user to the one specified in
the config-file (default navcron). This is done as a safety measure.


===== Logging =====

For logging the python-module 'logging' is used. It accepts the usual
loglevels (DEBUG, INFO). See
[[http://docs.python.org/lib/module-logging.html|Logging-module]] for more
information. Loglevels may be set in the snmptrapd config-file.

The snmptrapd, when daemonized, logs to two files: //snmptrapd.log// and
//snmptraps.log//. snmptrapd.log contains normal process logging and
snmptraps.log contains all traps received by the daemon. Logrotation
should be used on these files.


===== Configuration =====

The config-file is called snmptrapd.conf and is located in
''$NAV/etc''. It is read using the ConfigParser module (see
[[http://docs.python.org/lib/module-ConfigParser.html|ConfigParser-module]] for more
information). This means that options may be set using ''variable=value''. #-lines are comments.

The file is divided into sections. There is one general section, the
rest is config for the traphandlers. The most interesting parameters
are //loglevel// and //handlermodules//. The first one sets the loglevel for
the rootlogger and the last one defines which traphandlers are used to
handle the incoming traps.


===== Traphandlers =====

When the snmptrapd receives a trap it puts all the information in a
trap-object and sends the object to every traphandler stated in the
//traphandlers// option in snmptrapd.conf. It is then up to the traphandler
to decide if it wants to process the trap or just discard it.

Step by step it goes like this:
 - Receive trap
  * Make trap-object
  * Import traphandlers stated in snmptrapd.conf
  * Run function handleTrap(trap, config) in the traphandlers
  * Get resultstatus from traphandler

The traphandlers may be imported from any directory available from the
python-path. The total pythonpath must be specified in snmptrapd.conf. Also
they must contain the function handleTrap which takes a trap-object
and a config-object as input.

Every traphandler may be configured by defining a section for the
traphandler in snmptrapd.conf and putting parameters there.

Everyone can write and use their own traphandler for the
snmptrapd. There is a handlertemplate (handlertemplate.py) that may be
used when creating your own traphandler. It contains some comments and
show you the basics to get you started.

NB: For a traphandler to take effect, snmptrapd must be restarted. Use
"sudo ./nav restart snmptrapd".

-- JohnMagneBredal