Polling Configuration

Polling Configuration

This chapter describes all the backend collection and collation processes. It is used to describe new host or interface types and is how you add new sorts of checks. Unfortunately it is pretty complicated to wander your way around. The good news is you may not need to edit any of these tables for a default JFFNMS setup.

At first there are pollers, that collect data, and backends, that do something with the data that are collected by the poller. An interface type determines what values are stored and how autodiscovery is used. Finally a Poller Group creates a type which is a single interface types and a collection of pollers.

FIXME - Poller Group and Interface types have a cross reference, why? FIXME - it was for filtering ease, and Interface Types needs a Default PollerGroup and PollerGroups need to be filtered by InterfaceType on the Interfaces Screen.

Interface Types

The Interface Types are what drive the polling part of JFFNMS. These are the key to all other attributes such as what values to get, the graphs that are displayed and how interfaces are discovered and polled.

The list of Interface Types is shown with the Administration menu item Internal Configuration => Polling & Discovery => Interface Types. The table has a set of actions that can be performed on each Interface Type. Edit and Del edit and delete the Interface Type respectively. The View link displays the Interface Type Fields while the rest of the columns contain attributes about the Interface Type.

Description

A Description of the Interface Type. Such as Noise Level.

Autodiscovery Enabled

Check this if you are going to create an autodiscovery plugin and you want JFFNMS to attempt to find these sorts of interfaces on its regular interface discovery polls.

Validate in Autodiscovery

Each time the poller is run the interface IDs are checked again.

Autodiscovery Function

The name of a Discovery Script, in the engine/discovery directory without the .inc.php only the base name.

Autodiscovery Parameters

