Itential Docs & Guides | Drive Automation for Modern Networks

This guide defines the minimum requirements to have a functioning production or development instance of the Itential Automation Platform (IAP). Instructions on how to install core software and configure IAP properties are provided.

Requirements

This section includes both required and recommended installation requirements.

Physical Servers vs Virtual Machines

The IAP platform and all of its components support both physical servers and virtual machines. Virtual machines (VM) are recommended because they are less expensive and easier to manage as a solution. Moreover, performance appears to be comparable, assuming the VM hardware specs are guaranteed and not shared with other virtual machines.

Production

For production environments, all IAP components should be installed on their own individual servers to properly support high availability (HA).

Lab and Development

For non-production environments the specs may be lowered to provide lower cost options. However, keep in mind that depending on usage, these specs will need to be adjusted. For highly active developer environments with a great number of custom applications, increased CPU, memory, and disk space will be required.

IAP Server

The following table describes required IAP production server components.

Component	Requirement	Production ENV	Lab / Test ENV	Development ENV
CPU	64-bit x86 CPU cores.	Min: 8 / Rec: 16	Min: 4 / Rec: 8	Min: 2 / Rec: 4
RAM	Memory	Min: 32GB / Rec: 64GB	Min: 16GB / Rec: 32GB	Min: 4GB / Rec: 8GB
Disk	Total `/var/log/pronghorn` `/opt/pronghorn` `/var/log/redis`	250 GB 100 GB 100 GB 50 GB	125 GB 50 GB 50 GB 25 GB	65 GB 25 GB 25 GB 15 GB

The following hardware specs assume an IAP Server with a few custom applications. In situations where a number of custom applications are heavily utilized, or additional IAP backup storage is needed then the CPU, RAM, and disk space allocations will need to be increased.

MongoDB Server

The following table describes MongoDB server resources that are required by IAP in a production environment.

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.

Component	Requirement	Production ENV	Lab / Test ENV	Development ENV
CPU	64-bit x86 CPU cores.	Min: 8 / Rec: 16	Min: 4 / Rec: 8	Min: 2 / Rec: 4
RAM	Memory	Min: 64GB / Rec: 128GB	Min: 16GB / Rec: 32GB	Min: 4GB / Rec: 8GB
Disk	Total `/var/log/mongo` `/data`	1 TB 150 GB 850 GB	500 GB 100 GB 400 GB	250 GB 50 GB 200 GB

Redis Shared-Token Server

The following table describes Redis server resources that are required by IAP in a production environment using multiple IAP servers and shared-tokens.

Component	Requirement	Production ENV	Lab / Test ENV	Development ENV
CPU	64-bit x86 CPU cores.	Min: 4 / Rec: 8	Min: 2 / Rec: 4	Min: 1 / Rec: 2
RAM	Memory	Min: 4GB / Rec: 8GB	Min: 2GB / Rec: 4GB	Min: 1GB / Rec: 2GB
Disk	Total `/var/log/redis`	50 GB 50 GB	25 GB 25 GB	10 GB 10 GB

RabbitMQ Server

The following table describes RabbitMQ server resources that are required by IAP in a production environment.

Component	Requirement	Production ENV	Lab / Test ENV	Development ENV
CPU	64-bit x86 CPU cores.	Min: 4 / Rec: 8	Min: 2 / Rec: 4	Min: 1 / Rec: 2
RAM	Memory	Min: 4GB / Rec: 8GB	Min: 2GB / Rec: 4GB	Min: 1GB / Rec: 2GB
Disk	Total `/var/log/rabbitmq`	50 GB 50 GB	25 GB 25 GB	10 GB 10 GB

Alternative Lab and Development Environments

As an alternative solution a single larger VM may be used to run all of the IAP platform components. A lab environment may include MongoDB, Redis, RabbitMQ, and IAP on a single server.

Component	Requirement	Lab / Test ENV	Development ENV
CPU	64-bit x86 CPU cores.	Min: 8 / Rec: 16	Min: 4 / Rec: 8
RAM	Memory	Min: 16GB / Rec: 24GB	Min: 8GB / Rec: 16GB
Disk	Total `/var/log/pronghorn` `/opt/pronghorn` `/var/log/redis` `/var/log/rabbitmq` `/var/log/mongo` `/data`	650 GB 50 GB 150 GB 25 GB 50 GB 75 GB 300 GB	425 GB 25 GB 100 GB 25 GB 25 GB 50 GB 200 GB

