Itential Automation Gateway allows users to automate the administration of their network by providing a collection of Ansible roles that perform device monitoring and configuration tasks on supported device types. The roles are designed to utilize advanced features of the command and configuration networking modules that are developed, tested, and maintained by the Ansible open-source community. Devices are managed by running CLI and NETCONF commands over the SSH protocol. The parameters required for device connectivity are made available through the Automation Gateway inventory management subsystem.
Roles in Automation Gateway
The following roles are distributed with Automation Gateway.
| Role | Description |
|---|---|
itential_cli |
Execute CLI commands on a network device. |
itential_get_info |
Retrieve the device serial number, OS version, and MAC addresses for all network interfaces. |
itential_get_health |
Retrieve CPU and memory statistics for a device. |
itential_get_config |
Retrieve the current running configuration for a device. |
itential_set_config |
Add, modify, and delete specific configuration sections and lines on a device. |
itential_load_config |
Send a raw configuration string to a device. |
itential_restore_config |
Replace the current running configuration of a device with a completely new version. |
Example Request & Response Objects
Referenced below are several Automation Gateway roles, including examples of request and response objects.
itential_cli
Description: Execute CLI commands on a network device. This role also provides support for handling commands that are required to respond to a prompt in order to complete the command.
As of 2019.3, this role does not support handling command prompts for F5 (BigIP) devices or Junos devices that are configured with the ansible_connection variable set to netconf.
Request Object
Sample:
{
"hosts": [
"ios_aws"
],
"args": {"command": ["show clock"]}
}
Response Object
Sample:
[
{
"role": "itential_cli",
"task": "itential_cli response",
"host": "ios_host",
"status": "SUCCESS",
"argument_warnings": null,
"results": {
"stdout_lines": [
[
"*08:45:04.200 UTC Fri Nov 8 2019"
]
],
"stdout": [
"*08:45:04.200 UTC Fri Nov 8 2019"
],
"changed": false
}
}
]
Request Object for Command Prompts
Sample:
{
"hosts": [
"ios_aws"
],
"args":{"command": [{"command": "clear counters GigabitEthernet2", "prompt": ["confirm"], "answer": ["y"]}]}
}
Response Object for Command Prompts
Sample:
[
{
"role": "itential_cli",
"task": "itential_cli response",
"host": "ios_aws",
"status": "SUCCESS",
"argument_warnings": null,
"results": {
"stdout_lines": [
[
"Clear \"show interface\" counters on this interface [confirm]y"
]
],
"stdout": [
"Clear \"show interface\" counters on this interface [confirm]y"
],
"changed": false
}
}
]
itential_get_info
Description: Retrieve information about a device including OS type, serial number, and the MAC address for all network interfaces.
Request Object
Sample:
{
"hosts": [
"ios_aws"
],
"args": {}
}
Response Object
Sample:
{
"role": "itential_get_info",
"task": "itential_get_info response",
"host": "ios_aws",
"status": "SUCCESS",
"argument_warnings": null,
"results": {
"serial_number": "9IKZMWL4K0X",
"raw_ansible_facts": {
"ansible_net_serialnum": "9IKZMWL4K0X",
"ansible_net_all_ipv4_addresses": [
"10.11.0.72"
],
"ansible_net_model": "CSR1000V",
"ansible_net_hostname": "ph10894c",
"ansible_net_gather_subset": [
"hardware",
"default",
"interfaces"
],
"ansible_net_interfaces": {
"GigabitEthernet1.1": {
"macaddress": "0e4e.fc45.d044",
"lineprotocol": "down ",
"description": null,
"duplex": null,
"mediatype": null,
"mtu": 1500,
"operstatus": "deleted",
"bandwidth": 1000000,
"ipv4": [],
"type": "CSR vNIC"
},
"GigabitEthernet1": {
"macaddress": "0e4e.fc45.d044",
"lineprotocol": "up ",
"description": null,
"duplex": "Full",
"mediatype": "RJ45",
"mtu": 1500,
"operstatus": "up",
"bandwidth": 1000000,
"ipv4": [
{
"subnet": "24",
"address": "10.11.0.72"
}
],
"type": "CSR vNIC"
}
},
"ansible_net_version": "03.16.02.S",
"ansible_net_all_ipv6_addresses": [],
"ansible_net_memtotal_mb": 1672835,
"ansible_net_filesystems": [
"bootflash:"
],
"ansible_net_image": "bootflash:packages.conf",
"ansible_net_memfree_mb": 1442035
},
"interfaces": {
"GigabitEthernet1.1": {
"macaddress": "0e4e.fc45.d044",
"lineprotocol": "down ",
"description": null,
"duplex": null,
"mediatype": null,
"mtu": 1500,
"operstatus": "deleted",
"bandwidth": 1000000,
"ipv4": [],
"type": "CSR vNIC"
},
"GigabitEthernet1": {
"macaddress": "0e4e.fc45.d044",
"lineprotocol": "up ",
"description": null,
"duplex": "Full",
"mediatype": "RJ45",
"mtu": 1500,
"operstatus": "up",
"bandwidth": 1000000,
"ipv4": [
{
"subnet": "24",
"address": "10.11.0.72"
}
],
"type": "CSR vNIC"
}
},
"os_version": "03.16.02.S",
"changed": false
}
}
itential_get_health
Description: Retrieve CPU and memory statistics for a device. The itential_get_health response task returns a memory usage statistics object and an array of CPU usage objects.
The memory object contains the total memory and free memory values in megabytes. Each object in the cpu_stats array reflects a sample period during which the CPU usage was measured.
The number of objects in the array is based on what sample periods are available from each device. Note that some network devices track CPU utilization as a percentage, while others use the concept of load average.
The following keys are contained in each CPU usage object.
| Key | Description |
|---|---|
value |
CPU utilization (percentage) or load average. |
type |
Utilization or loading. |
period |
Sample space (in seconds) in which the value was calculated. |
Request Object
Sample:
{
"hosts": [
"ios_aws"
],
"args": {}
}
Response Object
Sample:
[
{
"role": "itential_get_health",
"task": "itential_get_health response",
"host": "ios_aws",
"status": "SUCCESS",
"argument_warnings": null,
"results": {
"memory": {
"memtotal_mb": 814,
"memfree_mb": 556
},
"cpu_stats": [
{ "value": 15, "type": "utilization", "period": 5 },
{ "value": 20, "type": "utilization", "period": 60 },
{ "value": 32, "type": "utilization", "period": 300 }
],
"changed": false
}
},
{
"role": "itential_get_health",
"task": "itential_get_health response",
"host": "eos_host",
"status": "SUCCESS",
"argument_warnings": null,
"results": {
"memory": {
"memtotal_mb": 1970,
"memfree_mb": 1120
},
"cpu_stats": [
{ "value": 0.8, "type": "loadavg", "period": 60 },
{ "value": 0.2, "type": "loadavg", "period": 300 },
{ "value": 0.2, "type": "loadavg", "period": 900 }
],
"changed": false
}
},
]
itential_get_config
Description: Retrieve the current running configuration from a device. The results returned in the config_data field can be directly passed as a value to the config_file parameter of the itential_restore_config role.
Request Object
Sample:
{
"hosts": [
"ios_host"
],
"args": {}
}
Response Object
Sample:
{
"role": "itential_get_config",
"task": "itential_get_config response",
"host": "ios_host",
"status": "SUCCESS",
"argument_warnings": null,
"results": {
"config_data": "! Last configuration change at 01:11:48 UTC Thu Feb 7 2019 by admin\n!\nversion 15.4\n
service timestamps debug datetime msec\nservice timestamps log datetime msec\nno platform punt-keepalive disable-kernel-core\n
platform console virtual\n!\nhostname roland-router\n!\nboot-start-marker\nboot-end-marker\n!\n!\n
enable secret 5 $1$.U3b$Uoy64G6eZ4qXzCbihv9rd0\nenable password admin\n!\naaa new-model\n!\n!\naaa authentication login default local\n
aaa authorization exec default local none \n!\n!\n!\n!\n!\naaa session-id common\n!\n!\n!\n!\n!\n!\n!\n\n\n
ip domain name test.example.com\n!\n!\n!\n!\n!\n!\n!\n!\n!\n!\nsubscriber templating\nmultilink bundle-name authenticated\n
!\n!\nlicense udi pid CSR1000V sn 9V86NBL1EE6\n!\nusername admin privilege 15 password 0 admin\n!\nredundancy\n mode none\n
!\n!\n!\nip ssh time-out 60\nip ssh authentication-retries 2\nip ssh version 2\nip ssh pubkey-chain\n username admin\n
key-hash ssh-rsa 3141D7C2ECA54D3611445D83564F8391 roland.provencher@itential.comendend\nip scp server enable\n
!\n!\n!\n!\ninterface GigabitEthernet1\n ip address 10.0.2.15 255.255.255.0\n negotiation auto\n!\ninterface GigabitEthernet2\n
ip address 192.168.32.40 255.255.255.0\n negotiation auto\n!\n!\nvirtual-service csr_mgmt\n!\nip forward-protocol nd\n!\n
no ip http server\nno ip http secure-server\n!\n!\nsnmp-server community redhat RO\nsnmp-server community REDSOX RO\n
snmp-server community PATS RO\n!\n!\n!\n!\ncontrol-plane\n!\n!\nline con 0\n stopbits 1\nline aux 0\n stopbits 1\n
line vty 0 4\n privilege level 15\n password admin\n login authentication local\n transport input ssh\n!\n!\nend",
"changed": false,
"_ansible_delegated_vars": {
"ansible_delegated_host": "localhost",
"ansible_host": "localhost"
}
}
}
itential_set_config
Description: Add, modify, and delete specific configuration sections and lines on a device. The itential_set_config role takes an array of transactions as an argument.
Each transaction is an object representing a single configuration line that will be applied to the device configuration in the order they appear in the array.
Each transaction will be treated individually and produce its own status and results. A failure on one transaction will not stop the next transaction from being attempted.
A transaction object consists of the following fields.
| Field | Description |
|---|---|
action |
Configuration action to perform on a device. Possible values are add, modify, and delete. |
parents |
The ordered set of parents that uniquely identify the section or hierarchy the configuration line should be applied against. If the parents argument is empty, the configuration line is applied against the root of the configuration tree. |
config_line |
The configuration line being acted upon by the device. The line must match the native device configuration syntax. |
id |
Optional. String parameter that can be used to match a transaction request with the corresponding device configuration response. The id string will be return as a key in the config_response results object of the role. |
Request Object
Sample:
{"hosts":["eos_host"],
"args":{"transactions": [{"action": "add", "parents": ["interface Management 1"], "config_line": "ip address 10.0.5.17/24", "id": "first"},
{"action": "modify", "parents": ["interface Management 1"], "config_line": "ip address 10.0.5.27/24", "id": "second" },
{"action": "delete", "parents": [""], "config_line": "ip address 10.0.5.27/24", "id": "third"}] }, "strict_args": true }
Response Object
Sample:
{
"role": "itential_set_config",
"task": "itential_set_config response",
"host": "eos_host",
"status": "SUCCESS",
"argument_warnings": null,
"results": {
"config_request": {
"action": "add",
"config_line": "ip address 10.0.5.17/24",
"parents": [
"interface Management 1"
],
"id": "first"
},
"config_response": {
"failed": false,
"id": "first"
},
"changed": false
}
},
{
"role": "itential_set_config",
"task": "itential_set_config response",
"host": "eos_host",
"status": "SUCCESS",
"argument_warnings": null,
"results": {
"config_request": {
"action": "modify",
"config_line": "ip address 10.0.5.27/24",
"parents": [
"interface Management 1"
],
"id": "second"
},
"config_response": {
"failed": false,
"id": "second"
},
"changed": false
}
},
{
"role": "itential_set_config",
"task": "itential_set_config response",
"host": "eos_host",
"status": "FAILURE",
"argument_warnings": null,
"results": {
"msg": "Configuration request failed",
"config_request": {
"action": "delete",
"config_line": "ip address 10.0.5.27/24",
"parents": [
""
],
"id": "third"
},
"config_response": {
"msg": "Error on executing commands ['', 'no ip address 10.0.5.27/24']",
"failed": true,
"data": "no ip address 10.0.5.27/24\r\n% Invalid input\r\nlocalhost(config-s-ansibl)#",
"id": "third"
},
"changed": false
}
}
]
itential_restore_config
Description: Replace the current running configuration of a device with a completely new version.
The itential_restore_config_role takes the argument config_file, which is a string buffer containing the device configuration file in its native format.
The itential_get_config role returns the device configuration file in its native format in the key config_data.
The results from that role can be a starting point for configuration modifications or be used "as is" for the argument value in the config_file.
SCP Requirements for IOS (Cisco) and EOS (Arista) Device Types
To execute the restore operation, Cisco IOS and Arista EOS devices require the new configuration file to be present on the system. The itential_restore_config role accomplishes this by using the Ansible scp module to transfer the new configuration file to the device. Below are instructions for SCP and SSH key configuration requirements when using the itential_restore_config role on IOS and EOS devices.
-
SCP must be enabled using the the following configuration mode command (IOS):
# ip scp server enable -
For the user account in the device inventory variable
ansible_user, SSH keys must be set-up between Automation Gateway and the IOS/EOS device so that a password in not required for device login. Otherwise, the SCP module will timeout and the role will fail. -
The inventory variable
ansible_ssh_private_key_filemust be present for the device and set to the path of the private key file that was created in the previous step.
Request Object
Sample:
{"hosts":["junos_host"],
"args":{"config_file": "## Last changed: 2019-01-11 06:31:03 UTC\nversion 12.1R1.9;\ngroups {\n global;\n}\napply-groups global;\nsystem {\n root-authentication {\n
encrypted-password \"$1$Fmd79e7l$0biZFh9lhSt1qb/E06HoL.\";\n }\n services {\n ftp;\n ssh;\n netconf {\n ssh;\n }\n
}\n syslog {\n user * {\n any emergency;\n }\n file messages {\n any notice;\n authorization info;\n
}\n file interactive-commands {\n interactive-commands any;\n }\n }\n}\ninterfaces {\n em0 {\n unit 0 {\n family
inet {\n address 192.168.32.30/24;\n }\n }\n }\n}\nsnmp {\n community itential;\n community redhat;\n}"
},
"strict_args": true
}
Response Object
Sample:
{
"role": "itential_restore_config",
"task": "itential_restore_config response",
"host": "junos_host",
"status": "SUCCESS",
"argument_warnings": null,
"results": {
"config_response": {
"failed": false,
"changed": true
},
"changed": false
}
}