...

How to filter or transform configuration data

TBD - just return new data, show example

Example Filtering Plugin

How to raise alerts and open (or close) NMIS events with a plugin

TBD - return alerts, point to values

Example Alerting Plugin

How to use a plugin to prepare derived information (or knowledge) for opConfig

TBD - what is this all about

Example Plugin

Plugin Input Argument Structures

node_info

contains the same data that you get when running ./bin/opnode_admin.pl act=export node=XYZ, ie. the node's configuration, connection information and os information.

credential_set

holds the credential set details that was configured for this node.
The credential set structure carries the same properties as the  credential set editing gui screen, with the following keys:

• username (always present),
•  password (may be empty if ssh_key is given)
•  password_privileged (may be empty if always_privileged is 1)
• ssh_key (may be empty or holds an ssh private key in the typical openssh format, e.g. "-----BEGIN RSA PRIVATE KEY-----...keymaterial....")
• setname and description
• always_privileged (0 or 1, if 1 password_privileged is ignored)

command

contains the command in question, plus some meta data.

This is structured similar to the command set definition, but with some extended or expanded properties:

• all settings that are inheritable from per-set scheduling_info are expanded,
•  the property command_set holds the name of the command set this came from.

logger

refers to an OMK::Log instance, a subclass of Mojo::Log.

you can use the following methods to log information, in order of severity: fatal error warn info debug (and debug2 to debug9).

your information is logged if the global verbosity level is at least as verbose as your chosen method. opConfig's default level is 'info'. e.g. $logger->warn("this is pretty bad")

will very likely end up in the opConfig log, while $logger->debug5("nuisance") will almost certainly be suppressed.

opconfig

refers to an OMK::opConfig instance, which can be used to schedule command execution, retrieve other command revisions and the like.

please consult the opConfig API documentation at FIXME/TBA for details.

Plugin Response/Result Structures

alerts

must be a hashref if present. In the simplest case, the key is the alert/event name, and the value is 0 or 1. In this case opConfig raises (value 1) or closes (value 0) an event with the given event name for the current node.

As an alternative, the value may be a hash with any of the following keys instead of 0/1:

• event: event name (default: the alerts key is used)
• upevent: event name for closing the event (default: NMIS derives that from the event name)
• element: what element the event is associated with, optional
• node: the name of the node the event should be associated with (default: current node)
• level: one of Normal, Warning, Minor, Major Critical or Fatal.
  Normal closes the alert/event, all others raise.
• details: extra information to attach to the event, optional

conditions

must be a hashref if present, and must be two levels deep.

The outer key is not displayed by opConfig at this time but  separates conditions signalled by different plugins, so we recommend  that each plugin picks a unique outer key.
The data structure behind that outer key must be a hashref again.

Its key must be he name of the condition that is to be signalled,  and the value must be one of 0, 1 or undef. 
0 means a bad state for this condition, 1 means a good state for the condition, undef signals that the state of this condition is not known.

derived_info

must be a hashref if present, and can have any depth.

Like for conditions and alerts, the outer key is used to separate information reported by different plugins (or different kinds of information);  a suitably unique key needs to be chosen.

The following keys have special meaning and should not be used for other purposes in your inner datastructure: type, tag, value, title, labels, rows.

All derived_info data is stored, but at this time the opConfig gui will only display derived info entries whose inner structure conforms to the following layout:

...

Your plugin must provide a process_configuration function that works on the given configuration_data argument and returns a modified version of that.
No other responses are required, but of course your plugin may also choose to report conditions, raise alerts or produce derived information at the same time.
Note that for single-line filtering no plugin is required, because opConfig command sets already allow you to specify single-line regular expressions for ignoring irrelevant lines.

Example Filtering Plugin

This example plugin removes PEM encoded private key material from the command output and replaces all of these keys with "<key omitted>".

