Itential Automation Platform

On this page:

Installation

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 is provided.

Requirements

This section includes required and recommended installation requirements.

Production

All requirements in this section are relevant 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 100 GB
/opt/pronghorn 200 GB
/var/log/redis 50 GB

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 64 GB. 128 GB is recommended.
Disk 1 TB
Disk

The following table describes disk space allocation requirements.

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

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 16 GB
Disk 400 GB

Disk

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

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

Development

A development environment may include MongoDB, Redis, and 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 15 GB
/opt/pronghorn 50 GB
/var/log/redis 15 GB
/var/log/mongo 20 GB
/data 100 GB

Host Operating System

IAP is supported on the following operating systems.

OS Release Production Development
CentOS 64-bit CentOS 7 x x
Ubuntu 64-bit Ubuntu 16.04.1 x x
RHEL 64-bit RHEL 7 x x
Mac OS X 64-bit Development only. x

Note: Customers with current support agreements will continue to receive support for CentOS 6.8, Ubuntu 14.04.5, and RHEL 6.8 until they upgrade.

OS Packages

Install the following Operating system packages on each IAP server.

  • coreutils
  • openssl
  • ntp
  • nscd

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
MongoDB 3.6
Node.js 10.16
Node.js Package Manager 6
RabbitMQ 3.7

Note: The Itential Automation Platform (IAP) is compatible with several third-party software products for network operating environments. Beginning with the system requirements for 2019.1.2, 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 versions are supported.

Component Version Documentation
Ansible Tower 3.1.4 Ansible Tower
Cisco VTS 2.6 VTS 2.6
Cisco NSO 5.1 NSO 5.1
Cisco NSO 4.7.3.2 NSO 4.7
Cisco NSO 4.6.2 NSO 4.6
Java JDK 1.8 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, MongoDB, and RabbitMQ. Links to additional documentation resources have been provided below.

Node.js and Redis must be installed on the same server as IAP. Both MongoDB and RabbitMQ may be installed on separate servers from IAP, but IAP must be able to access MongoDB via the port MongoDB is running on and RabbitMQ via the port RabbitMQ is running on. The following instructions will assume MongoDB and RabbitMQ share the server with IAP.

Node.js

Please refer to the official Node.js installation documentation for CentOS and Ubuntu.

Installation

  1. Download the RPM package at the URL.

    https://rpm.nodesource.com/pub_10.x/el/7/x86_64

  2. Install the RPM package.

    rpm -ivh nodejs-10.16.0-1nodesource.x86_64.rpm
  3. Check the Node.js version.

    $ node —v
    v10.16.0

Node.js Package Manager

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

Installation

Check the NPM version.

$ npm -v
5.4.0

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

Redis

The Redis Quick Start page states the following.

The suggested way of installing Redis is compiling it from sources as Redis has no dependencies other than a working GCC compiler and libc. Installing it using the package manager of your Linux distribution is somewhat discouraged as usually the available version is not the latest.

At the time of this distribution, the latest stable Redis release was 3.2.

Configuration

Apply the following recommended Redis configurations to a production 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 redis.conf file.

OS Packages

Install the following packages.

  • numactl
  • tuned
  • tuned-utils
Soft User Limits

Configure the maximum number of files available to the Redis user.

nofile = 10032
Transparent Huge Pages

Disable transparent huge pages.

  1. Refer to the THP in MongoDB Tutorial.

  2. Install the disable-transparent-hugepages startup script into the init.d directory.

  3. Create a custom tuned profile to ensure tuned does not re-enable transparent huge pages.

    /etc/tuned/no-thp:
    [main] include=virtual-guest
    [vm] transparent_hugepages=never
  4. Configure tuned to use the custom profile.

    tuned-adm profile no-thp

