2018.3

Itential Automation Platform

On this page:

Installation

This section 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 required and recommended installation requirements.

Production

All requirements in this section are relevent to a production IAP environment.

IAP Server

The following table describes required IAP production server components.

Component Requirement
Server Bare metal or virtual machine.
CPU Eight (8) 64-bit x86 CPU cores. Sixteen (16) cores are recommended.
RAM 32GB. 64GB recommended.
Disk 500GB
Disk

The following table describes disk space allocation requirements.

Path Min Size
/var/log/pronghorn 100GB
/opt/pronghorn 200GB
/var/log/redis 50GB

MongoDB Server

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

Component Requirement
Server Bare metal or virtual machine.
CPU Eight (8) 64-bit x86 CPU cores. Sixteen (16) cores are recommended.
RAM 64GB. 128GB is recommended.
Disk 1TB
Disk

The following table describes disk space allocation requirements.

Path Min Size
/var/log/mongo 150GB
/data 850GB

Lab

A lab environment may include MongoDB, Redis, NSO, and IAP on a single server.

Component Requirement
Server Bare metal or virtual machine.
CPU Eight (8) 64-bit x86 CPU cores. Sixteen (16) cores are recommended.
RAM 16GB
Disk 400GB

Disk

The following table describes disk space allocation requirements for a single server lab environment.

Path Min Size
/var/log/pronghorn 25GB
/opt/pronghorn 100GB
/var/log/redis 25GB
/var/log/mongo 50GB
/data 200GB

Development

A development environment may include MongoDB, Redis, and IAP on a single server.

Component Requirement
Server Virtual machine
CPU Eight (4) 64-bit x86 CPU cores. Sixteen (16) cores are recommended.
RAM 8GB
Disk 200GB

Disk

Path Min Size
/var/log/pronghorn 15GB
/opt/pronghorn 50GB
/var/log/redis 15GB
/var/log/mongo 20GB
/data 100GB

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

IAP requires the following software be installed.

Software Version
Redis 3.2.x
MongoDB 3.4.x
Node.js 8.x
NPM 5.x or 6.x

Note: The Itential Automation Platform (IAP) is compatible with several third-party software products for network operating environments. Beginning with the system requirements for 2018.3.11, all third-party software version compatibility is documented in Release Notes. To get the most up-to-date requirements for any third-party software, including open source, first identify which IAP release you’re using and then refer to the respective release note.

Integration Compatibility

IAP may require additional software or services depending on the integrations that are required. The following minor versions are supported; refer to your respective release note for the most up-to-date versions.

Component Version Documentation
Ansible Tower 3.1.x Ansible Tower
Cisco NSO 4.7.x NSO 4.7
Cisco NSO 4.6.x NSO 4.6
Cisco NSO 4.5.x NSO 4.5
Cisco NSO 4.4.x NSO 4.4
Java JDK 1.8.x JDK 8
Itential Tools NSO package 1.8+ While NSO integration is optional, if NSO adapter is used, the Itential Tools package must be found in NSO.

Installing Dependencies

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

Node.js must be installed on the same server as IAP. Redis and MongoDB 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.

Note: The following instructions assume component installation on a server running CentOS 7. The Redis and MongoDB 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 IAP release.

Verify that Node.js is installed and available from the PATH environment variable.

$ command -v node
/bin/node

Check which version of Node.js is installed.

$ node -v
v8.16.0

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.

$ command -v npm
/bin/npm

Check which version of npm is installed.

$ npm -v
6.13.4

If the version of npm is not greater than or equal to version 6, then upgrade npm with the following command.

npm i -g npm@6.13.4

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.

  1. Edit /etc/redis.conf on the Redis server.

  2. Comment out bind 127.0.0.1 so that it becomes #bind 127.0.0.1.

  3. Restart Redis.

    sudo systemctl restart redis

Note: These 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: Additional Redis configurations for a production environment can be found in the Redis Configuration section of the IAP Admin Guide.

MongoDB

Please refer to the official MongoDB installation instructions.

Post Installation

To verify a successful MongoDB installation:

  1. Start the MongoDB service.

    sudo service mongod start

  2. Show the operational status of the mongod service.

    $ sudo service mongod status
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.

Please go to the MongoDB Configuration section of the IAP Admin Guide to review configuration options 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.

  1. Edit /etc/mongod.conf on the MongoDB server.

  2. Change the line starting with bindIp: 127.0.0.1 so that it becomes bindIp: 0.0.0.0.

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

To install Template Builder dependencies:

  1. Install Pip for Python 2.

    sudo yum -y install python-pip

  2. Run the following commands. Once TextFSM is available, the template parser will be able to function properly.

    pip install textfsm

Installing IAP

Perform the following steps to install the IAP software. 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:

  1. Transfer the IAP binary package to the server.

  2. Change to directory (cd) where the package is stored.

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

Configuration