package FilterKey;
our $VERSION = "0.0.0";
use strict;
# replace any PEM private key info in the data with '<key omitted>'
sub process_configuration
{
    my (%args) = @_;
    my ($node, $node_info, $command, $configuration_data, 
            $derived, $alerts, $conditions, $logger, $opconfig)
            = @args{qw(node node_info command configuration_data 
                derived_info alerts conditions logger opconfig)};
    my $filtered = $configuration_data;
    $filtered 
            =~ s/-----BEGIN \S+ PRIVATE KEY-----.+?-----END \S+ PRIVATE KEY-----/\n<key omitted>\n/sg;
    return { success => 1,
             configuration_data => $filtered };
}
1;

How to raise alerts and open (or close) NMIS events with a plugin

To programmatically raise or close alerts with a plugin, your plugin must provide a process_configuration function that returns a list of alerts to raise or close in the alerts return value.
Your plugin may also perform filtering or condition reporting at the same time.

The alerts response structure must be a hashref if it is present at all.
In the simplest case, the key is the alert/event name, and the value is 0 or 1. In this case opConfig raises (value 1) or closes (value 0) an event in NMIS with the given event name and for the current node.

As a more precise alternative, the value may be a hash with the following supported keys:

• event: event name (default: the alerts key is used)
• upevent: event name for closing the event (default: NMIS derives that from the event name)
• element: what element the event is associated with, optional
• node: the name of the node the event should be associated with (default: current node)
• level: must be one of Normal, Warning, Minor, Major Critical or Fatal.
  Normal closes the alert/event, all others raise the event. If not present, the default level "Major" is used.
• details: extra information to attach to the event, optional

Example Alerting Plugin

This example plugin shows the different supported formats for alert handling:

package RaiseAlerts;
our $VERSION = "0.0.0";
use strict;
sub process_configuration
{
    my (%args) = @_;
    my ($node, $node_info, $command, $configuration_data, 
            $derived, $alerts, $conditions, $logger, $opconfig)
            = @args{qw(node node_info command configuration_data 
derived_info alerts conditions logger opconfig)};
    # ...insert logic that looks at context of command, configuration_data, node etc
    # to determine what alerts to raise
    
    return { success => 1,
             alerts => { 
               "Node Unhappy" => 1, # raise event
               "Node Unreachable" => 0, # clear event
               elsewhere => { event => "Node Not Cooperating", 
                              node => "some_other_node",
                              details => "this alert applies to another node",
                              level => "Minor", },
             },
    };
}
1;

How to use a plugin to report conditions to opConfig

A plugin can report named conditions to opConfig, which will be stored and displayed with the command in question. In opConfig a condition has a name and a ternary logic value (true, false, unknown).
Like before the plugin may also perform filtering or alert raising operations at the same  time.

To report conditions the plugin must provide a process_configuration function that returns a conditions return value which must be a (two levels deep) hashref if present.

The outer key is not displayed by opConfig at this time but  separates conditions signalled by different plugins, so we recommend  that each plugin picks a unique outer key.
The data structure behind that outer key must be a hashref again.

The inner hashref's key must be he name of the condition that is to be signalled,  and the value must be one of 0, 1 or undef. 
0 means a bad state for this condition, 1 means a good state for the condition, undef signals that the state of this condition is not known.

Example Plugin

The following small example plugin reports some conditions, using its plugin package name as the separating key:

package ReportConditions;
our $VERSION = "0.0.0";
use strict;
sub process_configuration
{
    my (%args) = @_;
    my ($node, $node_info, $command, $configuration_data, 
            $derived, $alerts, $conditions, $logger, $opconfig)
            = @args{qw(node node_info command configuration_data 
derived_info alerts conditions logger opconfig)};
    # ...insert logic that looks at context of command, configuration_data, node etc
    # to determine what conditions and states these imply
    
    return { success => 1,
             conditions => { 
               "ReportConditions" => {
                  "node is lacking something" => 0,
                  "command implies something is in good shape" => 1,
                  "something unexpectedly couldn't be analysed" => undef,
               },
             },
           };
}
1;

