In opReports 34.0 the various methods for selecting what to report on have been consolidated and simplified.
This page describes what mechanisms are available, and how to control them in the GUI, with opreports-cli and for report schedules.
| Table of Contents |
|---|
Which selection mechanisms are supported by what report types?
Join Paul McClendon, an Opmantek Support Engineer, as he demonstrates quickly and easily you can generate reports using opReports.
...
| Report Type | Selection Mechanisms | Notes | |||||
|---|---|---|---|---|---|---|---|
| Node | single node only | The node report supports a single node only. If your selection contains more nodes, then the report is created for the first listed node. | |||||
| Node Health | all except node_gpon_port_list, interfaces irrelevant | Interface selections are not relevant for this report. | |||||
| Node Availability | all except node_gpon_port_list, interfaces irrelevant | Interface selections are not relevant for this report. | |||||
| Grouped (Node) Availability | all except node_gpon_port_list, interfaces irrelevant | Interface selections are not relevant for this report. | |||||
| WAN | all except node_gpon_port_list, interfaces ignored before 3.1.4 | Before version 3.1.4 the WAN report ignored interface selections. It operates on all active or any selected interfaces of the selected nodes whose net type is "wan". | |||||
| WAN Utilisation Distribution and WAN Utilisation Distribution Summary | all except node_gpon_port_list, new in opReports 3.1.8 | It operates on all active or any selected interfaces of the selected nodes whose net type is "wan". | |||||
| QoS | all except node_gpon_port_list, interfaces ignored before 3.1.4 | Before version 3.1.4 the QoS report ignored interface selections. It operates on all active or any selected interfaces of the selected nodes', if QoS is configured for the interface. | |||||
| CoS | all except node_gpon_port_list | For each selected node this report covers all active or any selected interfaces that have Class of Service configured. | |||||
| Uptime | all except node_gpon_port_list, interfaces irrelevant | Interface selections are not relevant for this report. | |||||
| Response Time | all except node_gpon_port_list, interfaces irrelevant | Interface selections are not relevant for this report. | |||||
| Interface Capacity | all except node_gpon_port_list | ||||||
| GPON Port Capacity | All active Nodes, | Grouped Interface Capacity | all new in opReports 34.12.82 | ||||
| Grouped Interface Utilisation | all | Interface selections are honored but the "type" component (in selections by node+interface+type) are ignored as not relevant. | Capacity | all except node_gpon_port_list | Interface Unicast Packets | all | |
| Interface Utilisation | all except node_gpon_port_list | Interface selections are honored but the "type" component (in selections by node+interface+type) are ignored as not relevant. | |||||
| CPU | all, interfaces irrelevant | Interface selections are not relevant for this report. | |||||
| Free Memory | all, interfaces irrelevant | Interface selections are not relevant for this report. | |||||
| Memory Pool | all, interfaces irrelevant | Interface selections are not relevant for this report. | |||||
| GPON Port Utilisation | All active Nodes, new in opReports 4.2.2 | ||||||
| Interface Unicast Packets | all except node_gpon_port_list | Interface selections are honored but the "type" component (in selections by node+interface+type) are ignored as not relevant. | |||||
| CPU | all except node_gpon_port_list, | Memory Buffer | all, interfaces irrelevant | Interface selections are not relevant for this report. | |||
| Monitored ServicesFree Memory | all except node_gpon_port_list, interfaces irrelevant | Interface selections are not relevant for this report. | |||||
| Traffic UsageMemory Pool | all, interfaces irrelevant | Interface selections are honored but the "type" component (in selections by node+interface+type) are ignored as not relevant. | |||||
| Traffic Summary | node+interface+type | This report strictly requires this specific selection format. | |||||
| Traffic Snapshot | opCharts Business Services, selected per page | This report type strictly requires lists of Business Services for each of its (multiple) page definitions. | |||||
| Configuration Summary | all, interfaces irrelevant | Interface selections are not relevant for this report |
Choosing the selection mechanism for scheduled reports
For scheduled reports your schedule must contain a property named sources, with one of the following values: "everything", "group_each_regexp", "group_regexp", "node_regexp", "node_group", "nodes", "node_list", "node_intf_list", "node_intf_type_list", or "business_services" (in 3.0.14 an newer). Those mechanisms are described below.
If you use the opReports schedule editing GUI then this property will be managed on your behalf.
The Simplest Choice: Everything
If you do not make an explicit selection, then opReports will work on all active nodes (and all their active interfaces, for report types that handle interfaces).
In the GUI this choice is shown as "All Active Nodes".
Nodes that belong to a specific group
In NMIS every node belongs to precisely one group, and this concept therefore applies to opReports as well.
With opreport-cli you have to give the argument group=<groupname>. In a report schedule this is expressed using the property node_group. In the GUI this choice is presented as "by Group".
There are two "wildcard" groups available:
- Group "All" is equivalent to the default choice, all active nodes. This wildcard should not be used as we will likely retire it in a future version of opReports.
- Group "Each" is available for scheduled reports only, excluding 'once only' scheduled reports, and causes the generation of a separate report for each of the known groups.
Nodes whose name matches a regular expression
In the GUI this choice is called "by Regular Expression for Nodes", opreports-cli uses the command line argument node_regexp=<regular expression>, and for scheduled reports you'd specify this with the property node_regexp.
The node regular expression is evaluated at report creation time.
The regular expression syntax is Perl's standard, described in detail in this Perl Regexp Tutorial.
Nodes and Interfaces whose names/descriptions match regular expressions
This feature was added to opReports in version 3.1.4.
Nodes must match the regular expression given for the node name, but interface descriptions must also match a separate regular expression.
Only those interfaces are selected where both regular expressions match.
However, for reports where interfaces are not relevant, interfaces are disregarded.
The regular expression for interfaces is applied to both the interface's ifDescr and Description properties in parallel, and a match for either or both selects the interface.
(The NMIS GUI presents ifDescr as "Name" or "Name (ifDescr)". Depending on the device and its modelling ifDescr may or may not be adjustable, but Description can be set easily within NMIS.)
In the GUI this option is called "by Regular Expression for Nodes and Interfaces".
opreports-cli requires that you supply both node_regexp=<regular expression> and node_intf_regexp=<regular expression> arguments.
The report schedules use the same property names as the opreports-cli parameters.
Both regular expressions are evaluated at report creation time.
Groups, Nodes and Interfaces whose names/descriptions match regular expressions
This feature was added to opReports in version 3.1.8.
...
| not relevant for this report. | ||
| Memory Buffer | all except node_gpon_port_list, interfaces irrelevant | Interface selections are not relevant for this report. |
| Monitored Services | all except node_gpon_port_list, interfaces irrelevant | Interface selections are not relevant for this report. |
Traffic Usage | all except node_gpon_port_list | Interface selections are honored but the "type" component (in selections by node+interface+type) are ignored as not relevant. |
| GPON Port User Traffic | All active Nodes Pick from Node List, new in opReports 4.2.2 | |
| Traffic Summary | node+interface+type | This report strictly requires this specific selection format. |
| Traffic Snapshot | opCharts Business Services, selected per page | This report type strictly requires lists of Business Services for each of its (multiple) page definitions. |
| Configuration Summary | all except node_gpon_port_list, interfaces irrelevant | Interface selections are not relevant for this report |
Choosing the selection mechanism for scheduled reports
For scheduled reports your schedule must contain a property named sources, with one of the following values: "everything", "group_each_regexp", "group_regexp", "node_regexp", "node_group", "nodes", "node_list", "node_intf_list", "node_intf_type_list", or "business_services" (in 3.0.14 an newer). Those mechanisms are described below.
If you use the opReports schedule editing GUI then this property will be managed on your behalf.
The Simplest Choice: Everything
If you do not make an explicit selection, then opReports will work on all active nodes (and all their active interfaces, for report types that handle interfaces).
In the GUI this choice is shown as "All Active Nodes".
Nodes that belong to a specific group
In NMIS every node belongs to precisely one group, and this concept therefore applies to opReports as well.
With opreport-cli you have to give the argument group=<groupname>. In a report schedule this is expressed using the property node_group. In the GUI this choice is presented as "by Group".
There are two "wildcard" groups available:
- Group "All" is equivalent to the default choice, all active nodes. This wildcard should not be used as we will likely retire it in a future version of opReports.
- Group "Each" is available for scheduled reports only, excluding 'once only' scheduled reports, and causes the generation of a separate report for each of the known groups.
Nodes whose name matches a regular expression
In the GUI this choice is called "by Regular Expression for Nodes", opreports-cli uses the command line argument node_regexp=<regular expression>, and for scheduled reports you'd specify this with the property node_regexp.
The node regular expression is evaluated at report creation time.
The regular expression syntax is Perl's standard, described in detail in this Perl Regexp Tutorial.
Nodes and Interfaces whose names/descriptions match regular expressions
This feature was added to opReports in version 3.1.4.
Nodes must match the regular expression given for the node name, but interface descriptions must also match a separate regular expression.
Only those interfaces are selected where both regular expressions match.
However, for reports where interfaces are not relevant, interfaces are disregarded.
The regular expression for interfaces is applied to both the interface's ifDescr and Description properties in parallel, and a match for either or both selects the interface.
(The NMIS GUI presents ifDescr as "Name" or "Name (ifDescr)". Depending on the device and its modelling ifDescr may or may not be adjustable, but Description can be set easily within NMIS.)
In the GUI this option is called "by Regular Expression for Nodes and Interfaces".
opreports-cli requires that you supply both node_regexp=<regular expression> and node_intf_regexp=<regular expression> arguments.
The report schedules use the same property names as the opreports-cli parameters.
Both regular expressions are evaluated at report creation time.
Groups, Nodes and Interfaces whose names/descriptions match regular expressions
This feature was added to opReports in version 3.1.8.
Groups must match the regular expression given for the group name AND
Nodes must match the regular expression given for the node name AND
Interface descriptions must also match a separate regular expression.
Only those interfaces are selected where all three regular expressions match.
However, for reports where interfaces are not relevant, interfaces are disregarded.
The regular expression for interfaces is applied to both the interface's ifDescr and Description properties in parallel, and a match for either or both selects the interface.
(The NMIS GUI presents ifDescr as "Name" or "Name (ifDescr)". Depending on the device and its modelling ifDescr may or may not be adjustable, but Description can be set easily within NMIS.)
In the GUI this option is called "by Regular Expression for Groups Nodes and Interfaces".
opreports-cli requires that you supply group_regexp=<regular expression> AND node_regexp=<regular expression> AND node_intf_regexp=<regular expression> arguments.
The report schedules use the same property names as the opreports-cli parameters.
All three regular expressions are evaluated at report creation time.
Groups, Nodes and Interfaces whose names/descriptions match regular expressions for separate report for each group
This feature was added to opReports in version 3.1.8.
This option causes the generation of a separate report for each of the known groups.
This option is available for scheduled reports only, excluding 'once only' scheduled reports.
Groups must match the regular expression given for the group name AND
Nodes must match the regular expression given for the node name AND
Interface descriptions must also match a separate regular expression.
Only those interfaces are selected where all three regular expressions match.
However, for reports where interfaces are not relevant, interfaces are disregarded.
The regular expression for interfaces is applied to both the interface's ifDescr and Description properties in parallel, and a match for either or both selects the interface.
(The NMIS GUI presents ifDescr as "Name" or "Name (ifDescr)". Depending on the device and its modelling ifDescr may or may not be adjustable, but Description can be set easily within NMIS.)
In the GUI this option is called "by Regular Expression for a Nodes and Interfaces Report per Group".
The report schedules requires that you supply group_each_regexp=<regular expression> AND node_regexp=<regular expression> AND node_intf_regexp=<regular expression>.
All three regular expressions are evaluated at report creation time.
Explicitly listed Nodes
In the GUI this choice is called "Pick from Node List".
To use this mechanism with opreports-cli, you have to list each node you want in a separate nodes=<nodename> argument.
In a report schedule the property nodes would have to be set to an array of node names, like in this example:
| Code Block |
|---|
"nodes" : [
"ASGARD",
"midgard"
], |
Nodes listed in a file
opReports expects a node list file to contain one node name per line. Whitespace before or after the node name is removed.
In the GUI this choice is called "from Node List File (Upload)", and you need to select a suitable file for uploading.
For opreports-cli, the command line argument node_list=<path to node list file> would be used. In that case the node list file must already reside on the opReports server.
In a report schedule definition, you'd use the property node_list, with the path to the list file as value:
| Code Block |
|---|
"node_list" : "/tmp/my_list_of_lotsa_nodes.txt" |
Nodes and specific Interfaces, listed in a file
Certain reports allow a more precise selection of nodes and just some of their interfaces. This is implemented using a list file.
In the GUI you'd select "from Node and Interfaces List File (Upload)" and upload the file of choice. For opreports-cli you use node_intf_list=<path to listfile>, and for a scheduled report you would set the property node_intf_list with the value being the path to the list file.
The node and interface list can be in one of two formats, JSON or plain text:
JSON: it must be a valid JSON document, consisting of a hash of the node name as key, and the value being a list of the interfaces in question.
Code Block { "testnode": [ "eth0" ], "othernode" : [ 1, 2, "Tunnel20" ] }
Plain Text: a text file, one entry per line.
Each entry must start with the node name, followed by one or more TAB characters, and one or more interfaces (again separated by TAB characters). If you list a node on multiple lines then all listed interfaces will be combined into a single list. Blank lines and lines starting with the "#" sign are treated as comments and are ignored.Code Block testnode 2 14 eth0 othernode Dialer1 testnode 17
For both JSON and Plain Text formats, interfaces can be identified by the numeric SNMP interface index, or by the SNMP ifDescr property.
Nodes, specific Interfaces and Types, listed in a file
| Note |
|---|
Careful not to confuse this option with 'Nodes and specific Interfaces, listed in a file' described above. If the 'Type' option is not necessary this is not the appropriate feature. |
Certain reports offer a refinement of the above, with the added notion of a "Type" for grouping of Node+Interface into particular reporting classes.
| Info |
|---|
"Type" is completely arbitrary. This value can be anything the user would like. This value is not referenced anywhere else in opReports or any other OMK application. |
This is implemented again using a list file, but with a very specific format - which has a few inherent limitations; Starting with version 3.0.16, opReports also supports CSV as format for this type of input.
The relevant GUI choice is called "from Node, Interfaces and Type List File (Upload)", for opreports-cli the parameter is node_intf_type_list=<path to listfile>, and in a report schedule the controlling property is node_intf_type_list (value again the path to the list file).
Nodes and specific GPON Ports, listed in a file
Certain GPON Port
The regular expression for interfaces is applied to both the interface's ifDescr and Description properties in parallel, and a match for either or both selects the interface.
(The NMIS GUI presents ifDescr as "Name" or "Name (ifDescr)". Depending on the device and its modelling ifDescr may or may not be adjustable, but Description can be set easily within NMIS.)
In the GUI this option is called "by Regular Expression for Groups Nodes and Interfaces".
opreports-cli requires that you supply group_regexp=<regular expression> AND node_regexp=<regular expression> AND node_intf_regexp=<regular expression> arguments.
The report schedules use the same property names as the opreports-cli parameters.
All three regular expressions are evaluated at report creation time.
Groups, Nodes and Interfaces whose names/descriptions match regular expressions for separate report for each group
This feature was added to opReports in version 3.1.8.
This option causes the generation of a separate report for each of the known groups.
This option is available for scheduled reports only, excluding 'once only' scheduled reports.
...
The regular expression for interfaces is applied to both the interface's ifDescr and Description properties in parallel, and a match for either or both selects the interface.
(The NMIS GUI presents ifDescr as "Name" or "Name (ifDescr)". Depending on the device and its modelling ifDescr may or may not be adjustable, but Description can be set easily within NMIS.)
In the GUI this option is called "by Regular Expression for a Nodes and Interfaces Report per Group".
The report schedules requires that you supply group_each_regexp=<regular expression> AND node_regexp=<regular expression> AND node_intf_regexp=<regular expression>.
All three regular expressions are evaluated at report creation time.
Explicitly listed Nodes
In the GUI this choice is called "Pick from Node List".
To use this mechanism with opreports-cli, you have to list each node you want in a separate nodes=<nodename> argument.
In a report schedule the property nodes would have to be set to an array of node names, like in this example:
| Code Block |
|---|
"nodes" : [
"ASGARD",
"midgard"
], |
Nodes listed in a file
opReports expects a node list file to contain one node name per line. Whitespace before or after the node name is removed.
In the GUI this choice is called "from Node List File (Upload)", and you need to select a suitable file for uploading.
For opreports-cli, the command line argument node_list=<path to node list file> would be used. In that case the node list file must already reside on the opReports server.
In a report schedule definition, you'd use the property node_list, with the path to the list file as value:
| Code Block |
|---|
"node_list" : "/tmp/my_list_of_lotsa_nodes.txt" |
Nodes and specific Interfaces, listed in a file
Certain reports allow a more precise selection of nodes and just some of their interfaces. This is implemented using a list file.
In the GUI you'd select "from Node and Interfaces GPON Port List File (Upload)" and upload the file of choice. For opreports-cli you use node_gpon_intfport_list=<path to listfile>, and for a scheduled report you would set the property node_gpon_intfport_list with the value being the path to the list file.
The node Node and interface GPON Port list can be in one of two three formats, JSON or , plain text (tab delimited) or CSV (comma delimited):
JSON: it must be a valid JSON document, consisting of a hash of the node name as key, and the value being a list of the interfaces in question.
Code Block { "testnode": [ "eth0" ], "othernode" : [ 1, 2, "Tunnel20" ] }
Plain Text: a text file, one entry per line.
Each entry must start with the node name, followed by one or more TAB characters, and one or more interfaces (again separated by TAB characters). If you list a node on multiple lines then all listed interfaces will be combined into a single list.
Blank lines and lines starting with the "#" sign are treated as comments and are ignored.Code Block testnode 2 14 eth0 othernode Dialer1 testnode 17
For both JSON and Plain Text formats, interfaces can be identified by the numeric SNMP interface index, or by the SNMP ifDescr property.
Nodes, specific Interfaces and Types, listed in a file
| Note |
|---|
Careful not to confuse this option with 'Nodes and specific Interfaces, listed in a file' described above. If the 'Type' option is not necessary this is not the appropriate feature. |
Certain reports offer a refinement of the above, with the added notion of a "Type" for grouping of Node+Interface into particular reporting classes.
| Info |
|---|
"Type" is completely arbitrary. This value can be anything the user would like. This value is not referenced anywhere else in opReports or any other OMK application. |
This is implemented again using a list file, but with a very specific format - which has a few inherent limitations; Starting with version 3.0.16, opReports also supports CSV as format for this type of input.
Dialer1 testnode 17CSV: a csv file, one entry per line.
Each entry must start with the node name, followed by one COMMA character, and one or more GPON Ports (again separated by COMMA characters).
Blank lines and lines starting with the "#" sign are treated as comments and are ignored.Code Block testnode,2,14,"Service_Port 1/0/9" othernode,"Service_Port 5/0/12" testnode,17
For JSON, Plain Text and CSV formats, GPON Ports can be identified by the numeric SNMP PORT index, or by the SNMP ONTBASE propertyThe relevant GUI choice is called "from Node, Interfaces and Type List File (Upload)", for opreports-cli the parameter is node_intf_type_list=<path to listfile>, and in a report schedule the controlling property is node_intf_type_list (value again the path to the list file).
Plain Text Format
Please note: as of version 3.0.16 it's recommended that you use CSV as a safer alternative to this format.
...
The "type" will be used to group all nodes and interfaces with the same type value into a group for summary reporting.
CSV Format (3.0.16 and newer)
opReports now also supports CSV (with comma as the separator character) for this kind of input.
The lines in your file must contain at least the following four columns, in the following order:
...
| Code Block |
|---|
# comment, ignored. columns: nodename,interface index,interface description,type name "some node","1","FastEthernet0/0","categoryA" "not_the_greatest_name","10","Dialer1","catB" "pleasefindme",,"Dialer1194","categoryA" "iknowtheindex",12,,"catB" |
Nodes and Interfaces that are part of an opCharts Business Service
If you have opReports version 3.0.14 and newer and opCharts is installed on the same system, then you can make use of Business Services to declare nodes and interfaces for reporting.
Configuration
The following three configuration options (in conf/opCommon.nmis) are vital for opReports accessing opCharts:
...
If you've changed the password for the default nmis user (or disabled it altogether), then these configuration items need to be adjusted accordingly.
Once that's done you need to restart the OMK webserver (using sudo service omkd restart) to activate the changed configuration.
Usage
In the GUI you will be presented with a list of known Business Service names, which supports multiple selections.
...