Cisco Support Community
Showing results for 
Search instead for 
Did you mean: 

WGB Roaming: Internal details and Configuration





WGB is a very useful tool on the design and deployment of a wireless network, as it allows non-wireless devices to gain mobility. As such, it has lots of details on roaming, security access, etc., that impact deployment scenarios depending of your needs.


In code versions 12.4(25d)JA and higher we introduced a set of commands and changes thought to optimize the use of WGB on high speed roaming environments


This document will cover different aspects of how a WGB works, including roaming algorithm decision points, and how to configure it for the intended usage model.



What is a Work Group Bridge?


A WGB is  basically an AP configured to act as a wireless client towards an infrastructure, to provide L2 connectivity for the devices connected to its ethernet interface.


A typical WGB deployment has the following components:

  • WGB device, normally with at least one radio and one Ethernet interface
  • A wireless infrastructure, called normally the "root AP", which can  be either Autonomous or Unified
  • One or more wired client  devices connected to the WGB. This document will not cover mixed role scenarios (one radio as WGB, one radio as root on same AP)


There are three main types of WGB:

  • Cisco WGB: any IOS  based AP configured as WGB (1130, 1240, 1250, etc). This mode will use the IAPP protocol to inform the network infrastructure of the devices that the WGB has learned on its Ethernet interface. In this case, the WLC or root AP has L2 visibility of the devices "hanging" from the WGB.


  • Non  Cisco WGB: this is a third party device acting as a WGB, connecting one or more wired devices to the wireless infrastructure. they will not support IAPP, and they either only allow a single wired device, or they provide a "mac address" translation mechanism, hiding all their wired clients, behind a single 802.11 mac address.  This type of devices need  special handling on ARP and DHCP frames if the infrastructure is a WLC due to the security checks and frame handling done on controllers. This will be discussed on separated document.


  • There is one special  case: Cisco AP configured as "Universal WGB". This is a mode  that suppresses the IAPP mechanism, so the WGB could be used towards a either Cisco infrastructure or third party root APs. In this case, the WGB takes the address of its ethernet client, limiting the number of devices behind it to one.


Here we  will focus on the scenario of a Cisco WGB used either towards autonomous or WLC infrastructure



Usage Scenarios




Typical WGB  use examples include:

  • Connecting a wired printer to the network
  • Different manufacturing deployments, where it is not feasible or practical to run a cable to the wired device
  • In-Vehicle deployments, where the WGB provides connectivity from a car, metro train, etc, to an outdoor wireless network
  • Wired Cameras


Each example has its own requirements on terms of:

  • Bandwidth needed to support the application that will run on top of the wireless infrastructure
  • Roaming delay tolerance: how long it takes for the WGB to move from current AP to next one while the device is moving
  • Forwarding time tolerance: how many frames are lost on each roaming


A printer will not be moving much, so roaming requirements will be lower. A train mounted WGB on the other hand, will need fine tuning on the roaming component, to insure correct behavior while  it is moving around.


A video stream may have a  large bandwidth requirement, so it will need high wireless data rates, but a telemetry application may only need few frames from time to time.


It is very important that the requirements are properly  defined from the beginning, as they affect not only the configuration of the WGB, but also how the wireless infrastructure has to be designed. For example, AP placement, distance, power levels, enabled rates, etc, all affect roaming characteristics, so they will be a crucial point if high speed roaming is needed.


In general, we must have the following details clear:

  • What is the needed bandwidth for the application?
  • What is the roaming delay tolerance?
  • Can  the application handle properly network disconnections? is there an additional backup mechanism  ?
  • Can the application handle packet loss properly? (even on the best wireless design, you must expect a percentage of packet loss)


This document will not address the details on how to design a RF environment for high speed roaming/outdoor. Please refer to outdoor Mesh deployment guide.




For a wireless device, roaming is a very critical part of its functionality.


Basically, roaming means  the capability to go from one AP to another,  both belonging to the same wireless infrastructure.

As a roaming  needs a change from the current AP, to the next, there is a resultant disconnection or time without service . This disconnection can be very small, for example less than 200ms  on voice deployments, or much longer, even seconds, if the security needed enforces a full authentication on each roam event.


