-
Notifications
You must be signed in to change notification settings - Fork 35
2. Using Sastre
The command line is structured as a set of base parameters, the task specification followed by task-specific parameters:
sdwan <base parameters> <task> <task-specific parameters>
Base parameters define global options such as verbosity level, vManage credentials, etc.
Task indicates the operation to be performed. The following tasks are currently available:
- Backup: Save vManage configuration items to a local backup.
- Restore: Restore configuration items from a local backup to vManage.
- Delete: Delete configuration items on vManage.
- Migrate: Migrate configuration items from a vManage release to another. Currently, only 18.4, 19.2 or 19.3 to 20.1 is supported. Minor revision numbers (e.g. 20.1.1) are not relevant for the template migration.
- Encrypt: Encrypt values using target vManage keys. Used to generate CRYPT_CLUSTER encrypted values, which can only be decrypted by the target vManage.
- Transform: Modify configuration items. Currently, copy, rename and crypt-update operations are supported.
- Attach: Attach WAN Edges/vSmarts to templates. Allows further customization on top of the functionality available via "restore --attach".
- Detach: Detach WAN Edges/vSmarts from templates. Allows further customization on top of the functionality available via "delete --detach".
- Certificate: Restore device certificate validity status from a backup or set to a desired value (i.e. valid, invalid or staging).
- List: List configuration items or device certificate information from vManage or a local backup.
- Show-template: Show details about device templates on vManage or from a local backup.
- Report: Generate a customizable report file containing the output of multiple commands. Also provide option to generate a diff between reports.
- Show: Run vManage real-time, state or statistics commands; collecting data from one or more devices. Query vManage alarms and events.
Task-specific parameters are provided after the task argument, customizing the task behavior. For instance, whether to execute a restore task in dry-run mode or the destination directory for a backup task.
Notes:
- Either 'sdwan' or 'sastre' can be used as the main command.
- The command line described above, and in all examples that follow, assume Sastre was installed via PIP.
- If Sastre was cloned from the git repository, then 'sdwan.py' or 'sastre.py' should be used instead. Please check the Installing section for more details.
% sdwan --help
usage: sdwan [-h] [-a <vmanage-ip>] [-u <user>] [-p <password>] [--tenant <tenant>] [--pid <pid>] [--port <port>] [--timeout <timeout>] [--verbose] [--debug] [--version] <task> ...
Sastre-Pro - Cisco-SDWAN Automation Toolset
positional arguments:
<task> task to be performed (backup, restore, delete, migrate, attach, detach, certificate, transform, list, show-template, show, report, encrypt)
<arguments> task parameters, if any
options:
-h, --help show this help message and exit
-a <vmanage-ip>, --address <vmanage-ip>
vManage IP address, can also be defined via VMANAGE_IP environment variable. If neither is provided user is prompted for the address.
-u <user>, --user <user>
username, can also be defined via VMANAGE_USER environment variable. If neither is provided user is prompted for username.
-p <password>, --password <password>
password, can also be defined via VMANAGE_PASSWORD environment variable. If neither is provided user is prompted for password.
--tenant <tenant> tenant name, when using provider accounts in multi-tenant deployments.
--pid <pid> CX project id, can also be defined via CX_PID environment variable. This is collected for AIDE reporting purposes. Use 0 if not applicable.
--port <port> vManage port number, can also be defined via VMANAGE_PORT environment variable (default: 443)
--timeout <timeout> REST API timeout (default: 300)
--verbose increase output verbosity
--debug include additional API call details to the log files
--version show program's version number and exit
vManage address (-a/--address), username (-u/--user), password (-p/--password), port (--port) and CX project ID (--pid) can also be provided via environment variables:
- VMANAGE_IP
- VMANAGE_USER
- VMANAGE_PASSWORD
- VMANAGE_PORT
- CX_PID
A good approach to reduce the number of parameters that need to be provided at execution time is to create rc text files exporting those environment variables for a particular vManage. This is demonstrated in the Getting Started section below.
For any of these arguments, vManage address, user, password and CX pid; user is prompted for a value if they are not provided via the environment variables or command line arguments.
CX project ID is only applicable to Sastre-Pro. CX_PID and --pid option are not available in Sastre (std). If CX project ID is not applicable, simply use value 0.
Task-specific parameters and options are defined after the task is provided. Each task has its own set of parameters.
% sdwan backup -h
usage: sdwan backup [-h] [--archive <filename> | --workdir <directory>] [--no-rollover] [--save-running]
[--regex <regex> | --not-regex <regex>]
<tag> [<tag> ...]
Sastre - Cisco-SDWAN Automation Toolset
Backup task:
positional arguments:
<tag> one or more tags for selecting items to be backed up. Multiple tags should be separated by space. Available
tags: all, config_group, feature_profile, policy_customapp, policy_definition, policy_list,
policy_security, policy_vedge, policy_voice, policy_vsmart, template_device, template_feature. Special tag
"all" selects all items, including WAN edge certificates and device configurations.
options:
-h, --help show this help message and exit
--archive <filename> backup to zip archive
--workdir <directory>
backup to directory (default: backup_198.18.1.10_20220915)
--no-rollover by default, if workdir already exists (before a new backup is saved) the old workdir is renamed using a
rolling naming scheme. This option disables this automatic rollover.
--save-running include the running config from each node to the backup. This is useful for reference or documentation
purposes. It is not needed by the restore task.
--regex <regex> regular expression matching item names to backup, within selected tags.
--not-regex <regex> regular expression matching item names NOT to backup, within selected tags.
- vManage URL: Constructed from the provided vManage IP address and TCP port (default 443). All operations target this vManage.
- Workdir: Defines the location (in the local machine) where vManage data files are located. By default, it follows the format "backup_<vmanage-ip>_<yyyymmdd>". The --workdir parameter can be used to specify a different location. Workdir is under a 'data' directory. This 'data' directory is relative to the directory where Sastre is run.
- Tag: vManage configuration items are grouped by tags, such as policy_apply, policy_definition, policy_list, template_device, etc. The special tag 'all' is used to refer to all configuration elements. Depending on the task, one or more tags can be specified in order to select groups of configuration elements.
A number of Sastre tasks provide output in the form of one or more tables. For instance, list, show-template and show tasks. There is a common set of options shared by all such tasks:
Table export options:
- --save-csv: Export as CSV file(s).
- --save-json: Export as JSON file(s).
Table filtering options:
- --include: Include rows matching the provided regular expression, exclude all other rows.
- --exclude: Exclude rows matching the provided regular expression.
Include/exclude regular expressions match on any cell value of the particular row. In other words, any cell value matching the regular expression will cause a row match.
Both --include and --exclude can be provided at simultaneously. In this case, exclude match is performed first then include.
Create a directory to serve as root for backup files, log files and rc files:
% mkdir sastre
% cd sastre
When Sastre is executed, data/ and logs/ directories are created as needed to store backup files and application logs. These are created under the directory where Sastre is run.
Create a rc-example.sh file to include vManage details and source that file:
% cat <<EOF > rc-example.sh
export VMANAGE_IP='198.18.1.10'
export VMANAGE_USER='admin'
EOF
% source rc-example.sh
Note that in this example the password was not defined, the user will be prompted for a password.
Test vManage credentials by running a simple query listing configured device templates:
% sdwan list configuration template_device
vManage password:
+============================================================================================+
| Name | ID | Tag | Type |
+============================================================================================+
| DC_ADVANCED | bf322748-8dfd-4cb0-a9e4-5d758be239a0 | template_device | device template |
| DC_BASIC | 09c02518-9557-4ae2-9031-7e6b3e7323fc | template_device | device template |
| VSMART_v1 | 15c1962f-740e-4b89-a269-69f2cbfba296 | template_device | device template |
| BRANCH_ADVANCED | ad449106-7ed6-442f-9ba8-820612b85981 | template_device | device template |
| BRANCH_BASIC | cc2f7a24-4c93-49ed-8e6b-1c107797ba95 | template_device | device template |
+-----------------+--------------------------------------+-----------------+-----------------+
Any of those vManage parameters can be provided via command line as well:
% sdwan -p admin list configuration template_device
Perform a backup:
% sdwan --verbose backup all
INFO: Starting backup: vManage URL: "https://198.18.1.10" -> Local workdir: "backup_198.18.1.10_20210927"
INFO: Saved vManage server information
INFO: Saved WAN edge certificates
INFO: Saved device template index
<snip>
INFO: Saved prefix list index
INFO: Done prefix list DefaultRoute
INFO: Done prefix list InfrastructureRoutes
INFO: Saved local-domain list index
INFO: Done local-domain list DCLOUD
INFO: Task completed successfully
Note that '--verbose' was specified so that progress information is displayed. Without this option, only warning-level messages and above are displayed.
The backup is saved under data/backup_10.85.136.253_20191206:
% ls
data logs rc-example.sh
% ls data
backup_198.18.1.10_20210927