diff options
Diffstat (limited to 'docs/cli/exec.md')
-rw-r--r-- | docs/cli/exec.md | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/docs/cli/exec.md b/docs/cli/exec.md new file mode 100644 index 0000000..fe39c12 --- /dev/null +++ b/docs/cli/exec.md @@ -0,0 +1,298 @@ +<!-- + ~ 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. + --> + +# Executing Commands on Devices + +ANTA CLI provides a set of entrypoints to facilitate remote command execution on EOS devices. + +### EXEC Command overview +```bash +anta exec --help +Usage: anta exec [OPTIONS] COMMAND [ARGS]... + + Execute commands to inventory devices + +Options: + --help Show this message and exit. + +Commands: + clear-counters Clear counter statistics on EOS devices + collect-tech-support Collect scheduled tech-support from EOS devices + snapshot Collect commands output from devices in inventory +``` + +## Clear interfaces counters + +This command clears interface counters on EOS devices specified in your inventory. + +### Command overview + +```bash +anta exec clear-counters --help +Usage: anta exec clear-counters [OPTIONS] + + Clear counter statistics on EOS devices + +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] + --help Show this message and exit. +``` + +> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices + +### Example + +```bash +anta exec clear-counters --tags SPINE +[20:19:13] INFO Connecting to devices... utils.py:43 + INFO Clearing counters on remote devices... utils.py:46 + INFO Cleared counters on DC1-SPINE2 (cEOSLab) utils.py:41 + INFO Cleared counters on DC2-SPINE1 (cEOSLab) utils.py:41 + INFO Cleared counters on DC1-SPINE1 (cEOSLab) utils.py:41 + INFO Cleared counters on DC2-SPINE2 (cEOSLab) +``` + +## Collect a set of commands + +This command collects all the commands specified in a commands-list file, which can be in either `json` or `text` format. + +### Command overview + +```bash +anta exec snapshot --help +Usage: anta exec snapshot [OPTIONS] + + Collect commands output from devices in inventory + +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] + -c, --commands-list FILE File with list of commands to collect [env var: + ANTA_EXEC_SNAPSHOT_COMMANDS_LIST; required] + -o, --output DIRECTORY Directory to save commands output. [env var: + ANTA_EXEC_SNAPSHOT_OUTPUT; default: + anta_snapshot_2023-12-06_09_22_11] + --help Show this message and exit. +``` + +> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices + +The commands-list file should follow this structure: + +```yaml +--- +json_format: + - show version +text_format: + - show bfd peers +``` +### Example + +```bash +anta exec snapshot --tags SPINE --commands-list ./commands.yaml --output ./ +[20:25:15] INFO Connecting to devices... utils.py:78 + INFO Collecting commands from remote devices utils.py:81 + INFO Collected command 'show version' from device DC2-SPINE1 (cEOSLab) utils.py:76 + INFO Collected command 'show version' from device DC2-SPINE2 (cEOSLab) utils.py:76 + INFO Collected command 'show version' from device DC1-SPINE1 (cEOSLab) utils.py:76 + INFO Collected command 'show version' from device DC1-SPINE2 (cEOSLab) utils.py:76 +[20:25:16] INFO Collected command 'show bfd peers' from device DC2-SPINE2 (cEOSLab) utils.py:76 + INFO Collected command 'show bfd peers' from device DC2-SPINE1 (cEOSLab) utils.py:76 + INFO Collected command 'show bfd peers' from device DC1-SPINE1 (cEOSLab) utils.py:76 + INFO Collected command 'show bfd peers' from device DC1-SPINE2 (cEOSLab) +``` + +The results of the executed commands will be stored in the output directory specified during command execution: + +```bash +tree _2023-07-14_20_25_15 +_2023-07-14_20_25_15 +├── DC1-SPINE1 +│ ├── json +│ │ └── show version.json +│ └── text +│ └── show bfd peers.log +├── DC1-SPINE2 +│ ├── json +│ │ └── show version.json +│ └── text +│ └── show bfd peers.log +├── DC2-SPINE1 +│ ├── json +│ │ └── show version.json +│ └── text +│ └── show bfd peers.log +└── DC2-SPINE2 + ├── json + │ └── show version.json + └── text + └── show bfd peers.log + +12 directories, 8 files +``` + +## Get Scheduled tech-support + +EOS offers a feature that automatically creates a tech-support archive every hour by default. These archives are stored under `/mnt/flash/schedule/tech-support`. + +```eos +leaf1#show schedule summary +Maximum concurrent jobs 1 +Prepend host name to logfile: Yes +Name At Time Last Interval Timeout Max Max Logfile Location Status + Time (mins) (mins) Log Logs + Files Size +----------------- ------------- ----------- -------------- ------------- ----------- ---------- --------------------------------- ------ +tech-support now 08:37 60 30 100 - flash:schedule/tech-support/ Success + + +leaf1#bash ls /mnt/flash/schedule/tech-support +leaf1_tech-support_2023-03-09.1337.log.gz leaf1_tech-support_2023-03-10.0837.log.gz leaf1_tech-support_2023-03-11.0337.log.gz +``` + +For Network Readiness for Use (NRFU) tests and to keep a comprehensive report of the system state before going live, ANTA provides a command-line interface that efficiently retrieves these files. + +### Command overview + +```bash +anta exec collect-tech-support --help +Usage: anta exec collect-tech-support [OPTIONS] + + Collect scheduled tech-support from EOS devices + +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] + -o, --output PATH Path for test catalog [default: ./tech-support] + --latest INTEGER Number of scheduled show-tech to retrieve + --configure Ensure devices have 'aaa authorization exec default + local' configured (required for SCP on EOS). THIS + WILL CHANGE THE CONFIGURATION OF YOUR NETWORK. + --help Show this message and exit. +``` + +> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices + +When executed, this command fetches tech-support files and downloads them locally into a device-specific subfolder within the designated folder. You can specify the output folder with the `--output` option. + +ANTA uses SCP to download files from devices and will not trust unknown SSH hosts by default. Add the SSH public keys of your devices to your `known_hosts` file or use the `anta --insecure` option to ignore SSH host keys validation. + +The configuration `aaa authorization exec default` must be present on devices to be able to use SCP. +ANTA can automatically configure `aaa authorization exec default local` using the `anta exec collect-tech-support --configure` option. +If you require specific AAA configuration for `aaa authorization exec default`, like `aaa authorization exec default none` or `aaa authorization exec default group tacacs+`, you will need to configure it manually. + +The `--latest` option allows retrieval of a specific number of the most recent tech-support files. + +!!! warning + By default **all** the tech-support files present on the devices are retrieved. + +### Example + +```bash +anta --insecure exec collect-tech-support +[15:27:19] INFO Connecting to devices... +INFO Copying '/mnt/flash/schedule/tech-support/spine1_tech-support_2023-06-09.1315.log.gz' from device spine1 to 'tech-support/spine1' locally +INFO Copying '/mnt/flash/schedule/tech-support/leaf3_tech-support_2023-06-09.1315.log.gz' from device leaf3 to 'tech-support/leaf3' locally +INFO Copying '/mnt/flash/schedule/tech-support/leaf1_tech-support_2023-06-09.1315.log.gz' from device leaf1 to 'tech-support/leaf1' locally +INFO Copying '/mnt/flash/schedule/tech-support/leaf2_tech-support_2023-06-09.1315.log.gz' from device leaf2 to 'tech-support/leaf2' locally +INFO Copying '/mnt/flash/schedule/tech-support/spine2_tech-support_2023-06-09.1315.log.gz' from device spine2 to 'tech-support/spine2' locally +INFO Copying '/mnt/flash/schedule/tech-support/leaf4_tech-support_2023-06-09.1315.log.gz' from device leaf4 to 'tech-support/leaf4' locally +INFO Collected 1 scheduled tech-support from leaf2 +INFO Collected 1 scheduled tech-support from spine2 +INFO Collected 1 scheduled tech-support from leaf3 +INFO Collected 1 scheduled tech-support from spine1 +INFO Collected 1 scheduled tech-support from leaf1 +INFO Collected 1 scheduled tech-support from leaf4 +``` + +The output folder structure is as follows: + +```bash +tree tech-support/ +tech-support/ +├── leaf1 +│ └── leaf1_tech-support_2023-06-09.1315.log.gz +├── leaf2 +│ └── leaf2_tech-support_2023-06-09.1315.log.gz +├── leaf3 +│ └── leaf3_tech-support_2023-06-09.1315.log.gz +├── leaf4 +│ └── leaf4_tech-support_2023-06-09.1315.log.gz +├── spine1 +│ └── spine1_tech-support_2023-06-09.1315.log.gz +└── spine2 + └── spine2_tech-support_2023-06-09.1315.log.gz + +6 directories, 6 files +``` + +Each device has its own subdirectory containing the collected tech-support files. |