Itential Docs & Guides | Drive Automation for Modern Networks

This guide covers Itential Automation Platform (IAP) configurations along with several common adapter configurations. For more detailed information regarding each adapter's configurable properties, refer to the documentation for that adapter.

Configuration File

The main IAP configuration file is located at /opt/pronghorn/current/properties.json.

The properties.json file contains global configurations. Several adapter-specific configurations must also be integrated into various systems within the customer environment (i.e., LDAP, NSO, etc.).

Encrypting Passwords

The properties.json file will likely contain passwords. As a best practice, use the rule of least privilege any time this file is managed.

Set the file system permissions to user-read.

chmod 0600 /opt/pronghorn/current/properties.json

Change to the following directory.

/opt/pronghorn/current/node_modules/@itential/pronghorn-core/utils

Use the IAP encrypt tool to encrypt sensitive passwords before saving them in the properties.json file.
```
$ node encrypt.js password
Encrypted Password: $ENC93eb9439537ae34196db49409dd0261a8b87218fafd0419
```
Note: The encrypt.js tool will respond with a string that starts with $ENC. Use this string when configuring passwords in the properties.json file.

Store the entire string below in the properties.json file without exposing the password.

"mongoProps": {
    "db": "pronghorn",
    "url": "mongodb://localhost:27017",
    "credentials": {
        "dbAuth": true,
        "user": "pronghorn",
        "passwd": "$ENC82ee8a234a69f15bdb8e05409cda2418878b2f85af"
    }
}

Alternatively, use the Vault Encryption feature. See the HashiCorp Vault Encryption guide to learn more.

Configuration Properties

Configuration properties for IAP are summarized below. Much of the configuration occurs within Admin Essentials→Profiles but other configuration occurs in the various Admin Essentials→Service Config interfaces and within the properties.json file.

Profile Properties

The following properties are configured within the Admin Essentials→Profiles→{active profile}->Configure Tab. Navigate to Edit Profile Properties and select the properties in the appropriate "section" discussed below.

Adapter Strategy

If there is a need, an adapter strategy can be defined for IAP to show a preference for one southbound system (provider) over another. By setting the adapterStrategy property, an administrator of IAP can better direct how device-bound calls interact with external/southbound systems. Additionally, an exception can be set for the runCommand APIs and workflow tasks if the order needs to be further controlled.

Note: Any custom adapter that has implemented the device broker methods would come next after the configured preferential order has been exhausted.

Currently Supported	Values
Strategy Types	`device`
Adapter Types	`AutomationGateway` `NSO`
Exception	`runCommand`

Example Adapter Strategy

"adapterStrategy" : {
  "device": {
    "adapterTypes": [
        "AutomationGateway",
        "NSO"
    ],
    "exceptions": {
        "runCommand": "NSO"
    }
  }
}

Properties in the adapterStrategy object include the type of strategy, and currently device is the only one supported. This object contains two properties: adapterTypes and exceptions.

The property value for adapterTypes is an array of strings that are the types of the adapters; however, only AutomationGateway and NSO are possible values to be set. Under that section you can set the default order of the provider. In the example above, the calls that are shown in the lists below will prefer AutomationGateway over NSO. These names are types of adapters and not names of adapter instances defined by the user such as nso45 or nso46. If for some reason the preferred provider cannot fulfill the request IAP will try the next one on the list. Lastly, if a custom adapter implements the device broker, then it will be attempted next. If all adapters have tried to fulfill the request and fail, an error is returned.

The exceptions object contains key/value pairs that represent specific function level overrides. An exception definition will use the provider value for that function over the preferred provider order defined in adapterTypes. Currently only runCommand is supported.

Once this object is configured the way you would like, save the configuration and restart IAP.

WARNING: These are 'system-wide' properties so multiple calls will be impacted. See the tables below for the specific calls that are affected.

When IAP communicates with its registered providers it will call them in the order defined in the adapter strategy. Based on the example above IAP will call any AutomationGateway providers first, then any NSO providers, then any providers not listed in the strategy; unless the call is runCommand where it will call the NSO provider first. The strategy ensures the call will return after the first successful provider responds.

The following APIs and workflow tasks will be affected if the adapterStrategy property is set:

Workflow Task Name	API Route and Endpoint
`backUpDevice`	`POST /configuration_manager/devices/backups`
`getDevice`	`GET /configuration_manager/devices/:name`
`getDeviceConfig`	`GET /configuration_manager/devices/:name/configuration`
`getDeviceConfigFormat`	`GET /configuration_manager/devices/:name/configuration/:format`
`getDevicesFiltered`	`POST /configuration_manager/devices`
`isAlive`	`GET /configuration_manager/devices/:name/isAlive`
`lookupDiff`	`PUT /configuration_manager/lookup_diff`
`runNodeReport`	`GET /golden_config/compliance/node/:tree/:nodeid`
`runReportForDevice`	`GET /golden_config/compliance/:treeid/:device`
`runSelectedReport`	`GET /golden_config/compliance/:tree/:nodeid/:selected`
`runTreeReport`	`GET /golden_config/compliance/tree/:tree`
`GetBootFlash`	`POST /mop/GetBootFlash`
`passThru`	`POST /mop/passThru/:device`
`ping`	`POST /mop/ping`
`RunCommand`	`POST /mop/RunCommand`
`RunTemplateDevice`	`POST /mop/RunTemplateDevice`
`RunTemplateDevices`	`POST /mop/RunTemplateDevices`
`SetBoot`	`POST /mop/SetBoot`
`isAlive`	`POST /nso_manager/isAlive`
`liveStatus`	`POST /nso_manager/liveStatus`
`DryRunDeletion`	`POST /smart_template/st/dryrun/deletion`
`ProvisionDeletion`	`POST /smart_template/st/provision/deletion`
`ProvisionST`	`POST /smart_template/st/provision`
`getDevicesFiltered`	`POST /policy-manager/devices-filtered`
`importPoliciesFromDevice`	`POST /policy-manager/import/device`
`importPoliciesPreview`	`POST /policy-manager/import/preview`
`pushDryrun`	`POST /policy-manager/device/dryrun`
`DryRunWF`	`POST /smart_template/st/dryrunWF`
`ProvisionWF`	`POST /smart_template/st/provisionWF`

The following APIs endpoints (e.g. no corresponding workflow task) will be affected if the adapterStrategy property is set:

API Route and Endpoint	Method Name
`POST /configuration_manager/patch_device/:deviceName`	`patchDeviceConfiguration`
`POST /golden_config/addNative`	`addNativeRules`
`GET /golden_config/compare/:device/:tree/:nodeid`	`compareDeviceToLeaf`
`GET /mop/devices/:substring`	`getDevicesFiltered`
`GET /mop/devices/detailed/:substring`	`getDevicesFilteredDetailedResults`
`POST /mop/RunCommandDevices`	`RunCommandDevices`
`POST /mop/RunCommandTemplateSingleCommand`	`RunCommandTemplateSingleCommand`
`POST /mop/deviceObjects`	`getDeviceObjectsFiltered`
`GET /nso_manager/devices/:substring`	`getDevicesFiltered`
`POST /policy-manager/device/push`	`pushToDevice`
`POST /smart_template/st/autogenerate`	`CreateST`

The following Workflow tasks (e.g. no corresponding APIs) will be affected if the adapterStrategy property is set:

Workflow Task	Application
`runAutoRemediation`	Configuration Manager
`runComplianceForDevice`	Configuration Manager
`runComplianceForNode`	Configuration Manager
`runComplianceForTree`	Configuration Manager

Additionally, the following calls are affected if the exceptions property is set:

