In opReports 3.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.

The Default 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 interfaced).

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, 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", opreports-cli uses the command line argument noderegex=<regular expression>, and for scheduled reports you'd specify this with the property  node_regexp.

The regular expression syntax is Perl's standard, described in detail in this Perl Regexp Tutorial.

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:

"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:

"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.

   

  { "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.

  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

Certain reports offer a refinement of the above, with the added notion of a "Type" for grouping of Node+Interface into particular reporting classes.

This is implemented again using a list file, but  with a very specific format. 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).

The list file format is plain text, and each line must consist of precisely one node name, one of its interfaces and a "type" declaration. The interface must be identified by its SNMP Interface Index.

Node name and interface must be separated by "_", and this must be separated by the "type" by one or more spaces, like in the example below:

nodeA_1 groupA
nodeB_41 groupB
nodeC_41_eth0 groupB

The example also shows an optional format variant: the node+interface stanca may include a trailing "_<ifdescr>".  It is recommended that you do not use this flavour as it's ambiguous: interface descriptions can (and often do) include both _ and space characters.

The "type" will be used to group all nodes and interfaces with the same type value into a group for summary reporting.

Providing more precision than necessary is allowed

You can use a node and interfaces (and even types) list file for all reports; for reports where interfaces are not relevant, the extra information will simply be discarded and the listed nodes will be used. Reports that don't need the summary type will simply use the nodes (and possibly the interfaces).

Providing insufficiently precise information to reports that require it will result in an error message (e.g. trying to run a summary report with just group=X).

Order of Precedence

If you happen to provide multiple (conflicting) selection criteria, here is how opReports handles such:

• The first type of selection that is found becomes the sole source of information.
• All other selections are ignored.
• The order of checking selections is: node regexp, explicit list of nodes, group name, node list file, node + interface list file, node + interface + type list file.