Cisco Catalyst SD-WAN Control Components and Device Management Guide, Releases 26.x and Later

PDF

Cisco Catalyst SD-WAN Control Components and Device Management Guide, Releases 26.x and Later

Configure devices in Cisco Catalyst SD-WAN

Updated: June 9, 2026

Want to summarize with AI?

Log in

Describes template-based device configuration, covering types of templates, use of template variables, populating parameters through files and CSV formats, and procedures for skeleton CSV generation, file import, and manual value entry.

Describes template-based device configuration, covering types of templates, use of template variables, populating parameters through files and CSV formats, and procedures for skeleton CSV generation, file import, and manual value entry.

You can use SD-WAN Manager to create and store configurations for all devices. The SD-WAN Manager systems themselves, SD-WAN Controllers, SD-WAN Validator, and routers. When the devices start up, they contact SD-WAN Manager, which then downloads the device configuration to them. (A device starting up first contacts the SD-WAN Validator, which validates the device and sends it the IP address of SD-WAN Manager.)

The general procedure for creating configurations for all devices is the same. This section provides a high-level description of the configuration procedure and describes the prerequisite steps you must complete before creating configurations and configuring devices in the overlay network.

Types of templates

There are two types of templates:

  • Feature templates

  • Device templates

Feature templates

Feature templates are the building blocks of complete configuration for a device. For each feature that you can enable on a device, Cisco SD-WAN Manager provides a template form that you fill out. The form allows you to set the values for all configurable parameters for that feature.

Because device configurations vary for different device types and the different types of routers, feature templates are specific to the type of device.

Some features are mandatory for device operation, so creating templates for these features is required. Also for the same feature, you can create multiple templates for the same device type.

Special Characters in Feature Template

In releases prior to Cisco IOS XE Catalyst SD-WAN Release 17.7.1a, if you enter < or > special characters in a SD-WAN Manager feature template definition or description, SD-WAN Manager generates a 500 exception error while attempting to preview a SD-WAN Manager feature template.

Starting from Cisco IOS XE Catalyst SD-WAN Release 17.7.1a, if you enter < or > special characters in a SD-WAN Manager feature template definition or description, the special characters are converted to their HTML equivalents, &lt; and &gt;.

This applies to all feature templates. You no longer receive a 500 exception error when previewing a SD-WAN Manager feature template.

Device templates

Device templates contain the complete operational configuration for a device and are created by consolidating feature templates.

  • Each device template is specific to a device type.

  • If multiple devices of the same type share the same configuration, you can use the same template for all of them. Differences between devices are handled using configuration variables.

  • If devices of the same type have different configurations, you create separate templates.

CLI-based device templates

You can create a device template by entering a CLI-style configuration directly in SD-WAN Manager by

  • Uploading a text file with the configuration

  • Copying and pasting configuration text

  • Typing the configuration directly into SD-WAN Manager

From Cisco IOS XE Catalyst SD-WAN Release 17.5.1a and Cisco vManage Release 20.5.1, you can review your last edited configuration when your latest configuration is not being pushed to the device. For more information, see Edit a device template when a push fails.

From Cisco vManage Release 20.5.1, device variable page shows text area instead of text input field to configure CLI device template for the ease of configuration.

Template variables

Within a feature template, some configuration commands and options are identical across all device types, while others are variable, changing from device to device. Examples of variable parameters include:

  • Device system IP address

  • Geographic latitude and longitude

  • Timezone

  • Overlay network site identifier

When you attach a device template to a device, you are prompted to enter the actual values for these variables. You can provide these values in two ways:

  1. Manually: Type the values for each variable for each device.

  2. Bulk upload: Upload an excel file in CSV format containing the values for all devices.

Use variable values in configuration templates

In an overlay network, multiple devices of the same type might have similar configurations. This often happens with routers in different stores or branch locations that provide identical services but have unique hostnames, IP addresses, GPS locations, and site-specific properties such as BGP neighbors. It also applies to redundant controllers like Cisco SD-WAN Controllers and Cisco SD-WAN Manager systems, where each controller has its own hostname and IP address.

