Predownloading an Image to an Access Point

Image pre-downloads to AP

An image pre-download is a software distribution process that

  • downloads an upgrade image to an AP from the device,

  • minimizes network outages and allows continuous connectivity during the image download process, and

  • ensures the AP can join and register with the controller immediately after the upgrade.

Additional reference information

Previously, you could download an upgrade image to the device and reset it. This AP then entered discovery mode. After discovering the controller with the new image, the AP downloads the new image, resets itself, enters discovery mode, and rejoins the device.

You can now download the upgrade image to the controller. When the controller is operational with the upgrade image, the AP joins the controller and moves to Registered state, because the AP image has been predownloaded to the AP.

Feature history for AP pre-download

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

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

Table 1. Feature history for AP pre-download

Release

Feature Information

Cisco IOS XE Bengaluru 17.5.x

This feature now has GUI and YAML support.

For more information, see the Programmability Configuration Guide, Cisco IOS XE Bengaluru 17.5.x.

Cisco IOS XE Gibraltar 16.11.1

This feature minimizes network outages, downloads an upgrade image to an access point from the device without resetting the access point or losing network connectivity.

This feature has CLI support only.

Restrictions and best practices for pre-downloading an image to an AP

Restrictions

  • You can pre-download images for up to 100 APs per Wireless Network Control Daemon (WNCD) instance on the controller when using the default CAPWAP method, and up to 50 APs per WNCD instance when using the HTTPS upgrade method. For the Catalyst 9800-L model, image pre-download is limited to 25 APs per WNCD instance for CAPWAP method.

    The controller initiates pre-download requests periodically until the maximum number of APs allowed for that interval is reached. The trigger interval is every ten seconds for CAPWAP-based upgrades and every one second for HTTPS-based upgrades.

  • If an AP has only 16 MB total available memory, it may not have enough free memory to download an upgrade image. To free up space, the AP may automatically delete crash information files, radio files, and backup images. Pre-downloading is not affected because the pre-download image replaces any backup images on the AP.

  • Ensure that all primary, secondary, and tertiary controllers run the same images. If the images differ, the feature does not work.

  • Each AP can store only two software images.

  • The controller supports only self-signed certificates and does not support Cisco certificates. If AP join fails after you move APs between controllers, run the capwap ap erase all command to remove the hash string from the APs.

  • If the latest upgrade image is already on the AP, pre-download is not triggered. Check whether the primary and backup image versions are the same as the upgrade image, using the show ap image command.

Known behavior

  • Predownload of the AP image is based on the AP model rather than the image type.

  • If the AP flaps after Stateful Switchover (SSO) and during AP pre-download, the AP continues to be in predownloading state. Use the ap image predownload abort command and then the clear ap predownload stats command only then the pre-download can be initiated again.

  • When you upgrade Cisco Wave 1 APs from Cisco AireOS Release 8.3 to Cisco IOS XE Gibraltar 16.10.1, the AP may download the image twice. This can increase downtime during migration.

Best Practices

  • Before you reset the controller, ensure all APs have completed downloading the image.

  • To view cumulative statistics about AP images in the controller, you must first use the clear ap predownload statistics command to clear the statistics and ensure that the correct data is displayed. Then, use the show ap image command to view cumulative statistics about AP images in the controller,

  • During AP image pre-download, the WNCD CPU may reach 99 percent. This is normal and does not cause crashes or disconnect problems for clients or APs.

Procedures

Pre-download an image to AP (CLI)

Minimize downtime during controller upgrades by pre-downloading and activating a new software image on connected APs.

Use this task if you want to push an image to APs before an upgrade, minimizing downtime during switchover.

For more information, see this video.

Before you begin

  • Ensure the controller is in install mode.

  • Confirm the AP model exists in the new capability XML file on the controller and maintained internally in the controller. With the appropriate modification of the capability XML through a controller upgrade, APSP, or APDP installation, the controller can override the existing AP image for a particular model.

  • Copy the new image either from the TFTP server, flash image, or USB.

Procedure

Step 1

Add and expand the controller software image.

Example:
Device# install add file bootflash:image.bin

