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:
- Retrieve devices from Open-AudIT.
- Create a node file suitable for passing into node_admin.pl.
- Create a new node if one does not exist, or update an existing node if it does.
- Update the mapping of Open-AudIT devices to NMIS nodes.
- 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',
'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',
'open_audit_query_ids' => [60, 77],
);
| Key | Type | Description |
|---|---|---|
| log_path | A string representing either a fully-qualified path, or a path relative to the integration's execution. | The path for the integration log. This log will contain a summary of actions that are taken for each integration, including system calls to node_admin.pl. |
| node_admin_path | A string representing either a fully-qualified path, or a path relative to the integration's execution. | The path to the executable for the node admin tool. All interactions with NMIS are controlled via the node admin tool. |
| integration_rules_path | A string representing either a fully-qualified path, or a path relative to the integration's execution. | The path to the rules file for the integration. The rules file defines how values from Open-AudIT devices should translate into NMIS nodes. It is recommended to give this file a .nmis extension, as it is written in the .nmis format. |
| open_audit_lookup_path | A string representing either a fully-qualified path, or a path relative to the integration's execution. | The path to the lookup file for the integration. The lookup file stores mappings between Open-AudIT devices and NMIS nodes. It is recommended to give this file a .nmis extension, as it is written in the .nmis format. |
| open_audit_query_ids | An array of integers. OR An array of integers and strings. (Open-AudIT 3.0.0+ only.) | The ID/s of the Open-AudIT queries to be used for this integration. See the section about Open-AudIT queries for more. If using Open-AudIT 3.0.0 or greater, you may also specify query names as well as IDs. For example, this value could be 'open_audit_query_ids' => ['centos_query', 11, 63, 'extra query name'], |
| open_audit_details.host | A string representing a URL. | The Open-AudIT server you wish to target for the integration. This should include the protocol, but should NOT include any path. |
| open_audit_details.user | A string. | The username of the Open-AudIT user the integration will run under. You should ensure the chosen user has access to all the devices you wish to integration with NMIS. |
| open_audit_details.password | A string. | The password of the Open-AudIT user. |
| open_audit_details.log_path | A string representing either a fully-qualified path, or a path relative to the integration's execution. | The path to the Open-AudIT log. This log will contain records of all the requests that are made to the Open-AudIT server (excluding authentication requests). |
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.
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' => {
# name will resolve to the 'name' field in the device if it exists, or
# an empty string otherwise.
'name' => ['$DEVICE.name'],
# 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 use default values when any new node is created.
'active' => ['true'],
'ping' => ['true'],
'model' => ['automatic'],
},
# Only the node fields defined here will be considered for an update.
'update' => {
'roleType' => ['$DEVICE.nmis_role', 'core'],
'group' => ['$DEVICE.nmis_group', 'Open-AudIT'],
}
}
);
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.
The rest of the integration is completely driven by the options set in the configuration file.
# 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