To simplify configuration, create a single configuration template with both static and variable values. Static values remain common across all devices, while variable values apply to individual devices. You provide the variable values when attaching a device to the configuration template.

You can configure variable values in a feature template in two ways:

  • Set the parameter scope to Device Specific:

    For a parameter, select Device Specific to mark it as a variable. Each variable has a unique key. When you select Device Specific, the Enter Key box appears with a default key. You can use the default key, or you can change it by typing a new string and then moving the cursor out of the Enter Key box.

  • Mark a group of parameters as optional:

    For some features in some feature configuration templates, you can mark the entire feature as optional. To mark the feature in this way, click Mark as Optional Row in a section of a feature configuration template. The variable parameters are then dimmed, and you cannot configure values for them in the feature configuration template.

Enter device-specific values for the variables when attaching the device to the configuration using one of these methods:

  • From a file: When you are attaching a template to a device, you load a file to SD-WAN Manager. This is an Excel file in CSV format that lists all the variables and defines the variable's value for each device.

  • Manually: When you attach a device template to a device, the SD-WAN Manager prompts you for the values for each of device-specific parameters, and you type in the value for each parameter.

Cisco Catalyst SD-WAN supports up to 500 variables in a single template push operation.

Use a file for variable parameters

To load device-specific variable values, create a template variables file in Excel CSV format. This file lists all the variables in your device configurations and defines their values. Create the file offline, and then import it into the SD-WAN Manager server when you attach a device configuration to one or more devices in the overlay network.

We recommend creating a template variables CSV file if your overlay network includes more than a few Cisco IOS XE Catalyst SD-WAN devices.

CSV file format

File description

The CSV file is an Excel spreadsheet with one column for each variable required to configure a device. The header row lists the variable names (one variable per column), and each subsequent row represents a device and defines its variable values.

Spreadsheet options

You can create one spreadsheet for all devices in the overlay network: Cisco IOS XE Catalyst SD-WAN devices, SD-WAN Manager systems, SD-WAN Controller, and SD-WAN Validators, or create a separate spreadsheet for each device type. The system identifies the device type by its serial number.

In the spreadsheet, specify values only for the required variables for each device type and device. If a variable does not need a value, leave the corresponding cell blank.

Make the first three columns in the spreadsheet these items, and arrange them in the order shown:

Column Column heading Description
1 csv-deviceId Serial number of the device (used to uniquely identify the device). For Cisco IOS XE Catalyst SD-WAN devices, you receive the serial numbers in the authorized serial number file sent to you from Cisco. For other devices, the serial number is included in the signed certificate you receive from Symantec or from your root CA.
2 csv-deviceIP System IP address of the device (used to populate the system ip address command).
3 csv-host-name Hostname of the device (used to populate the system hostname command).

Use unique variable keys from the Enter Key box of a feature configuration template as the headings for the remaining columns. You can arrange these columns in any order.

Generate a skeleton CSV file

To have SD-WAN Manager generate a skeleton CSV file:

You create a template variables CSV file manually using the format described in the previous section, or let SD-WAN Manager generate a skeleton CSV file containing all required columns and headings. The generated CSV file includes one row for each Cisco device type and column headings for all variables required by the feature templates in the device configuration. The column headings use the key strings that identify device-specific parameters. Then fill each row with values for the corresponding variables.

Procedure

1.

From the SD-WAN Manager menu, choose Configuration > Templates.
2.

Click Feature Templates, and click Add Template.

In Cisco vManage Release 20.7.x and earlier releases, Feature Templates is titled Feature.
3.

Create the required feature templates for one Cisco IOS XE Catalyst SD-WAN device router, one Cisco Catalyst SD-WAN Controller, one Cisco SD-WAN Manager system, and one Cisco Catalyst SD-WAN Validator.inf

In each feature template:

  • For fields that have default values, verify that you want to use that value for all devices. If you do not want to use the default, change the scope to Global or Device-specific.

  • For fields that apply to all devices, select the Global icon next to the field and set the desired global values.

  • For fields that are device specific, select the Device-specific icon next to the field and leave the field blank.
