Filters
From OpenNMS
Think of the filter (also referred to as a rule) as a shorthand SQL statement that automatically selects ipaddr from the ipinterface table. You are basically building the WHERE clause with the rule that you write. There is an XML file called database-schema.xml in the /opt/opennms/etc directory that informs the filter code of what tables it can use in building the WHERE clause. Here is an explaination of that file:
Each table used by the filter code is in a <table> tag. If a table has an attribute of 'visible=false' then no columns in that table can be used in the WHERE clause and thus can't appear in the rule. You will get some sort of syntax exception if it sees any non-visible columns in the rule. The same applies to a non-visible column in a table.
A <join> tag tells the filter module how to relate this table to the ipinterface table. The ipinterface table is marked with the attribute 'key=primary', meaning that it is going to be the table we select ipaddr from and join all other tables to.
In brief, you can use C / Java-style comparison operators to data types they apply to ( == and != can be used on strings, as can the SQL LIKE keyword). You can group expressions using parentheses and apply boolean operators anywhere in an expression. Note that, in a departure from C / Java convention, boolean operators are single characters rather than double, so they look more like the bitwise arithmetic operators in C:
- AND
- &
- OR
- |
- NOT
- !
Each comparision is joined together with the & or | operators meaning logical AND, logical OR operations. Anything delimited by an & or | character gets translated into a sub-select that selects the ipaddr based on the comparision for that clause. Here is an example:
Rule:
(nodesysname == 'something') & (snmpifdescr == 'something else')
SQL:
SELECT ipaddr
FROM ipinterface
WHERE ipaddr in (SELECT ipaddr FROM ipinterface, node
WHERE nodesysname='something'
AND ipinterface.nodeid =node.nodeid)
AND ipaddr in (SELECT ipaddr FROM ipinterface, snmpInterface
WHERE snmpifdescr='something else'
AND ipinterface.ipaddr = snmpInterface.ipaddr);
The IPLIKE function is a short hand to call a Postgres function that was written in C to compare ipaddresses using *, lists and ranges. is<Service> is a shorthand to build a complicated join to match on a service name. notis<Service> can be used since 1.2.7 or so.
Components of openNMS that use filters
- notifd
- Notification rules control whether or not a received event triggers a notification. Each event is tested against the rules in notifications.xml looking for a match. When a match is found, the corresponding notification is sent. The default for most notifications is "IPADDR IPLIKE *.*.*.*", however, any valid rule may be used. To do an exclusive filter use "!(IPADDR IPLIKE 169.254.*.*)". This allows you to be very granular when defining what to alert on.
- collectd
- Controls which IP interfaces are included in a collection package. Evaluated at startup.
- pollerd
- Controls which IP interfaces are included in a polling package. Evaluated at startup.
- rtcd
- Controls which IP interfaces are included in the various categories that are shown on the front page in the webUI. Evaluated at startup and when a "uei.opennms.org/nodes/assetInfoChanged" event is received (usually generated when asset information is changed in the webUI).
- threshd
- Controls which IP interfaces are included in a thresholding package. Evaluated at startup.
- webUI
- The webUI uses filters to validate rules when configuring notifications. This insures that the rule will be syntactically correct, and it allows the administrator to preview the list of matching interfaces before finalizing the notification.
- Filters are also used with rules when configuring path outages to select a list of nodes that lie behind the specified outage path. This list may be previewed before finalizing the configuration.
So How the Hell do I use them?
Rules can be much richer than simply filtering by IP, you can use parameters from nodes, categories etc. Parameters not present in database-schema.xml can be added for use in filter expressions, as long as the existing database table hierarchy is followed. Here is a partial list:
- Pollers
- dpNumber
- dpName
- dpIP
- dpComment
- dpDiscLimit
- dpAdminState
- dpRunState
- Nodes
- nodeID
- dpName
- nodeCreateTime
- nodeParentID
- nodeType
- nodeSysOID
- nodeSysName
- nodeSysDescription
- nodeSysLocation
- nodeSysContact
- nodeLabel
- Catagories
- categoryID
- categoryName
- categoryDescription
- Applications
- name - This field is used for alerting on user defined Applications, that span multiple systems and services.
- IpInterface
- ipAddr
- ipHostname
- isManaged
- ipStatus
- ipLastCapsdPoll
- SNMP Interface
- snmpIpAdEntNetMask
- snmpPhysAddr
- snmpIfIndex
- snmpIfDescr
- snmpIfType
- snmpIfSpeed
- snmpIfAlias (from 1.6.6 and 1.7.4)
- snmpIfAdminStatus
- snmpIfOperStatus
- Services
- serviceName
- ifServices
- serviceID
- lastGood
- lastFail
- Server Map
- serverName
- Service Map
- serviceMapName
- Assets
- displayCategory
- notifyCategory
- pollerCategory
- thresholdCategory
- category
- manufacturer
- vendor
- modelnumber
- serialnumber
- description
- circuitid
- assetnumber
- operatingsystem
- rack
- slot
- port
- region
- division
- department
- address1
- address2
- city
- state
- zip
- building
- floor
- room
- vendorphone
- vendorfax
- vendorassetnumber
- lease
- leaseexpires
- supportphone
- maintcontract
- maintcontractexpires
- comment
- managedobjectinstance
- managedobjecttype
Configuration examples
There are at least two formats which these rules can exist on the xml level (GUI format to follow).
In this first example, the entire rule is wrapped in "<![CDATA[...]]>" so that ampersands ("&") do not have to be escaped (the CDATA bits are in bold and in blue):
<rule><![CDATA[(IPADDR != '0.0.0.0') & (IPADDR IPLIKE 192.168.1.1-154) & (isSMTP | isPOP3 ) & (categoryName == 'Production')]]></rule>
In this example, instead of using the CDATA construct above, the ampersands are escaped as "&" (in bold and in blue):
<rule>(IPADDR != '0.0.0.0' & (IPADDR IPLIKE 192.168.1.1-154) & (isSMTP | isPOP3 ) & (categoryName == 'Production'))</rule>
For the GUI you simply drop in the unescaped value into the text field:
(IPADDR != '0.0.0.0' & (IPADDR IPLIKE 192.168.1.1-154) & (isSMTP | isPOP3 ) & (categoryName == 'Production'))
- catinc
Sometimes you need to include hosts belonging to more than one Category, via an AND operator. eg. All hosts that belong to BOTH Production and Linux groups need to be included. It is not currently possible to do this using any variation of eg. (categoryName == 'Production') & (categoryName == 'Linux').
The "catinc" function is used the following way. Note Category names can not have spaces for this to work:
<rule> <![CDATA[((IPADDR != '0.0.0.0') & catincProduction & catincLinux)]]> </rule>
New Pages