Cisco Catalyst SD-WAN Solution Integrations Guide, Releases 26.x and Later

PDF

Cisco Catalyst SD-WAN Solution Integrations Guide, Releases 26.x and Later

Configure third-party custom application integration

Updated: September 28, 2026

Want to summarize with AI?

Log in

Configure third-party custom application integration at a high level to enable monitoring and management of custom applications on devices.

This task enables you to integrate third-party custom applications with your SD-WAN infrastructure to extend device functionality and monitoring capabilities.

Third-party application integration allows you to deploy and manage custom applications on SD-WAN devices through a series of configuration steps that prepare the device environment, upload application images, and create deployment profiles.

Procedure

  1. Activate Cisco IOx on devices

  2. Upload the third-party custom application to Cisco SD-WAN Manager

  3. Create a configuration group profile with a custom application feature

  4. Add a custom application feature to a configuration group

  5. Deploy a configuration group with a custom application feature

The third-party custom application integration is configured and ready for deployment on your SD-WAN devices.

What to do next

After the configuration steps, you can monitor the activity of the application operating on a device. See Monitor a third-party custom application on devices.

Activate Cisco IOx on devices

This procedure activates Cisco IOx on devices to enable running third-party custom Cisco IOx applications.

This procedure activates Cisco IOx on devices, which is necessary for running third-party custom Cisco IOx applications.

Before you begin

  • For Cisco Catalyst SD-WAN Manager Release 20.16.x, ensure to activate Cisco IOx on devices before running third-party custom Cisco IOx applications on the devices.

  • From Cisco Catalyst SD-WAN Manager Release 20.18.1, activating Cisco IOx on devices is not required.

Follow these steps to activate Cisco IOx on devices:

Procedure

  1. Create a configuration group with a CLI add-on profile.

  2. In the CLI add-on profile, include the iox command to activate Cisco IOx.

    iox

  3. Use the configuration group deployment procedure in the Cisco Catalyst SD-WAN Configuration Groups Reference Guide to deploy the configuration group to devices before installing a third-party custom Cisco IOx application.

Cisco IOx is activated on the devices and ready to run third-party custom Cisco IOx applications.

Upload the third-party custom application to Cisco SD-WAN Manager

You can host a third-party custom application in one of the two ways:

  • Upload the third-party custom application to the SD-WAN Manager local repository, or

  • Upload the third-party custom application to a remote repository

Third-party custom applications can be hosted in either a local or remote repository depending on your environment configuration and requirements. The local repository option is available in single-tenant environments or for service providers operating multitenant environments, while the remote repository option provides flexibility for tenants when applications are not available locally.

Before you begin

Minimum supported release: Cisco Catalyst SD-WAN Manager Release 20.18.1 and later

Custom application package

Ensure that the third-party custom application package meets the requirements described in the Cisco IOx documentation.

In addition to the above package requirements for a third-party application, ensure the image_properties.xml file uses this format:

<image_properties>
<vnf_type>app-hosting</vnf_type>
<name>Custom-App</name>
<arch>aarch64/x86_64</arch>
<version>0.85</version>
<imageType>dockertype</imageType> 
<applicationDescription><Custom App Description></applicationDescription>
<applicationVendor>Cisco Systems</applicationVendor>
<applicationMaxInstances>1</applicationMaxInstances>
</image_properties>
Table 1. Image_properties.xml element descriptions

Elements

Description
vnf_type Specifies the VM functionality. It is always app-hosting when uploading the application image to SD-WAN Manager.

name

Name of the application. For third-party applications, use Custom-App .

arch

Architecture type of the third-party application. Possible values:

  • x86_64

  • aarch64

See the package.yml file to find the application's architecture.

version

Version of the third-party application as defined in the package.yml file.

imageType

Specifies the type of image: dockertype

applicationDescription

Description of the application, as defined in the package.yml file.

applicationVendor

Name of the application vendor.

applicationMaxInstances

Maximum number of application instances.

