> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Built-in Ansible roles > Reference for the Ansible roles distributed with Itential Gateway for device monitoring and configuration tasks on supported network devices. Itential Gateway includes a collection of built-in Ansible roles that perform device monitoring and configuration tasks on supported device types. The roles use advanced features of the command and configuration networking modules developed, tested, and maintained by the Ansible open-source community. Devices are managed by running CLI and NETCONF commands over SSH. Device connectivity parameters are made available through the Gateway inventory management subsystem. ## Roles in Itential Gateway The following roles are distributed with Itential 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. | ## Role examples The following examples show request and response objects for select roles distributed with Gateway. ### itential\_cli This role also supports handling commands that require a prompt response to complete. 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: ```json { "hosts": [ "ios_aws" ], "args": {"command": ["show clock"]} } ``` #### Response object Sample: ```json [ { "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: ```json { "hosts": [ "ios_aws" ], "args":{"command": [{"command": "clear counters GigabitEthernet2", "prompt": ["confirm"], "answer": ["y"]}]} } ``` #### Response object for command prompts Sample: ```json [ { "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 #### Request object Sample: ```json { "hosts": [ "ios_aws" ], "args": {} } ``` #### Response object Sample: ```json { "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 The `itential_get_health` response returns a memory usage statistics object and an array of CPU usage objects. The memory object contains total and free memory values in megabytes. Each object in the `cpu_stats` array reflects a sample period during which 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: ```json { "hosts": [ "ios_aws" ], "args": {} } ``` #### Response object Sample: ```json [ { "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 The results returned in the `config_data` field can be passed directly as the value for the `config_file` parameter of the `itential_restore_config` role. #### Request object Sample: ```json { "hosts": [ "ios_host" ], "args": {} } ``` #### Response object Sample: ```json { "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 The `itential_set_config` role takes an array of transactions as an argument. Each transaction is an object representing a single configuration line applied to the device configuration in the order it appears in the array. Each transaction is treated individually and produces its own status and results. A failure on one transaction doesn't 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 is returned as a key in the `config_response` results object of the role. | #### Request object Sample: ```json {"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: ```json [ { "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 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 in its native format in the `config_data` key — those results can serve as a starting point for configuration modifications or be passed as-is to `config_file`. #### SCP requirements for IOS (Cisco) and EOS (Arista) device types Cisco IOS and Arista EOS devices require the new configuration file to be present on the system before the restore operation can execute. The `itential_restore_config` role handles this by using the Ansible `scp` module to transfer the new configuration file to the device. The following SCP and SSH key configuration requirements apply when using `itential_restore_config` on IOS and EOS devices. #### Enable SCP on the device SCP must be enabled using the following configuration mode command (IOS): ```bash ip scp server enable ``` #### Configure SSH keys For the user account in the device inventory variable `ansible_user`, SSH keys must be set up between Gateway and the IOS/EOS device so that a password isn't required for device login. Otherwise, the SCP module times out and the role fails. #### Set the private key file inventory variable The inventory variable `ansible_ssh_private_key_file` must be present for the device and set to the path of the private key file created in the previous step. #### Request object Sample: ```json {"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: ```json { "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 } } ```