This tool automates Cisco Catalyst SD-WAN lab deployment inside Cisco Modeling Labs (CML).
The tool will help you automate your CML lab deployments with SD-WAN Manager, Controllers and Validators and up to 20 SD-WAN edges. You can build as pods as your CML platform can host. Please refer to the Limitations and scale for details.
Catalyst SD-WAN Lab Deployment Tool requires Linux or macOS system. To run is on Windows, please use Linux on Windows with WSL or set up Linux VM/container.
Catalyst SD-WAN Lab Deployment Tool requires Python 3.9 or newer. This can be verified by pasting the following to a terminal window:
% python3 -c "import sys;assert sys.version_info>(3,9)" && echo "ALL GOOD"
If 'ALL GOOD' is printed it means Python requirements are met. If not, download and install the latest 3.x version at Python.org (https://www.python.org/downloads/).
All the Python prerequisites are automaticaly installed when you install the package. Please refer to the Installing section for details.
This tool requires CML 2.6 or higher.
The recommended way to install is via pip.
Create a directory to store the virtual environment and runtime files:
mkdir csdwan
cd csdwan
Create virtual environment:
python3 -m venv venv
Activate virtual environment:
source venv/bin/activate
Upgrade initial virtual environment packages:
pip install --upgrade pip setuptools
To install SD-WAN Lab Deployment Tool:
pip install --upgrade catalyst-sdwan-lab
Verify that SD-WAN Lab tool can run:
sdwan-lab --version
You can also use the following shortcut to run any lab task:
csdwan --version
Notes:
Simmilar to Sastre, the command line is structured as a set of base parameters, the task specification followed by task-specific parameters:
sdwan-lab <base parameters> <task> <task-specific parameters>
Base parameters define global options such as verbosity level, CML credentials, etc.
Task indicates the operation to be performed. The following tasks are currently available:
Task-specific parameters are provided after the task argument.
sdwan-lab -h
usage: sdwan-lab.py [-h] [-c <cml-ip>] [-u <cml-user>] [-p <cml-password>] [-v] [--version] {setup,deploy,add,backup,restore,delete} ...
Catalyst SD-WAN Lab Deployment Tool - Automation Tool for managing Cisco Catalyst SD-WAN labs inside Cisco Modelling Labs
positional arguments:
{setup,deploy,add,backup,restore,delete}
Task to be performed.
setup Setup on-prem CML to use Catalyst SD-WAN Lab automation.
deploy Deploy a new Catalyst SD-WAN lab pod.
add Add Catalyst SD-WAN device to running lab pod.
backup Backup running Catalyst SD-WAN lab pod.
restore Restore Catalyst SD-WAN POD from backup.
delete Delete the CML lab and all the lab data.
sign Sign CSR using the SD-WAN Lab Deployment Tool Root CA.
optional arguments:
-h, --help show this help message and exit
-c <cml-ip>, --cml <cml-ip>
CML IP address, can also be defined via CML_IP environment variable. If neither is provided user is prompted for CML IP.
-u <cml-user>, --user <cml-user>
CML username, can also be defined via CML_USER environment variable. If neither is provided user is prompted for CML username.
-p <cml-password>, --password <cml-password>
CML password, can also be defined via CML_PASSWORD environment variable. If neither is provided user is prompted for CML password.
-v, --verbose Increase output verbosity.
--version show program's version number and exit
Most of the parameters can also be provided via environment variables:
For any of the required arguments, user is prompted for a value if they are not provided via the environment variables or command line arguments.
The easiest way to run the tool is to provide all the lab variables in the rc file and source that file. The example file below contains all the variables required to run all the tasks.
% cat rc-example.sh
export CML_IP='10.0.0.1'
export CML_USER='user1'
export CML_PASSWORD='password123'
export MANAGER_IP='10.0.0.10'
export MANAGER_USER='sdwan'
export MANAGER_PASSWORD='sdwanlab123'
export MANAGER_MASK='/24'
export MANAGER_GATEWAY='10.0.0.254'
export LAB_NAME='sdwan'
% source rc-example.sh
Note that if password was not defined, the user will be prompted for a password. Also please note we recommend not to use admin user as MANAGER_USER. Instead, configure a different user name to always have a backup user. By default, the MANAGER_PASSWORD will be set for both admin user and the MANAGER_USER that you specify.
Note that MANAGER_IP can be:
Task-specific parameters and options are defined after the task is provided. Each task has its own set of parameters. Check the task documentation to learn more about task-specific parameters.
This task makes sure your CML is ready to run Catalyst SD-WAN labs. The task will:
On each CML server that you want to use, you should run a setup task at least once to create required node and image definitions. You can rerun the setup task each time you want to add a new Catalyst SD-WAN software image to your CML server.
This task have one task-specific argument that allows you to migrate the node and image definitions to new format if you've used SD-WAN Lab 1.x in the past.
sdwan-lab setup -h
usage: sdwan-lab.py setup [-h] [--migrate]
optional arguments:
-h, --help show this help message and exit
--migrate Migrate node and image definitions from SD-WAN Lab v1.x to v2.x. This task should be run once if CML server was using SD-WAN LAb Tool v1.x in the past.
This task:
You should run this task to deploy a new lab with control plane configured and build any WAN Edge topology you like.
This task has several task-specific parameters, including software version that you want to run on the control components.
sdwan-lab deploy -h
usage: sdwan-lab.py deploy [-h] [--manager <manager-ip>] [--mmask <manager-mask>] [--mgateway <manager-gateway>] [--muser <manager-user>] [--mpassword <manager-password>] [--bridge <custom-bridge-name>] [--dns <dns-server-ip>]
<software-version>
positional arguments:
<software-version> Software version that will be used on SD-WAN Control Components.
optional arguments:
-h, --help show this help message and exit
--manager <manager-ip>
SD-WAN Manager IP address, can also be defined via MANAGER_IP environment variable. If neither is provided user is prompted for SD-WAN Manager IP.
--mmask <manager-mask>
Subnet mask for given SD-WAN Manager IP (e.g. /24), can also be defined via MANAGER_MASK environment variable. If neither is provided user is prompted for SD-WAN Manager subnet mask.
--mgateway <manager-gateway>
Gateway IP for given SD-WAN Manager IP, can also be defined via MANAGER_GATEWAY environment variable. If neither is provided user is prompted for Manager gateway IP.
--muser <manager-user>
SD-WAN Manager username, can also be defined via MANAGER_USER environment variable. If neither is provided user is prompted for SD-WAN Manager username.
--mpassword <manager-password>
SD-WAN Manager password, can also be defined via MANAGER_PASSWORD environment variable. If neither is provided user is prompted for SD-WAN Manager password.
--lab <lab_name> Set CML Lab name, can also be defined via LAB_NAME environment variable. If not provided, default name "sdwan<number>" will be assigned.
--bridge <custom-bridge-name>
Set custom bridge for SD-WAN Manager external connection. Default is System Bridge
--dns <dns-server-ip>
Set custom DNS server for Internet/VPN0 transport. Default is same as CML DNS
--retry If for some reason your script lost connectivity during SD-WAN Manager boot, you can add --retry to continue onboarding the lab that is already in CML.
Time to complete the deployment task depends on:
This task adds Catalyst SD-WAN nodes (Validators/Controllers/Edges) into existing Catalyst SD-WAN lab. This task will:
This task has several task-specific parameters.
sdwan-lab add -h
usage: sdwan-lab.py add [-h] [--manager <manager-ip>] [--muser <manager-user>] [--mpassword <manager-password>] [--lab <lab_name>] <number-of-devices> <device-type> <software-version>
positional arguments:
<number-of-devices> Number of devices to be added.
<device-type> Type of device/s to be added (e.g. validator, controller, edge, sdrouting).
<software-version> Software version that will be used.
optional arguments:
-h, --help show this help message and exit
--manager <manager-ip>
SD-WAN Manager IP address, can also be defined via MANAGER_IP environment variable. If neither is provided user is prompted for SD-WAN Manager IP.
--muser <manager-user>
SD-WAN Manager username, can also be defined via MANAGER_USER environment variable. If neither is provided user is prompted for SD-WAN Manager username.
--mpassword <manager-password>
SD-WAN Manager password, can also be defined via MANAGER_PASSWORD environment variable. If neither is provided user is prompted for SD-WAN Manager password.
--lab <lab_name> CML Lab name, can also be defined via LAB_NAME environment variable. If neither is provided user is prompted for lab name.
Below you will find few examples of add task:
sdwan-lab add 1 validator 20.9.4 --lab sdwan1
sdwan-lab add 2 controllers 20.12.2 --lab sdwan2
sdwan-lab add 5 edges 17.09.03a --lab vsdwan1
sdwan-lab add 2 sdrouting 17.12.2 --lab vsdwan1
This task creates a backup of the Catalyst SD-WAN lab running in CML. CML doesn't natively support configuration export from Catalyst SD-WAN nodes, but this script can help you to save your Catalyst SD-WAN configuration. This task will:
This task has several task-specific parameters, including working directory where backup is saved.
% sdwan-lab back -h
usage: sdwan-lab.py backup [-h] [--manager <manager-ip>] [--muser <manager-user>] [--mpassword <manager-password>] [--lab <lab_name>] [--workdir <directory>]
optional arguments:
-h, --help show this help message and exit
--manager <manager-ip>
SD-WAN Manager IP address, can also be defined via MANAGER_IP environment variable. If neither is provided user is prompted for SD-WAN Manager IP.
--muser <manager-user>
SD-WAN Manager username, can also be defined via MANAGER_USER environment variable. If neither is provided user is prompted for SD-WAN Manager username.
--mpassword <manager-password>
SD-WAN Manager password, can also be defined via MANAGER_PASSWORD environment variable. If neither is provided user is prompted for SD-WAN Manager password.
--lab <lab_name> CML Lab name, can also be defined via LAB_NAME environment variable. If neither is provided user is prompted for lab name.
--workdir <directory>
Backup destination folder
This task restores Catalyst SD-WAN lab from a backup. This task will:
This task has several task-specific parameters, including working directory from where backup is restored.
% sdwan-lab restore -h
usage: sdwan-lab.py restore [-h] [--manager <manager-ip>] [--mmask <manager-mask>] [--mgateway <manager-gateway>] [--muser <manager-user>] [--mpassword <manager-password>] [--lab <lab_name>]
[--workdir <directory>] [--deleteexisting] [--retry]
optional arguments:
-h, --help show this help message and exit
--manager <manager-ip>
SD-WAN Manager IP address, can also be defined via MANAGER_IP environment variable. If neither is provided user is prompted for SD-WAN Manager IP.
--mmask <manager-mask>
Subnet mask for given SD-WAN Manager IP (e.g. /24), can also be defined via MANAGER_MASK environment variable. If neither is provided user is prompted for SD-WAN Manager subnet mask.
--mgateway <manager-gateway>
Gateway IP for given SD-WAN Manager IP, can also be defined via MANAGER_GATEWAY environment variable. If neither is provided user is prompted for Manager gateway IP.
--muser <manager-user>
SD-WAN Manager username, can also be defined via MANAGER_USER environment variable. If neither is provided user is prompted for SD-WAN Manager username.
--mpassword <manager-password>
SD-WAN Manager password, can also be defined via MANAGER_PASSWORD environment variable. If neither is provided user is prompted for SD-WAN Manager password.
--lab <lab_name> CML Lab name, can also be defined via LAB_NAME environment variable. If neither is provided user is prompted for lab name.
--workdir <directory>
Restore source folder
--deleteexisting If there is already lab running with same name and using same SD-WAN Manager IP, delete this lab before restoring. Note the all running lab data will be lost!
--retry If for some reason your script lost connectivity during SD-WAN Manager boot, you can add --retry to continue restoring the lab that is already in CML
This task deletes the CML lab and removes all it's data. Note after this operation, all lab data is lost.
This task has several task-specific parameters.
sdwan-lab delete -h
usage: sdwan-lab.py delete [-h] [--lab <lab_name>] [--force]
optional arguments:
-h, --help show this help message and exit
--lab <lab_name> Lab name
--force Delete the lab without asking for confirmation. Note the all lab data will be lost!
This tasks reads the Certificate Signing Request (CSR) from a file and signs it using SD-WAN Lab Deployment Tool Root CA. At the end, the task prints the signed certificate in standard output.
This task has several task-specific parameters.
sdwan-lab delete -h
usage: sdwan-lab.py sign [-h] <csr_file>
positional arguments:
<csr_file> Certificate Signing Request (CSR) File
The tool supports the following scale per CML lab:
To install WSL on your Windows VM or Physical machine. Ensure that the HW Virutalization is enabled in the BIOS or VM Defintion.
If its on Windows server you may need to run this command to allow the WSL to function properly
Open PowerShell as Administrator and run:
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
Install WSL with default distribution (Ubuntu) Open PowerShell and run
wsl --install
Once the installation is finished and you have restarted Windows you are able to continue the installation of this tool as described in the installation section of this document.
You can read more about Linux on Windows with WSL here.
Tomasz Zarski (tzarski@cisco.com)
BSD-3-Clause