Step 2

Download the new image to all the APs or a specific AP connected to the device.

Example:
Device# ap image predownload
Device# ap name ap1 image predownload

Step 3

Verify the AP's pre-download status.

Example:
Device# show ap image

This command initially displays the status as Predownloading and then moves to Completed, when download is complete.

Step 4

Display image details of a particular AP.

Example:
Device# show ap name myapname image

Step 5

Swap images of the APs that have completed pre-download.

Example:
Device# ap image swap
Device# ap name myapname image swap
Device# ap image swap completed

Note

 

You can swap the AP images using ap image swap command even without pre-downloading a new image to the AP and there are no restrictions or prerequisites to swap the image.

Step 6

Run compatibility checks, install the package, and update the package status details

Example:
Device# install activate

For restartable packages, the command triggers the appropriate post-install scripts to restart the necessary processes,

For non-restartable packages, the command triggers a reload.

Note

 

This step reloads the complete controller stack. If HA is used, both primary and secondary controllers.

Step 7

Commit the activation changes to be persistent across reloads.

Example:
Device# install commit
.

The commit can be done after activation while the system is up, or after the first reload. If the package is activated but not committed, it remains active after the first reload, but not after the second reload.

The new software image is downloaded and activated on all designated APs

What to do next

Monitor AP connectivity and operation to confirm successful upgrade.

Pre-download an image to AP (GUI)

Before you begin

  • Ensure the Upgrade mode of the controller is in install mode.

You can minimize downtime during controller upgrades by pre-downloading and activating a new software image on connected APs using the connector GUI.

You can also see the video demonstration.

Procedure

Step 1

Choose Administration > Software Management and click the Software Upgrade .

Step 2

Set necessary parameters:

  1. Select a Transport Type.

  2. Select a File Path.

  3. Select Source File Path.

Step 3

Check the AP Image Predownload check box.

If you already have an inactive image file on your device, a dialog box prompts you to remove the unused image and proceed with the latest image download.

Step 4

Click Download and Install to initiate the upgrade process.

You can view and verify the pre-download progress in the Status dialog box. You can also check the progress log by clicking the Show Logs icon.

Step 5

When the pre-download is completed, click Save Configuration and Activate.

Step 6

Click Yes to confirm the activation.

This step runs compatibility checks, installs the package, and updates the package status details. After a successful activation, the AP reloads. If there are uncommitted files, the system prompts you to remove those.

Step 7

Click Commit to complete the upgrade process.

The new image is pre-downloaded, and activated on the APs. The APs reload with upgraded software.

Pre-download an image to AP (YANG)

Prepare an AP for a software upgrade or deployment by pre-downloading an image using YANG automation.

Use YANG with NETCONF and RESTCONF to automate and program network operations

Procedure
Command or Action Purpose

Send the NETCONF remote procedure call (RPC) call using your management client to initiate the image pre-download. Replace <uuid> with the correct value for your environment 


<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
  <set-rad-predownload-all xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-wireless-access-point-cmd-rpc">
    <uuid>12312341231234</uuid>
  </set-rad-predownload-all>
</rpc>
The image is pre-downloaded to the access point, making it available for upgrade or installation.
What to do next

Refer to the Cisco IOS XE Programmability Configuration Guide and YANG Data Models on Github website for more details.

Contact the Developer Support Community for NETCONF or YANG features.

Monitor AP pre-download

This section describes the commands for monitoring AP pre-download from the controller.

Verify the AP pre-download status and progress from the controller:


        Controller# show ap image
        Total number of APs  : 1
        
        Number of APs 
        Initiated                  : 1
        Predownloading             : 1
        Completed predownloading   : 0
        Not Supported              : 0
        Failed to Predownload      : 0
        
        AP Name                           Primary Image   Backup Image    Predownload Status    Predownload Ver...  Next Retry Time    Retry Count 
        ------------------------------------------------------------------------------------------------------------------------------------------
        AP1                               10.0.1.66       10.0.1.66       Predownloading        10.0.1.67           NA                           0 
        
        
      

        Controller# show ap image
        
        Total number of APs  : 1
        
        Number of APs 
        Initiated                  : 1
        Predownloading             : 0
        Completed predownloading   : 1
        Not Supported              : 0
        Failed to Predownload      : 0
        
        AP Name                           Primary Image   Backup Image    Predownload Status    Predownload Ver...  Next Retry Time    Retry Count 
        ------------------------------------------------------------------------------------------------------------------------------------------
        AP1                               10.0.1.66       10.0.1.67       Complete              10.0.1.67           NA   
        0