Roaming  is needed, so the device can find a new parent with hopefully better signal, and it can continue to access the network infrastructureproperly. At the same time, too many roams can cause  multiple disconnections or time without service, affecting access. It is important for a mobile device, like a WGB,  to have a good roaming algorithm, with enough configuration capabilities to adapt to different RF environments and data needs.


Elements of roaming



  • Triggers: each client implementation will have one or more triggers or events, that when met, will cause the device to move to another parent AP. Examples: beacon loss (device does not hear anymore the regular beacons from AP), packet retries, signal level, no data received, deauthentication frame received, low data rate in use, etc. The possible triggers can be very different from client implementation to another, as they are not fully standardized.  Simpler devices may have poor trigger set, causing bad (sticky clients) or unnecessary roams. In the case of WGB, it will support all of the previous elements described before.

  • Scan time:  The wireless device (WGB), will spend some time searching for potential parents. This normally implies going on different channels, doing active probing or passively listening for APs. As the radio has to scan, this means time that the WGB will spend doing something else different from forwarding data. From this scan time, the WGB will be able to build a valid set of parents that can be roamed to.


  • Parent selection: after scan time, the WGB will be able to check the potential parents, select the best one and trigger the association/authentication process. Sometimes, the decision point can be to remain on the current parent, if  there is not a significant benefit from a roaming event. (remember that roaming too much can be bad).


  • Association/Authentication: the WGB will proceed to associate to the new AP, which normally covers both 802.11 authentication and association phases, plus completing the security policy configured on the SSID (WPA(2)-PSK, CCKM, none, etc)



  • Traffic Forwarding restore:  WGB will update network infrastructure of its known wired clients, through IAPP updates after roaming. After this point, the traffic to/from the wired clients to the network will resume





Configuration Guide


Security policies


One important aspect for roaming on mobile devices is what is the security policy that will be implemented on the infrastructure . There are several options, each one with good/bad points, showing here the most important ones:


  • Open: basically no security. This is the fastest, and simpler of all policies. This has the main problem of not restricting unauthorized access to the infrastructure , and no protection against attacks, limiting its usage to very specific scenarios, for example mines where no external attacks are possible due to sheer nature of the deployment

  • Mac address authentication: basically same level of security as open, as mac address spoofing is a trivial attack. Not recommended in general due to the added time to complete the mac validation, which slows down roaming

  • WPA2-PSK: offers good level of encryption (AES-CCMP), but authentication security depends on the quality of the preshared key. For security measures a password of minimum 12 characters, random, is recommended. As any pre-shared key method, as the key is used on multiple devices, if the key is compromised, the password will need to be modified across all equipments. The roaming speed is acceptable, as it is done in 6 frame exchanges, and we can calculate what will be the upper/lower time bounds for it to complete, as it does not involve any external equipment (no radius server, etc). In general, this method is the preferred one after balancing problems/benefits

  • WPA2 with 802.1x: this improves on the previous method, by using a per device/user credential, which can be individually changed. The main problem is that for roaming, this method will not work properly when the device is moving fast, or very short roaming times are needed. In general, this will use the same 6 frames plus the EAP exchange which can be between 4 and up, depending on which EAP type is selected, and the certificate sizes. Normally this will take between 10 to 20 frames, plus the added delay of radius server processing.

  • WPA2+CCKM: this mechanism offers good protection, uses 802.1x to build the initial authentication, then will do a very quick exchange of just 2 frames on each roam event. This will offer a very quick roaming time.  It main problem is that in case of a failed roam, it will revert back on 802.1x then start using CCKM again, after it authenticates. if the application on top of the WGB can tolerate an occasional long roaming time in case of problems, it can be used as best option vs PSK.

We will not cover not recommended technologies that have security issues like LEAP, WPA-TKIP, WEP, etc.



Configuring WPA2-PSK

On the WGB, this is fairly simple to configure. We just need SSID definition, and the proper encryption on the radio:



dot11 ssid wgbpsk

   vlan 32

   authentication open

   authentication key-management wpa version 2

   wpa-psk ascii YourReallySecurePSK!

   no ids mfp client




interface Dot11Radio0


ssid wgbpsk

encryption mode ciphers aes-ccm

