Efficient Image Upgrade

Efficient image upgrades for FlexConnect APs

Efficient image upgrade is an optimized upgrade method for FlexConnect APs that

  • reduces WAN link load by limiting simultaneous image downloads to three secondary APs per primary AP.

  • allows simultaneous secondary AP downloads from a designated primary AP, and

  • enables faster image pre-downloads for FlexConnect APs.

Feature History

Release

Feature

Feature Information

Cisco IOS XE 17.11.1

Out-of-Band AP Image Download

This feature enhances the AP image upgrade method to make upgrades faster and more flexible.

Commands Introduced:

  • ap upgrade method https

  • ap file-transfer https port

  • show ap upgrade method

Analogy: relay race

Efficient image upgrades work like a relay race for file sharing. Imagine a group of runners (APs) at a remote location needing a baton (the software image) from the main building (the controller). Instead of each runner making the trip directly and crowding the hallway (the WAN link), one designated runner (the primary AP) gets the baton first and brings it back. The others then take the baton from this runner in controlled small groups (three at a time), so the hallway never gets overcrowded, saving time and reducing congestion.

Restrictions

  • Efficient image upgrades work only in FlexConnect (flex mode).

  • Ensure all FlexConnect APs are grouped under the same site tag, and are physically co-located.

  • Efficient image upgrades do not operate when the default-site-tag is applied.

  • You cannot remove flex profile configurations from a site tag that is configured as a site.

  • Use the no local-site command to prepare a site tag for Flexconnect. Otherwise, the Flex profile configuration is not applied.

  • Efficient AP image download uses port 8443 for HTTPS connections. The listener also uses this port to upload client debug bundles and transfer Clean Air spectral recordings from the AP to the controller. This port remains open even if you disable efficient AP image download because multiple services use it.

Efficient image upgrade download

Efficient AP image download minimizes WAN load, accelerates image distribution for co-located FlexConnect APs, and ensures reliable and consistent image deployment within site tags.

Summary

The key components involved in the process are:

  • Controller: Hosts and distributes AP images through WAN.

  • Primary AP: Selected for each model per site tag to fetch the image from the controller.

  • Secondary APs: Retrieve the image from the primary AP through TFTP. Up to three secondary APs can download simultaneously.

Workflow

These stages describe the efficient AP image download:

  1. The controller selects one AP per model and site tag as the primary AP.
  2. The primary AP downloads the required image directly from the controller over WAN.
  3. Up to three secondary APs download the image simultaneously through TFTP from the primary AP. This approach minimizes WAN usage.
  4. The process uses port 8443 for HTTPS connections. This port is also used for uploading debug bundles and spectral recordings.
  5. The port remains open, as multiple services use this listener even if efficient AP image download is disabled.

Result

Efficient AP image download minimizes WAN load, accelerates image distribution for co-located FlexConnect APs, and ensures consistent, reliable image deployment within site tags.

Enable pre-download in a FlexConnect AP (GUI)

Allow access points to download software images in advance to minimize downtime during upgrades.

Use this task when you want APs to pre-download image updates through the GUI.

Follow these steps to enable pre-download for an AP:

Procedure

Step 1

Choose Configuration > Wireless > Access Points.

Step 2

In the Access Points window, expand the All Access Points section and click the name of the AP to edit.

Step 3

In the Edit AP window, click the Advanced tab and from the AP Image Management section, click Predownload.

Step 4

Click Update & Apply to Device.

The selected AP downloads the software image in advance, reducing downtime during the upgrade process.

Configure an efficient image upgrade for FlexConnect APs

To configure pre-download, you must complete the described series of tasks:

  1. Create a flex profile using the CLI and enable pre-download. You can also use an existing flex profile. See Enable pre-download in a flex profile (CLI).

  2. Configure a site tag. Site tags group APs and apply common settings, such as the flex profile you created in the previous task. See Configure a site tag for FlexConnect APs (CLI).

  3. Attach the policy tag and site tag to the AP. This task configures APs with the correct policy and site tag. See Attach policy tag and site tag to an AP (CLI).

  4. Trigger pre-download for a site tag to start the image pre-download to the APs associated with the site tag. You can then verify the pre-download status. See Trigger and verify pre-download to a site tag.

