Profile Properties

The iap_profiles collection holds the active profile settings for the Itential platform. Detailed information on each profile property is summarized below.

Most of the configuration for the active profile happens within Admin Essentials → Profiles but other configuration occurs in the various Admin Essentials → Service Config interfaces and within the properties.json file.

Configuring the 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

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

Sample Adapter Strategy Properties

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

The properties of 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:

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

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

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

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

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.

The following alarms are currently supported by IAP.

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

For a comprehensive list of SNMP notifications, see Itential SNMP MIB.

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.

Sample Application Properties

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

Audit

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

Sample Audit Properties

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

Authentication

The authentication properties in authenticationProps allow for optional enforcement of a unique session per user requirement and the assignment of IAP administrator groups. The ability for an AAA adapter to provide a principal document is also supported.

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 active IAP Profile 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: provenance and group.

Sample Authentication Properties

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

Note: Be sure to configure the AAA adapter in addition to 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.

Sample Express Properties

"expressProps": {
  "description": "Express Server",
  "cacheControl": false,
  "timeout": 300000,
  "access_control_allow_origin": "*",
  "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
  }
}

Exposing IAP on Different Ports

For IAP, the expressProps port for both HTTP and HTTPS is above 1024; IAP cannot be exposed on standard ports (i.e., 80-HTTP, 443-HTTPS) due to the service not running as root. In Linux, only root or setuid applications can bind to ports below 1024. Please refer to Privileged Ports to learn more on running services at specific ports.

To workaround this limitation and run IAP over port 443, it will require setting HAProxy to listen on 443 and forward to localhost 3443.

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.

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.

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

Path

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

Sample Path Properties

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

Redis

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

Sample Redis Properties

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

Retry Strategy

When a service in IAP throws a JavaScript exception without handling it, IAP will attempt to retry the service. To configure the number of times IAP will attempt to retry a failed service, set the maxRetries property. When the number of times IAP restarts a service exceeds the maxiumum number allowed in maxRetries, all attempts to restart the service will stop. The count will then reset if the number of milliseconds configured within the retryResetTimer property has elapsed between any two retry attempts.

Sample Retry Strategy Properties

"retryStrategy" : {
  "maxRetries": 15,
  "retryResetTimer": 2500
}

Care should be taken when configuring each of these properties as they work together to achieve the best retry strategy. For instance, retryResetTimer can be configured to account for occasional crashes (even expected daily crashes) by having the counter reset after a short period to avoid reaching the maxRetries threshold for retry activity to stop.

Syslog

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

See the following references for more detail:

• BSD Syslog RFC
• 5424 Syslog RFC
• Winston-Syslog

Sample Syslog Properties

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

System

The following table presents the systemProps that may be configured.

Sample System Properties

Below is a sample systemProps configuration when used with the Advanced Mode editor.

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

UI

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

Sample UI Properties

"uiProps": {
  "description": "UI",
  "layout": "node_modules/@itential/pronghorn-core/ui/views/layout.pug",
  "home": "node_modules/@itential/pronghorn-core/ui/lib/iap-ui/build/index.html",
  "login": "node_modules/@itential/pronghorn-core/ui/views/login.pug",
  "profile": "node_modules/@itential/pronghorn-core/ui/views/profile.pug",
  "fav_icon": "node_modules/@itential/pronghorn-core/ui/img/favicon.ico"
}