Procedure

  1. Method 1: If you choose to host the the third-party custom application image in the SD-WAN Manager local repository, follow these steps.

    This option is available in a single-tenant environment, or for a service provider operating a multitenant environment.

    1. From the Cisco SD-WAN Manager menu, choose Maintenance > Software Repository.
    2. Click Virtual Images.
    3. Click Add New Virtual Image and select Manager.
    4. Choose your custom application image and click Upload.

      SD-WAN Manager creates an entry in Virtual Images for the locally hosted third-party custom application.

  2. Method 2: If you choose to host the third-party custom application on a remote repository server, follow these steps.

    This option is available in a single-tenant environment, or for tenants in a multitenant environment. Tenants in a multitenant environment can use this option if the custom application image is not available in the local SD-WAN Manager repository.

    1. Set up a file server and register it in SD-WAN Manager, as described in the information about registering a remote server in the Cisco Catalyst SD-WAN Monitor and Maintain Configuration Guide.
    2. From the Cisco SD-WAN Manager menu, choose Maintenance > Software Repository > Virtual Images.
    3. Click Add New Virtual Image and select Remote Server.
    4. Enter the third-party custom application image file name.
    5. For Select service type, choose App-Hosting.
    6. For Select app type, choose Custom-App.
    7. Enter the version of your custom application.
    8. For Select architecture, choose aarch64 or x86_64.
    9. In the Remote Server section, select the name of the remote server that you have registered.

      The Remote Server Details shows the details of the locally hosted server.

    10. Click Save.

SD-WAN Manager creates an entry in Virtual Images for the third-party custom application, making it available for deployment to compatible devices in your network.

Create a configuration group profile with a custom application feature

Create a configuration group profile that incorporates a custom application feature to support third-party-developed applications in your network environment.

Because third-party-developed custom applications are unique, Cisco SD-WAN Manager cannot validate the configuration against a common standard. To ensure that the application operates correctly, configure the parameters here according to the requirements of the application.

Before you begin

On the Configuration > Configuration Groups page, choose either

  • SD-WAN, or

  • SD-Routing

as the solution type.

Follow these steps to create a configuration group profile with a custom application feature:

Procedure

  1. From the Cisco SD-WAN Manager menu, choose Configuration > Configuration Groups.

  2. Create and configure a Custom Application feature in an Other profile.

    1. Enter a name and description for the feature.

      Table 2. Name and Description

      Field

      Description

      Name

      Name for the feature.

      Description

      Optionally, add a description.

    2. The basic settings are mandatory.

      Table 3. Basic Settings

      Field

      Description

      Application Name

      Enter a name for the custom application. You can use upper- or lower-case letters, but not spaces or special characters.

      This name appears as part of the event details on the Monitor > Logs > Events page.

      Virtual Image

      Choose a custom application image file from the drop-down list.

      The list shows custom application images uploaded to the virtual image repository in Maintenance > Software Repository > Virtual Images.

    3. If the custom application has a requirement for network configuration, click Add Configuration and enter the network connectivity details for up to three connections. This configures communication between the Cisco IOx application and

      • the device on which the application is operating, and

      • any external assets, such as a server if the application communicates with a server.

      Note

      At least one network configuration is required for a third-party custom application.

      Here are the options for the SD-WAN solution:

      Table 4. Network Configuration, SD-WAN Solution

      Field

      Description

      Name

      Name describing the entity for which you are configuring connectivity.

      Service VPN

      Service VPN providing the connectivity between the application and either (a) the device, or (b) an external asset.

      VPG IP Address

      IP address within the subnet mask defined in the Subnet Mask field for communication between the custom application and a device virtual port group (VPG) interface or external asset.

      Application IP Address

      IP address to assign to the custom application, for mapping to a VPG interface on the device.

      Subnet Mask

      Subnet mask for the VPG interface. The subnet mask defines an address space for the service VPN for communication between the custom application and a device VPG interface or external asset.

      Action

      Provides an option to delete a row.

      Here are the options for the SD-Routing solution:

      Table 5. Network Configuration, SD-Routing Solution

      Field

      Description

      Network Configuration

      Name

      Name describing the entity for which you are configuring connectivity.

      Communication Interface

      Physical or virtual interface providing connectivity between the application and either (a) the device, or (b) an external asset.

      Action

      Provides an option to delete a row.

    4. Some custom applications require information passed as variables, either global or device-specific. To add variables, click Add Variable and enter the details.

      The specifics of the valid key:value pairs depend entirely on the details of the custom application. Consult with the custom application developer for information about configuring variables. Note that these values are case sensitive.

      Maximum number of variables: 10

      Table 6. Environment Variables

      Field

      Description

      Key

      Key name for a variable.

      Value

      Value of the variable. Choose Device Specific to provide a specific key value for each device.

      Action

      Provides an option to delete a row.

    5. Some custom applications use data input provided through a serial interface. This option supports any serial port available on the platform.

      To add a data source, click Add Data Source and enter the serial port.

      Maximum number of serial ports: 7

      Table 7. Data Configuration

      Field

      Description

      Serial Line

      Enter a serial port available on the device. See the platform documentation for information about serial ports.

      Example: /dev/ttySerial

      Action

      Provides an option to delete a row.