Workflow Task Name	API Route and Endpoint
`GetBootFlash`	`POST /mop/GetBootFlash`
`passThru`	`POST /mop/passThru/:device`
`RunCommand`	`POST /mop/RunCommand`
`RunTemplateDevice`	`POST /mop/RunTemplateDevice`
`RunTemplateDevices`	`POST /mop/RunTemplateDevices`
`SetBoot`	`POST /mop/SetBoot`

The following APIs endpoints (e.g. no corresponding workflow task) will be affected if the exceptions property is set:

API Route and Endpoint	Method Name
`POST /mop/RunCommandDevices`	`RunCommandDevices`
`POST /mop/RunCommandTemplateSingleCommand`	`RunCommandTemplateSingleCommand`

Important: All the calls above are affected by the adapterStrategy property setting. Use care and caution when using the property as many of these calls could be difficult to find deep within workflows.

Alarm

The alarm properties allow the administrator to configure the remote SNMP trap destinations the health check alarms will be sent to. Currently, SNMP v1 and SNMP v2 are supported. A list of alarm receivers may be configured for a high-availability solution. IAP will attempt to deliver each alarm to all configured receivers.

As of the date of this publication, the following alarms are supported by IAP.

Alarm	Objects	Description
Pronghorn Running		IAP has successfully started and is currently operational.
Pronghorn System Error	System Error	Reserved for future use.
Adapter Unreachable	Adapter ID, Remote IP Address, Remote Port	An IAP adapter could not establish a connection with its external system.
Adapter Connected	Adapter ID, Remote IP Address, Remote Port	An IAP adapter successfully established a connection with its external system.
Adapter Function Error	Adapter ID, Adapter Function, Adapter Error	Reserved for future use.

The IAP SNMP MIB defining each of the supported alarms is located at /opt/pronghorn/current/snmp/pronghorn.mib.

For a comprehensive list of IAP SNMP MIB, see the Itential SNMP MIB guide.

Property	Type	Default	Description
`ip`	String	`127.0.0.1`	The IP address of the remote alarm receiver. FQDNs are also supported in this field.
`community`	String	`public`	The SNMP community to apply to the outgoing trap or inform.
`type`	String	`trap`	The type can be configured as either a trap or inform. Traps are delivered without acknowledgement, e.g., `fire-and-forget`. Informs are delivered with an expected acknowledgement.
`properties.transport`	String	`udp4`	The protocol to use to send alarms to this receiver. Valid options are `udp4` and `udp6`.
`properties.trapPort`	Number	`162`	The remote port of this alarm receiver. Must be a number in the range 1 - 65535.
`properties.version`	String	`V2:`	The SNMP version to use when delivering notifications to this alarm receiver. Valid options are `V1` and `V2`.
`properties.retries`	Number	`1`	The number of timeout cycles to wait for an acknowledgement when delivering inform type notifications.
`properties.timeout`	Number	`5000`	The number of seconds to wait for an acknowledgement when delivering inform type notifications.

Sample Alarm Properties

"alarmProps": [{
  "ip" : "127.0.0.1",
  "community" : "public",
  "type" : "trap",
  "properties" : {
    "transport" : "udp4",
    "trapPort" : 162,
    "version" : "V1"
  }
},{
  "ip" : "127.0.0.1",
  "community" : "public",
  "type" : "inform",
  "properties" : {
    "transport" : "udp4",
    "trapPort" : 162,
    "version" : "V2",
    "retries" : 1,
    "timeout" : 5000
  }
}]

Sample Alarm Configuration Option

"alarmProps": {
    "ip": "127.0.0.1",
    "community": "public",
    "properties": {
        "retries": 1,
        "timeout": 5000,
        "transport": "udp4",
        "trapPort": 1162,
        "version": "V1"
    },
    "type": "trap"
}

Application

The application properties are captured by the applicationProps object.

Property Name	Type	Default	Description
`description`	String	Application	The description property.
`directory`	String	`/opt/pronghorn/current/node_modules`	This property provides the location of the `node_modules` directory. This property should generally remain unchanged and be set to the default.

Sample Application Properties

"applicationProps": {
  "description": "Application",
  "directory": "/opt/pronghorn/current/node_modules"
}

Audit

The audit properties control whether user auditing and broker validation features are enabled. If user auditing is enabled, user actions on the network are stored in the audit_trail MongoDB collection.

If broker validation is enabled, all calls coming into IAP will be validated against a set of JSON schemas to validate if requests are in the proper format.

Note: The broker validation feature is currently in beta mode. You should continue to run with brokerValidation disabled unless Itential Support specifically requests that this feature be enabled.

Property	Type	Default	Description
`description`	String	`Audit`	The description property.
`audit`	Boolean	`true`	A boolean flag indicating whether auditing is enabled. This should be set to true for production environments.
`brokerValidation`	Boolean	`true`	A boolean flag indicating whether broker validation is enabled.

Sample Audit Properties

"auditProps": {
  "description": "Audit",
  "audit": true,
  "brokerValidation": false
}

Authentication

The authentication properties in authenticationProps allow for optional enforcement of a unique session per user requirement and the assignment of IAP administrator groups.

IAP authorization and authentication relies on an external authentication system; a property exists to specify which group within the external authentication adapter specifies the user with administrative access to IAP.

This property is set within the properties.json file and can contain multiple group names. Every user that is a member of the external group name within the list will be granted IAP administrator access.

Each entry in the administrator list must contain two fields.

Property	Description
`provenance`	The name of the AAA adapter.
`group`	The name of the group returned by the AAA adapter.

Property	Type	Default	Description
`description`	String	`audit`	The description property.
`uniqueSession`	Boolean	`false`	When set to true, only one session may be enabled for a given user. If a second session is established for the same user, the original session will be invalidated.
`admins`	Array	`["g1", "g2", ...]`	A list of groups which are authorized to perform user management activities. Members of these groups will be implicitly assigned the `pronghorn_admin` role.
`admins.provenance`	String	`<adapter_name>`	The name of the AAA adapter in which the groups reside.
`admins.group`	String	`pronghorn_admin`	The name of a user group which will have IAP user management capabilities.

Sample Authentication Properties

"authenticationProps": {
  "description": "audit",
  "uniqueSession": false,
  "admins": [{
    "provenance": "local_aaa",
    "group": "pronghorn_admin"
  }]
}

Note: Be sure to configure the AAA adapter in addition to the authenticationProps.

Express

IAP uses the Node.js Express web server to capture incoming requests. The Express properties allow an administrator to configure whether IAP will listen on HTTP and/or HTTPS. The properties also allow an administrator to configure HTTPS keys, certificates, TLS versions, and supported cipher suites.

The private key referenced by express_https.key property should contain one of the following patterns.

Unencrypted Private Key

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

The private key may also be encrypted.

Encrypted Private Key

-----BEGIN ENCRYPTED PRIVATE KEY-----
...
-----END ENCRYPTED PRIVATE KEY-----

Note: If the private key contains the following pattern, the express_https.passphrase should be configured with the passphrase of the private key.

The certificate file referenced by the express_https.cert property should be like the following.

Unencrypted Private Key

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

For more information on the set of cipher suites that are supported by Node.js, see Modifying the Default TLS Cipher Suite.

Property Name	Type	Default
`description`	String	`Express Server`
`cacheControl`	Boolean	`false`
`timeout`	Number	`300000`
`express_http.enable`	Boolean	`true`
`express_http.port`	Number	`3000`
`express_https.enable`	Boolean	`true`
`express_https.port`	Number	`3443`
`express_https.key`	String	`/etc/ssl/keys/pronghorn.key`
`express_https.passphrase`	String
`express_https.cert`	String	`/etc/ssl/keys/pronghorn.cert`
`express_https.secureProtocol`	String	`TLSv1_2_method`
`express_https.ciphers`	String	See Modifying the Default TLS Cipher Suite.
`express_https.client_reneg_limit`	Number	`1`
`express_https.client_reneg_window`	Number	`600`

