Migrate from AireOS WLC to Catalyst 9800 Using Automation with WLANPoller for AP Pre-download

Introduction

This document describes the specific use case of a migration from an AireOS Wireless LAN Controller (WLC) to a Cisco IOS-XE based Catalyst 9800 WLC.

Requirements

This is a migration where the network adminiustrator is looking to minimize the downtime to wireless clients as much as possible. This article does not cover the migration of the configuration between the two controller models and only focuses on automating the AP-predownload so that the Access Points (AP) only reboot once when changing controller.

Components used

This article was written based on a 9800-L and 3504 scenario, running 8.10 and 17.4.1, however it must apply similarly to all software versions as well as to 9800-CL,9800-40,9800-80, 5520,8540, vWLC and 8510.

It requires WLANPoller version 3.1

Prerequisites

This document assumes you have an AireOS WLC and a 9800 WLC both already configured and ready for migration. It also assumes that you have configured a TFTP/SFTP server in your network that is reachable by the access points.

Problem

To minimize the downtime during an upgrade, the network administrator typically relies on AP pre-download. This feature allows, when the controller has already downloaded a new code but has not rebooted on that new code yet, APs to download the new code already while still servicing clients. This means that when the WLC reboots on the new code, the APs reboot only once in order to boot on that new code.

Without AP pre-download, APs have to wait for the WLC to come back online on the new code in order to try to join it and realize only then that they need to download a new code, download it all at the same time and then reboot and try to join once again.

AP pre-download, on top of reducing client downtime, is also helpful for situations where branches have a small WAN connection or the latency on the WAN connection means a long time to download the new code for these APs. The download happens while the AP is still servicing clients when using AP pre-download.

However, the problem in the case of a migration is that you are dealing with two separate controller (one running AireOS and one running Cisco IOS-XE) and there is no embedded means to use AP pre-download in this situation for the AP to pre-download a code from another controller. The solution lies in programmability and automation.

Solution

Workflow concept