station-role workgroup-bridge


Your SSID name and preshare key have to match your network infrastructure



Configuring WPA2 with 802.1x


It basically builds on top of previous config, with the addition of  EAP profiles, and authentication method:




dot11 ssid wlan1

   authentication open eap eap

   authentication network-eap eap

   authentication key-management wpa version 2

   dot1x credentials wgb

   dot1x eap profile eapfast

   no ids mfp client



!This would cover the EAP method type used on your network


eap profile eapfast

method fast



!This is your WGB username/password        

dot1x credentials wgb

username cisco

password 7 1511021F0725




interface Dot11Radio0

encryption mode ciphers aes-ccm

ssid wlan1




Configuring WPA2 with CCKM


Just one step on top of WPA2, with just one minor change, using  CCKM flag on SSID config, This assumes the WLAN is configured for CCKM only on the WLC side:




dot11 ssid wlan1

   authentication open eap eap

   authentication network-eap eap

   authentication key-management cckm

   dot1x credentials wgb

   dot1x eap profile eapfast

   no ids mfp client



Validation of the method used



A quick check on the WGB can report the encryption and key management in use, for example in CCKM:


wgb-1260#sh dot11 associations al

Address           : 0024.97f2.75a0     Name             : lap1140-etsi-1

IP Address        :      Interface        : Dot11Radio 0

Device            : LWAPP-Parent      Software Version : NONE

CCX Version       : 5                  Client MFP       : Off


State             : EAP-Assoc          Parent           : -                 

SSID              : wlan1                          

VLAN              : 0

Hops to Infra     : 0                  Association Id   : 1

Tunnel Address    :

Key Mgmt type     : CCKM               Encryption       : AES-CCMP


Current Rate      : m7.-               Capability       : WMM ShortHdr ShortSlot

Supported Rates   : 48.0 54.0 m0. m1. m2. m3. m4. m5. m6. m7.

Voice Rates       : disabled           Bandwidth        : 20 MHz

Signal Strength   : -59  dBm           Connected for    : 72 seconds

Signal to Noise   : 41  dB            Activity Timeout : 8 seconds

Power-save        : Off                Last Activity    : 7 seconds ago

Apsd DE AC(s)     : NONE


Packets Input     : 12064              Packets Output   : 136      

Bytes Input       : 2892798            Bytes Output     : 19514    

Duplicates Rcvd   : 87                 Data Retries     : 8        

Decrypt Failed    : 0                  RTS Retries      : 0        

MIC Failed        : 0                  MIC Missing      : 0        

Packets Redirected: 0                  Redirect Filtered: 0



Configuring Roaming


On the WGB, we can modify several parameters affecting roaming algorithm:


Packet retries

By default the WGB will retransmit a frame 64 times, and if  it is not properly ACK by parent, it will assume that parent is not longer valid, and it will start a scan/roaming process. We should see this one as a "async" roaming trigger, as it can be done at any moment that a transmission fails.



The command to configure this, goes inside the dot11 interface, and it takes the following options:

packet retries NUM [drop]


Num: is between 1 and 128, with default of 64. A good number is generally 32 for a quick roaming trigger. Using a lower number may be not advisable on most RF environments.


drop: if not present, the WGB will start a roaming event when max retries are reached. When present, the WGB will not start new roaming, and it will use other triggers (beacon loss, signal etc)




RSSI Monitoring


WGB can implement a "proactive" signal scan for the current parent, and start a new roaming process when the signal falls below an expected level.

This process takes two parameters, a timer, which wakes up the check process every X seconds, and a RSSI level, which is used to start a roaming process if the current signal is bellow it. For example:


in do0
mobile station period 4 threshold 75



The time should not be lower that what the WGB will take to complete an authentication process, to prevent a "roamming loop" in some conditions or to avoid a too aggresive roaming behavior. In general it should be tested to see what accomodates the application needs

For PSK it can be lower than  in EAP based methods. (typical 2 and 4 for very aggresive applications)


The RSSI level is expresed as a positive interger, although it is basically a normal -dBm measured level. You should use a sightly higher number than the minimum needed to keep your data rate working properly. For example, if your desired minimum rate is 6 mbs, a threshold RSSI of -87 should be ok. For a 48 mbps, you would need -70 dBm etc