Sample Express Properties

"expressProps": {
  "description": "Express Server",
  "cacheControl": false,
  "timeout": 300000,
  "express_http": {
    "enable": false,
    "port": 3000
  },
  "express_https": {
    "enable": true,
    "port": 3443,
    "key": "/etc/ssl/keys/pronghorn.key",
    "passphrase": "$ENC82ee8a234a69f15bdb8e05409cda2418878b2f85af",
    "cert": "/etc/ssl/keys/pronghorn.cert",
    "secureProtocol": "TLSv1_2_method",
    "ciphers": "ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256",
    "client_reneg_limit": 1,
    "client_reneg_window": 600
  }
}

Logger

The logger properties control where IAP will store its log files, how much space to dedicate to log storage, and the verbosity levels of the log messages that will be stored. IAP supports the following log levels.

Log Level	Description
error	The most severe level. Indicates a problem, such as a prematurely terminated program.
warn	Used for warning conditions. Warn events may or may not indicate a problem.
info	Used for informational messages.
debug	Used only when debugging problems or transactions. Provides detailed information on messages between IAP adapters and external systems.
trace	Trace events have a higher verbosity than debug. Trace events are uncommon.
spam	The least severe level. Spam events have the highest verbosity and are rare.

Production environments should run at either warn or info level. Running production environments in debug or trace levels will likely generate a large amount of log data and place additional load on the server. A production server should only be configured in debug mode at the request of the Itential Support.

IAP provides native support for rotation of the pronghorn.log file. Administrators can define the total allocated storage for logs by configuring the maximum file size and maximum number of files. For example, if the maximum file size is 1 MB and the total number of files is 100, the total space consumed by pronghorn.log files will be 100 MB. Be sure the disk that holds the IAP logs contains enough space for IAP to exercise a full log rotation cycle (100 MB).

The log levels for each application and adapter are configurable at run-time using the IAP UI. When the server is restarted, the log levels for all applications and adapters is returned to the defaults provided by the log_level and console_level properties.

IAP allows for the verbosity of its console logging to be configured. For systemd based operating systems, this console logging is controlled by the system journal. The system journal may contain application life cycle error messages that are not capable of being written to the pronghorn.log file itself. The system journal should be reviewed for errors and warnings during any troubleshooting sessions. The system journal is also written to /var/log/messages on many systems. The storage required to store the system journal and /var/log/messages files should also be considered during the storage planning phases.

Use the following command to monitor the system journal.

journalctl -f

Use the pronghorn.service unit to tail the system journal and filter only IAP messages.

journalctl -f -u pronghorn.service

For more details about configuring the system journal daemon and using the journalctl command, see the official Red Hat documentation: Using the Journal.

Property	Type	Default	Description
`description`	String	`Logging`	The description property.
`log_directory`	String	`/var/log/pronghorn`	The directory to store IAP log files.
`log_filename`	String	`pronghorn.log`	The name of the current IAP log file.
`log_max_file_size`	Number	`1048576`	The maximum size of each IAP log file in bytes. Once the maximum file size is reached, the IAP log will be rotated.
`log_max_files`	Number	`100`	The maximum number of log files maintained on the server. Once the maximum number of files is reached, the oldest file will be deleted during log rotation.
`log_timezone_offset`	Number	`0`	The offset from GMT/UTC time that will be used when writing to the log files. Valid values are whole numbers ranging from -12-12 as is listed in List of UTC time offsets.
`log_level`	String	`info`	The verbosity level the server is configured to log messages to the IAP log. This can be one of the following: error, warn, info, debug, trace or spam. As a recommendation, run production servers at info level logging.
`console_level`	String	`warn`	The verbosity level the server is configured to log messages to the system journal or `/var/log/messages`. This can be one of the following: error, warn, info, debug, trace or spam. The verbosity of the IAP log and the system journal may be adjusted independently.
`metrics_filename`	String	`metrics.log`	The name of the metrics log file inside the WorkflowEngine metrics directory. Note: This is a metrics logging specific property, that currently only pertains to Job Metrics.
`metrics_max_files`	Number	`31`	The max number of allowed log files inside the WorkflowEngine metrics directory for retention before deleting the oldest files when a rotation occurs. Note: This is a metrics logging specific property, that currently only pertains to Job Metrics.
`metrics_rotation_interval`	String	`7d`	The maximum amount of time between metrics file rotations, before a file rotation occurs. If a file is rotated due to size before this interval is reached, then the interval timer is reset. The allowed suffix values are s (seconds), m (minutes), h (hours), d (days), or M (months). Note: This is a metrics logging specific property, that currently only pertains to Job Metrics.
`metrics_rotation_size`	String	`10M`	The maximum size a metrics file can reach before a file rotation occurs. The allowed suffix values are B (Bytes), K (KiloBytes), M (MegaBytes), or G (GigaBytes). Note: This is a metrics logging specific property, that currently only pertains to Job Metrics.

Sample Logger Properties

"loggerProps": {
  "description": "Logging",
  "log_directory": "/var/log/pronghorn",
  "log_filename": "pronghorn.log",
  "log_max_file_size": 1048576,
  "log_max_files": 10,
  "log_timezone_offset": -5,
  "log_level": "info",
  "console_level": "warn",
  "metrics_filename": "metrics.log",
  "metrics_max_files": 31,
  "metrics_rotation_interval": "7d",
  "metrics_rotation_size": "10M"
}

Syslog

The syslog properties allow IAP to send log messages to a local or remote syslog daemon.

Note: Please be aware of the maximum message length supported by the remote syslog receiver. IAP will send messages greater than 1024 bytes. Remote syslog receivers may truncate messages greater than a certain length.

See the following references for more details.

Property	Type	Default	Description
`level`	String	`info`	The minimum log level to send to the syslog server. Possible levels are: debug, info, warning, error.
`host`	String	`localhost`	The host running syslogd.
`port`	Number	`514`	The port on the host that syslog is running on. Must be a number in the range 1 - 65535.
`protocol`	String	`udp4`	The network protocol to log over. Can be one of `tcp4`, `udp4`, `unix` or `unix-connect`.
`path`	String	N/A	The path to the syslog dgram socket, e.g., `/dev/log` or `/var/run/syslog` on OS X). If `path` is used, `host`, `port` and `protocol` do not need to be configured.
`pid`	String	`process.pid`	Process identifier (PID) of the process that log messages are coming from.
`facility`	String	`local( )`	Syslog facility to use.
`localhost`	String	`localhost`	Host to indicate that log messages are coming from.
`type`	String	`BSD`	The type of syslog protocol to use. Possible values are `BSD` and `5424`.
`app_name`	String	`process.title`	The name of the application.
`eol`	String	N/A	The end of line character to be added to the end of the message.

Sample Syslog Properties

"loggerProps": {
  "syslog": {
    "level": "warning",
    "host": "localhost",
    "port": 514,
    "protocol": "udp4",
    "facility": "local0",
    "type": "5424"
  }
}

Path

The path properties provide the location of customer-installed IAP applications and adapters.

Property Name	Type	Default	Description
`description`	String	File Path Variables	The description property.
`encrypted`	Boolean	`true`	A boolean flag indicating IAP core is encrypted. This should be set to true for all customer installations.

Sample Path Properties

"pathProps": {
  "description": "File Path Variables",
  "sdk_dir": "/opt/pronghorn/pronghorn-applications",
  "encrypted": true
}

Redis Properties

The Redis properties, redisProps, should be configured to point your IAP instance to a local Redis service.