This article explains the automation (using the publicly available WLAN Poller tool, available at https://community.cisco.com/t5/wireless-mobility-documents/enterprise-wlan-poller-version/ta-p/4010526) of a simple process :

• Connect to all, or a subset of, APs joined to the AireOS WLC via SSH
• Start the pre-download of the Cisco IOS-XE AP image via the archive download-sw command. The AP then downloads the image to its backup partition while still servicing clients and operating normally
• When ready to migrate the AP, configure the 9800 WLC as primary WLC for the APs and reboot them
• APs reboot on the new (Cisco IOS-XE compatible) code immediately and join the 9800 WLC without any further reboot, limiting the downtime to one reboot cycle.

The advantage lies in the de-coupling of the code download from the actual migration/reboot and the limitation to one reboot cycle

Prepare the file server with the AP images

The easiest way is to download the AP bundle file contain all AP images for a given version. Go to cisco.com download section and download the 9120 Embedded Wireless Controller file for the release of your choice. It is a .tar file containing the CAPWAP AP image for each AP model. Simply extract all the .tar content to your TFTP/SFTP server and you are done.

Configure WLAN Poller files for the code download operation

After downloading WLAN Poller for Mac or Windows, there are a couple of files to edit to adapt it to your network and configuration.

The WLANPoller, when ran, connects to the WLC, check the APs joined and SSH to all of them. It then runs a specific list of commands on the WLC and on the APs.

CMDlist_wlc.txt

This file contains the list of commands that WLAN Poller runs on the AireOS WLC everytime it is run. We do not need all the commands that are in this file by default, so reduce this file content to only these 2 :

show time
show ap summary

This  lists the APs joined to the WLC and the time, just for tracking and logging purpose

Cmdlist_cos.txt / Cmdlist_cos_bcm.txt / Cmdlist_cos_qca.txt

This file contains the list of commands that are sent to the APs of the x800 series (1800,2800,3800).

Delete the existing set of commands and replace with these commands

show clock
archive download-sw /no-reload tftp://192.168.1.12/%apimage%

Please replace the IP address from the previous example with the IP of your TFTP or SFTP server details

This step depends on several level of the AP models you are targetting.

The file cmdlist_cos_qca only executes commands on 9117 and 9130 access points. The file cmdlist_cos_bcm only executes commands on 9115 and 9120 access points.

the file cmdlist_cos executes commands on 1800s/2800/3800/1540/1560 APs.

This means that you need to write your commands in one or more of these files depending on the APs you have.

The second trick is that you need to specify the right AP image for the right AP model. The example given just before was ran on a 1815 AP which runs the "ap1g5" image file. The keyword %apimage% (percentage characters included) is a special keyword for WLANPoller to replace with the actual ap image filename.

For convenience, here is a table of AP models and the image they run :

Config.ini

The config.ini is the main configuration file and must be changed for certain fields. This section only covers the fields that need to be changed from the default :

wlc_user: <enter the username of the AireOS WLC>
wlc_pasw: <enter the password of the AireOS WLC>
wlc_enable: <re-enter the username of the AireOS WLC>

ap_user: <enter the username for the AP SSH connection>
ap_pasw: <enter the password for the AP SSH connection>
ap_enable: <enter the enable password for the AP SSH connection>

ipaddr: <enter the IP address of the AireOS WLC>

How to select which APs get affected ?

By default, if you just followed the instructions so far, ALL of the APs currently joined to the AireOS WLC is affected by the script.

If you want to do it by batch of APs at a time, there are several ways.

In the config.ini file, you can uncomment the "ap_name_filter =" field and type an AP name prefix.

For example :

ap_name_filter = Branch1-

This filter connects to all APs joined to the WLC whose name start with "Branch1-"

If you want to be more specific, you can use the "aplist:" field of the config.ini file.

A sample CSV file is provided with wlanpoller, you can enter there the list of AP names and IPs that the script must connect to.

Run the AP code pre-download operation and verify

Run the "wlanpoller" script. It then displays the connection details and gives you the amount of APs it saw on the WLC and was able to SSH into. Any error can be displayed in the "Error" section at the end.

Enterprise-WlanPoller-Mac-3.0-Bundle % ./wlanpoller
* Detected local address        : 192.168.1.63
* Logging to syslog server      : 192.168.1.63
* Logging to console enabled    : False
* Logging to file               : ./logs/20210125_wlanpoller.log
* Using TFTP address            : 192.168.1.63
* Using TFTP IPv6 address       : self
* Using FTP address             : 192.168.1.63
* WLC Type AirOS[1] 9800[2]     : 1
* Transfer mode                 : tftp
* Poller enable                 : True
* Event enable                  : False
* DFS trace enable              : False
* WLC config backup             : False
* WLC AP crash upload           : False
* WLC Support Bundle upload     : False
============================================================
 Summary
============================================================
Total APs           : 1
Processed APs       : 1
Failed APs          : 0
============================================================
 Errors
============================================================

Problems running ?

To verify if the script ran just fine so far you can go check for each AP if the backup image is your target Cisco IOS-XE code.

A "show version" on the AP CLI would display for example at this point if all was successful:

AP Running Image     : 8.10.142.0
Primary Boot Image   : 8.10.142.0
Backup Boot Image    : 17.4.1.6

In the WLANpoller "logs" folder, you find timestamped-log file of the WLANpoller script itself if anything went wrong.

The script maybe ran successfully itself but the transfer can have failed. In the "data" folder inside Wlan Poller you find the result of the SSH sessions established by WLAN Poller towards the WLC and APs and can identify any problem. Here is an example where the TFTP server was not online :

ndarchis@NDARCHIS-M-J3HN 25 % pwd
/Users/ndarchis/Downloads/Enterprise-WlanPoller-Mac-3.0-Bundle/data/2021/01/25
ndarchis@NDARCHIS-M-J3HN 25 % ls
cos_1815AP.log	wlc_WLCNico.log
ndarchis@NDARCHIS-M-J3HN 25 % cat cos_1815AP.log
<run timestamp='2021-01-25T14:37:30.888559' device='cos' hostname='1815AP' model='AIR-AP1815I-E-K9' version='8.10.142.0'>
<cmd string='show clock'>
show clock
*13:38:02 UTC Mon Jan 25 2021
1815AP#
</cmd>

<cmd string='archive download-sw /no-reload tftp://192.168.1.12/ap1g5'>
archive download-sw /no-reload tftp://192.168.1.12/ap1g5
Starting download AP image tftp://192.168.1.12/ap1g5 ...
It may take a few minutes. If longer, please abort command, check network and try again.
-=O=-                                                  #     #   #   #
curl: (28) Error
%Error opening tftp://192.168.1.12/ap1g5 (Error 28:  Operation timeout)
Image transfer failed
1815AP#
</cmd>

</run>

ndarchis@NDARCHIS-M-J3HN 25 %

Configure WLAN Poller files for the AP migration operation

Cmdlist_cos.txt

show clock
capwap ap secondary-base dummy 192.0.2.1
capwap ap primary-base <9800 name> <9800 IP>
%confirm% reload

The %confirm% keyword is required when the command after the keyword requires a "[confirm]" prompt such as the reload command does. This auto-accepts the prmopt.

This set of commands sets the 9800 as primary WLC and then triggers the AP reload.

References

https://community.cisco.com/t5/wireless-mobility-documents/enterprise-wlan-poller-version/ta-p/4010526