Configure a flex profile for pre-download (CLI)

Enable image pre-downloading for remote APs in a FlexConnect flex profile from the CLI.

Use this task to pre-download software images on APs associated with a flex profile. This accelerates upgrade rollouts and reduces network downtime.

Before you begin

  • Identify the target flex profile to be updated.

Procedure

Step 1

Enter the global configuration mode.

Example:

Device# configure terminal

Step 2

Configure a flex profile and enter the flex profile configuration mode.

Example:

Device(config)# wireless profile flex rr-xyz-flex-profile

Step 3

Enable pre-download of the image.

Example:

Device(config-wireless-flex-profile)# predownload

Step 4

Exit the configuration mode and return to privileged EXEC mode.

Example:

Device(config-wireless-flex-profile)# end

Pre-download is enabled for the selected flex profile. APs in this profile download the image before upgrades.

What to do next

Monitor AP status to verify successful pre-download before scheduling the upgrade.

Configure a site tag for FlexConnect APs (CLI)

Set up a site tag for wireless deployments to enable site-specific configurations using the CLI.

Before you begin

  • Gather required information, such as the desired site tag name and flex profile name.

Procedure

Step 1

Enter global configuration mode.

Example:

Device# configure terminal

Step 2

Configure a site tag and enter site tag configuration mode.

Example:

Device(config)# wireless tag site rr-xyz-site

Step 3

Configure a flex profile.

Example:

Device(config-site-tag)# flex-profile rr-xyz-flex-profile

  • You cannot remove flex profile configurations from a site tag that is configured as a local site.

    Use the no local-site command to remove local site configurations before applying flex profile configurations.

Step 4

Add a description for the site tag.

Example:

Device(config-site-tag)# description "default site tag"

Step 5

Save the configuration, exit configuration mode and return to privileged EXEC mode.

Example:

Device(config-site-tag)# end

Step 6

(Optional) Display the number of site tags.

Example:

Device# show wireless tag site summary

The site tag is configured on the device, and site-specific settings are applied.

What to do next

Verify the site tag configuration.

Verify site tag configuration

Verify the site tag configuration:

  • To view detailed information about a site, use the show wireless tag site detailed site-tag-name command.

  • To view default tag (site-tag) type when both site tag and policy tag are not configured, use the output of the show wireless loadbalance tag affinity wncd wncd-instance-number command.

Attach policy tag and site tag to an AP (CLI)

Assign a policy tag and site tag to an AP using CLI.

Use this procedure to associate specific network policies and locations with an AP in your Cisco wireless deployment.

Before you begin

Make sure you have the wired MAC address of the AP.

Procedure

Step 1

Enter global configuration mode.

Example:

Device# configure terminal

Step 2

Configure a Cisco AP and enters AP profile configuration mode.

Example:

Device(config)# ap F866.F267.7DFB

Note

 

The mac-address should be a wired mac address.

Step 3

Map a policy tag to the AP.

Example:

Device(config-ap-tag)# policy-tag rr-xyz-policy-tag

Step 4

Map a site tag to the AP.

Example:

Device(config-ap-tag)# site-tag rr-xyz-site

Step 5

Associate the RF tag.

Example:

Device(config-ap-tag)# rf-tag rf-tag1

Step 6

Save the configuration, exit configuration mode, and return to privileged EXEC mode.

Example:

Device(config-ap-tag)# end

Step 7

(Optional) Display AP details and the tags associated to it.

Example:

Device# show ap tag summary

Step 8

Display the AP name with tag information.

Example:

Device# show ap name "ap-name" tag info

Step 9

(Optional) Display the AP name with tag details.

Example:

Device# show ap name ap-name tag detail

The AP is now associated with the specified policy, site, and optionally, RF tags. You can confirm these assignments using the verification commands.