Verify the image details of a particular AP:


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

AP image download time enhancement

AP image download time enhancement is a feature that

  • adds support to multiple sliding windows for control packets going from controller to AP

  • reduces image download time in Cloud and FlexConnect deployments where the AP and controller are separated by a WAN or Internet link, and

  • is supported only on OEAP profiles.

CAPWAP communication and window enhancement

The wireless controller and the access point (AP) communicate with each other using CAPWAP. The CAPWAP has two channels, namely control and data. The control channel is used to send configuration messages, download images and client keys, or the context to the AP. The control channel has a single window in the current implementation. A single window means that every message that is sent from the controller has to be acknowledged by the AP. The next control packet is not transmitted till the earlier one is acknowledged by the AP.

The AP Image Download Time Enhancement feature adds support to multiple sliding windows for control packets going from controller to AP. The sliding window can be set to N (static) instead of a single window. The request queue size is decided based on the maximum window size the AP supports.

The following table shows the recommended window size for different network conditions:

Table 2. Recommended window size

Link Bandwidth1

Less than 200 ms RTT

Greater than 200 ms RTT

More than 20 Mbps

10

15

Between 5 and 20 Mbps

10

15

Between 1 and 5 Mbps

5

10

Less than 1 Mbps

3

5
1 The window size recommendation provided in the table is for packet loss of less than one percent (< 1%). If the network supporting the CAPWAP link has packet loss of more than one percent (> 1%), use a smaller value for window size. For good links with round-trip time (RTT) of about 100ms and packet drops of less than half a percent (< 0.5%), use a window size of up to 20 for better performance.

Note

  • The window size can be changed only during the AP join process.

  • All image upgrades should be in the install mode for faster upgrade. Image upgrade should be done from the one-shot command to include OEAP predownload.

  • Configure the window size only for AP profiles that are exclusively used for Teleworker or Office Extend Access Points (OEAP).

  • An AP reload is not required after disabling this feature.

  • This feature is supported only on the OEAP profiles.

  • GUI does not support AP predownload. Therefore, the AP downloads after disjoining the controller during CAPWAP join phase. This causes a long disruption in the network as the Image download for AP can take upto one hour.


Important

If you downgrade the software to Cisco IOS XE Gibraltar 16.12.4 or earlier from Cisco IOS XE Amsterdam 17.3.1, you should reset the CAPWAP multi window to a single window prior to the downgrade. Failure to do so necessitates a manual AP recovery.

High-level workflow for AP Image Download Time Enhancement:

  1. Select an existing AP join profile or create a new one.

  2. Set the CAPWAP window size.

  3. Associate the AP join profile to an existing site tag or new one.

  4. Apply the site tag to the AP using: Static, Filter, Location, AP, or Default mapping method.

Configure AP Image Download Time Enhancement (GUI)

AP Image Download Time Enhancement optimizes the download performance of access point images by configuring CAPWAP window size settings to improve data transfer efficiency.

Use this procedure when you need to optimize access point image download performance through CAPWAP configuration settings. This enhancement is particularly useful in environments with high-latency network connections or when managing large numbers of access points.

Follow these steps to configure AP Image Download Time Enhancement using the GUI:

Procedure

Step 1

Choose Configuration > Tags & Profiles > AP Join > CAPWAP > Advanced.

Step 2

In the CAPWAP Window Size field, enter the unit of measurement of the window.

Step 3

Click Save & Apply to Device.

The AP Image Download Time Enhancement configuration is applied to the device. Access points will use the optimized CAPWAP window size settings for improved image download performance.

Configure AP Image Download Time Enhancement (CLI)