Property	Type	Default	Description
`host`	String	`127.0.0.1`	The IP or hostname of the server running the Redis service.
`port`	Number	`6379`	The port Redis is running on. Must be a number in the range 1 - 65535.
`db`	Number	`0`	The optional Redis database number to connect to (number may be 0-15).
`password`	String		The optional passphrase protecting access to the Redis database.
`maxRetriesPerRequest`	Number	`20`	The maximum number of connection retries on a lost Redis link. IAP will be shutdown when maxRetriesPerRequest is reached.
`maxHeartbeatWriteRetries`	Number	`20`	The maximum number of write retries on the lost ability to write data in Redis. IAP will be shutdown when maxHeartbeatWriteRetries is reached.

Sample Redis Properties

"redisProps": {
  "host": "127.0.0.1",
  "port": 6379,
  "db": 0,
  "password": "$ENC87eb897b507afc1796db49409dd1251c87872e85afd2469e",
  "maxRetriesPerRequest": 20,
  "maxHeartbeatWriteRetries": 20
}

System Properties

The following table presents the systemProps that may be configured.

Property	Type	Default	Description
`launchDelay`	Number	0	The time in seconds that IAP will wait between launching its services. This can be used to manage the resource usage incurred by starting many services at the same time.
`launchTimeout`	Number	600	The time in seconds that IAP will wait for a service registration. If a service has not registered itself to IAP within this time frame, it will consider it lost.
`deadProcessCheck`	Boolean	`false`	If true, IAP will perform a health check on its services in timed intervals set by the `deadProcessCheckInterval`. If a process is considered dead it will be restarted.
`deadProcessCheckInterval`	Number	5	The interval in seconds that IAP will check the health of its services. This check interval works in conjunction with `deadProcessMaxPeriod` to define when IAP considers the service lost.
`deadProcessMaxPeriod`	Number	15	The threshold in seconds after which IAP considers a service lost if it has not received a health update. At each check interval (see `deadProcessCheckInterval`), if the last received healthcheck for this service is longer than the `deadProcessMaxPeriod`, then IAP will then consider the service lost. IMPORTANT: The longest interval a service can be down before being caught is the sum of `deadProcessMaxPeriod` and `deadProcessCheckInterval`. In other words, with the defaults supplied herein, it might be 20 seconds before a service is detected to be down due to the time lag of the check interval when compared against this threshold. Keep this in mind if you modify these settings.
`servicesBlacklist`	Array	[]	A list of service types that will be "blacklisted" for the current user. This means the user will not be able to perform CRUD (CREATE, UPDATE, DELETE) operations on any of the services configured within the system that have the listed service type in this property. Only the `admin` user will be able to configure these service types. For example, if an admin would like to prevent all users of the system from modifying the AAA adapter then they can do so by specifying "LDAP" (if LDAP is the configured AAA system) within the `servicesBlacklist` property. Remember the values in the `servicesBlacklist` property are the `service type`. To find this value, navigate to the service config (e.g. Adapter Configuration) and look for the "properties" array and the "type" value for the targeted service. Use the value of "type" and remember that all adapters of this type will be restricted; in other words, it restricts by type and not by instance.
`shutdownTimeout`	Number	3	The time (seconds) IAP waits before it shuts down its services. This allows a service to have some time to perform any operations it may need to do before it exits. This timeout also applies to the service life-cycle actions "stop", "restart", and "crashes".

Below is a sample configuration for systemProps when used with Advanced Mode:

"systemProps": {
  "launchDelay": 0,
  "launchTimeout": 60,
  "deadProcessCheck": false,
  "deadProcessCheckInterval": 5,
  "deadProcessMaxPeriod": 15,
  "servicesBlacklist": [ "NSO", "local_aaa", "GitHub:v5" ],
  "shutdownTimeout": 3
}

UI

The UI properties are captured by the uiProps object. These properties may be used to overwrite certain pages and icons as a part of customer branding.

Property Name	Type	Default	Description
`description`	String	UI	The description property.
`layout`	String	`node_modules/@itential/pronghorn-core/ui/views/layout.jade`	The jade file that governs the overall IAP layout page.
`home`	String	`node_modules/@itential/pronghorn-core/ui/views/home.jade`	The jade file that creates the user's individual home page.
`login`	String	`node_modules/@itential/pronghorn-core/ui/views/login.jade`	The jade file that creates the login page presented to unauthenticated users.
`profile`	String	`node_modules/@itential/pronghorn-core/ui/views/profile.jade`	The jade file that presents the user's profile.
`fav_icon`	String	`node_modules/@itential/pronghorn-core/ui/img/favicon.ico`	The path to a custom-branded icon displayed in the browser's tab and URL bars.

Sample UI Properties

"uiProps": {
  "description": "UI",
  "layout": "node_modules/@itential/pronghorn-core/ui/views/layout.jade",
  "home": "node_modules/@itential/pronghorn-core/ui/views/home.jade",
  "login": "node_modules/@itential/pronghorn-core/ui/views/login.jade",
  "profile": "node_modules/@itential/pronghorn-core/ui/views/profile.jade",
  "fav_icon": "node_modules/@itential/pronghorn-core/ui/img/favicon.ico"
}

Automation Engine in a Service Config

The activate property determines if tasks are worked upon startup of an IAP system. For example, if a disaster recovery system needs to be running but not processing events, this property can help control that behavior.

Property Name	Type	Default	Description
`activate`	Boolean	`true`	If true, the Automation Engine worker is enabled and tasks are worked. If false, the worker is not enabled and does not work new tasks.

Sample Automation Engine Properties in the WorkFlowEngine Service Properties UI

"properties": {
  "activate": true,
},

MongoDB in the properties.json file

The MongoDB properties must be configured to connect to a single MongoDB server or a MongoDB replica set. Be sure to align your authentication and encryption settings with the configurations of the MongoDB you are connecting to.

Note: Itential currently supports the use of MongoDB 4.2.x on all released IAP versions. If you are using an earlier version it is recommended that you upgrade.

Property Name	Type	Default	Description
`db`	String	`pronghorn`	The name of the database to connect to.
`url`	String	`mongodb://localhost:27017`	The MongoDB URL to use when connecting to the database.
`credentials.dbAuth`	Boolean	`false`	A boolean flag indicating whether user authentication is enabled.
`credentials.dbAuthSource`	String	The user provided `db` property value.	Specify the database name associated with the user’s credentials. Corresponds to `authSource` in MongoDB connection options.
`credentials.user`	String		The username to use for connections when authentication is enabled.
`credentials.passwd`	String		The password to use for connections when authentication is enabled.
`ssl.enabled`	Boolean	`false`	A boolean flag indicating whether SSL is enabled.
`ssl.sslValidate`	Boolean	`false`	A boolean flag indicating whether the MongoDB server's certificate will be validated.
`ssl.sslCA`	String		Path to the certificate authority PEM (privacy enhanced mail) file that signed the MongoDB certificates.
`ssl.acceptInvalidCerts`	Boolean		A boolean flag indicating whether to validate the MongoDB certificate against the certificate authority PEM file.
`ssl.checkServerIdentity`	Boolean		A boolean flag indicating whether to validate the name of the server configured in the URL against the common name of the certificate the server presents.
`replSet.enabled`	Boolean	`false`	A boolean flag indicating whether we are connecting to a replica set. When connecting to a replica set, the names of the servers and the replica set name must be configured as part of the URL.

Minimal MongoDB Configuration

"mongoProps": {
  "db": "pronghorn",
  "url": "mongodb://localhost:27017"
}

Sample Production Configuration

"mongoProps": {
  "db": "pronghorn",
  "url": "mongodb://mongo01:27017,mongo02:27017,mongo03:27017?rs=rs1",
  "credentials": {
    "dbAuth": true,
    "user": "pronghorn",
    "passwd": "$ENC93f88824437dfe5784c7570f99d7251f878a2284aed6449259"
  },
  "ssl": {
    "enabled": true,
    "sslValidate": true,
    "sslCA": "/etc/ssl/keys/mongo_ca_chain.cert",
    "acceptInvalidCerts": false,
    "checkServerIdentity": true
  },
  "replSet": {
    "enabled": true
  }
}

