Predownloading an Image to an Access Point

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.

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.

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. For the 9800-L model, you can pre-download images for up to 25 APs per WNCD instance. The controller triggers pre-downloads in sets of 16 APs per WNCD instance. This process repeats every 60 seconds.

  • 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.

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

Information About AP Image Download Time Enhancement (OEAP or Teleworker Only)

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.

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 of 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.

Configuring AP Image Download Time Enhancement (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.

Configuring AP Image Download Time Enhancement (CLI)

Procedure

  Command or Action Purpose

Step 1

configure terminal

Example:

Device# configure terminal

Enters the global configuration mode.

Step 2

ap-profile ap-profile

Example:

Device(config)# ap profile capwap_multiwindow

Configures an AP profile.

Step 3

capwap window size window-size

Example:

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

Configures the AP CAPWAP control packet transmit queue size.

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

end

Example:

Device(config-ap-profile)# end

Returns to privileged EXEC mode.

Verifying AP Image Download Time Enhancement Configuration

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

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

Capwap window size : 10

To view the CAPWAP status and modes, use the following 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 the following command:

Device# show ap config general | in Wind

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