Note: This command may also trigger a "roaming by data rate change" which is too aggresive.  It must be used together with "minimum-rate" for good results


Minimum Data Rate


Starting with 12.4(25d)JA, we added a configurable parameter, to control when the WGB should trigger a new roaming event, if the current data rate to parent is bellow a given value.

This is very helpful to ensure we try to keep a desired lower bound on speed to support video or voice applications.


Before this command was available, the WGB will trigger a roaming very frequently if the rate was found to be lower than the previous time. Basically on time X+1, if the rate was lower than previous X time, the WGB will start a roaming process. On the logs you would see these messages:

*Mar  1 00:36:43.490: %DOT11-4-UPLINK_DOWN: Interface Dot11Radio1, parent lost: Had to lower data rate


This is too aggresive, and normally, the only solution was to configure a single data rate both in WGB and on parent APs.

The recommended way now is to always configure this command, whenever a mobile station period command is used.


in d0

mobile station  minimum-rate 2.0


With this, the new roaming process will only be triggered if  the current rate is lower than the configured value, reducing unnecesary roamings, and allowing to keep an expected rate value.

Note: the message "Had to lower data rate" is expected to happen even with this config, just that now it should only be seen if WGB was TX at a lower than configured speed, when the mobile station period check time was triggered.


Scan Channels

The WGB will scan all "country channels" while doing a roaming event. This means that depending on radio domain, we can have to scan channels 1 to 11 on 2.4, or 1 to 13.

Each scanned channel will take some time. On 11bg this will be around 10 to 13 ms, on 11a, it can be up to 150 ms if  channel is DFS enabled (so not probing, just doing passive scan  there)


A good optimization is to restrict the scanned channels to  use only the ones in service by the infrastructure. This is specially important on 11a, as the channel list is large, and the time per channel can be long if DFS is in use



There are three points to take when designing a channel plan for WGB/Roaming:

  • For 2.4 GHz band, try to stick to 1/6/11 to minimize side channel interference. Any other channel plan with 4, etc, tends to be difficult to engineer properly from RF point of view, without increasing interference


  • Using single channel setup for all APs is good idea from scan point of view. This only makes sense, if the total  number  of clients to support is very low, and there are not high bandwidth requirements. This basically eliminates the radio change time from the scan time. Please be aware that  few environments can benefit from this option, so use with care.

  • For 5.0 GHz band, if it is possible by your local regulations, using indoor non-DFS channels(36 to 48)  allows faster scan time, as WGB can actively probe each one, instead of doing passive listening for longer time


The channel plan in use for your deployment may need to accommodate other requirements, please use general RF design recommendations.


To configure the scan channel list:

in d0

mobile station scan 1 6 11



Note: the mobile station only shows up when using WGB role on the radio

Note 2:  make sure your WGB  scan list matches your infrastructure channel list, if not the WGB will not find your available APs.



Configure Timers

Starting on 12.4(25a)JA, there are several new commands to optimize recovery timer when a problem is found, which are only available when the AP is on WGB mode.



wgb-1260(config)#workgroup-bridge timeouts ?

  assoc-response  Association Response time-out value

  auth-response   Authentication Response time-out value

  client-add      client-add time-out value

  eap-timeout     EAP Timeout value

  iapp-refresh    IAPP Refresh time-out value




In the case of assoc-response, auth-response, client-add , this will indicate how long the WGB will wait for parent AP to answer, before considering the AP as dead, and trying next candidate. The default values are 5 seconds, which is too long for some applications. The minimum timer is 800 ms and is recomended for most mobile applications


In eap-timeout, the WGB will set a maximum time to wait, until the full EAP authentication process is completed. This works from a EAP supplicant point of view, to restart the process if the EAP authenticator is not answering back. The default value is 60 seconds. We should be careful on never configuring a value that can be lower than the actual time needed to complete a full 802.1x authentication. Normally setting this to 2 to 4 seconds is correct for most deployments.