Trigger and verify pre-download to a site tag

Start and confirm an image pre-download for a specific site tag by using CLI

Use this task to distribute a new software image to primary and secondary APs in advance of a full deployment.

Before you begin

Identify the site tag to which you want to pre-download the image.

Procedure

Step 1

Enter the privileged EXEC mode.

Example:

Device> configure terminal

Step 2

Instruct the primary APs to start image predownload.

Example:

Device# ap image predownload site-tag rr-xyz-site start

Step 3

Display the list of primary APs per AP model per site tag.

Example:

Device# show ap primary list

Step 4

Display the pre-downloading state of primary and secondary APs.

Example:

Device# show ap image

Note

 

To check if efficient image upgrade is enabled in the AP, use the show capwap client rcb command on the AP console.

Example

The output displays the primary AP.

Device# show ap primary list
AP Name                        WTP Mac          AP Model          Site Tag       
-----------------------------------------------------------------------------------------
AP0896.AD9D.3124               f80b.cb20.2460   AIR-AP2802I-D-K9 ST1

The output shows that the primary AP has started pre-downloading the image. 

Device# show ap image
Total number of APs: 6
 
AP Name             Primary Image   Backup Image  Predownload Status   Predownload Version  Next Retry Time   Retry Count
--------------------------------------------------------------------------------------------------------------------------
APE00E.DA99.687A    16.6.230.37     0.0.0.0       None                 0.0.0.0              N/A               0
AP188B.4500.4208    16.6.230.37     8.4.100.0     None                 0.0.0.0              N/A               0
AP188B.4500.4480    16.6.230.37     0.0.0.0       None                 0.0.0.0              N/A               0
AP188B.4500.5E28    16.6.230.37     16.4.230.35   None                 0.0.0.0              N/A               0
AP0896.AD9D.3124    16.6.230.37     8.4.100.0     Predownloading       16.6.230.36          0                 0
AP2C33.1185.C4D0    16.6.230.37     8.4.100.0     None                 0.0.0.0              N/A               0

The output shows that the primary AP has completed pre-download and the pre-download has been initiated in the secondary APs.

Device# show ap image

Total number of APs: 6
AP Name             Primary Image   Backup Image  Predownload Status   Predownload Version  Next Retry Time   Retry Count
--------------------------------------------------------------------------------------------------------------------------
APE00E.DA99.687A    16.6.230.37     0.0.0.0       Initiated            16.6.230.36          N/A               0
AP188B.4500.4208    16.6.230.37     8.4.100.0     None                 0.0.0.0              N/A               0
AP188B.4500.4480    16.6.230.37     0.0.0.0       None                 0.0.0.0              N/A               0
AP188B.4500.5E28    16.6.230.37     16.4.230.35   None                 0.0.0.0              N/A               0
AP0896.AD9D.3124    16.6.230.37     8.4.100.0     Complete             16.6.230.36          0                 0
AP2C33.1185.C4D0    16.6.230.37     8.4.100.0     Initiated            16.6.230.36          0                 0

The output shows image status of a particular AP.

Device# show ap name APe4aa.5dd1.99b0 image 
AP Name : APe4aa.5dd1.99b0
Primary Image : 16.6.230.46
Backup Image : 3.0.51.0
Predownload Status : None
Predownload Version : 000.000.000.000
Next Retry Time : N/A
Retry Count : 0

The output shows pre-download completion on all APs. 

Device# show ap image
Total number of APs: 6
 
Number of APs
        Initiated                  : 0
        Predownloading             : 0
        Completed predownloading   : 3
        Not Supported              : 0
        Failed to Predownload      : 0