Host Operating System

IAP is supported on the following operating systems.

OS	Release	Production	Development
CentOS 64-bit	CentOS 7	x	x
RHEL 64-bit	RHEL 7	x	x

OS Packages

Install the following operating system packages on each IAP server.

coreutils
openssl
ntp
nscd
epel-release
gcc-c++
make

Security

The following security related packages are recommended.

iptables
auditd
selinux-policy
selinux-policy-targeted
selinux-policy-mls
policycoreutils
libselinux
libselinux-utils
setools-console

Operational

For operational troubleshooting, the following packages are recommended.

telnet
bind-utils
sysstat
tcpdump
dos2unix
curl
wget
zip
unzip
gzip
man

Required Software

Although IAP is compatible with several third-party software products, consult the Release Notes before installing any software to obtain the currently supported versions. IAP requires the following software be installed.

Privileged User Access

During installation, various config files, paths, and system resources may need to be modified. Thus, installation of Itential software will require temporary root access via sudo. This temporary root access is only required during new installations and major upgrades if using the installer.bin method. Temporary root access post-installation can be replaced with a limited set of sudo commands as listed below. To run sudo as a root user, it is recommended that Itential admins have privileged user account access for updating configuration files. Since those files are owned by the application user, admins will need to switch as a different user, which provides the necessary security privileges to upgrade and configure IAP.

This command lets you switch as an <itential> application user to view/edit configuration and log files.

sudo su - itential

The following is a list of recommended post-installation sudo commands using pronghorn for IAP:

/bin/systemctl start pronghorn.service
/bin/systemctl stop pronghorn.service
/bin/systemctl restart pronghorn.service
/bin/systemctl enable pronghorn.service
/bin/systemctl disable pronghorn.service
----
/bin/journalctl * pronghorn.service

You will want to replace pronghorn with the service you want to control such as automation-platform, automation_gateway, mongod, redis, or rabbitmq-server. Keep in mind these commands are only the basic sudo commands a user might need, along with the command that provides the ability to switch as an <itential> user for editing configuration files.

Installing Dependencies

Install the prerequisite software: Node.js, Redis, MongoDB, and RabbitMQ. Links to additional documentation resources have been provided below.

Node.js must be installed on the same server as IAP. Redis, MongoDB, and RabbitMQ should be installed on separate servers from IAP in a production deployment, but alternatively can be installed on the same server as IAP for an all-in-one type development deployment. If a shared token Redis instance exists, it can be used rather than a second Redis instance. See the High Availability Architecture section for production deployment options.

Note: The following instructions assume component installation on a server running CentOS 7. The Redis, MongoDB, and RabbitMQ steps will work either directly on the IAP server or a standalone server, unless stated otherwise.

Node.js

Please refer to the NodeSource README.md for details on Node.js installation.

Post Installation

The version of Node.js that IAP requires may be found in the Release Notes of the the IAP release version.

Verify that Node.js is installed and available from the PATH environment variable. The path will depend on your environment. The path below is provided as an example.

$ command -v node
/bin/node

Check which version of Node.js is installed. Refer to the Release Notes for the current supported version.

$ node -v
<vxx.x.x>

Node.js Package Manager

The Node.js Package Manager tool, npm, is installed along with Node.js. However, a minimum version is required.

Post Installation

Verify that npm is installed and available from the PATH environment variable. The path will depend on your environment. The path below is provided as an example.

$ command -v npm
/bin/npm

Check which version of npm is installed. Consult the Release Notes for the current supported version.

$ npm -v
<x.xx.x>

If the version of npm is not greater than or equal to version 6, then upgrade npm with the following command. Always consult the Release Notes for the current supported version.

npm i -g npm@<6.xx.x>

Redis

Please refer to the Redis documentation for details on Redis installation.

Post Installation

If Redis is running on a different server than IAP, the Redis process may bind to the localhost. If this occurs then Redis and IAP may not be able to communicate.

The following are example steps for allowing Redis to communicate outside of localhost.

Edit /etc/redis.conf on the Redis server.
Comment out bind 127.0.0.1 so that it becomes #bind 127.0.0.1.
Restart Redis.
```
sudo systemctl restart redis
```

Note: The instructions open the Redis TCP port externally, so security hardening should be considered.

Configuration

Apply the following recommended Redis configurations to a production or development environment. These recommendations are relevant where Redis is running in a virtual machine. However, many of these configurations may also apply to a bare metal installation.

