Itential Docs & Guides | Drive Automation for Modern Networks

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 their users.

Properties.yml

Configuring Optional Subsystems

Starting in Release 2020.2, all subsystems supported by Automation Gateway (i.e., Ansible, Scripts, Terraform) are optional and enabled/disabled by setting the configuration parameters found in properties.yml. See the Sample Properties File section for more information.

Note: To help ease the transition for existing Automation Gateway users, Ansible and Scripts are enabled by default and do not require any additional configuration. A future release of Automation Gateway will require that all subsystems be configured so it is suggested that the parameters for those subsystems be set right away if currently being utilized.

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.com/ 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: false

# 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.
# This must remain true for testing, production but may be disabled if it is
# helpful while still developing/decorating custom content.
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.
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"

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

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

# 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"

# 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: false

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

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

# 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: false

# 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=true if absent/misconfigured)
#vault_cert_verification: true

# 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"

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.

Figure 1: Password Reset

Password Reset

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

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.

Note: 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

Itential Automation Gateway

Help us improve by sending feedback...

On this page:

Properties