Migrate from AireOS WLC to Catalyst 9800 with WLANPoller

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.

Prerequisites

Requirements

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.

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.

9800 version 17.9 requires an upgrade path through 17.3.7 if coming from an earlier version and if coming from AireOS 8.x software. It is not possible to have a smooth transition between an 8.5 WLC and a 17.9 9800 using this article to achieve a single pre-download, you need to use this article to do a pre download to 17.3.7 and then let the APs download 17.9 from the WLC using the usual process after that.

If an AP downloads the 17.9 code while running a version earlier than 17.3.5/17.3.6/17.3.7, it complain about not having enough space to install the 17.9 image. This upgrade path is not required if you are going to an earlier 9800 release than 17.9 (check the 9800 release notes to see if there an upgrade path. Consider coming from AireOS is like coming from a 16.12 9800).

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

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, see  Enterprise WLAN-Poller Version) 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>

Select Which APs are 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 the list of AP names and IPs that the script must connect to there.

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
============================================================

If There are Problems During the Run 

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:

username % pwd
/Users/username/Downloads/Enterprise-WlanPoller-Mac-3.0-Bundle/data/2021/01/25
username % ls
cos_1815AP.log wlc_WLCNico.log
username % 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>

username %

Configure WLAN Poller Files for the AP Migration Operation

If you now move the APs to the 9800, they try to join it with their current partition, notice the code is different but that they have the right code version in their backup partition and then reboot.

You could be a few seconds quicker (saving the first join attempt) by adding a "config boot path 2" and then "%confirm% reload" commands to this text file. This would then set the backup partition as the new active and immediately reboot (without giving the time to try to join the 9800 WLC). The AP will immediately reboot and then join the 9800 with the right code version.

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.

Cmdlist_cos.txt

show clock
capwap ap secondary-base dummy 192.168.2.1
capwap ap primary-base <9800 name> <9800 IP>

Related Information

• Enterprise WLAN-Poller Version
• Cisco Technical Support & Downloads