Max Memory

By default, Redis will consume up to 80% of the memory available on the platform. Set the upper limit to 20% of the available memory so IAP may consume the remaining 80%.

Change the # maxmemory <bytes> value in the /etc/redis.conf file.

Restart Redis to allow the /etc/redis.conf changes to go into effect.

sudo systemctl restart redis

Note: Further Redis configuration for a production environment can be found in the Redis Configuration of the IAP Admin Guide.

RabbitMQ

A supported version of Erlang/OTP must be installed before installing RabbitMQ. Although Erlang is part of CentOS and standard Red Hat repositories, it is most likely out-of-date. Please check the RabbitMQ Erlang Version Requirements Guide for currently supported versions at this link: Which Erlang Version?

Please refer to the RabbitMQ installation guide for details on RabbitMQ installation.

Verify the installed RabbitMQ version matches the version specified in the Release Notes dependency section for the relevant IAP version.

⚠ Note: Due to limitations in dependencies of RabbitMQ, passwords for RabbitMQ cannot have certain special characters. The character types confirmed to be invalid are \, /, :, and ?.

Post Installation

Check that the RabbitMQ service is running.

$ systemctl status rabbitmq-server

    rabbitmq-server.service - RabbitMQ broker
    Loaded: loaded (/usr/lib/systemd/system/rabbitmq-server.service; enabled; vendor preset: disabled)
    Active: active (running) since Thu 2020-01-02 17:38:38 UTC; 5s ago

Note: RabbitMQ TCP port 5672 is exposed externally by default. Hardening RabbitMQ security should be considered.

Event Deduplication

To use the event deduplication feature, additional install steps must be completed (see below).

Note: Event deduplication is highly recommended for HA configurations.

Operational Requirements

The event deduplication feature requires that all IAP instances in an HA cluster share the same event deduplication settings in their active profile and all have the same plugins enabled. Mismatched settings will result in undefined behavior and are not supported.

Required Third-Party Plugins

elixir-VERSION.ez
rabbitmq_message_deduplication-VERSION.ez

Installation Steps

Consult the README.md for the third-party plugins: rabbitmq-message-deduplication
Download the correct version of the two plugins listed above according to your version of RabbitMQ (3.8.x recommended).
Install the plugins by copying their .ez files to the plugin directory of your RabbitMQ instance.
Enable the following plugins using rabbitmq-plugins enable:
- rabbitmq_management
- rabbitmq_shovel
- rabbitmq_shovel_management
- rabbitmq_message_deduplication
Verify the admin port (default 15672) is exposed to IAP. This is required for automatic settings configuration by IAP.
Make sure the same plugins are installed and activated on all RabbitMQ instances when a cluster is being used.

MongoDB

Please refer to the official MongoDB installation instructions.

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.

Required Authorization for the IAP MongoDB User

IAP requires access to the readWrite role within MongoDB for all internal collections. When using roles outside of the built-in roles, a minimum of the same permissions as those included in the readWrite role is necessary.

Post Installation

To verify a successful MongoDB installation:

Start the MongoDB service.
```
sudo service mongod start
```
Show the operational status of the mongod service.
```
sudo service mongod status
```

If it is running, you will see a message similar to this:

Redirecting to /bin/systemctl status mongod.service
● mongod.service - High-performance, schema-free document-oriented database Loaded: loaded (/usr/lib/systemd/system/mongod.service; enabled; vendor preset: disabled)
Active: active (running) since Fri 2018-11-09 16:12:57 UTC; 3 weeks 0 days ago
Docs: https://docs.mongodb.org/manual
Main PID: 7587 (mongod)
CGroup: /system.slice/mongod.service
      !"7587 /usr/bin/mongod -f /etc/mongod.conf
Nov 09 16:12:56 localhost.localdomain systemd[1]: Starting High-performance,schema-free document-oriented database...
Nov 09 16:12:56 localhost.localdomain mongod[7583]: about to fork child process, waiting until server is ready for connections.
Nov 09 16:12:56 localhost.localdomain mongod[7583]: forked process: 7587
Nov 09 16:12:57 localhost.localdomain mongod[7583]: child process started successfully, parent exiting
Nov 09 16:12:57 localhost.localdomain systemd[1]: Started High-performance, schema-free document-oriented database.

