| | | ICMP Interface Example |
The previous chapter described how to expand JFFNMS in some detail, but often it helps to have a concrete example of what you are trying to do for illustration.
This chapter will guide you, step by step, through all the things needed to get a simple poller going. Use this as a guide or a template for your own pollers.
We will use the example of creating a graph that shows the number of incoming ICMP messages coming into a server. ICMP stands for Internet Control Message Protocol and is used by IP networks to send control messages. The most well-known ICMP messages are echo reply and request, which are used by the ping program. When you "ping" something you are sending an ICMP echo request packet and the thing you just pinged replies with an ICMP echo reply.
This counter is a good one to use for an example because it is found on on most systems and is easy to increment by pinging the device.
Most people assume you plug the MIB somehow into JFFNMS and it will poll everything fine. This is an incorrect assumption as you need to work out which value you want to measure. MIBs are also in a tree structure, with the root being . and the leaf being the value you want to measure, while JFFNMS uses an OID, which is a chain of nodes from the root to your leaf.
It is best to work backwards in the MIB. Find the values you want to monitor and find their parents and then grandparents until you get back to the top of the tree.
The particular OID we want to use is the icmpInMsgs counter, found in the IP MIB. It's OID is .1.3.6.1.2.1.5.1.0 I can check this counter with a simple command line:
We can see that the host responds with a value, and there have been 1397 incoming ICMP messages for this host since the SNMP daemon was last started.
A Poller Item is referenced in a Poller Group (see next). For our Interface Type, we want to use the snmp_counter plugin to poll the host our OID. To create the Poller Item:
Remember what you have put into the Name column as that is used elsewhere in the setup. The Description is just information for you so you know what the poller does.
Next is to get the Poller Group to join the Poller Item created in the previous step to the Backend that takes the value from the poller and puts it into the RRD file for later graphing.
As we are only polling 1 item, the group is rather simple:
Next step on our list is to create the Interface Type. This is the object that holds all the other pieces together. It also allows us to setup the values the Interface Type has, see next section.
Interface Type Fields are the containers that are used to hold parameters for a particular interface type. It tells JFFNMS, for example, what RRD files to create.
For our example, we just need the index and a single RRD file. We're more interested in the rate of incoming ICMP packets than the absolute value of packets received since last reboot, so the RRD counter type is the one to use.
The Poller Group references an Interface Type. The Interface Type references a Poller Group. There is a chicken and egg problem here as you need to create one before the other. As we created the Interface Type after the Poller Group, it is OK and has the Default Poller column set, but now we need to fix the Poller Group so it will appear in the list of pollers available for interfaces of this type.
Now we are ready for some testing. Make sure whatever host you run it on has SNMP and it does give you a value for this counter. Run the snmpwalk command described at the start of this chapter.
Next go into the Administration menu item Hosts and Interfaces => Hosts, this should then show you the host table. Find the Host you are testing, then set the combo box on the left of that row to "Manual Discovery w/o Portscan" and click the white/blue arrow next to it.
You should see another pane open below the Host table, showing a whole lot of Interfaces. If your changes are working, there will also be a new interface having a type of "ICMP In Message". This means the discovery part of your changes is working.
Take note of the ID of the host. It is the number in bold immediately to the right of the white/blue arrow. We will need this host ID in the next stage.
Click the checkbox on the left side of your interface, then click the button marked "Add Marked Interfaces" right down the bottom of the interface table. This will change the windows to bring up an Interface edit window. The interface has an ID, make note of that too. This interface ID is different to the host ID.
To check the poller, once you have an interface of this type find the host ID and interface ID and run it on the command line.
The poller is working nicely, the rrd backend is sending the value 402 into the RRD file labelled icmp_inmsgs.
OK, so we're collecting data, what now? We need to graph it. To do this we either need to use an existing graph plugin or write one. The plug-in is there to tell JFFNMS what to do with the graphs and is basically a bunch of lines that get sent to rrdtool. We have only 1 RRD file so our plugin is pretty simple. Make a file called graphs/icmp_inmsgs.inc.php
function graph_icmp_inmsgs ($data) {
$opts_DEF = rrdtool_get_def($data,array("icmp_inmsgs"));
$opts_GRAPH = array(
"AREA:icmp_inmsgs#00CC00:'ICMP Messages '",
"GPRINT:icmp_inmsgs:AVERAGE:'Average\:%4.0lf %sEps'",
"GPRINT:icmp_inmsgs:LAST:'Last\:%4.0lf %sEps\\n'");
$opts_header[] = "--vertical-label='Messages per Second'";
return array ($opts_header, @array_merge($opts_DEF,$opts_GRAPH));
}
The function name has to be whatever you call the filename with graph_ at the front of it. This filename (without the .inc.php) is used in the GUI to create a new graph type.
Now to tell JFFNMS about the plug-in. Go to Internal Configuation => Polling & Discovery => Graph Types. Click on the Add button at the top of the table to make a new Graph Type.
Enter in the following values:
As long as you have already checked the "Have Graph" box in the Interface Types table, you should be able to see this graph in the Performance windows.
JFFNMS Manual, last changed July 3, 2008
| | | ICMP Interface Example |