Enable AP Image Download Time Enhancement to optimize the download process for access points.
AP Image Download Time Enhancement improves the efficiency of firmware downloads to access points by configuring the CAPWAP control packet transmit queue size. This configuration is particularly beneficial for teleworker or OEAP deployments.

Procedure

Step 1

Enter global configuration mode.

Example:

Device# configure terminal

Step 2

Configure an AP profile.

Example:

Device(config)# ap profile ap-profile-name

Example:

Device(config)# ap profile capwap_multiwindow

Step 3

Configure the AP CAPWAP control packet transmit queue size.

Example:

Device(config-ap-profile)# capwap window size window-size

Example:

Device(config-ap-profile)# capwap window size 20

Note

 

Configure the window size only for AP profiles that are exclusively used for teleworker or OEAP.

Be aware that any change in window size may impact other APs.

Step 4

Return to privileged EXEC mode.

Example:

Device(config-ap-profile)# end
The AP Image Download Time Enhancement is now configured with the specified CAPWAP window size, optimizing firmware download performance for the designated AP profile.

Verify AP image download time enhancement configuration

Verify AP Image Download Time Enhancement Configuration using commands to view CAPWAP window size, status, and modes.

To view the CAPWAP window size present in an AP profile, use this command:

Device# show ap profile name default-ap-profile detailed | in wind

Capwap window size : 10

To view the CAPWAP status and modes, use this command:

Device# show capwap client rcb 

OperationState                     : UP
Name                               : AP4001.7A39.2D5A
MwarHwVer                          : 0.0.0.0
Location                           : default location
ApMode                             : Remote Bridge
ApSubMode                          : Not Configured
CAPWAP Path MTU                    : 1485
Software Initiated Reload Reason   : Reload command
CAPWAP Sliding Window
Active Window Size                 : 10
Last Request Send To Application   : 184
Expected Seq Num                   : 185
Received Seq Num                   : 184
Request Packet Count               : 42424
Out Of Range Packets Count         : 0
Window Moved  Packets Count        : 0
In Range Packets Count             : 960
Expected Packets Count             : 41464

To view the AP configuration details, including the CAPWAP window size, use this command:

Device# show ap config general | in Wind

Capwap Active Window Size                       : 5
Capwap Active Window Size                       : 10
Capwap Active Window Size                       : 1

AP image download time enhancement

AP image download time enhancement is a feature that

  • adds support to multiple sliding windows for control packets going from controller to AP

  • reduces image download time in Cloud and FlexConnect deployments where the AP and controller are separated by a WAN or Internet link, and

  • is supported only on OEAP profiles.

CAPWAP communication and window enhancement

The wireless controller and the access point (AP) communicate with each other using CAPWAP. The CAPWAP has two channels, namely control and data. The control channel is used to send configuration messages, download images and client keys, or the context to the AP. The control channel has a single window in the current implementation. A single window means that every message that is sent from the controller has to be acknowledged by the AP. The next control packet is not transmitted till the earlier one is acknowledged by the AP.

The AP Image Download Time Enhancement feature adds support to multiple sliding windows for control packets going from controller to AP. The sliding window can be set to N (static) instead of a single window. The request queue size is decided based on the maximum window size the AP supports.

The following table shows the recommended window size for different network conditions:

Table 3. Recommended window size

Link Bandwidth2

Less than 200 ms RTT

Greater than 200 ms RTT

More than 20 Mbps

10

15

Between 5 and 20 Mbps

10

15

Between 1 and 5 Mbps

5

10

Less than 1 Mbps

3

5
2 The window size recommendation provided in the table is for packet loss of less than one percent (< 1%). If the network supporting the CAPWAP link has packet loss of more than one percent (> 1%), use a smaller value for window size. For good links with round-trip time (RTT) of about 100ms and packet drops of less than half a percent (< 0.5%), use a window size of up to 20 for better performance.