Installation

  1. Run the install command.

    yum install redis
  2. Start Redis as a service.

    sudo service redis start
  3. Verify that the Redis service is running properly.

    $ sudo service redis status
    Redirecting to /bin/systemctl status redis.service
    ● redis.service - Redis persistent key-value database
    Loaded: loaded (/usr/lib/systemd/system/redis.service; enabled; vendor preset: disabled)
    Drop-In: /etc/systemd/system/redis.service.d
       !"limit.conf
    Active: active (running) since Fri 2018-11-09 16:13:03 UTC; 2 weeks 6 days ago
    Main PID: 7665 (redis-server)
    CGroup: /system.slice/redis.service
       !"7665 /usr/bin/redis-server 127.0.0.1:7379
    Nov 29 19:04:24 localhost.localdomain redis[7665]: Background saving started by pid 21629
    Nov 29 19:04:24 localhost.localdomain redis[21629]: DB saved on disk
    Nov 29 19:04:24 localhost.localdomain redis[7665]: Background saving terminated with success
    Nov 29 19:09:25 localhost.localdomain redis[7665]: 10 changes in 300 seconds. Saving...
    Nov 29 19:09:25 localhost.localdomain redis[7665]: Background saving started by pid 21965
    Nov 29 19:09:25 localhost.localdomain redis[21965]: DB saved on disk
    Nov 29 19:09:25 localhost.localdomain redis[7665]: Background saving terminated with success
    Nov 29 19:14:26 localhost.localdomain redis[7665]: 10 changes in 300 seconds. Saving...
    Nov 29 19:14:26 localhost.localdomain redis[7665]: Background saving started by pid 22305
    Nov 29 19:14:26 localhost.localdomain redis[7665]: Background saving terminated with success

Post Installation

  1. Start Redis Server in the background.
  2. Verify the server is running.
  3. Verify Redis is enabled. If not, enable it for automatic start.

RabbitMQ

Please refer to the official RabbitMQ installation guide.

Installation

  1. Run the install command.

    yum install rabbitmq-server
  2. Start RabbitMQ as a service.

    systemctl start rabbitmq-server
  3. Verify the RabbitMQ service is running properly.

    $ systemctl status rabbitmq-server
    ● rabbitmq-server.service - RabbitMQ broker
    Loaded: loaded (/usr/lib/systemd/system/rabbitmq-server.service; disabled; vendor preset: disabled)
    Active: active (running) since Mon 2019-08-19 20:01:46 UTC; 16s ago
    Main PID: 5799 (beam.smp)
    CGroup: /system.slice/rabbitmq-server.service
            ├─5799 /usr/lib64/erlang/erts-5.10.4/bin/beam.smp -W w -K true -A30 -P 1048576 -- -root /usr/lib64/erlang -progname erl -- -home /var/lib/rabbitmq -- -pa /...
            ├─5814 /usr/lib64/erlang/erts-5.10.4/bin/epmd -daemon
            ├─5883 inet_gethost 4
            └─5884 inet_gethost 4
    
    Aug 19 20:01:45 localhost.localdomain systemd[1]: rabbitmq-server.service: Got notification message from PID 5839, but reception only permitted for main PID 5799
    Aug 19 20:01:45 localhost.localdomain systemd[1]: rabbitmq-server.service: Got notification message from PID 5840, but reception only permitted for main PID 5799
    Aug 19 20:01:46 localhost.localdomain rabbitmq-server[5799]: RabbitMQ 3.3.5. Copyright (C) 2007-2014 GoPivotal, Inc.
    Aug 19 20:01:46 localhost.localdomain rabbitmq-server[5799]: ##  ##      Licensed under the MPL.  See http://www.rabbitmq.com/
    Aug 19 20:01:46 localhost.localdomain rabbitmq-server[5799]: ##  ##
    Aug 19 20:01:46 localhost.localdomain rabbitmq-server[5799]: ##########  Logs: /var/log/rabbitmq/rabbit@localhost.log
    Aug 19 20:01:46 localhost.localdomain rabbitmq-server[5799]: ######  ##        /var/log/rabbitmq/rabbit@localhost-sasl.log
    Aug 19 20:01:46 localhost.localdomain rabbitmq-server[5799]: ##########
    Aug 19 20:01:46 localhost.localdomain systemd[1]: Started RabbitMQ broker.
    Aug 19 20:01:46 localhost.localdomain rabbitmq-server[5799]: Starting broker... completed with 0 plugins.

Post Installation

  1. Start RabbitMQ Server in the background.
  2. Verify the service is running.
  3. Verify RabbitMQ is enabled. If not, enable it for automatic start.

MongoDB

Please refer to the official MongoDB installation instructions.

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.

Post Installation

  1. Start the mongod service in the background.
  2. Verify the service is running.
  3. Verify MongoDB is enabled to start on system boot. If not, enable it for automatic start.

Adapter Integration

IAP uses network and OSS adapters to facilitate the integration and interaction of IAP with various systems, applications, and environments. For more information, see the IAP Integrations User Guide.

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.

  1. Transfer the IAP package to the server.

  2. cd to directory where the package is stored.

  3. Install in the /opt directory.

    bash itential-<build-id>_version.linux.x86_64.bin -i