Refer to the MongoDB Configuration section of the IAP Admin Guide to review configuration considerations for a production environment.

Note: The network settings specified in the mongod.conf file may need verification. This file is set to 127.0.0.1 but may need to be changed to 0.0.0.0. For more information on adapting the config settings for this file, refer to the MongoDB documentation.

Standalone Server

If running MongoDB on a server other than the IAP server, perform the following steps so that IAP will be able to reach it.

Edit /etc/mongod.conf on the MongoDB server.
Change the line starting with bindIp: 127.0.0.1 so that it becomes bindIp: 0.0.0.0.
Restart MongoDB.
```
sudo systemctl restart mongod
```

Note: MongoDB security hardening is recommended as the previous steps open the default MongoDB TCP port 27071 externally.

Template Builder Dependencies

There are two sets of dependencies for Template Builder. The first set, python, textfsm, and jinja2, are required for Template Builder to function. The second set, chroot, sudo, and ldd are required to allow Template Builder to execute Jinja2 templates in a contained context. Without this second set of dependencies available and the appropriate configuration in place to allow the IAP process to execute them in a subshell, Jinja2 templates will have access to environment variables from the parent process and the file system. It is highly recommended that you configure Template Builder to execute Jinja2 templates in a contained context.

Base Dependencies

To install base dependencies:

Install Python 3.

Note: Starting with Python version 3.4, pip has been included as part of the Python installers.
```
sudo yum install -y python3
```
Verify the Python version installed.
```
python3 --version
```
Verify pip3 version installed.
```
pip3 --version
```
Run the following commands. Once TextFSM and Jinja2 are available, the template parser will be able to function properly.
```
sudo pip3 install textfsm
sudo pip3 install jinja2
```
Verify the versions of Jinja2 and TextFSM installed.
```
pip3 freeze
```

Security Dependencies

To install and configure Template Builder security dependencies:

Make sure the following shell utilities are installed. These are all likely to be installed already.
```
yum -y install sudo glibc-common coreutils
```
Verify the user used to run the server (usually pronghorn) is permitted to run sudo chroot without a password prompt. An example command which accomplishes this is shown below as follows, but the system administrator is expected to tailor these commands to their needs. As long as the server is permitted to run chroot through sudo without a password prompt, Template Builder can sandbox Jinja2 template execution.
```
echo "pronghorn ALL=(ALL) NOPASSWD: $(command -v chroot)" >> /etc/sudoers
```
Make sure Template Builder is permitted to copy in all dependencies required by Python. These dependencies are those output by the ldd command, as well as all paths in Python's internal sys.path constant. If file permissions prevent Template Builder from copying these files into its chroot jail directory, Python will not be able to execute within the sandbox subshell and Template Builder will fall back to executing in insecure mode.

Testing the Template Builder Security Configuration

To test the Template Builder security configuration:

Ensure IAP is running.
Examine the logs. Template Builder will report that it is creating a sandbox directory for Jinja2 template execution, and when it is finished, it will report either the success or failure of the process. On the first run of the server, this will likely take several minutes, and Template Builder will report back to API requests that it is still initializing until it is finished.
Once Template Builder has finished initializing the sandbox directory, run a Jinja2 template.
Examine the server logs and look to make sure there are no warnings stating that Jinja2 execution is running in insecure mode.

Installing IAP

Perform the following steps to install the IAP software onto a CentOS 7 server. Be sure the latest version of the IAP package has been copied to the server. You can acquire the link for this build from the portal.

Installation

Perform the following steps to install IAP onto the server.

Transfer the IAP binary package to the server.
Change to directory, cd, where the package is stored.
Run the install binary as a privileged user. The default installation directory is /opt/pronghorn/current.
```
sudo bash itential-<build-id>_version.linux.x86_64.bin -i
```

Note: Change <build-id> in the installer binary above to match the version being installed.

Custom Directory Options

In some instances users may need to use alternative folders when installing IAP. This section covers how to install IAP in another directory and adjust the properties. To customize the IAP installation, bin -h can be used to view available options and pick an alternative directory other than the default location used in a standard IAP install. An example showing the -h command is provided below.

Use Tab completion in the Linux command line and then type -h at the end of the line.

→ sh ./itential-<build-id>_version.linux.x86_64.bin -h

The results will display directory information from the environment you are using.

Note: The <build-id> in the installer binary above will match the version being installed.

Configuration