Profiler in a Service Config

To help troubleshoot performance issues resulting in high CPU usage, Itential Automation Platform (IAP) has a built-in profiler based on:

Profiling can be enabled in IAP, along with select applications and adapters in IAP release version 2020.1 and later.

Note: This feature should not impose any security limitations; however, Itential strongly recommends this feature is not enabled for production deployment due to possible performance impacts.

Prerequisites

Must have write permission to the working directory to create profiling logs.

How to enable profiling in IAP

To set profiling in IAP:

When running IAP in a Docker environment, use the following to set profiling in the /docker/startContainer.
```
set `PHCORE_PROFILING=true`
```
When running IAP directly in shell, use the --prof CLI option.
```
sudo -u pronghorn node --prof server.js
```

How to enable profiling for adapters/applications

To enable profiling for adapters and applications running on a development server:

Go to Admin Essentials.
Expand the Applications or Adapters collections menu (left sidebar)and select the appropriate adapter/application.
From the Configuration tab, switch the toggle (upper-right) to turn-on the Advanced View and display the Service Config editor.
Profiling of select applications/adapters can be enabled (and disabled) by directly editing its configuration (see example below).
Once the profiling feature is enabled/disabled, click save and restart the application/adapter for the change to take effect.

Example: Profiling Enabled for NSO Manager

Pictured below is an example of profiling enabled for the NSO Manager application.

Profiling Enabled NSO Manager Service Config

How to process profiler logs

The profiler will gather (log) all data in a file that can be found in the working directory as isolate-*-v8.log.

Example: Profiling Logs

Profiling Logs

To process the profiler logs into a user-friendly pretty-format, simply use the Node.js --prof-process CLI option.

node --prof-process isolate-0x5589eb9afae0-v8.log > isolate-0x5589eb9afae0-v8-PRETTY.log

Profiling info can then be inspected by opening the log file in your preferred editor/viewer.

Remove Profiler Logs

Once you've analyzed all profile data, remember to remove the profiling log files to save disk space.

Redis Adapter Properties in a Service Config

In a shared Redis setup, configuration points to a master/slave group of Redis servers that share token data between IAP cogs. For shared sessions, the Redis adapter should be configured to connect to a set of Redis instances monitored by sentinels.

Property Name	Type	Default	Description
`name`	String	`pronghorn-tokens`	The name of the Redis sentinel group.
`password`	String		The password for the Redis sentinels the adapter is connecting to. When using Redis sentinels the passwords for all the Redis servers must be configured to the same value.
`sentinels`	Array		The list of sentinels to connect to.
`sentinels[x].host`	String		The IP or FQDN of the Redis server.
`sentinels[x].port`	Number	`26379`	The port number of the Redis sentinel. Must be a number in the range 1 - 65535.

Sample Redundant Configuration

{
  "id": "redis",
  "type": "Redis",
  "properties": {
    "name": "pronghorn-tokens",
    "password": "$ENC93f88824437dfe5784c7570f99d7251f878a2284aed6449259"
    "sentinels": [{
      "host": "redis1",
      "port": 26379
    },{
      "host": "redis2",
      "port": 26379
    },{
      "host": "redis3",
      "port": 26379
    }]
  },
  "brokers": [ "persistence" ]
}

Max Retries Property in properties.json

The maxRetries property determines the number of times a service will restart due to uncaught exceptions and unhandled rejections. If IAP restarts a service more than the maximum number of maxRetries, it will no longer attempt to restart it. If the service is subsequently started again, the retry count is reset to 0. The maxRetries property is set in the properties.json file and applies to all services in IAP.

Property	Type	Default	Description
`maxRetries`	Number	10	Maximum number of times IAP will restart services due to uncaught exceptions and unhandled rejections.

System Properties in a Service Config

System properties are used to control service level internal properties, such as v8 and node properties for a service process. System properties are set in the Services page (Applications and Adapters) by adding systemProps as a top level property.

The following properties are available for systemProps:

Property	Type	Default	Description
`maxOldSpaceSize`	Number	2048	The `maxOldSpaceSize` property sets the maximum memory size (in MBs) of a service's process (v8 old memory section). This system property is set to 2 GB by default for all services except for Automation Engine, which is set to 8 GB by default. The `maxOldSpaceSize` is specified in Admin Essentials->Applications->Admin Essentials service configuration file by adding `systemProps` as a top level property.

Here is a sample configuration for a systemProps when used with Advanced Mode:

"systemProps": {
  "maxOldSpaceSize": 4095
}

Core Adapters

Configuration for the Core adapters in Itential Automation Platform (IAP) are detailed as follows.

Adapter Properties

The adapter properties section of the properties.json file will vary depending on the set of adapters that are installed. Each adapter will have a unique id, a type, and a set of type-specific properties.

Property Name	Description
`adapters`	An array of adapter objects.
`adapters[x].id`	A unique identifier for the adapter.
`adapters[x].type`	The type of adapter. This should come from the adapter package. Ensure the adapter package is installed.
`adapters[x].properties`	A set of type-specific properties to configure for each adapter. Refer to the adapter configuration for an example configuration of each module.
`adapters[x].brokers`	The broker(s) to register the adapter with.

Adapter Properties

"adapterProps": {
  "adapters": [
    {
      "id": "adapter-id",
      "type": "adapter-type",
      "properties": {
        ...
      },
      "brokers": [ "brokername" ]
    }
  ]
}

Redis Adapter

The Redis adapter should be configured to connect to a Redis server running on the same node as IAP. The properties for the Redis adapter are described by the Redis client node module.

A full reference can be found on GitHub at ioredis.

Property	Type	Default	Description
`host`	String	`127.0.0.1`	The address/hostname of the Redis server.
`port`	Number	`6379`	The port that Redis is using. Must be a number in the range 1 - 65535.
`db`	String	`0`	The number of the Redis database to connect to.
`password`	String		The password for the Redis database you are connecting to.

The default configuration assumes Redis is running on localhost and listening on port 6379. Configure the Redis adapter to be a member of the persistence broker.

Minimal Redis Adapter Configuration

{
  "id": "redis",
  "type": "Redis",
  "properties": {
  },
  "brokers": [ "persistence" ]
}

Sample Production Configuration

{
  "id": "redis",
  "type": "Redis",
  "properties": {
    "host": "127.0.0.1",
    "port": 6379,
    "password": "$ENC93f88824437dfe5784c7570f99d7251f878a2284aed6449259"
  },
  "brokers": [ "persistence" ]
}

Redis Sentinels

The Redis adapter may also be configured to connect to a set of Redis sentinels.

Property Name	Type	Default	Description
`name`	String	`pronghorn-tokens`	The name of the Redis sentinel group.
`password`	String		The password for the Redis sentinels we are connecting to. When using Redis sentinels the passwords for all the Redis servers must be configured to the same value.
`sentinels`	Array		The list of sentinels to connect to.
`sentinels[x].host`	String		The IP or FQDN of the Redis server.
`sentinels[x].port`	Number	`26379`	The port number of the Redis sentinel. Must be a number in the range 1 - 65535.

Sample Redundant Configuration

{
  "id": "redis",
  "type": "Redis",
  "properties": {
    "name": "pronghorn-tokens",
    "password": "$ENC93f88824437dfe5784c7570f99d7251f878a2284aed6449259"
    "sentinels": [{
      "host": "redis1",
      "port": 26379
    },{
      "host": "redis2",
      "port": 26379
    },{
      "host": "redis3",
      "port": 26379
    }]
  },
  "brokers": [ "persistence" ]
}

