Itential Automation Gateway

On this page:

Properties

Overview

This guide provides information pertaining to configuring the properties file for Itential Automation Gateway (IAG). This entails configuration for its web server, associated integrations, and custom content supplied by end users.

Configuration UI

Starting in release 2021.2, the Configuration user interface (UI) is introduced to administer IAG properties. The UI provides a simple and straightforward way to view and modify the IAG server configuration.

Figure 1: Configuration UI

Configuration UI

All configuration parameters except those that reside in the System and Databases section of the properties file can be modified via the UI. The changes take effect dynamically without rebooting the IAG server. With the introduction of RBAC in the 2021.2 release, configuration changes are restricted to users who are members of the admin group.

Note: Breaking changes have been made to the data types of certain configuration parameters. To learn more, refer to IAG Breaking Changes in Product Notices.

Backup Database

Starting in 2021.2, the IAG server configuration is saved in the database, automation-gateway.db. Therefore, it is very important to take a backup of this file before doing any upgrades. During the first boot of the server, the configuration parameters found in the properties file are injected into the database. This applies to both newly created property files as well as pre-2021.2 property files being utilized to upgrade to 2021.2. All subsequent reboots of the server will use the configuration stored in the database. Any changes to the configuration parameters after the first server boot are required to be made from the Configuration UI. The only exception to this paradigm are parameters found in the System and Databases sections of the 2021.2 properties file. Those parameters are still modified by editing the properties file and restarting the server.

Save Config

To modify the configuration for a subsystem, (i.e., Ansible, Nornir, Scripts), click Ansible in the left sidenav menu and edit the properties. Once changes are ready to be saved, click the save icon button on the top left corner and verify the success dialog appears on the top right corner of the page.

Figure 2: Save Config UI

Save Config UI

System Configuration

The System Configuration menu option is read-only. The page is only to be used to view the System Configuration and cannot be edited.

Figure 3: System Configuration

System Configuration

Properties.yml

Sample Properties File

An example properties.yml file is shown below. Note that the configuration is highly self-documenting and ordered by general webserver categories as well as one category per integration (Ansible, Nornir, etc).

---
---
# Notes:
#
# While many customizations can be made based on your environment and which integrations you
# would like enabled, this file is meant to mimic the installation process found at
# https://docs.itential.io/ as closely as possible so the user can use as many defaults as possible.
#
# This configuration file accepts any valid YAML syntax including the bash-like syntax for lists, etc.

##########
# System #
##########

# The port on which Automation Gateway server will listen for requests.
# Mutually exclusive with bind_list
port: 8083

# The IP addresses to bind the web application to.
# For ipv4 only use "0.0.0.0", for ipv6 and ipv4 use "[::]"
# Mutually exclusive with bind_list
#bind_address: [::]

# List of addresses and ports to bind to.
# This setting will override both 'port' and 'bind_address'
#bind_list:
#  - "0.0.0.0:8083"

# Base of url for external proxy, used for generating redirects:
# external_address: 'http://automation-gateway.example.com:8080'

# The number of http server threads for handling requests.
# A good starting point is 2-4 x NUM_CORES then adjust based on observed workload.
#http_server_threads: 8

# A flag that determines whether authentication is disabled or not.
# Warning: only disable authentication for temporary, non production testing.
authentication_disabled: False

# The maximum number of concurrent sessions allowed.
authentication_max_sessions: 5000

# The idle timeout of each session (in seconds).
authentication_idle_timeout: 600

# A boolean flag that enables password reset support (default=False if absent/misconfigured).
password_reset_enabled: True

# NOTE: Log levels for Automation Gateway Server are as follows.
# In order of ascending severity: DEBUG, INFO, WARNING, ERROR, or CRITICAL.
# Log messages of equal and greater severity will be displayed in the relevant log.
# Example: logging_level INFO will display log messages with a severity of INFO -> CRITICAL.
# (default=INFO if absent/misconfigured)

# Automation Gateway Server Logging Level
logging_level: INFO

# Automation Gateway HTTP Server Logging Level
# NOTE: request details are DEBUG level log messages, it may be useful to set this to DEBUG
http_logging_level: INFO

# A flag that enables/disables parameter schema validation for content decorations.
# Generally enabled when using multiple types per parameter, or when testing decorations.
# Example: "commands" could be a literal list of commands, or a string representing a jinja
#          variable from your host's variables "{{commands}}", etc.
strict_args: True