You have successfully created a configuration group profile with a custom application feature that is configured to support third-party applications according to their specific requirements.

What to do next

Also see Deploy a configuration group.

Add a custom application feature to a configuration group

Add Custom Application features to configuration groups to apply custom application policies across multiple devices in your SD-WAN network.

Custom Application profiles allow you to define application-specific policies that can be deployed consistently across devices within a configuration group. This task applies to both SD-WAN and SD-Routing solutions.

Before you begin

Follow these steps to add a Custom Application feature to a configuration group:

Procedure

  1. From the Cisco SD-WAN Manager menu, choose Configuration > Configuration Groups.

  2. In the solution drop-down list, choose either

    • SD-WAN, or

    • SD-Routing

    as the solution type to display configuration groups only for this solution.

  3. Click the Configuration Groups tab.

  4. If you need to create a configuration group, follow the steps described in Using Configuration Groups in the Cisco Catalyst SD-WAN Configuration Groups Reference Guide.

  5. For an existing configuration group, click Add Profile and add an Other Profile to the configuration group.

  6. In the configuration group, locate the Other Profile drop-down list and choose a Custom Application profile.

The Custom Application profile is added to the configuration group and can now be deployed to devices associated with this group.

Deploy a configuration group with a custom application feature

Deploy a configuration group that includes a custom application feature to devices in your SD-WAN network to enable custom application functionality.

Configuration groups allow you to deploy standardized configurations with custom applications across multiple devices in your SD-WAN network. This process includes activating Cisco IOx on target devices and monitoring the deployment progress.

Before you begin

See Supported platforms for third-party custom application integration before deploying a configuration group with the Custom Application feature.

Activate Cisco IOx on devices before deploying the configuration group. See Activate Cisco IOx on devices.

Follow these steps to deploy a configuration group with a custom application feature:

Procedure

  1. Use the configuration group deployment procedure in the Cisco Catalyst SD-WAN Configuration Groups Reference Guide to deploy a configuration group to devices in the network.

  2. If you are deploying to devices of the SD-WAN solution type, during deployment, enter any required device-specific variables for each router.

  3. If you want to monitor the progress of installing the application on a device, view the log messages for the installation.

    1. Click the task list button near the top right.

    2. Click the Deploy configuration group task.

      This opens a page showing the deployment progress for each device.

    3. Adjacent to a device, click the log icon in the Action column.

      The View Logs pane opens, showing the deployment progress for the device. When the deployment is complete, a success message, such as "Config Group successfully deployed to device," appears in the log.

      When you first deploy a configuration group with the Custom Application feature to a device, it triggers the device to install the application.

The configuration group with the custom application feature is successfully deployed to the selected devices. The custom application is installed and activated on the devices, enabling the configured functionality.

Uninstall a third-party custom application

Uninstall a third-party-developed custom application that has been previously deployed to devices.

Uninstalling a third-party-developed custom application presumes that you have installed the application already. See Configure third-party custom application integration.

Procedure

  1. Remove the Custom Application feature from the configuration group.

    1. From the Cisco SD-WAN Manager menu, choose Configuration > Configuration Groups.
    2. Click the Configuration Groups tab.
    3. Adjacent to a configuration group, click the arrow in the Actions column to expand the row to show the attached profiles.
    4. Adjacent to the Other Profile drop-down list, click the pencil icon to edit the profile.
    5. Within the profile, remove the Custom Application feature.

  2. Deploy the configuration group to devices. See Deploy a configuration group with a custom application feature.

The procedure uninstalls the custom application from devices to which it had been deployed.