This string is passed to the Discovery Script directly. (useful to write a discovery script only once and use it different things.

Autodiscovery Default Poller

If an interface of this type is discovered by the autodiscovery script then the specified Poller Group will be used for the new interface. Most of the time there is only one Poller Group for each Interface Type.

Internal Update Handler

Only used for some special interface types but it is a handler that is called each time the record of that type is updated for manipulating data. Generally leave blank.

Manual Interface Add

If this field is checked, the Administrator can manually add interfaces of this type. Used for things like TCP ports that are not automatically found.

Break By Card

Display the interfaces grouped by Card. Useful for things such as router or switch ports that have cards or blades.

Have Tools

If checked interfaces of this type have the tool icon displayed which takes the user to the tools.

Have Graph

Cosmetic Option, show a link to the performance (graph) system from the Interface Map.

Default Graph

Cosmetic Option, which graph to show by default on the Performance Viewer, from the Graph Types Table.

Default SLA

New interfaces of this type are given this SLA if discovered.

RRDTool Structure RRA

A standard RRA definition as specified in RRDTool manual page. Try to use

 RRA:AVERAGE:0.5:1:<resolution>

resolution> is replaced by the interface type resolution defined in the RRDTool Resolution Field.

RRDTool Resolution

- this is RRDTool resolution (how many datapoints do we need to store) 103680 is one year of 5 minutes intervals.

RRDTool Step

The step in a RRD file in seconds. This should be 300 (5 minutes) for almost all cases.

Interface Type Fields

The fields are used by the discovery, poller and graph plugins so whether or not you need any fields depends on if there is a value you want either an operator to put in or for the poller to track.

You may need to put some RRDToolDS type fields if you want to monitor some value. Without these type fields no RRD file is created.

Each interface type requires a set of interface fields. These fields are the containers which hold values for the interfaces. The fields are the same for each Interface Type, but the values that are held in the fields are different for each interface. Table * gives the list types of Interface Type fields.

Interface Type Field types

Field	Description
Index	A field that is unique for this Interface Type for a particular host. This is used by JFFNMS to determine which interface is what. For example, for SNMP interfaces JFFNMS uses the ifIndex SNMP OID.
Boolean	A value that can only be Yes or No.
Description	Interface icons that appear in the maps have the value for the description fields in them.
Other	A text field that is not part of the Index or used for Description.
RRDTool DS	A Data Source (DS) definition for a RRD file.

There should be only one field that has the Index type. Multiple Index fields will cause parts of JFFNMS to fail, such as the verify interface number backend.

Interface Type Fields are displayed by clicking on the View link for the desired Interface Type row. A new table appears below the Interface Type table that shows all the selected fields. Each row has an Edit and Del link as well as attributes of the fields

Description: A simple description of the field. For fields of Description type this string is displayed in the Interface icon on the maps.
Internal Name: This string is used by things such as the poller name and interface fields.
Position: The position orders fields of the same type.
Interface Type: The Interface Type this field is applied to.
Field Type: See table *
Show: This option will decide if the field is not shown anyway, shown in discovery and interface editing tables or just the table.
Overwritable: With this field checked, Administrators are able to overwrite the value
Tracked: Fields with this value checked will cause alarms if the autodiscovery detects a change.
Default Value: For most field types this is the value of the field if the autodiscovery does not fill it in. For RRDTool DS types it is the definition of the data source.

As previously mentioned, the Position attribute sets the orders of fields of the same type. For Description field types, it is the order of the fields that are displayed in the Interface maps. The top-most field having the lowest position number.

RRDTool DS fields also use the Position attribute for ordering. Generally a Poller Group will collect information. The definition of RRD files is out of the scope of this document, the general idea is the same for all RRD files not just ones defined in JFFNMS. Each RRDTool DS field has 4 attributes that define the Data Source.

The first is the DS type which uses the standard definitions of an RRD. The type can be Counter, Gauge or Absolute. The Min field is for the minimal value. Any value under this minimum is not added to the RRD.

Maximum value can be fixed or be derived from another field. If it is fixed then the value goes in the box immediately to the right of the Max: label. For maximums that come from another field, put the field name (Internal Name) in the Use box and check the "for Max:" checkbox.

Poller Groups

A Poller Group can be consider a device type where you want to collect the same information and status. It uses a single interface type which you then apply multiple pairs of pollers and backends.

Generally for most poller groups, they follow a standard order of things that need doing.

Verify that the id of the interfaces is still correct using an interface specific poller and the verify_interface_number backend.
Check the status of the interface and use the alarm backend to signal if there is a problem (or there was and now the interface is OK).
Collect some statistics about the interface, such as byte counts and store in temporal buffer.
Move information out of temporal buffer into a RRD file.

Poller Items

For JFFNMS to determine the state of some host's interface, it needs to measure something using some method. The poller table determines what command is used and what parameters as passed to that command. The commands are found in <JFFNMS>/engine/pollers directory. The pollers are called from the main program engine/poller.php

The table has the following fields:

Description - Text description of the poller.
Name - This must match an RRD DS column that has been defined in the RRDTool Structure DEF column in the Interface Types table if you want this data to be stored on a RRDTool file.
Poller Command - What program in engine/pollers will be used, ".inc.php" is appended to the name. See below to see what commands are already defined.
Parameters - What parameters are passed to the command. This column is dependent on what command you use. Predefined variables are explained further on.

The following commands are defined:

snmp_counter - Measure the value of some SNMP variable. Parameter is the OID to measure.
snmp_interface_status - Returns the value of the IfOperStatus SNMP table of the interface.
verify_bgp_peer_number - Checks that the BGP peer for internal Indexes change, this is to keep track of the BGP Peer when you add a new BGP Peer to the router
bgp_peer_status - Checks the status of your BGP peers, a status of down or active returns down. Requires BGP peer IP address.
tcp - Makes a TCP connection to the Host IP Address, using the port specified as the INum of the interface.

The following predefined values are available on this table. They are written in the Parameter column with angles like <fieldname>

host_ip - IP address of the Host. Defined in hosts Table.
interface - Interface Name, comes from the Interface Name column in the Interfaces Table.
interfacenumber - Interface Number, comes from INum column in Interfaces Table.
address - IP Address of the interface, comes from the Address column in the Interfaces Table.
peer - Peer IP address, comes from the Peer column in the Interfaces Table.
description - Interface Description, comes from the Description column in the Interfaces Table.

The job of the poller is to get some value or string which is then passed onto the specified backend. It is there the backend that determines what value the poller function should return. See the next section about backends for a description of the types and their expected values.

Backend Items

Backends are programs that are found in engine/backends. Like the pollers, the backends are called by engine/poller.php. The main difference between a poller and a backend is the poller collects more data while a backend works on existing or received from the poller data.

There are 4 supplied backend types that come with JFFNMS: alarm, verify_interface_number, rrd and buffer.

The alarm backend is used for sending alarms to interfaces. Unless you want the backend to do absolutely nothing, it must have a parameter that is the ID event type to raise or clear. The type is found in the Event Types table and is the ID column. The relevant poller will supply the backend with the string "up" or "down" which generates the relevant event for that interface, using the event type supplied.

The verify_interface_number has no parameters. The poller gives it the current interface id for the specific interface. The backend then checks this id with the existing one in the database and updates the database with the current one if they are different.

The RRD backend is used to update and create the RRD files. Unlike any of the other backends, this one does not use a corresponding poller (use No Poller). It retrieves the information from the temporal buffer and then saves the information in the RRD files.

The buffer backend takes the information from its poller and stores it in a buffer. This buffer is used by subsequent RRD backends. It takes no parameters.

Graph Types

JFFNMS can produce graphs for anything the pollers collect and put into an RRD file. The Graph Types table is used to tell JFFNMS what graphs are available for what Interface Types. Assuming they use the same variables, different Interface Types can use the same graph backend.

For each graph type, you can have two graphs on the same page. Not every graph type needs two graphs.

Description: The name of the graph. Appears in the drop-down box on the Performance pages.
Interface Type: The Interface Type the graph is for.
Allow Aggregation: Does this graph have permit an aggregation graph, that is a single graph that can show multiple lines of data of the same type. For more information see Aggregate Graphs.
Graph 1: This is used to find the name of the file the graph definition is located. The filename will be JFFNMS/engine/graphs/<name>.inc.php
Width 1: Width of the first graph
Height 1: Height of the first graph
Graph 2: Filename of second graph
Width 2: Width of second graph
Height 2: Height of second graph

Aggregate Graphs

An aggregate graph is one that is able to show simultaneously data from multiple graphs of the same Interface Type. The filename for the aggregate is like the standard graph, except it has _aggregate in it. For example if the graph filename is traffic.inc.php, the aggregate filename will be traffic_aggregate.inc.php

The function arguments are similar to that of the standard graph function except that the interfaces are in an array with an index of the interface ID. The array contains the standard Interface Parameters (see table * ).

Autodiscovery Policies

The Autodiscovery Policies are used by JFFNMS to change what it does for the autodiscovery polling. Each policy can have enabled any of the options from list below.

The Policies are found in the Administration menu item Polling & Discovery => Autodiscovery Policy.

Autodiscovery Policies Options

Option	Desctiption
Default Poller	New interfaces use the default poller as defined by the interface's Interface Type. If this option is not used, then No polling will be performed on new interfaces.
Permit Add	Allow the Autodiscovery process to add new interfaces if an interface is found but not in the database.
Permit Delete	Allow the Autodiscovery process to delete existing interfaces when they are not found in host.
Alert on Delete	Create an event when deleting an interface.
Permit Modify	Allow the Autodiscovery process to change interface attributes.
Permit Disable	Allow the Autodiscovery process to disable an interface.
Skip Loopback	Do not discover loopback interfaces (Interface name begins with "loopback", "lo" or "null" or IP address is 127.0.0.1) .
Check State	Only interfaces that are operationally up will be discovered.
Check Valid Address	Interfaces need a valid IP address before they are discovered.

It is unlikely that you will need to change anything on this table but JFFNMS does allow you to edit or add new policies. The options are hard coded deep inside the JFFNMS discovery code and would be difficult to change.

The standard set of Autodiscovery Policies should cover most situations and have the following features.

Autodiscovery Policies

Policy Name	Description
Standard (for switches)	As can be assumed from the name, use this for switches. They can be added or deleted but must be operationally up. This is the only policy that doesn't need a valid address for the interface.
Standard	Most network devices should use this policy. Interfaces are added and alarmed if deleted.
Just Inform	This policy will only alert on changes to the list of interfaces and does not make and changes to the database.
Automagic	Allows the process to do everything it needs to.
Administrative	This policy is like Standard except it doesn't use the default poller and it can delete interfaces.

JFFNMS Manual, last changed July 3, 2008

Polling Configuration