#############
# Databases #
#############

# Path to the main Automation Gateway sqlite database file.
data_file: "sqlite:////opt/automation-gateway/data/automation-gateway.db"

# A flag which determines whether or not audit logging is enabled. (default=True if absent/misconfigured)
audit: True

# The number of days (days >= 0) worth of data to retain in the audit log database
# Records earlier than the specified days will be deleted. (default=None if absent/misconfigured)
audit_retention_days: 30

# Path to the auxillary Automation Gateway sqlite database file for audit logs.
audit_db_file: "sqlite:////opt/automation-gateway/data/automation-gateway_audit.db"

# Path to the auxillary Automation Gateway sqlite database file for execution logs.
exec_history_db_file: "sqlite:////opt/automation-gateway/data/automation-gateway_exec_history.db"

#########
# Repos #
#########

# A boolean flag that enables Git repository (repos) support (default=True if absent/misconfigured).
repos_enabled: True

# Path to the location where repository clones should be stored for use by Automation Gateway.
repos_path: "/opt/automation-gateway/repos"

###########
# Ansible #
###########

# A boolean flag that enables Ansible support (default=True if absent/misconfigured).
ansible_enabled: True

# A boolean which logs additional debug messages when executing Ansible modules, roles, or playbooks.
# Set the ansible_debug property to True to log additional debug messages when
# executing Ansible modules, roles, or playbooks. (default=False if absent/misconfigured)
ansible_debug: False

# A flag to prevent deletion of the temporary files generated by executing
# Ansible content (modules, collections, roles, playbooks). (default=False if absent/misconfigured)
no_cleanup: False

# Path of the file that contains a password used by ansible-vault to encrypt sensitive data.
# Uncomment this property if you will be using Ansible vault encrypted variables.
# Be sure to secure this file with permissions of 0200 or 0400.
#vault_password_file: "/opt/automation-gateway/conf/.vault_password_file"

# Path to the Ansible external inventory file (folders not valid).
# A valid file will disable Ansible Internal inventory and instead use only this Ansible External inventory.
inventory_file: "/opt/automation-gateway/ansible/inventory/hosts"

# Path(s) to the Ansible modules that should be discovered by Automation Gateway and appended to Ansible's execution environment.
# All non-collection paths (see Ansible 2.10 notes below) known to Ansible are already included and do not need to be specified.
# Additionally, this parameter needs to be configured if the path reported by 'ansible --version' is incorrect
# or you would like to customize/trim down the set of Ansible modules that will be discovered (see Ansible<=2.9 notes below).
# Trim example for ansible 2.9: "/usr/local/lib/python3.9/site-packages/ansible/modules/network"
# NOTE: Use only the site-packages paths you need for your installation to avoid
#       cross environment issues in the case where multiple of these paths exist
module_path:
  # System installed Python, Ansible installed globally:
  - "/usr/local/lib/python3.9/site-packages/ansible/modules/network"
  - "/usr/local/lib/python3.9/site-packages/ansible_collections"
  # Manually installed Python, Ansible installed by the itential user
  - "/home/itential/.local/lib/python3.9/site-packages/ansible/modules/network"
  - "/home/itential/.local/lib/python3.9/site-packages/ansible_collections"
  # Any installation method for Python, Ansible installed inside of a virtualenv at $HOME/automation-gateway
  - "/home/itential/automation-gateway/lib/python3.9/site-packages/ansible/modules/network"
  - "/home/itential/automation-gateway/lib/python3.9/site-packages/ansible_collections"
  # Default location for custom content per the setup script
  - "/usr/share/ansible/modules"

# Path(s) to the Ansible collections that should be discovered by Automation Gateway and exclusively used in Ansible's execution environment.
# Due to differences in collections before/after Ansible 2.9, these will be the only paths relevant during discovery AND execution.
collection_path:
  # The first path will be the default location for additional collection installations via the API/GUI
  - "/opt/automation-gateway/.ansible/collections"
  ## The remaining paths will be used only for discovery and execution
  # Default location for custom content per the setup script
  - "/usr/share/ansible/collections"

