1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<!--
~ Copyright (c) 2023-2024 Arista Networks, Inc.
~ Use of this source code is governed by the Apache License 2.0
~ that can be found in the LICENSE file.
-->
# ANTA debug commands
The ANTA CLI includes a set of debugging tools, making it easier to build and test ANTA content. This functionality is accessed via the `debug` subcommand and offers the following options:
- Executing a command on a device from your inventory and retrieving the result.
- Running a templated command on a device from your inventory and retrieving the result.
These tools are especially helpful in building the tests, as they give a visual access to the output received from the eAPI. They also facilitate the extraction of output content for use in unit tests, as described in our [contribution guide](../contribution.md).
!!! warning
The `debug` tools require a device from your inventory. Thus, you MUST use a valid [ANTA Inventory](../usage-inventory-catalog.md#create-an-inventory-file).
## Executing an EOS command
You can use the `run-cmd` entrypoint to run a command, which includes the following options:
### Command overview
```bash
$ anta debug run-cmd --help
Usage: anta debug run-cmd [OPTIONS]
Run arbitrary command to an ANTA device
Options:
-u, --username TEXT Username to connect to EOS [env var:
ANTA_USERNAME; required]
-p, --password TEXT Password to connect to EOS that must be provided.
It can be prompted using '--prompt' option. [env
var: ANTA_PASSWORD]
--enable-password TEXT Password to access EOS Privileged EXEC mode. It
can be prompted using '--prompt' option. Requires
'--enable' option. [env var:
ANTA_ENABLE_PASSWORD]
--enable Some commands may require EOS Privileged EXEC
mode. This option tries to access this mode before
sending a command to the device. [env var:
ANTA_ENABLE]
-P, --prompt Prompt for passwords if they are not provided.
[env var: ANTA_PROMPT]
--timeout INTEGER Global connection timeout [env var: ANTA_TIMEOUT;
default: 30]
--insecure Disable SSH Host Key validation [env var:
ANTA_INSECURE]
--disable-cache Disable cache globally [env var:
ANTA_DISABLE_CACHE]
-i, --inventory FILE Path to the inventory YAML file [env var:
ANTA_INVENTORY; required]
-t, --tags TEXT List of tags using comma as separator:
tag1,tag2,tag3 [env var: ANTA_TAGS]
--ofmt [json|text] EOS eAPI format to use. can be text or json
-v, --version [1|latest] EOS eAPI version
-r, --revision INTEGER eAPI command revision
-d, --device TEXT Device from inventory to use [required]
-c, --command TEXT Command to run [required]
--help Show this message and exit.
```
> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices
### Example
This example illustrates how to run the `show interfaces description` command with a `JSON` format (default):
```bash
anta debug run-cmd --command "show interfaces description" --device DC1-SPINE1
Run command show interfaces description on DC1-SPINE1
{
'interfaceDescriptions': {
'Ethernet1': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-LEAF1A_Ethernet1', 'interfaceStatus': 'up'},
'Ethernet2': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-LEAF1B_Ethernet1', 'interfaceStatus': 'up'},
'Ethernet3': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-BL1_Ethernet1', 'interfaceStatus': 'up'},
'Ethernet4': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-BL2_Ethernet1', 'interfaceStatus': 'up'},
'Loopback0': {'lineProtocolStatus': 'up', 'description': 'EVPN_Overlay_Peering', 'interfaceStatus': 'up'},
'Management0': {'lineProtocolStatus': 'up', 'description': 'oob_management', 'interfaceStatus': 'up'}
}
}
```
## Executing an EOS command using templates
The `run-template` entrypoint allows the user to provide an [`f-string`](https://realpython.com/python-f-strings/#f-strings-a-new-and-improved-way-to-format-strings-in-python) templated command. It is followed by a list of arguments (key-value pairs) that build a dictionary used as template parameters.
### Command overview
```bash
$ anta debug run-template --help
Usage: anta debug run-template [OPTIONS] PARAMS...
Run arbitrary templated command to an ANTA device.
Takes a list of arguments (keys followed by a value) to build a dictionary
used as template parameters. Example:
anta debug run-template -d leaf1a -t 'show vlan {vlan_id}' vlan_id 1
Options:
-u, --username TEXT Username to connect to EOS [env var:
ANTA_USERNAME; required]
-p, --password TEXT Password to connect to EOS that must be provided.
It can be prompted using '--prompt' option. [env
var: ANTA_PASSWORD]
--enable-password TEXT Password to access EOS Privileged EXEC mode. It
can be prompted using '--prompt' option. Requires
'--enable' option. [env var:
ANTA_ENABLE_PASSWORD]
--enable Some commands may require EOS Privileged EXEC
mode. This option tries to access this mode before
sending a command to the device. [env var:
ANTA_ENABLE]
-P, --prompt Prompt for passwords if they are not provided.
[env var: ANTA_PROMPT]
--timeout INTEGER Global connection timeout [env var: ANTA_TIMEOUT;
default: 30]
--insecure Disable SSH Host Key validation [env var:
ANTA_INSECURE]
--disable-cache Disable cache globally [env var:
ANTA_DISABLE_CACHE]
-i, --inventory FILE Path to the inventory YAML file [env var:
ANTA_INVENTORY; required]
-t, --tags TEXT List of tags using comma as separator:
tag1,tag2,tag3 [env var: ANTA_TAGS]
--ofmt [json|text] EOS eAPI format to use. can be text or json
-v, --version [1|latest] EOS eAPI version
-r, --revision INTEGER eAPI command revision
-d, --device TEXT Device from inventory to use [required]
-t, --template TEXT Command template to run. E.g. 'show vlan
{vlan_id}' [required]
--help Show this message and exit.
```
> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices
### Example
This example uses the `show vlan {vlan_id}` command in a `JSON` format:
```bash
anta debug run-template --template "show vlan {vlan_id}" vlan_id 10 --device DC1-LEAF1A
Run templated command 'show vlan {vlan_id}' with {'vlan_id': '10'} on DC1-LEAF1A
{
'vlans': {
'10': {
'name': 'VRFPROD_VLAN10',
'dynamic': False,
'status': 'active',
'interfaces': {
'Cpu': {'privatePromoted': False, 'blocked': None},
'Port-Channel11': {'privatePromoted': False, 'blocked': None},
'Vxlan1': {'privatePromoted': False, 'blocked': None}
}
}
},
'sourceDetail': ''
}
```
!!! warning
If multiple arguments of the same key are provided, only the last argument value will be kept in the template parameters.
### Example of multiple arguments
```bash
anta -log DEBUG debug run-template --template "ping {dst} source {src}" dst "8.8.8.8" src Loopback0 --device DC1-SPINE1
> {'dst': '8.8.8.8', 'src': 'Loopback0'}
anta -log DEBUG debug run-template --template "ping {dst} source {src}" dst "8.8.8.8" src Loopback0 dst "1.1.1.1" src Loopback1 --device DC1-SPINE1
> {'dst': '1.1.1.1', 'src': 'Loopback1'}
# Notice how `src` and `dst` keep only the latest value
```
|
