Get OpenNMS
Get Involved
Get to Know Us
From OpenNMS
Contents |
Introduction
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).
For LIKE comparisons, the character _ matches any single character and % matches any series of characters (or none at all). For example, 'F_o%' matches 'Foo', 'Foom' and 'Flowers' but not 'Foip'.
For handling NULL values (which includes cases where you've joined across to a table where there is no matching row), the IS NULL and IS NOT NULL operators can be used. It's important to note that comparing a null value to anything with any other operator always returns false, so
categoryName != 'SomeCategory'
will not return you anything with a null categoryName. Instead you probably need to use
categoryName != 'SomeCategory' | categoryName IS NULL
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.
Note: Depending on the format you use in your rules, you might need to escape your AND operator. See #The_different_rule_formats here under.
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.
List of possible parameters
Here is a partial list of the possible rule parameters. 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.
- Pollers
- dpNumber
- dpName
- dpIP
- dpComment
- dpDiscLimit
- dpAdminState
- dpRunState
- Nodes
- nodeID
- dpName
- nodeCreateTime
- nodeParentID
- nodeType
- nodeSysOID
- nodeSysName
- nodeSysDescription
- nodeSysLocation
- nodeSysContact
- nodeLabel
- Surveillance 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
The different rule formats
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>