Email Adapter

The Email adapter can be used to deliver email notifications to end users. Currently, notifications are triggered based on job completion or from custom tasks within a workflow.

Property	Type	Default	Description
`host`	String	`127.0.0.1`	Hostname or IP address to connect to.
`port`	Number	`587`	The port to connect to (defaults to 587 if `secure` is false, or 465 if `secure` is true). Must be a number in the range 1 - 65535.
`auth.user`	String		The default username to send from.
`auth.pass`	String		The password for the default username.
`authMethod`	String	`PLAIN`	Defines preferred authentication method.
`secure`	Boolean	`false`	Use TLS.
`ignoreTLS`	Boolean		If this is true and `secure` is false then TLS is not used even if the server supports STARTTLS extension.
`requireTLS`	Boolean		If this is true and `secure` is false then the adapter tries to use STARTTLS even if the server does not advertise support for it. If the connection cannot be encrypted then message is not sent.
`tls.isServer`	Boolean		The SSL/TLS protocol is asymmetrical; TLSSockets must know if they are to behave as a server or a client. If true the TLS socket will be instantiated as a server.
`tls.requestCert`	Boolean		If true the server will request a certificate from clients that connect and attempt to verify that certificate.
`tls.rejectUnauthorized`	Boolean		If not false the server will reject any connection which is not authorized with the list of supplied CAs. This option only has an effect if `tls.requestCert` is true.
`tls.requestOCSP`	Boolean		If true specifies that the OCSP status request extension will be added to the client hello and an OCSPResponse event will be emitted on the socket before establishing a secure communication.
`name`	String		Optional hostname of the client used for identifying to the server; defaults to hostname of the machine.
`localAddress`	String		The local interface to bind to for network connections.
`connectionTimeout`	Number		How many milliseconds to wait for the connection to establish.
`greetingTimeout`	Number		How many milliseconds to wait for the greeting after connection is established.
`socketTimeout`	Number		How many milliseconds of inactivity to allow.

Note: Configure the email adapter to be a member of the notification broker.

Sample Minimal Configuration

{
  "id": "email",
  "type": "Email",
  "properties": {
    "host": "127.0.0.1",
    "port": 25,
    "secure": false
  },
  "brokers": [ "notification" ]
}

Sample Production Configuration

{
  "id": "email",
  "type": "Email",
  "properties": {
    "host": "mail.example.com",
    "port": 587,
    "secure": true,
    "authMethod": "PLAIN",
    "auth": {
      "user": "pronghorn",
      "pass": "$ENC93f88824437dfe5784c7570f99d7251f878a2284aed6449259"
    }
  },
  "brokers": [ "notification" ]
}

Email Adapter SMTP Services and Configuration

The Email adapter uses Nodemailer for SMTP connections to several well-known service providers. A list of the supported services can be found here at the Nodemailer site.

The Email adapter can be configured using Nodemailer or by using a host name and port number. Two examples are presented below.

Example 1

In this example, Outlook365 is the service provider being used in the configuration.

{
    "id": "email",
    "type": "Email",
    "properties": {
      "service": "Outlook365",
      "auth": {
        "user": "username",
        "pass": "password"
      },
      "secure": false
    },
    "brokers": [
      "notification"
    ],
    "groups": []
  }

Example 2

In this example, the host name is configured for outlook.office365.com and the port number is 993. A service provider is not used.

    "id": "email",
    "type": "Email",
    "properties": {
      "host": "outlook.office365.com",
      "port": 993,
      "auth": {
        "user": "username",
        "pass": "password"
      },
      "secure": false
    },
    "brokers": [
      "notification"
    ],
    "groups": []
  }

Authentication Adapters

The authentication adapters (LDAP, AAA) required for IAP enablement are discussed below.

LDAP Adapter

LDAP adapter is configured to establish connection with Active Directory and OpenLDAP servers.

For an LDAP based system it becomes important to understand which groups a user belongs to when working on the user information. Especially in systems that implement RBAC, understanding the groups for a user is necessary for the authorization process. Fortunately, LDAP has the support for reverse membership mapping if the user and group objects use certain object classes. By default an OpenLDAP system uses the memberOf overlay; however, this default is overridden by the userMembershipAttribute property.

Property Name	Type	Default	Description
`domain`	String	`example.itential.io uid={0},ou=people,o=support,dc=itential,dc=io`	The name of the LDAP domain. This is not necessarily the same as the DNS name of the server.
`url`	String	`ldaps://localhost:636`	URL of the LDAP server. For SSL, use LDAPS Default port is 636. For unencrypted connections (not recommended), use LDAP. Default port is 389.
`bindUsername`	String	`itential@domain cn=itential,ou=services,o=support,dc=itential,dc=io`	The username of the bind account. This administrative account is used to view all groups/users that IAP needs to know about. Utilize `<user@domain>` for Active Directory and `cn=user,dc=example,dc=com` for OpenLDAP.
`bindPassword`	String		If `$ENC` or `$SECRET` precedes the password, IAP will use it as an encrypted password. Otherwise, the password is stored in plain text.
`baseDN`	String	`dc=itential,dc=io`	The base DN from which the LDAP adapter will search for users and groups. If both `baseUserDN` and `baseGroupDN` are specified, this parameter will have no effect.
`baseUserDN`	String	`ou=people,o=support,dc=itential,dc=io`	The base DN from which the LDAP adapter will search for users. If not provided, `baseDN` is used. This property was introduced in adapter-ldap version 2.11.0.
`baseGroupDN`	String	`ou=groups,o=support,dc=itential,dc=io`	The base DN from which the LDAP adapter will search for groups. If not provided, `baseDN` is used. This property was introduced in adapter-ldap version 2.11.0.
`groupSearchFilter`	String	`(objectClass=groupOfNames)`	Filter for the group search. This property uses the official LDAP Search Filter Syntax.
`userSearchFilter`	String	`sAMAccountName uid`	Filter for the user search. This defines the common name (or other object) that defines users in the LDAP server. For example, most Active Directory implementations use `sAMAccountName` to define users. Utilize `uid` for OpenLDAP.
`userMembershipAttribute`	String	`memberOf`	This field should contain the name of the LDAP attribute on the user object that indicates which group(s) the user is a member of.
`healthCheckInterval`	Number	`5000`	Set interval to ping the LDAP server to ensure connectivity. Measured in milliseconds.
`timeout`	Number	`5000`	Set the default timeout for authentication attempts. Measured in milliseconds.
`connectTimeout`	Number	`5000`	Set the default connection timeout for authentication attempts. Measured in milliseconds.
`idleTimeout`	Number	`5000`	Set the default idle timeout. Measured in milliseconds.
`timeLimit`	Number	`10`	The maximum amount of time the server should take in responding, in seconds. Defaults to 10 seconds. Set to higher values to handle nested group searches. Many servers will ignore this.
`reconnect`	Boolean	`true`	Determine whether or not to attempt a reconnect.
`activeDirectory`	Boolean	`false`	Sets the type of directory service. If true, Active Directory authentication is used. If false, LDAP authentication is used.
`tlsOptions.secureProtocol`	String	`TLSv1_method`	Determine the protocol method to use. The possible values are listed as SSL_METHODS. Use the function names as strings.
`tlsOptions.requestCert`	Boolean	`true`	If true the server will request a certificate from clients that will connect and attempt to verify that certificate.
`tlsOptions.rejectUnauthorized`	Boolean	`true`	If true the server will reject any connection which is not authorized with the list of supplied CAs.
`tlsOptions.ca`	String	`/etc/ssl/keys/openldap_ca.pem`	Path to ca key (in PEM format).
`customGroups`	Array of Strings	`[]`	A list of predefined groups to search for a user and to list user groups. This property should only be used with Active Directory servers; it is not yet compatible with most OpenLDAP schemas.