Upon successful installation, a default IAP configuration file will be created at /opt/pronghorn/current/properties.json. This file will initially contain a default IAP configuration that may be edited to match the environment.

Edit /opt/pronghorn/current/properties.json.

Change all references of mongodb://mongo:27017 to either the hostname/IP address of your MongoDB server or localhost if hosted on the IAP server.

Example Options

  # Option 1) Hosted locally on IAP server.
  mongodb://localhost:27017

  # Option 2) Hosted on a standalone MongoDB server.
  mongodb://mongodb.test.com:27017

  # Option 3) MongoDB replica set.
  mongodb://mongo01.test.com:27017,mongo02.test.com:27017,mongo03.test.com:27017?replicaSet=rs0

Change all references of "host": "redis" to either the hostname or IP address of your Redis server or localhost if hosted on the IAP server.

Example Options
```
  # Option 1) Hosted locally on IAP server.
  "host": "localhost"

  # Option 2) Hosted on a standalone Redis server.
  "host": "redis.test.com"
```

DB Migration

A migration script must be manually run to import properties.json configuration into the MongoDB database. After the migration script is run once, the properties.json file will only be referenced by IAP for the MongoDB connection properties, with IAP referencing the database for all other configuration properties.

Note: Any desired changes to properties.json should be made before proceeding.

Enter the directory containing the IAP migration script.

cd /opt/pronghorn/current/node_modules/@itential/pronghorn-core/migration_scripts

Run the migration script. Key/value pairs after --userInputs can be changed to match the RabbitMQ deployment.

Example Options

# Option 1) RabbitMQ installed on IAP server with default port.
node migratePropertiesToDatabase.js --userInputs protocol=amqp port=5672 hosts="localhost"

# Option 2) RabbitMQ installed on standalone server.
node migratePropertiesToDatabase.js --userInputs protocol=amqp port=5672 hosts="rabbitmq.test.com"

The properties.json file will be updated during the migration script run to only contain the MongoDB connection properties, with all other configuration parameters stored within the default MongoDB database named pronghorn. The migration script creates a backup of the original properties.json file that will look similar to properties_b4b03d30-ad00-4f61-bd9e-7953968ef8c4.json.

Migration Script Help Options

The migratePropertiesToDatabase.js script has a --help option that allows you to use the script in unattended mode with the --userInputs option. The following example depicts the various help options available and briefly explains how they are used.

Figure: Help Options

Migration Script Help Options

Start IAP

Start IAP and set to auto-start on server reboot.
```
  systemctl enable --now pronghorn
```

Confirm IAP has started successfully.

  $ systemctl status pronghorn

  pronghorn.service - Itential Automation Platform Service
    Loaded: loaded (/etc/systemd/system/pronghorn.service; enabled; vendor preset: disabled)
    Active: active (running) since Thu 2020-01-02 20:37:43 UTC; 4min 29s ago
  Main PID: 30774 (Pronghorn core)

Note: The journalctl -u pronghorn -f command may be run to monitor IAP logs during startup or general usage.

Access IAP Web UI

IAP may be accessed by browsing to http://<SERVER_HOSTNAME>:3000/login with <SERVER_HOSTNAME> being either the hostname or IP address of the server that IAP is installed on. The default user is admin@pronghorn with password admin.

Note: Be sure to give the admin@pronghorn user access to all roles from the Settings->Authorization page in the IAP Web UI in order to access applications.

Password Encryption

Passwords stored within the properties.json IAP properties file should be encrypted. This can be achieved by using the encryption script that is included within the pronghorn-core package or by using Vault Encryption.

Note: Password encryption is one-way. Be sure all passwords are securely stored as retrieval is not possible.

Legacy Encryption

For legacy-based $ENC encryption, use the following steps to run the encryption script and generate a password value.

Navigate to the pronghorn-core node modules directory.

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

Run the following command where mypassword is the password value that requires encryption.

$ npm run encrypt mypassword
Encrypted Password:
$ENC8ef3972b5766e64a98df4b11d6d3221d82812e8caed3459e5a0d

Use the encrypted password value, beginning with $ENC, instead of the plain-text values that are inserted in the properties.json file.

Vault Encryption

For information on vault-based encryption, see the HashiCorp Vault Encryption guide.

AAA

IAP supports local group authorization and external authentication, authorization and auditing (AAA). Local groups may be created and roles may be assigned. Users which have previously logged in to IAP may be assigned to local groups.