For iapp-refresh, the WGB by default generates an IAPP bulk update to the parent AP after roaming, to  inform of the known wired clients. There is a second retransmission after association around 10 seconds later. This timer allows to do a "fast retry" of the IAPP bulk after association, to overcome the possibility that the first IAPP update was lost due to RF, or encryption keys not yet installed on the parent AP. For very fast roaming scenarios, we can use 100ms, but be aware  that for large number of WGB in use, this will increase significantly  the total number of IAPP sent to the infrastructure after each roaming.


Example for aggresive values:

workgroup-bridge timeouts eap-timeout 4
workgroup-bridge timeouts iapp-refresh 100
workgroup-bridge timeouts auth-response 800
workgroup-bridge timeouts assoc-response 800
workgroup-bridge timeouts client-add 800


These have been tested on mobile WGB deployment scenarios sucessfully.


Other WGB optimizations

There are other minor changes to take into consideration for WGB deployment scenarios:


Radio Related

  • Reduce rts retries: rts retries 32. This can save some RF time on very aggresive scenarios. Normally not needed

  • Antenna type: if using a single antenna (no diversity), you should configure the radio to improve general performance:


antenna transmit right-a

antenna receive right-a


In general, anternna diversity  is desirable, but not always possible when physically installing antennas on the vehicle. Proper antenna selection is critical for roaming, as as little as 2 dB can be a huge difference on general roaming average times.


Log Related

  • To save some miliseconds, reduce the console logging level to errors only: logging console errors . Do not disable it completely, as it can affect negatively the roaming performance on some conditions.
  • Ideally, use telnet or ssh from the ethernet side to collect debugs or logs, as this has a much lower impact on performance, when comparing to logging debugs over console: logging monitor debugging
  • The command to understand what is happenning for WGB roaming point of view is debug dot11 dot11 0 trace print uplink . This has low impact on CPU, but do not enable other debug options unless instructed, as each one may increment the total roaming time.
  • Try to use SNTP when possible. This will keep the WGB time on sync which is extremelly helpful on troubleshooting



MFP usage

  • MFP can be useful from security point of view, but it has the drawback that on roaming failure scenarios, the WGB will not accept deauth frames from AP parent to trigger a new roaming, if the encryption key between both of them has gone wrong for any reason
  • On these rare  failure scenarios, the WGB may take up to 5 seconds to trigger new scan, if the current parent can be heard with good RF signal. There is a "catch-all" detection mechanism that WGB can trigger, if no valid data frames are recieved during that time
  • By default, the WGB will try to use client MFP if the SSID has WPA2 AES in use
  • It is recommended to disable client MFP, if fast recovery times are needed (WGB to react to non-protected deauth frames). This is a compromise between security needs, and fast recovery times. The decision would depend on what is more important for the deployment scenario.



dot11 ssid wgbpsk 

   no ids mfp client


EAP-TLS on WGB and "clock save interval"

See Synchronize IOS Supplicant Clocks and Save Time Setting to NVRAM


Keep in mind that if using uWGB, the uWGB might never get a chance to do an sntp synch since it is typically associated with the attached MAC address and the uWGB BVI does not have network access.  Thus in the case of a uWGB, recommended to get a good clock sync in NVRAM at deployment at minimum.  If the attached enet device has the ability to be an NTP source (as well as updated client via its uWGB connection), then it is possible to consider having the uWGB sntp sync from it as an effective NTP reflection point.


Full Configuration Example



no service pad

service timestamps debug datetime msec

service timestamps log datetime msec

service password-encryption


hostname wgb-1260


logging rate-limit console 9

logging console errors


clock timezone CET 1

no ip domain lookup



dot11 syslog



dot11 ssid wgbpsk

   vlan 32

   authentication open

   authentication key-management wpa version 2

   wpa-psk ascii 7 060506324F41584B56

   no ids mfp client







username Cisco password 7 13261E010803



bridge irb



interface Dot11Radio0

no ip address

no ip route-cache


encryption mode ciphers aes-ccm


ssid wgbpsk


antenna transmit right-a

antenna receive right-a

  packet retries 32

station-role workgroup-bridge

rts retries 32

mobile station scan 2412 2437 2462

mobile station minimum-rate 6.0

mobile station period 3 threshold 70

bridge-group 1



interface GigabitEthernet0

no ip address

no ip route-cache

duplex auto

speed auto

no keepalive