Note: Execute the installer with the -v option for verbose output.

Configure IAP Properties

A sample, basic, properties.json configuration file is provided below. This configuration assumes that both MongoDB and Redis are running locally and are not encrypted in default configurations.

When preparing production environments, be sure to harden any MongoDB or Redis connections that are running on separate servers.

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

IAP Migration Script

The IAP Migration Script must be run in order to migrate properties from the properties.json file to the Mongo database. It should be run after IAP installation and before starting IAP for the first time.

  1. Enter the migration script directory /opt/pronghorn/current/node_modules/@itential/pronghorn-core/migration_scripts.

  2. Run the migration script.

    node migratePropertiesToDatabase.js
  3. Respond to the migration script prompts based on the output below.

    Retrieving properties.json file...
    Found properties.
    
    Connecting to Database...
    Are you sure you want to delete the following databases:
    iap_profiles
    service_configs
    (y)es (n)o y
    y
    No service_configs collection detected, skipping.
    No iap_profiles collection detected, skipping.
    localhost:5671 is the current RabbitMQ endpoint, do you wish to change it?
    (y)es (n)o n
    n
    Retaining: localhost:5671
    Would you like to run WITHOUT SSL?
    (y)es (n)o y
    y
    RabbitMQ credentials currently set to
    
    username: guest
    password: guest
    
    do you wish to change them?
    (y)es (n)o n
    n
    Retaining guest credentials
    RabbitMQ properties:
    
    {
    "protocol": "amqp",
    "hostname": "localhost",
    "port": 5672,
    "username": "guest",
    "password": "$ENC84ff82395069f15bdb8e01479ad6221b828b208ea7",
    "locale": "en_US",
    "frameMax": 0,
    "heartbeat": 0,
    "vhost": "/",
    "certPath": "",
    "keyPath": "",
    "passphrase": "guest",
    "caPath": ""
    }
    
    Press enter to continue.
    Backing up properties.json to /opt/pronghorn/itential-platinum-20192_2019.2.0/properties_07ced4cb-c61f-4a37-9aef-f662b98c7398.json
    
    Loading services...
    (node:6130) Warning: Use Cipheriv for counter mode of aes-256-ctr
    Services loaded 35
    
    Generating init file data...
    Config data generated.
    
    Generating DB data...
    DB data generated.
    
    Connection established.
    
    Creating databases...
    Creating service_configs
    Creating iap_profiles
    Database creation complete.
    
    Creating IAP database config...
    Could not find adapter properties for RADIUS... Addition to the profile services list will be skipped.
    Could not find adapter properties for azure_aaa... Addition to the profile services list will be skipped.
    Could not find adapter properties for LDAP... Addition to the profile services list will be skipped.
    Could not find adapter properties for Email... Addition to the profile services list will be skipped.
    Could not find adapter properties for PolicyEngine... Addition to the profile services list will be skipped.
    Could not find adapter properties for Prospector... Addition to the profile services list will be skipped.
    Could not find adapter properties for NSO... Addition to the profile services list will be skipped.
    Could not find adapter properties for AnsibleManager... Addition to the profile services list will be skipped.
    Collection iap_profiles created!
    IAP database config created.
    
    Creating service configs entries...
    Collection service_configs created!
    Service configs entries created.
    
    Cleaning up properties.json...
    Migration complete!

Note: The migration script will modify properties.json during migration. A backup of properties.json is created in the same directory as the original properties.json file. The backup will will look similar to properties_b3b9a216-3408-4cc8-b19f-055b9ee30c75.json.

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.

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

  1. Navigate to pronghorn-core node modules directory.

    cd /opt/pronghorn/current/node_modules/@itential/pronghorn-core
  2. Run the following command where mypassword is the password values that requires encryption.

    $ npm run encrypt mypassword
    Encrypted Password:
    $ENC8ef3972b5766e64a98df4b11d6d3221d82812e8caed3459e5a0d

Use the encrypted password value, beginning with $ENC, in place 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 the Local AAA adapter which stores user accounts and passwords in a MongoDB database. This adapter will work well with a quick-start application but should not be used in production environments.

IAP supports the following external authentications.

  • Active Directory
  • LDAP
  • Radius

Troubleshooting

User Cannot Log In

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

User Cannot See Applications

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>