IAP comes pre-configured with a Local AAA adapter that stores user accounts and passwords in a MongoDB database. The adapter works well with a quick-start application but should not be used in production environments.

IAP supports the following external authentications.

Active Directory
LDAP
Radius

Secure MongoDB Connectivity in Local AAA

Use this section to set up the Local AAA adapter in IAP using a password and SSL protected MongoDB.

Note: The information presented here assumes MongoDB is not using authorization.

Set up the Admin user.

db.createUser(
{
    "user":"admin",
    "pwd":"password",
    "roles":[
        {
            "role":"root",
            "db":"admin"
        },
        {
            "role":"userAdminAnyDatabase",
            "db":"admin"
        },
        {
            "role":"clusterMonitor",
            "db":"admin"
        },
        {
            "role":"dbOwner",
            "db":"LocalAAA"
        },
        {
            "role":"dbOwner",
            "db":"pronghorn"
        }
    ]
}
)

Set up the Pronghorn user.

db.createUser(
{
    "user":"pronghorn",
    "pwd":"password",
    "roles":[
        {
            "role":"dbOwner",
            "db":"pronghorn"
        },
        {
            "role":"dbOwner",
            "db":"LocalAAA"
        },
        {
            "role":"clusterMonitor",
            "db":"admin"
        }
    ]
}
)

Set up the local AAA user.

db.createUser(
{
    "user":"localaaa_user",
    "pwd":"pronghorn",
    "roles":[
        {
            "role":"dbOwner",
            "db":"LocalAAA"
        }
    ]
}
)

Modify the mongod.conf file to turn on authorization.

/etc/mongod.conf

# network interfaces
net:
    port: 27017
    bindIp: 0.0.0.0  
# Listen to local interface only, comment to listen on all interfaces.
security:
    authorization: enabled

Modify the properties.json file.

/opt/pronghorn/current/properties.json

"id": "profile1",
"mongoProps": {
    "credentials": {
    "dbAuth": true,
    "passwd": "password",
    "user": "pronghorn"
    },
    "db": "pronghorn",
    "url": "mongodb://127.0.0.1:27017"
}

Modify properties for the MongoDB adapter via IAP (navigate to Admin Essentials > Adapters).