Upon successful installation, a default IAP configuration file will be created here: /opt/pronghorn/current/properties.json. The properties.json file will need to be updated to match the environment prior to starting IAP. At a minimum, the MongoDB and Redis properties need to be correctly configured in order to start IAP, which the following steps describe.

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

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

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

    Examples

      # Option 1) Hosted locally on IAP server
  "host": "localhost"

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

  4. For reference, an example properties.json with MongoDB and Redis parameters set to localhost for an all-in-one development install is below.

    {
"applicationProps": {
    "directory": "./node_modules/"
},
"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",
    "user_config": "node_modules/@itential/pronghorn-core/ui/views/user_config.jade",
    "group_config": "node_modules/@itential/pronghorn-core/ui/views/group_config.jade",
    "new_user": "node_modules/@itential/pronghorn-core/ui/views/dialogs/new_user.jade",
    "edit_user": "node_modules/@itential/pronghorn-core/ui/views/dialogs/edit_user.jade",
    "new_group": "node_modules/@itential/pronghorn-core/ui/views/dialogs/new_group.jade",
    "fav_icon": "node_modules/@itential/pronghorn-core/ui/img/favicon.ico"
},
"authenticationProps": {
    "description": "audit",
    "uniqueSession": false,
    "admins": [{
    "provenance": "Local AAA",
    "group": "pronghorn_admin"
    }]
},
"expressProps": {
    "description": "Express Server",
    "express_http": {
    "enable": true,
    "port": 3000
    },
    "express_https": {
    "enable": false,
    "port": 3443,
    "key": "./keys/key.pem",
    "cert": "./keys/cert.pem",
    "secureProtocol": "TLSv1_2_method",
    "client_reneg_limit": 1,
    "client_reneg_window": 600
    }
},
"loggerProps": {
    "description": "Logging",
    "log_max_files": 100,
    "log_max_file_size": 1048576,
    "log_level": "warn",
    "log_directory": "/var/log/pronghorn",
    "log_filename": "pronghorn.log",
    "console_level": "warn"
},
"mongoProps": {
    "credentials": {
    "passwd": "itentialPassword",
    "user": "itentialUser"
    },
    "db": "pronghorn",
    "url": "mongodb://localhost:27017"
},
"redisProps": {
    "host": "localhost",
    "port": 6379
},
"auditProps": {
    "description": "Audit",
    "audit": true,
    "brokerValidation": true
},
"pathProps": {
    "description": "File Path Variables",
    "sdk_dir": "/opt/pronghorn-applications",
    "encrypted": true
},
"statsCollectorProps": {
    "description": "Health Dashboard",
    "persistence_url": "mongodb://localhost:27017/pronghorn",
    "TIMEOUT_INTERVAL": 120000,
    "FLUSH_THRESHOLD": 86400000
},
"adapterProps": {
    "adapters": [{
        "id": "Local AAA",
        "type": "local_aaa",
        "properties": {
        "database": {
            "db": "LocalAAA",
            "url": "mongodb://localhost:27017",
            "credentials": {
            "dbAuth": false
            }
        }
        },
        "brokers": [
        "aaa"
        ]
    },
    {
        "id": "mongo",
        "properties": {
        "db": "pronghorn",
        "url": "mongodb://localhost:27017"
        },
        "type": "MongoDriver",
        "brokers": [
        "persistence"
        ],
        "groups": []
    },
    {
        "id": "redis",
        "properties": {
        "host": "localhost"
        },
        "type": "Redis",
        "brokers": [
        "persistence"
        ]
    }
    ]
},
"alarmProps": {
    "ip": "127.0.0.1",
    "community": "public",
    "properties": {
    "port": 161,
    "retries": 1,
    "timeout": 5000,
    "transport": "udp4",
    "trapPort": 162,
    "version": "V1"
    },
    "type": "trap"
}
}

Start IAP

  1. Start IAP and set to auto-start on server reboot.

      systemctl enable --now pronghorn

  2. 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 can be run to monitor IAP logs during startup or general usage.

Access IAP Web UI

IAP can 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.

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

Perform the following steps to run the encryption script and generate a password value.

  1. Navigate to the pronghorn-core node module directory.

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

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

  npm run encrypt mypassword

  > @itential/pronghorn-core@6.1.12 encrypt /opt/pronghorn/ph6/node_modules/@itential/pronghorn-core
  > node utils/encrypt.js "mypassword"

  Encrypted Password:  $ENC8ef3972b5766e64a98df4b11d6d3221d82812e8caed3459e5a0d

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

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 which 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

For additional information see the sections on Active Directory Authentication and Authorization in the IAP Admin Guide.

Secure MongoDB Connectivity in Local AAA

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

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

  1. Setup 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"
        }
    ]
}
)

  2. Setup the Pronghorn user.

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

  3. Setup the Local AAA user.

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

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

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

  6. Modify properties for the Mongo adapter via IAP (navigate to Settings > Services > Adapters).

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

  7. 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": []
},

  8. Restart MongoDB.

    systemctl restart mongod

  9. Stop Pronghorn (Itential).

    systemctl stop pronghorn

  10. Start Pronghorn (Itential).

    systemctl start pronghorn

  11. Check status of Pronghorn (Itential).

    systemctl status pronghorn

Encrypt Passwords in Local AAA (Optional)

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"

Troubleshooting Hints

User Cannot Log In

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

Note: Default user if using Local AAA adapter.

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