4.

For each Cisco device type, create a device template.
5.

From the SD-WAN Manager menu, choose Configuration > Templates.
6.

Click Device Templates, and select the desired device template from the template list table.

In Cisco vManage Release 20.7.x and earlier releases, Device Templates is titled Device.
7.

Click …, and click Export CSV.
8.

Repeat Steps 7 and 8 for each device template.

Edit the exported CSV file to include at least the device serial number, system IP address, and hostname for each device in the overlay network. Then enter values for the desired device-specific variables. Ensure that variable names do not include forward slashes (/), backslashes (), or parentheses (( )).

If needed, combine multiple CSV files into a single file.

Import a CSV file

To import the CSV file containing device-specific variable values when you attach a device template to the Viptela device.

Procedure

1.

From the Cisco SD-WAN Manager menu, choose Configuration > Templates.
2.

Click Device Templates.

In Cisco vManage Release 20.7.x and earlier releases, Device Templates is titled Device.
3.

For the desired template, click ..., and select Attach Devices.
4.

In the Attach Devices dialog box, select the desired devices in Available Devices and click the arrow to move them to Selected Devices.
5.

Click Attach.
6.

Click the Up arrow. The Upload CSV File box displays.
7.

Choose the CSV file to upload, and click Upload.

During the attachment process, click Import file to load the Excel file. If SD-WAN Manager detects duplicate system IP addresses for devices in the overlay network, it shows a warning message or pop-up. Correct the system IP addresses to remove any duplicates before continuing to attach device templates to Viptela devices.

Manually enter values for device-specific variables and for optional rows

To manually enter values for device-specific variables or for variables in optional rows when you attach the template to a device:

When you attach a device template that includes device-specific parameters, SD-WAN Manager prompts you to enter the parameter values. When you attach a device template that includes device-specific parameters, SD-WAN Manager prompts you to enter the parameter values. However, this method does not scale well for larger networks.

When many devices share the same configuration except for a few parameters, you can specify those parameters as optional rows in the feature configuration template. When you select Optional Row, the feature template automatically marks those parameters as device-specific and dims them so you cannot modify them in the template. You do not have to individually mark the parameters as device specific. When you attach the device template to a device, SD-WAN Manager prompts you to enter the values for those parameters.

Using optional rows to enter device-specific values is useful when a group of many Cisco IOS XE Catalyst SD-WAN devices provide identical services at their branch or site, but individual routers have their own hostname, IP address, GPS location, and other site or store properties, such as BGP neighbors.

Optional rows are available for some parameters in some feature configuration templates. To treat a parameter or set of parameters as an optional row, click the Mark as Optional Row box. For these types of parameters, the feature configuration template has a table listing all the configured parameters. The Optional column indicates which are optional rows

Procedure

1.

From the Cisco SD-WAN Manager menu, choose Configuration > Templates.
2.

Click Device Templates, and select the desired device template.
3.

Click …, and click Attach Devices.

The Attach Devices dialog box opens.
4.

Choose one or more devices from Available Devices and move them to Selected Devices.
5.

Click Attach.
6.

In the Chassis Number list, select the desired device.
7.

Click …, and click Edit Device Template. The Update Device Template dialog box opens.
8.

Enter values for the optional parameters. When you are using optional rows, if you do not want to include the parameter for the specific device, do not specify a value.
9.

Click Update.
10.

Click Next.

If any devices have the same system IP address, a dialog box appears or an error message is displayed when you click Next. Modify the system IP addresses so that there are no duplicates, and click Save. Then click Next again.

You need to shut down the OMP on the device, before changing the system-ip on the device.
11.

In the left pane, select the device. The right pane displays the device configuration and the Config Preview tab in the upper right corner is selected.
12.

Click Config Diff to preview the differences between this configuration and the configuration currently running on the device, if applicable. To edit the variable values entered in the previous screen, click Back.
13.

Click Configure Devices to push the configuration to the devices.

The Status column displays whether the configuration was successfully pushed. Click the right angle bracket to the left of the row to display details of the push operation.