"properties": {
    "id": "mongo",
    "properties": {
        "credentials": {
            "dbAuth": true,
            "passwd": "password",
            "user": "pronghorn"
        },
        "db": "pronghorn",
        "url": "mongodb://127.0.0.1:27017"
    },

Modify Local AAA properties.

Note: In this example, "pronghorn" was used for the password. This is consistent with how the Local AAA user was set in Step 3 above.

"properties": {
    "id": "Local AAA",
    "type": "local_aaa",
    "properties": {
        "database": {
            "db": "LocalAAA",
            "url": "mongodb://127.0.0.1:27017",
            "credentials": {
                "dbAuth": true,
                "passwd": "pronghorn",
                "user": "localaaa_user"
            }
        }
    },
    "brokers": [
        "aaa"
    ],
    "groups": []
},

Restart MongoDB.
```
systemctl restart mongod
```
Stop Pronghorn (Itential).
```
systemctl stop pronghorn
```
Start Pronghorn (Itential).
```
systemctl start pronghorn
```
Check status of Pronghorn (Itential).
```
systemctl status pronghorn
```

Encrypt Passwords in Local AAA (Optional)

Itential recommends that all passwords are encrypted. This can be achieved by using the encryption script that is included within the pronghorn-core package or by using Vault Encryption.

Legacy Encryption

To encrypt passwords:

cd /opt/pronghorn/current/node_modules/@itential/pronghorn-core/utils
npm run encrypt.js

Alternately, you can use:

node encrypt.js

The encrypt tool will respond with a string that starts with $ENC. For example:

password:  $ENC93eb9439537ae34196db49409dda241c8282228cabd94098

pronghorn: $ENC93f88824437dfe5784c7570f99d72f1d81822788aad246995b

Replace the unencrypted password with the encrypted password.

Unencrypted

"passwd": "password"

Encrypted

"passwd": "$ENC93eb9439537ae34196db49409dda241c8282228cabd94098"

Note: If you need to add users in the Local AAA collection within MongoDB by using bcrypt-cli, refer to the Add Users and Groups section of the IAP Configuration guide for more information.

Vault Encryption

For vault-based encryption, see the Vault Encryption guide.

Additional Adapter Installation (Optional)

IAP uses network and OSS adapters to facilitate the integration of IAP with various systems and applications.

In order to add a new adapter to IAP, the adapter module must be installed under node_modules within the IAP installation directory. For example:

npm install @itentialopensource/adapter-db_mongo

Once the adapter module is installed, restart IAP and the adapter will be auto-discovered during IAP startup and become available when adding an adapter via the IAP UI.

Instantiate an adapter

From the IAP home page:

Click Admin Essentials in the left navbar.
Click the plus (+) icon in the top toolbar to open the Create dialog.
Select Adapter from the drop down and then enter the desired adapter name. Select the type and click the Create button. The main user interface (UI) for Adapters will display, consisting of the Configuration and Logging tabs.
A skeleton JSON object of the Service Config for the adapter will be created and can be edited to match your environment. Use the toggle switch located in the upper-right corner to turn-on the Advanced View editor.
Once all changes are made, save the Service Config for your adapter.
Adapter connectivity can be confirmed from the Admin Essentials home page in the Alerts card.

Import adapter service config

From the Admin Essentials home page:

Click the Import icon in the top toolbar to display the Import dialog.
Select Adapter from the dropdown.
You can import (upload) your Adapter file by drag-and-drop, or click Browse Files to find and select the Adapter you want to import.
Once the Adapter is imported, the name of the Adapter will pre-populate from the file, along with a description, in the Import modal. You can change the description, as needed, to provide specific information for your import and to better communicate what the adapter is used for within your platform.
Once you click the Import button, and upon successful import, the Adapter will be added to the collection list in the left sidebar.

Refer to the Admin Essentials User Guide for more information.

Troubleshooting Hints

User Cannot Log In

The default user and password values are admin@pronghorn and admin.

User Cannot See Applications

Upon browsing to the IAP Web UI as the admin@pronghorn user for the first time, you will be presented with the following message:

You currently don't have access rights to any apps. If you think that's a mistake, please ask your Administrator for help.

Be sure to add permissions to the admin group for your applications.

Authorization Manager

NSO Service Models Missing

Be sure to add the service models to the ncs.conf file load-path.

<load-path>
    <dir>./packages</dir>
    <dir>./yang</dir>
    <dir>${NCS_DIR}/etc/ncs</dir>

    <!-- To disable northbound snmp altogether -->
    <!-- comment out the path below -->
    <dir>${NCS_DIR}/etc/ncs/snmp</dir>
</load-path>

Invalid Credentials for Local AAA

If you are getting invalid credentials, the Local AAA user has not been set up properly, or you have the wrong credentials or parameters in your properties file for the Local AAA adapter.

Check to see if the user and password for Local AAA is valid:

mongo -u localaaa_user -p pronghorn LocalAAA

show users....

If you are logged in and can see the configured users, check the Local AAA adapter properties to verify they are set correctly. The same also applies to pronghorn if IAP does not come up; be sure the pronghorn user and password are valid in the properties.json file and in the adapter properties for MongoDB.

Itential Automation Platform

Help us improve by sending feedback...

On this page:

Installation

Requirements

Physical Servers vs Virtual Machines

Production

Lab and Development

IAP Server

MongoDB Server

Redis Shared-Token Server

RabbitMQ Server

Alternative Lab and Development Environments

Host Operating System

OS Packages

Security

Operational

Required Software

Privileged User Access

Installing Dependencies

Node.js

Post Installation

Node.js Package Manager

Post Installation

Redis

Post Installation

Configuration

Max Memory

RabbitMQ

Post Installation

Event Deduplication

Operational Requirements

Required Third-Party Plugins

Installation Steps

MongoDB

Required Authorization for the IAP MongoDB User

Post Installation

Standalone Server

Template Builder Dependencies

Base Dependencies

Security Dependencies

Testing the Template Builder Security Configuration

Installing IAP

Installation

Custom Directory Options

Configuration

DB Migration

Migration Script Help Options

Start IAP

Access IAP Web UI

Password Encryption

Legacy Encryption

Vault Encryption

AAA

Secure MongoDB Connectivity in Local AAA

Encrypt Passwords in Local AAA (Optional)

Legacy Encryption

Vault Encryption

Additional Adapter Installation (Optional)

Instantiate an adapter

Import adapter service config

Troubleshooting Hints

User Cannot Log In

User Cannot See Applications

NSO Service Models Missing

Invalid Credentials for Local AAA