AP Name             Primary Image   Backup Image  Predownload Status   Predownload Version  Next Retry Time   Retry Count
--------------------------------------------------------------------------------------------------------------------------
APE00E.DA99.687A    16.6.230.37     16.6.230.36   Complete            16.6.230.36           N/A               0
AP188B.4500.4208    16.6.230.37     8.4.100.0     None                0.0.0.0               N/A               0
AP188B.4500.4480    16.6.230.37     0.0.0.0       None                0.0.0.0               N/A               0
AP188B.4500.5E28    16.6.230.37     16.4.230.35   None                0.0.0.0               N/A               0
AP0896.AD9D.3124    16.6.230.37     16.6.230.36   Complete            16.6.230.36           0                 0
AP2C33.1185.C4D0    16.6.230.37     16.6.230.36   Complete            16.6.230.36           0                 0

Feature History for Out-of-Band AP Image Download

This table provides release and related information for the feature explained in this module.

This feature is available in all the releases subsequent to the one in which it is introduced in, unless noted otherwise.

Table 1. Feature History for Out-of-Band AP Image Download

Release

Feature

Feature Information

Cisco IOS XE Dublin 17.11.1

Out-of-Band AP Image Download

The AP image upgrade method is enhanced to make the upgrades faster and more flexible.

Information About Out-of-Band AP Image Download

In WLAN deployments, the APs gather their software image and configuration from the controller (in-band) during the join, predownload, and upgrade phases over the CAPWAP control path. This mechanism has limitations in the context of CAPWAP window size, processing of CAPWAP packets, and parallel image downloads. With image upgrade being a significant activity in the lifecycle of APs, upgrades become a time-consuming activity when the deployment size increases, especially for remote deployments, because the image always comes from the controller, irrespective of the deployment types.

To make upgrades faster and more flexible, the AP image upgrade method is enhanced in Cisco IOS XE Dublin 17.11.1 release. An enhanced webserver (nginx) running on the controller helps the AP image downloads to be available out of the CAPWAP path (out of band).

Note

  • HTTPS configuration done at the global level applies to all the APs joining the controller.

  • When AP image download over an Out-of-Band method fails, the download falls back to the CAPWAP method, as a result of which the APs will not be stranded.

  • AP image download over HTTPS may fail if the HTTPS server Trustpoint has a chain of CA certificates.

  • Before you downgrade from Cisco IOS XE Dublin 17.11.1 to an earlier version, ensure that the Out-of-Band AP Image Download feature is disabled, as it is not supported in previous releases.

Restrictions for Out-of-Band AP Image Download

This feature is not supported on the following platforms:

  • Cisco Embedded Wireless Controller on Catalyst Access Points

  • Cisco Embedded Wireless Controller on Catalyst Switches

  • Cisco Wave 1 Access Points

Download AP Image from Controller Using HTTPS (CLI)

Before you begin

  • HTTPS configuration must be enabled.

  • The ngnix server must be running on the controller. Use the show platform software yang-management process command to check whether the ngnix server is running.

  • The custom-configured port must be reachable between the controller and the corresponding AP.

Procedure

  Command or Action Purpose

Step 1

configure terminal

Example:

Device# configure terminal

Enters the global configuration mode.

Step 2

ap upgrade method https

Example:

Device(config)# ap upgrade method https

Configures the corresponding AP to download the image over HTTPS from the controller if the AP supports out-of-band AP image download method.

You can check whether the AP supports efficient download method using the show ap config general command.

Use the no form of this command to disable out-of-band AP image download method.

Step 3

ap file-transfer https port port_number

Example:

Device(config)# ap file-transfer https port 8445

Configures a custom port for image download from the nginx server running on the controller.

For HTTPS port, the valid values range from 0 to 65535, with a default of 8443. You cannot use port 443 for AP file transfers because it is the default port used for other HTTPS requests. Also, avoid configuring standard and well-known ports because the configuration may fail.

By default, the Efficient AP image download feature uses port 8443 for HTTPS. If the same port is configured for HTTPS access for controller GUI, then GUI access will not work. In such instances, use a port number other than 8443 for controller GUI Access or configure a different port for AP file transfer over HTTPS instead of 8443.

The port 8443 is customazible. A sample config is given below:

Source= wireless controller
Destination= Access Point
Protocol=HTTPS
Destination Port=8443
Source Port=any
Description= "Out of Band AP Image Download"