bridge-group 1


interface BVI1

ip address

no ip route-cache


ip default-gateway

no ip http server

no ip http secure-server


bridge 1 route ip


sntp server

clock save interval 1

workgroup-bridge timeouts eap-timeout 4

workgroup-bridge timeouts iapp-refresh 100

workgroup-bridge timeouts auth-response 800

workgroup-bridge timeouts assoc-response 800

workgroup-bridge timeouts client-add 800


Debug Analysis



In case of problems, it is important to capture the output of "debug dot11 dot11 0 trace print uplink " as first step, as it gives a good view of what is going on on the roaming process.


As example, this is example current parent as candidate.


Sep 27 11:42:38.797: %DOT11-4-UPLINK_DOWN: Interface Dot11Radio0, parent lost: Signal strength too low

 Sep 27 11:42:38.797: CDD051F1-0 Uplink: Lost AP, Signal strength too low

This is trigger for low signal met. It will depends on mobile station period X threshold Y command First message is sent always to console, second is part of the uplink debug traces. As such it is not a problem, but part of normal  WGB process.



 Sep 27 11:42:38.798: CDD052C7-0 Uplink: Wait for driver to stop

Uplink process will force a radio queue purge, before starting channel scan. This step can take from few miliseconds, to some seconds depending on channel utilization, and queue depth. Data frames are not timed out. Voice frames have a time comparision done so should be dropped faster. Some delay may be observed here on very noisy enviroments



 Sep 27 11:42:38.798: CDD05371-0 Uplink: Enabling active scan
 Sep 27 11:42:38.799: CDD05386-0 Uplink: Scanning

This is the actual channel scan taking place. it will park the radio aprox 10 to 13 ms per configured channel


 Sep 27 11:42:38.802: CDD064CD-0 Uplink: Rcvd response from 0021.d835.ade0 channel 1 3695

This is the list of probe responses recieved. First numnber is channel, second is microseconds taken to receive it


 Sep 27 11:42:38.808: CDD078F1-0 Uplink: Compare1 0021.d835.ade0 - Rssi 58dBm, Hops 0, Count 0, load 0
 Sep 27 11:42:38.809: CDD07929-0 Uplink: Compare2 0021.d835.cce0 - Rssi 46dBm, Hops 0, Count 0, load 0

Actual comparision done, see bellow for details


 Sep 27 11:42:38.809: CDD07BDB-0 Uplink: Same as previous, send null data packet


Parent selection

 Sep 27 11:42:38.809: CDD07BF7-0 Uplink: Done
 Sep 27 11:42:38.808: %DOT11-4-UPLINK_ESTABLISHED: Interface Dot11Radio0, Associated To AP AP1 0021.d835.ade0 [None WPAv2 PSK]Roaming completed.

This is the point where the roaming is "finished". Traffic will resume as soon as IAPP frames are processed by parent


Parent Compare information

 Sep 27 14:16:47.590: F515B1FF-0 Uplink: Compare1 0021.d835.7620 - Rssi 60dBm, Hops 0, Count 0, load 3
 Sep 27 14:16:47.591: F515B238-0 Uplink: Compare2 0021.d835.e8b0 - Rssi 58dBm, Hops 0, Count -1, load 0

The compare1 prints the actual association count -1 (so WGB itself is not taken in the number) if the “current” AP is still the one WGB is associated, then actual hops, and load


The compare2 prints the differences, that is why is possible to see a negative number there. If test has higher number than current, you see negative.


Depending on current association count, load, signal difference, mobile threshold value, the WGB may or many not select a new parent.

The comparison is always between 2 Aps, with the selected AP replacing the current for next iteration, so some of the decisions could be due to RSSI on one loop, or due to other factors on next test.

Version history
Revision #:
2 of 2
Last update:
‎08-28-2017 02:17 AM
Updated by:
New Member

Unbelievable....just what I have been looking for.

From my perspective I have been troubleshooting a mobile WGB installation for the last three weeks and exactly what is written in this is what I see.

The only addition I might want to see is a design guide on choosing antenna for different application.  Train, car, etc.

This is a great, great start though and it is sorely missing on the regular Cisco website.  Thank you!


thanks Javier/Gordon