How to use a plugin to prepare derived information (or knowledge) for opConfig

A plugin may report extracted 'knowledge', information that it derived from the configuration data, to opConfig for display and storage.
To do so, the plugin must have a process_configuration function that returns a derived_info response.

The derived_info response structure must be a hashref if it is present, and can have any depth.
The outer key is used to separate information reported by different plugins (or different kinds of information); a suitably unique key needs to be chosen by the plugin author.

The following keys have special meaning and should not be used for other purposes in your inner datastructure: type, tag, value, title, labels, rows.

All derived_info data is stored by opConfig, but at this time the opConfig gui will only display derived info entries whose inner structure conforms to the following layout:

• property 'type' must be set to 'table',
• property 'labels' must be an array whose elements are displayed as column headings (setting a label to undef causes this column to be skipped in the display),
• property 'rows' must be an array of arrays whose elements are to be shown as table.
• property 'title' may be set but is optional.

Example Plugin

The following example plugin produces two tabular instances of derived information, which will be displayed by the opConfig GUI, and further example data which will be stored but not displayed.

package DerivedInfo;
our $VERSION = "0.0.0";
use strict;
sub process_configuration
{
    my (%args) = @_;
    my ($node, $node_info, $command, $configuration_data, 
            $derived, $alerts, $conditions, $logger, $opconfig)
            = @args{qw(node node_info command configuration_data 
              derived_info alerts conditions logger opconfig)};
    # ...insert logic that derives knowledge from the context
    
    return { success => 1,
             derived_info => {
                     
               some_reportable_thing =>
               {
                 type => "table",
                 title => "Reported by ".__PACKAGE__,
                 labels => [ 'one col', 'another col', ],
                 rows => [ [ 'maybe key', 'maybe value', ],
                           [ 'maybe key2', 'maybe value', ],
                           [ 'last row', 'last value', ],
                         ],
               },
               my_filtered_table => {
                 type => 'table',
                 labels => [ 'first col', 'second', undef, 'and at long last' ],
                 rows => [ 
                           [ 'note that', 'there is', 'a gap', 'something that you were not meant to see' ],
                           [ 1, 2, 3, 4, ],
                         ],
               },
                         
               ours_but_not_displayed =>
               {
                 doesnt_display => "whatever",
                 stored =>  [ 4, 7, 29 ],
                 deep_is_ok => { other => { thing => [ 1..10 ],  } },
               },
             },
    };
}
1;

Plugin Input Argument Structures

node_info

contains the same data that you get when running ./bin/opnode_admin.pl act=export node=XYZ, ie. the node's configuration, connection information and os information.

credential_set

holds the credential set details that was configured for this node.
The credential set structure carries the same properties as the  credential set editing gui screen, with the following keys:

• username (always present),
•  password (may be empty if ssh_key is given)
•  password_privileged (may be empty if always_privileged is 1)
• ssh_key (may be empty or holds an ssh private key in the typical openssh format, e.g. "-----BEGIN RSA PRIVATE KEY-----...keymaterial....")
• setname and description
• always_privileged (0 or 1, if 1 password_privileged is ignored)

command

contains the command in question, plus some meta data.

This is structured similar to the command set definition, but with some extended or expanded properties:

• all settings that are inheritable from per-set scheduling_info are expanded,
•  the property command_set holds the name of the command set this came from.

logger

refers to an OMK::Log instance, a subclass of Mojo::Log.

you can use the following methods to log information, in order of severity: fatal error warn info debug (and debug2 to debug9).

your information is logged if the global verbosity level is at least as verbose as your chosen method. opConfig's default level is 'info'. e.g. $logger->warn("this is pretty bad")

will very likely end up in the opConfig log, while $logger->debug5("nuisance") will almost certainly be suppressed.

opconfig

refers to an OMK::opConfig instance, which can be used to schedule command execution, retrieve other command revisions and the like.

please consult the opConfig API documentation at TBA for details

...

.