Step 4

end

Example:

Device(config)# end

Returns to privileged EXEC mode.

Download AP Image from Controller Using HTTPS (GUI)

Procedure

Step 1

Choose Configuration > Wireless > Wireless Global.

Step 2

In the AP Image Upgrade section, enable the HTTPS Method to allow image download on APs from the controller, over HTTPS. This out-of-band file transfer is an efficient method for AP image upgrade.

Note

 

The AP should support out-of-band image download. You can verify this in the Configuration > Wireless > Access Points window. Select the AP, and in the Edit AP > Advanced tab, view the details of the support in the AP Image Management section.

Step 3

Enter the HTTPS Port to designate AP file transfers on that port. Valid values range from 0 to 65535, with the default being 8443. Note that you cannot use port 443 for AP file transfers because that is the default port for other HTTPS requests.

By default, the Efficient AP image download feature uses port 8443 for HTTPS. If the same port is configured for HTTPS access for controller GUI, then GUI access will not work. In such instances, use a port number other than 8443 for controller GUI Access or configure a different port for AP file transfer over HTTPS instead of 8443.

Step 4

Click Apply to Device to save the configuration.

Verifying Image Upgrade

To check whether an AP supports efficient download method, use the following command:

Device# show ap config general

Cisco AP Name : AP002C.C862.E880
=================================================

Cisco AP Identifier : 002c.c88b.0300
Country Code : Multiple Countries : IN,US
Regulatory Domain Allowed by Country : 802.11bg:-A 802.11a:-ABDN
AP Country Code : US - United States
AP Regulatory Domain
802.11bg : -A
AP Upgrade Out-Of-Band Capability : Enabled
AP statistics : Disabled

To view the AP image download statistics, use the following command.

Use the show ap image command to see the detailed output. 

Device# show ap image summary

Total number of APs  : 1
Number of APs 
        Initiated                  : 0
        Downloading                : 0
        Predownloading             : 0
        Completed downloading      : 0
        Completed predownloading   : 0
        Not Supported              : 0
        Failed to Predownload      : 0
        Predownload in progress    : No

To view the method used to download the AP image, use the following command:

Device# show wireless stats ap image-download

AP image download info for last attempt
AP Name  Count ImageSize StartTime         EndTime            Diff(secs) Predownload Aborted  Method 
-----------------------------------------------------------------------------------------------------
mysore1  1     40509440  08/23/21 22:17:59 08/23/21 22:19:06  67         No          No       CAPWAP

To view the method used to download the AP image, use the following command:

Device# show ap upgrade method 

AP upgrade method HTTPS : Disabled

To view the port used for the AP image transfer, use the following command:

Device# show ap file-transfer https summary 
 

       Configured port                 : 8443
       Operational port                : 8443

!If different ports are shown under 'Configured port' and 'Operations port' 
!that means custom port configuration has failed and is continuing with the previous port. 
!The failure reason could be the input port, which is a well-known port and already in use.

To view the whether an AP supports image download over HTTPS, use the following command:

Device# show ap name AP2800 config general | sec Upgrade

AP Upgrade Out-Of-Band Capability               : Enabled

To view the detailed output an AP's pre-image, use the following command:

Device# show ap image

Total number of APs  : 2
Number of APs 
        Initiated                  : 0
        Downloading                : 0
        Predownloading             : 0
        Completed downloading      : 2
        Completed predownloading   : 0
        Not Supported              : 0
        Failed to Predownload      : 0
        Predownload in progress    : No
AP Name    Primary Image Backup Image Predownload Status Predownload Version Next Retry Time Retry Count Method
--------------------------------------------------------------------------------------------------------------------
AP_3800_1  17.11.0.69    17.11.0.71   None               0.0.0.0             N/A             0           HTTPS
AP2800     17.11.0.69    17.11.0.71   None               0.0.0.0             N/A             0           HTTPS

!The 'method' column indicates the download method used by the AP.