Cisco Catalyst 9800 Series Wireless Controller Software Configuration Guide, Cisco IOS XE 26.1.x

PDF

Cisco Catalyst 9800 Series Wireless Controller Software Configuration Guide, Cisco IOS XE 26.1.x

Image pre-downloads to AP

Updated: April 10, 2026

Want to summarize with AI?

Log in

Introduces AP image pre-download concepts, detailing feature history and outlining restrictions that impact image deployment to access points on controllers.

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

1.

Add and expand the controller software image.

Example:

Device# install add file bootflash:image.bin
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
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.
4.

Display image details of a particular AP.

Example:

Device# show ap name myapname image
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.
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.
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

1.

Choose Administration > Software Management and click the Software Upgrade .

2.

Set necessary parameters:

  1. Select a Transport Type.

  2. Select a File Path.

  3. Select Source File Path.
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.
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.

5.

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

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.

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

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