# Path(s) to the Ansible roles that should be discovered by Automation Gateway and appended to Ansible's execution environment.
role_path:
  # The first path will be the default location for additional role installations (via the API or ansible-galaxy)
  - "/opt/automation-gateway/.ansible/roles"
  # Default location for custom content per the setup script
  - "/usr/share/ansible/roles"

# Path(s) to customized roles that extend device support of the Itential roles found in the release, i.e., itential_cli, itential_get_config.
#extended_device_role_path:
  #This is a sample path to roles that extend device support
  #- /usr/share/device_support/roles


# Discovery behavior for Ansible playbooks. Determines whether or not to
# recursively search the directories found in the 'playbook_path' parameter, or
# to only search those directories and no deeper. (default=True if absent/misconfigured)
playbook_recursive: True

# Path(s) to the Ansible playbooks that should be discovered by Automation Gateway and appended to Ansible's execution environment.
playbook_path:
  # Default location for custom content per the setup script
  - "/usr/share/ansible/playbooks"
  ## Default Itential custom content locations - uncomment to display some sample playbooks
  # - "/usr/local/lib/python3.9/site-packages/automation_gateway/integrations/playbooks"
  # System installed Python, Automation Gateway installed globally:
  # - "/usr/local/lib/python3.9/site-packages/automation_gateway/integrations/playbooks"
  # Manually installed Python, Automation Gateway installed by the itential user
  # - "/home/itential/.local/lib/python3.9/site-packages/automation_gateway/integrations/playbooks"
  # Any installation method for Python, Automation Gateway installed inside of a virtualenv
  # - "/home/itential/automation-gateway/lib/python3.9/site-packages/automation_gateway/integrations/playbooks"

#################
# HTTP_Requests #
#################

# A boolean flag that enables HTTP_Requests support (default=True if absent/misconfigured).
http_requests_enabled: True

###########
# NETCONF #
###########

# A boolean flag that enables HTTP_Requests support (default=True if absent/misconfigured).
netconf_enabled: True

###########
# Netmiko #
###########

# A boolean flag that enables Netmiko support (default=False if absent/misconfigured).
netmiko_enabled: True

##########
# Nornir #
##########

# A boolean flag that enables Nornir support (default=False if absent/misconfigured).
nornir_enabled: True

# Path to the Nornir configuration file.
# A valid file will allows the use of Nornir External inventory.
nornir_config_file: "/opt/automation-gateway/nornir/config.yaml"

# Discovery behavior for Nornir modules. Determines whether or not to
# recursively search the directories found in the 'nornir_module_path' parameter, or
# to only search those directories and no deeper. (default=True if absent/misconfigured)
nornir_module_recursive: True

# Path(s) to the Nornir modules that should be discovered by Automation Gateway.
nornir_module_path:
  # Default location for custom content per the setup script
  - "/usr/share/nornir/modules"

###########
# Scripts #
###########

# A boolean flag that enables Scripts support (default=True if absent/misconfigured).
scripts_enabled: True

# Discovery behavior for standalone scripts. Determines whether or not to
# recursively search the directories found in the 'script_path' parameter, or
# to only search those directories and no deeper. (default=True if absent/misconfigured)
script_recursive: True

# Path(s) to the standalone scripts that should be discovered by Automation Gateway.
script_path:
  # Default location for custom content per the setup script
  - "/usr/share/scripts"
  # Legacy path for backwards compatibility
  - "/usr/share/ansible/scripts"

#############
# Terraform #
#############

# A boolean flag that enables Terraform support (default=False if absent/misconfigured).
terraform_enabled: True

# Discovery behavior for Terraform modules. Determines whether or not to
# recursively search the directories found in the 'terraform_path' parameter, or
# to only search those directories and no deeper. (default=True if absent/misconfigured)
terraform_recursive: True

# Path(s) to the Terraform modules that should be discovered by Automation Gateway.
terraform_path:
  # Default location for custom content per the setup script
  - "/usr/share/terraform"
  # Legacy path for backwards compatibility
  - "/usr/share/terraform/scripts"

###################
# Hashicorp Vault #
###################

# A flag that enables Hashicorp Vault support. (default=False if absent/misconfigured)
vault_enabled: False

# The URL to the Hashicorp Vault server.
#vault_server: "https://localhost:8200"

# The mount point on which the Hashicorp Vault KV-V2 secret engine is enabled.
#vault_mount_point: secret

