OpenAudIT-NMIS Integration

Open-AudIT Queries

The integration leverages Open-AudIT's query feature as a way of controlling the devices you want to integrate with NMIS. You can read about Open-AudIT queries in detail here.

Integration Description

An integration run has the following steps:

1. Retrieve devices from Open-AudIT.
2. Create a node file suitable for passing into node_admin.pl.
3. Create a new node if one does not exist, or update an existing node if it does.
4. Update the mapping of Open-AudIT devices to NMIS nodes.
5. Update the device on the Open-AudIT server if necessary.

Configuration

The following is a sample configuration file for the integration. The configuration is written in the .nmis format common to other Opmantek products.

%hash = (
  'log_path' => 'log/nmisintegration.log',
  'node_admin_path' => '/usr/local/nmis/admin/node_admin.pl',
  'node_file_path' => '/usr/local/nmis/conf/Nodes.nmis',
  'open_audit_details' => {
    'host' => 'https://demo.opmantek.com',
    'log_path' => 'log/openauditapi.log',
    'password' => 'OA_password',
    'user' => 'OA_user'
  },
  'open_audit_lookup_path' => 'conf/oa_nmis_lookup.nmis',
  'integration_rules_path' => 'conf/integration_rules.nmis',
  'open_audit_query_ids' => [60, 77],
);

'open_audit_query_ids' => ['centos_query', 11, 63, 'extra query name'],

Integration Rules

The rules file defines how values from Open-AudIT devices should translate into NMIS nodes. The configuration is written in the .nmis format common to other Opmantek products.

Within the rules file, you define NMIS fields and give them a list of candidate values (a ruleset). These values can be either constants (strings), or they can refer to fields from the device itself. The integration will use the first value it can resolve, or the empty string if it cannot resolve any values.

To refer to fields from the device, use the format $DEVICE.fieldname.

There is also the option to provide pre-built transformations to fields that apply after they are resolved.

An example rules file is provided below, along with an explanation of how the rulesets might resolve.

 %hash = (
  'nmis' => {

    # Different rules can be defined for when an NMIS node is created and when
    # it is updated. This lets you avoid overwriting values the you edit in NMIS.
    'create' => {

      # version will resolve to the 'os_version' field in the device if it exists, or
      # an empty string otherwise.
      'version' => ['$DEVICE.os_version'],

      # roleType and group try to use a value from the device if it exists, but
      # will fall back to a constant if it does not.
      'roleType' => ['$DEVICE.nmis_role', 'core'],
      'group' => ['$DEVICE.nmis_group', 'Open-AudIT'],

      # host checks multiple fields from the device, choosing the first one
      # that has a value (or the empty string if no values are found).
      'host' => ['$DEVICE.ip', '$DEVICE.hostname','$DEVICE.dns_hostname', '$DEVICE.fqdn'],

      # active, ping, and model just use a default value when any new node is created.
      'active' => ['true'],
      'ping' => ['true'],
      'model' => ['automatic'],
 
      # name uses an array of candidates like all the other fields, but it also applies
      # a set of transform functions after a candidate is chosen.
      'name' => {
        'candidates' => ['$DEVICE.name'],
        'transforms' => ['trim_whitespace'],
      }
    },

    # Only the node fields defined here will be considered for an update.
    'update' => {

      'roleType' => ['$DEVICE.nmis_role', 'core'],
      'group' => ['$DEVICE.nmis_group', 'Open-AudIT'],

    }
  }
);

Transform functions

Transform functions provide additional functionality by transforming fields in some predefined way. If an invalid transform function is provided, the integration will fail. A list of valid transform functions are listed below.

Usage

To run the integration, simply invoke the executable and pass it a configuration file as described in the previous section. You can also invoke the tool by itself, which will look for a configuration file at conf/nmisIntegration.nmis by default.

While most of the integration is driven by the options set in the configuration file, additional options can be passed at runtime. These options can be seen in the usage instructions for the integration script.

# Calling the tool with a custom-named configuration file
./bin/oa_nmis_integration.pl conf=conf/my_custom_config.nmis
 
# Calling the tool by itself (uses conf/nmisIntegration.nmis)
./bin/oa_nmis_integration.pl
 
# Show the usage instructions
./bin/oa_nmis_integration.pl -h

Special Cases

This section documents the behaviour that can be expected from the integration in special cases such as a node being deleted from one system or another.

Call to node admin tool to create new node snorri failed with errmsg: Node snorri already exist.