Note

  • The window size can be changed only during the AP join process.

  • All image upgrades should be in the install mode for faster upgrade. Image upgrade should be done from the one-shot command to include OEAP predownload.

  • Configure the window size only for AP profiles that are exclusively used for Teleworker or Office Extend Access Points (OEAP).

  • An AP reload is not required after disabling this feature.

  • This feature is supported only on the OEAP profiles.

  • GUI does not support AP predownload. Therefore, the AP downloads after disjoining the controller during CAPWAP join phase. This causes a long disruption in the network as the Image download for AP can take upto one hour.


Important

If you downgrade the software to Cisco IOS XE Gibraltar 16.12.4 or earlier from Cisco IOS XE Amsterdam 17.3.1, you should reset the CAPWAP multi window to a single window prior to the downgrade. Failure to do so necessitates a manual AP recovery.

High-level workflow for AP Image Download Time Enhancement:

  1. Select an existing AP join profile or create a new one.

  2. Set the CAPWAP window size.

  3. Associate the AP join profile to an existing site tag or new one.

  4. Apply the site tag to the AP using: Static, Filter, Location, AP, or Default mapping method.

Configure AP Image Download Time Enhancement (GUI)

AP Image Download Time Enhancement optimizes the download performance of access point images by configuring CAPWAP window size settings to improve data transfer efficiency.

Use this procedure when you need to optimize access point image download performance through CAPWAP configuration settings. This enhancement is particularly useful in environments with high-latency network connections or when managing large numbers of access points.

Follow these steps to configure AP Image Download Time Enhancement using the GUI:

Procedure

Step 1

Choose Configuration > Tags & Profiles > AP Join > CAPWAP > Advanced.

Step 2

In the CAPWAP Window Size field, enter the unit of measurement of the window.

Step 3

Click Save & Apply to Device.

The AP Image Download Time Enhancement configuration is applied to the device. Access points will use the optimized CAPWAP window size settings for improved image download performance.

Configure AP Image Download Time Enhancement (CLI)

Enable AP Image Download Time Enhancement to optimize the download process for access points.
AP Image Download Time Enhancement improves the efficiency of firmware downloads to access points by configuring the CAPWAP control packet transmit queue size. This configuration is particularly beneficial for teleworker or OEAP deployments.

Procedure

Step 1

Enter global configuration mode.

Example:

Device# configure terminal

Step 2

Configure an AP profile.

Example:

Device(config)# ap profile ap-profile-name

Example:

Device(config)# ap profile capwap_multiwindow

Step 3

Configure the AP CAPWAP control packet transmit queue size.

Example:

Device(config-ap-profile)# capwap window size window-size

Example:

Device(config-ap-profile)# capwap window size 20

Note

 

Configure the window size only for AP profiles that are exclusively used for teleworker or OEAP.

Be aware that any change in window size may impact other APs.

Step 4

Return to privileged EXEC mode.

Example:

Device(config-ap-profile)# end
The AP Image Download Time Enhancement is now configured with the specified CAPWAP window size, optimizing firmware download performance for the designated AP profile.

Verify AP image download time enhancement configuration

Verify AP Image Download Time Enhancement Configuration using commands to view CAPWAP window size, status, and modes.

To view the CAPWAP window size present in an AP profile, use this command:

Device# show ap profile name default-ap-profile detailed | in wind

Capwap window size : 10

To view the CAPWAP status and modes, use this command:

Device# show capwap client rcb 

OperationState                     : UP
Name                               : AP4001.7A39.2D5A
MwarHwVer                          : 0.0.0.0
Location                           : default location
ApMode                             : Remote Bridge
ApSubMode                          : Not Configured
CAPWAP Path MTU                    : 1485
Software Initiated Reload Reason   : Reload command
CAPWAP Sliding Window
Active Window Size                 : 10
Last Request Send To Application   : 184
Expected Seq Num                   : 185
Received Seq Num                   : 184
Request Packet Count               : 42424
Out Of Range Packets Count         : 0
Window Moved  Packets Count        : 0
In Range Packets Count             : 960
Expected Packets Count             : 41464

To view the AP configuration details, including the CAPWAP window size, use this command:

Device# show ap config general | in Wind

Capwap Active Window Size                       : 5
Capwap Active Window Size                       : 10
Capwap Active Window Size                       : 1