# The path to a file containing the vault access token used by the AG Server for
# Hashicorp Vault operations. The file should be secured with 0400 permissions.
#vault_access_token: "/opt/automation-gateway/conf/.vault_token_file"

# A flag that enables TLS certificate verification when sending reqests to the Hashicorp
# Vault Server. (default=False if absent/misconfigured)
#vault_cert_verification: False

# The path to a CA (Certificate Authority) file.  This file is used to perform TLS certificate
# verification when sending requests to a Hashicorp Vault Server configured with a self-signed
# certificate. This parameter is not required when sending requests to a Hashicorp Vault Server
# configured with a certificate signed by a trusted authority.
#vault_ca_file: "/opt/automation-gateway/conf/certs/cert.pem"

# The path to a client certificate PEM file used for performing TLS authentication of the AG
# vault client with the Hashicorp Vault Server. Both a client certificate file and a key file
# must be configured for TLS authentication to be utilized.
#vault_client_cert_file: "/opt/automation-gateway/conf/certs/cert.pem"

# The path to a client key PEM file used for performing TLS authentication of the AG vault
# client with the Hashicorp Vault Server. Both a client certificate file and a key file
# must be configured for TLS authentication to be utilized.
#vault_client_key_file: "/opt/automation-gateway/conf/certs/key.pem"

###############
# IAG Connect #
###############

# The port on which iag-connect server will listen for requests.
iag_connect_port: 7083

# The API key used to authenticate with the iag-connect.
# This a 256 bits long SHA256 hash. You should replace it with your own key in production
# On Linux you can use `echo -n "your_secret_key" | sha256sum`
# On macOS you can use `echo -n "your_secret_key" | shasum -a 256`
iag_connect_api_key: "543ed2ff052fe0cdd8c15478732d35868ea6c498f82a876d1e77eba5c19eb028"

# File used to save established connections
iag_connect_data: "/opt/automation-gateway/data/connections.json"

Server Configuration

This section covers additional information pertaining to the configuration and functionality of the web server.

Password Reset Functionality

If the password_reset_enabled flag is set to true (enabled), admin and users have the ability to recover username or reset the password rather than getting locked out of IAG server.

For more details on first time login with password reset functionality enabled, refer to Validation in the IAG Admin Guides.

Figure 4: Password Reset

Password Reset

Audit Log

If the audit in config file is set to true, audit logging is enabled. It is enabled by default. To disable it, set it to false.

For more details, refer to Audit Logs in the IAG User Guides.

Ansible Configuration

This section covers the inventory files and paths for Ansible configuration. For additional detail and information, see the official Ansible Configuration reference guide.

Inventory Modes

Before configuring Itential Automation Gateway, determine which inventory mode you require. For existing Ansible users, specify your inventory file in the inventory_file property to maintain all existing device variables and groups as used within your current Ansible® environment. Automation Gateway (AG) considers this mode external inventory. Conversely, internal inventory (i.e., an empty inventory_file property) allows manipulation of inventory information and management of your inventory (including management of inventory variables) via Automation Gateway.

One important factor used to determine which mode to run Automation Gateway in depends on the desired mechanism for managing inventory:

  • Internal - Management via Automation Gateway API.
  • External - Management via file manipulation as with any Ansible installation.

Consider each approach, the inventory mode you desire, and choose accordingly.

Ansible Module Search Paths

By default, Automation Gateway uses information from the ansible --version command to determine the path to search for Ansible network modules. A recursive search of the path is performed at startup time as part of the module discovery process. If for some reason this path is incorrect, the module_path parameter can be configured to override the default Ansible module search path. This allows users to configure a superset or a subset of the Ansible directories to be searched. The default module_path configures a superset (all possible network modules). In order to trim down the overall number of network modules that will be discovered, one may provide a list of more finely tuned paths instead. Note that a recursive search will be performed on all paths.

Support for module search paths outside of the Ansible release directory structure is also available by updating the Ansible Configuration settings. This is done by editing the ansible.cfg configuration file. Simply add the library key to the [defaults] section of the ansible.cfg file to expand the list of directories Automation Gateway will search for in addition to the network modules found in the Ansible release directory.

[defaults]
library = /path/to/ansible/modules1:/path/to/ansible/modules2