Note: Configure the LDAP adapter to be a member of the AAA broker. Only one AAA adapter may be configured at a time.

Active Directory Configuration

Use the following example for Active Directory configuration.

Sample Active Directory Configuration

{
    "id": "ldap",
    "type": "LDAP",
    "properties": {
        "domain": "example.itential.io",
        "url": "ldaps://example.itential.io:636",
        "bindUsername": "itential",
        "bindPassword": "itential-ldap-password",
        "baseDN": "dc=itential,dc=io",
        "baseGroupDN": "ou=groups,o=support,dc=itential,dc=io",
        "baseUserDN": "ou=people,o=support,dc=itential,dc=io",
        "groupSearchFilter": "(objectCategory=Group)",
        "userSearchFilter": "sAMAccountName",
        "userMembershipAttribute": "memberOf",
        "healthCheckInterval": 5000,
        "timeout": 5000,
        "connectTimeout": 5000,
        "idleTimeout": 5000,
        "timeLimit": 10,
        "reconnect": true,
        "activeDirectory": true,
        "tlsOptions": {
            "secureProtocol": "TLSv1_method",
            "requestCert": true,
            "rejectUnauthorized": true,
            "ca": "/etc/ssl/keys/activedirectory_ca.pem"
        },
        "customGroups" : [
         "Group1",
         "Group2"
        ]
    },
    "brokers": [ "aaa" ]
}

OpenLDAP Configuration

Use the following example for OpenLDAP configuration. The hostname in the URL must match the common name of the LDAP server certificate.

Sample OpenLDAP Configuration

{
    "id": "ldap",
    "type": "LDAP",
    "properties": {
        "domain": "uid={0},ou=people,o=support,dc=itential,dc=io",
        "url": "ldaps://example.pronghorn.io:636",
        "bindUsername": "cn=itential,ou=services,o=support,dc=itential,dc=io",
        "bindPassword": "itential-user-password",
        "baseDN": "dc=itential,dc=io",
        "baseGroupDN": "ou=groups,o=support,dc=itential,dc=io",
        "baseUserDN": "ou=people,o=support,dc=itential,dc=io",
        "groupSearchFilter": "(objectClass=groupOfNames)",
        "userSearchFilter": "uid",
        "userMembershipAttribute": "memberOf",
        "healthCheckInterval": 5000,
        "timeout": 5000,
        "connectTimeout": 5000,
        "idleTimeout": 5000,
        "timeLimit": 10,
        "reconnect": true,
        "activeDirectory": false,
        "tlsOptions": {
            "secureProtocol": "TLSv1_method",
            "requestCert": true,
            "rejectUnauthorized": true,
            "ca": "/etc/ssl/keys/openldap_ca.pem"
        }
    },
    "brokers": [ "aaa" ]
}

Local AAA Adapter

The Local AAA adapter may be used in lab and development environments to locally authenticate users against a MongoDB collection inside the local AAA database.

Configure the Local AAA adapter to be a member of the AAA broker. Only one AAA adapter may be configured at a time.

The Local AAA adapter no longer uses the persistence broker and you can point local AAA to any MongoDB database you choose. You must add the database configuration property, as shown in the example below.

Sample Local AAA Configuration

{
  "id": "Local AAA",
  "type": "local_aaa",
  "properties": {
    "database": {
      "db": "LocalAAA",
      "url": "mongodb://127.0.0.1:27017",
      "credentials": {
        "dbAuth": false
      }
    }
  },
  "brokers": [ "aaa" ]
}

Note: If you are using dbAuth, then make sure that the username which Local AAA adapter is using is created inside the same database you set in db property.

Add Users and Groups

To add more users for testing and development, you can create and import a new user JSON document.

Encrypt the user password using bcrypt-cli to create a hash.

$ bcrypt-cli password 10
$2a$10$5KXKzv9Ech1w2nOSSPWCMuaqOS6aFCpKZV6IzfaYRRgN/xkwXYso2

Be sure to create group documents for each group referenced by the accounts. After each group is created, configure the group from the Authorization menu by logging in as the IAP administrator.

Sample User Account Document (Local AAA User)

$ mongo db01/pronghorn --ssl -u pronghorn -p
MongoDB shell version v3.6.6
Enter password:
connecting to: mongodb://db01:27017/ph6
MongoDB server version: 3.6.6
$ use LocalAAA
switched to db LocalAAA
$ db.accounts.find();
{
    "_id": ObjectId("5b6f9fc3fe38e3bd73795d4d"),
    "username" : "admin@pronghorn",
    "activeTenant" : "*",
    "firstname" : "admin",
    "groups" : [ "pronghorn_admin" ],
    "password" : "$2a$10$5KXKzv9Ech1w2nOSSPWCMuaqOS6aFCpKZV6IzfaYRRgN/xkwXYso2",
    "tenants": []
}

Note: If you need to use local AAA encryption for securing IAP to MongoDB, learning how to encrypt the password for use in an adapter, or obfuscating the password, refer to the Encrypt Passwords on Local AAA section of the IAP Installation guide for more information.

Sample Group Document (Local AAA Group)

$ mongo db01/pronghorn --ssl -u pronghorn -p
MongoDB shell version v3.6.6
Enter password:
connecting to: mongodb://db01:27017/ph6
MongoDB server version: 3.6.6
$ use LocalAAA
switched to db LocalAAA
$ db.groups.find();
{
    "_id": ObjectId("5b6f9fc3fe38e3bd73795d56"),
    "name": "pronghorn_users",
    "group": "pronghorn_admin"
}

Database Indexes

IAP requires indexes to be created in the MongoDB collections for optimal performance. The following applications contain database index scripts that must be applied.

app-form_builder
app-mop
app-service_catalog
app-workflow_engine

This section will describe the required indexes for all the applications in the IAP portfolio. If an app is not installed on your system, no indexes are required; just skip the instructions to load the indexes for that application and continue with the next application in the list.

Depending on the application, there are two methods of applying indexes. The first is a MongoDB script method which should be run using the mongo command line and the second is running the npm run index command from the IAP server itself. If you have the mongo client installed on the IAP server, you can run the MongoDB script method on the IAP server. If you do not have the mongo client installed on the IAP server, copy the scripts to the MongoDB server and create the indexes from there.

Method 1: Apply Database Indexes with a MongoDB Script

The Form Builder application uses this method to apply the indexes. The relevant script file is located here:

/opt/pronghorn/current/node_modules/@itential/app-form_builder/database/scripts/create_indexes.js

If your IAP is configured to connect to a MongoDB database other than pronghorn, you will need to edit the following line in the script and replace the pronghorn string with the name of the custom database to which IAP is connected.

How to Change Database Name

const pDB = db.getSiblingDB('pronghorn');

Form Builder

Create the Form Builder indexes using the following command as a reference. You will need to replace the mongo command-line options with values that will let you authenticate against your MongoDB database. If your database is named something other than pronghorn, remember to edit the script to change the database name before the script is executed.

Example

$ cd /opt/pronghorn/current/node_modules/@itential/app-form_builder/database/scripts
$ mongo mongo01.zone1.itential.io:27017/pronghorn --ssl -u pronghorn create_indexes.js
MongoDB shell version v3.4.18
Enter password:
connecting to: mongodb://mongo01.zone1.itential.io:27017/pronghorn
MongoDB server version: 3.4.18
{
    "createdCollectionAutomatically" : false,
    "numIndexesBefore" : 1,
    "numIndexesAfter" : 2,
    "ok" : 1
}

Method 2: Apply Database Indexes with the NPM Run Index Command

This method involves a node script run from the IAP server itself. The npm run index command is a wrapper npm script that calls one or more node scripts. The following applications must have the indexes applied in this manner:

Automation Engine
Command Templates/MOP
Service Catalog

An example is shown below in Automation Engine of which scripts are run once npm run index is invoked:

/opt/pronghorn/current/node_modules/@itential/app-workflow_engine/database/scripts/ensureJobIndexes.js

/opt/pronghorn/current/node_modules/@itential/app-workflow_engine/database/scripts/ensureTaskIndexes.js

/opt/pronghorn/current/node_modules/@itential/app-workflow_engine/database/scripts/ensureWorkflowIndexes.js

Each app might have a different filename for the scripts but the main principle is maintained where npm run index is the common wrapper/interface for the user to run.

The following sections provide additional detail for how to run the npm run index method.

Automation Engine

The final set of indexes for the Automation Engine application may be applied using the following npm script.

Automation Engine scripts are built on top of Node.js and read the database connection parameters from the IAP properties.json file. This script must be run from the IAP server itself.

Example

$ cd /opt/pronghorn/current/node_modules/@itential/app-workflow_engine
$ npm run index

> @itential/app-workflow_engine@4.16.6 index /opt/pronghorn/current/node_modules/@itential/app-workflow_engine
>  node database/scripts/ensureWorkflowIndexes.js; node database/scripts/ensureJobIndexes.js; node database/scripts/ensureTaskIndexes.js

Retrieving properties.json file...
Found properties!

Converting Mongo Properties (mongoProps) to Node Mongo Driver schema...
Properties converted!

Connecting to Database...
Db.prototype.authenticate method will no longer be available in the next major release 3.x as MongoDB 3.6 will only allow auth against users in the admin db and will no longer allow multiple credentials on a socket. Please authenticate using MongoClient.connect with auth credentials.
Connection established!

Retrieving indexes from collection workflows...
Indexes retrieved!

Verifying Indexes...
Indexes verified!

Creating Indexes...
Indexes created...

Index reconciliation complete!

Retrieving properties.json file...
Found properties!

Converting Mongo Properties (mongoProps) to Node Mongo Driver schema...
Properties converted!

Connecting to Database...
Db.prototype.authenticate method will no longer be available in the next major release 3.x as MongoDB 3.6 will only allow auth against users in the admin db and will no longer allow multiple credentials on a socket. Please authenticate using MongoClient.connect with auth credentials.
Connection established!

Retrieving indexes from collection jobs...
Indexes retrieved!

Verifying Indexes...
Indexes verified!

Creating Indexes...
Indexes created...

 Index reconciliation complete!

Retrieving properties.json file...
Found properties!

Converting Mongo Properties (mongoProps) to Node Mongo Driver schema...
Properties converted!

Connecting to Database...
Db.prototype.authenticate method will no longer be available in the next major release 3.x as MongoDB 3.6 will only allow auth against users in the admin db and will no longer allow multiple credentials on a socket. Please authenticate using MongoClient.connect with auth credentials.
Connection established!

Retrieving indexes from collection tasks...
Indexes retrieved!

Verifying Indexes...
Indexes verified!

Creating Indexes...
Indexes created...

 Index reconciliation complete!

Verify Automation Engine Indexes

After the Automation Engine scripts have completed, run the following commands on MongoDB to verify the indexes have been created.

Commands

db.jobs.getIndexes()
db.tasks.getIndexes()
db.workflows.getIndexes()

Example

$ mongo mongo01.zone1.itential.io:27017/pronghorn --ssl -u pronghorn
MongoDB shell version v3.4.18
Enter password:
connecting to: mongodb://mongo01.zone1.itential.io:27017/pronghorn
MongoDB server version: 3.4.18
rs0:PRIMARY> db.jobs.getIndexes()

[{
    "v": 2,
    "key": {
      "_id": 1
    },
    "name": "_id_",
    "ns": "pronghorn.jobs"
  },
  {
    "v": 2,
    "key": {
      "name": 1,
      "type": 1,
      "groups": 1,
      "status": 1,
      "metrics.start_time": -1,
      "metrics.progress": 1,
      "metrics.user": 1
    },
    "name": "name_1_type_1_groups_1_status_1_metrics.start_time_-1_metrics.progress_1_metrics.user_1",
    "ns": "pronghorn.jobs",
    "background": true
  },
  {
    "v": 2,
    "key": {
      "name": 1,
      "type": 1,
      "watchers": 1,
      "status": 1,
      "metrics.start_time": -1,
      "metrics.progress": 1,
      "metrics.user": 1
    },
    "name": "name_1_type_1_watchers_1_status_1_metrics.start_time_-1_metrics.progress_1_metrics.user_1",
    "ns": "pronghorn.jobs",
    "background": true
  }
]

rs0: PRIMARY > db.tasks.getIndexes()[{
  "v": 2,
  "key": {
    "_id": 1
  },
  "name": "_id_",
  "ns": "pronghorn.tasks"
}, {
  "v": 2,
  "key": {
    "name": 1,
    "status": 1,
    "groups": 1,
    "type": 1,
    "job.name": 1,
    "job._id": 1,
    "job.task": 1,
    "metrics.owner": 1,
    "metrics.start_time": -1
  },
  "name": "name_1_status_1_groups_1_type_1_job.name_1_job._id_1_job.task_1_metrics.owner_1_metrics.start_time_-1",
  "ns": "pronghorn.tasks",
  "background": true
  },
  {
  "key": {
    "status": 1,
    "locked": 1
  },
  "background": true,
}, {
  "key": {
    "job._id": 1,
    "job.task": 1
  },
  "background": true
}]

rs0: PRIMARY > db.workflows.getIndexes()[{
  "v": 2,
  "key": {
    "_id": 1
  },
  "name": "_id_",
  "ns": "pronghorn.workflows"
}, {
  "v": 2,
  "unique": true,
  "key": {
    "name": 1,
    "type": 1
  },
  "name": "name_1_type_1",
  "ns": "pronghorn.workflows",
  "background": true
}, {
  "v": 2,
  "key": {
    "groups": 1,
    "created": -1,
    "created_by": 1,
    "last_updated": -1,
    "last_updated_by": 1
  },
  "name": "groups_1_created_-1_created_by_1_last_updated_-1_last_updated_by_1",
  "ns": "pronghorn.workflows",
  "background": true
}]

Command Template/MOP

The final set of indexes for the Command Template/MOP application may be applied using the following npm script.

Example

$ cd /opt/pronghorn/current/node_modules/@itential/app-mop
$ npm run index
...
...

Service Catalog

The final set of indexes for the Service Catalog application may be applied using the following npm script.

Example

$ cd /opt/pronghorn/current/node_modules/@itential/app-service_catalog
$ npm run index
...
...

Itential Automation Platform

Help us improve by sending feedback...

On this page:

Configuration

Configuration File

Encrypting Passwords

Configuration Properties

Profile Properties

Adapter Strategy

Alarm

Application

Audit

Authentication

Express

Logger

Syslog

Path

Redis Properties

System Properties

UI

Automation Engine in a Service Config

MongoDB in the properties.json file

Profiler in a Service Config

Prerequisites

How to enable profiling in IAP

How to enable profiling for adapters/applications

How to process profiler logs

Remove Profiler Logs

Redis Adapter Properties in a Service Config

Max Retries Property in properties.json

System Properties in a Service Config

Core Adapters

Adapter Properties

Redis Adapter

Redis Sentinels

Email Adapter

Email Adapter SMTP Services and Configuration

Authentication Adapters

LDAP Adapter

Active Directory Configuration

OpenLDAP Configuration

Local AAA Adapter

Add Users and Groups

Database Indexes

Method 1: Apply Database Indexes with a MongoDB Script

Form Builder

Method 2: Apply Database Indexes with the NPM Run Index Command

Automation Engine

Verify Automation Engine Indexes

Command Template/MOP

Service Catalog