Working with external programs

Working with external programs

JFFNMS is able to work with other programs to bring in different status information. This chapter describes the various types of external programs and how to get them working with JFFNMS.

SNMP Traps

To get jffnms receiving traps, you will need to install a SNMP trapd from net-snmp (formerly CMU snmp) package or one that works similarly. In the configuration file for snmptrapd, eg /etc/snmp/snmptrapd.conf put a line like:

traphandle default /opt/jffnms/engine/trap_receiver.sh

This tells snmptrapd to run that trap receiver program every time it gets a trap. See snmptrapd.conf(5) manual page for details about what this does.

Syslog

There are two ways of working with syslog. The original way was to use a syslog program called msyslog which is shipped from the same site as JFFNMS. The second is to use syslog-ng and make a simple script to input the data.

Using msyslog to import events

To get JFFNMS to receive syslog messages from your routers you have to install a syslog daemon that sends messages to a MySQL database. Some distributions have msyslog included, which in that case just install that package. If your distribution doesn't, you can install the provided msyslog package found on the JFFNMS Website. To install it, follow the instructions below.

    tar xvzf msyslog-v1.08a
    cd msyslog-v1.08a
    ./configure 
    make 
    make install

Then you have to modify you syslog start script (/etc/init.d/syslog) to use the new server, and new configuration, examples are provided in the docs/unix folder.

You need to start msyslog as something like:

    /usr/local/sbin/syslogd -i linux -i unix -i udp

You also need to configure your routers to send syslog messages to an specific facility (again examples are provided).

Using syslog-ng to import events

Some distributions do not ship msyslogd or it has been withdrawn (due to stability and maintenance problems). In that case you can use syslog-ng for importing events from syslog.

You need to use a pipe for this method, the messages are sent out the pipe and then collected by a script that is running a MySQL client.

This document cannot be a full manual on syslog-ng, but essentially the configuration file creates sources (where the information came from), filters (based on syslog facility and level) and destinations, which are like the things in the right-hand-side of a traditional syslog file.

To start you off, the example given in the JFFNMS documents for msyslogd sends all messages for facility local6 to JFFNMS, for syslog-ng it would look like:

source s_jffnms { unix-dgram("/dev/log"); internal(); udp(); };

filter f_jffnms { facility(local6); };

destination d_jffnms {
  pipe("/var/run/syslogmysql.pipe"
  template("INSERT INTO syslog (date, date_logged, host, message) VALUES ('$YEAR-$MONTH-$DAY $HOUR:$MIN:$SEC', NOW\(\), '$FULLHOST', '$MSG');\n") template-escape(yes));
};

log { source{s_jffnms}; filter{f_jffnms}; destination{d_jffnms}; };

Next you need to make the script, it essentially keeps the mysql client running. An example script is:

#!/bin/sh

MYPIPE="/var/run/syslogmysql.pipe"

if [ ! -e $MYPIPE ] ; then
  mkfifo $MYPIPE
  fi

  while [ -e $MYPIPE ] ; do
    mysql -u jffnms --password=jffnms jffnms < $MYPIPE
	done

Then you just need to run it. Once you checked it actually works, you can get it running from init, by putting something like the following into /etc/inittab

N1:23:/usr/local/sbin/mysqlpipe.sh

Smokeping

Smokeping is a great program for measuring round trip times (RTT) and packet loss to remote destinations. It not only prints these two figures but the distribution of the RTT so you can see if there is variance in the ping times. Integration has been available since JFFNMS version 0.7.0. The best way to use it is to create a new host specially for Smokeping with no IP address. For Smokeping to work, JFFNMS needs to know the top of the data directory (where the RRDs are found). You tell JFFNMS by setting the SNMP read-only community to the value of the top directory.

If you don't know what your data directory is, look in the Smokeping configuration file and find the line beginning with datadir. Once you have set the directory, you should see the Smokeping interfaces when you use the "Get Interfaces" command from the host table.

To alarm a Smokeping interface, such as letting you know if the RTT or packet loss is too high, you would use a SLA just like checking for any other interface parameter. Just like a normal interface, the performance and reporting features are available.

Working with external programs