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 are 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 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
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
MongoDB 3.6
Node.js 8
Node.js Package Manager 6

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 Ansible Tower
Cisco NSO 4.7 NSO 4.7
Cisco NSO 4.6 NSO 4.6
Cisco NSO 4.5 NSO 4.5
Cisco NSO 4.4 NSO 4.4
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 and MongoDB. Links to additional documentation resources have been provided below.

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

Node.js

Please refer to the official Node.js installation documentation for your selected OS.

Installation

  1. Download the RPM package at the URL.

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

  2. Install the RPM package.

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

    node —v
    v8.11.4

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 with the following command.

npm -v

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

Installation

  1. Run the install command.

    yum install redis
  2. Start Redis as a service.

    sudo service redis start
  3. Verify 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.

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.

Transparent Huge Pages

To disable transparent huge pages (THP) on RHEL and CentOS systems:

  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

Template Builder Dependencies

To install Template Builder dependencies:

  1. Consult the release notes to verify if your version of python is supported.

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

    pip install textfsm

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. Change to directory (cd) where the package is stored.

  3. Install in the /opt directory as a privileged user.

    sudo 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 basic sample 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"
  }
}

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. Please ensure 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 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 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

Troubleshooting

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

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>