Implementing Clustering
A key feature provided by the Devicescape Wireless Infrastructure Platform is the ability to incorporate clustering behavior into your Access Point (AP) target devices. Clustering allows multiple AP devices on a network to recognize each other and dynamically share configuration information, thereby participating in a "self-managed" wireless local area network (WLAN).
This topic provides a quick overview of what AP clustering looks like on a deployed network from an Administrative perspective, describes the default clustering behavior of the Devicescape Reference AP that ships with the platform, and provides information on how to implement clustering on your target AP devices during development.
Understanding Clustering Behavior on the Target AP
Clustering is the ability of AP devices to form a dynamic, configuration-aware group (called a cluster) with other similarly designed APs in a network in the same subnet. Access points can participate in a self-organizing cluster which makes it easier for you to deploy, administer, and secure your wireless network. The cluster provides a single point of administration and lets you view the deployment of access points as a single wireless network rather than a series of separate wireless devices.
For example, if your design and cluster strategy allows the target AP device to share its SSID (network name) and MAC address filtering lists, then when the Administrator changes the SSID or adds addresses to the MAC filtering lists on a deployed network of your devices via the configuration as represented for one of these device's IP address, the SSIDs and MAC filtering lists for the other devices will be automatically updated. From the Administrator's point of view, the SSID and MAC filtering lists updates were only two updates to the configuration for the entire network; although the updates were actually propagated to configurations for 11 other access points in addition to the original access point on which the change was made.
What is a Cluster?
A cluster is a group of access points which are coordinated as a single group via AP administration.
You can have multiple clusters on the same subnet if they have different cluster "names".
You can have multiple heterogeneous clusters (clusters that include APs of different models) on the same subnet if they have compatible properties.
How Many APs Can a Cluster Support?
Currently, there is no hard limit on the number of APs in a cluster. Validation testing has verified a dozen or more supported on the same subnet. You can include as many APs as needed in a cluster at any one time.
What Kinds of APs Can Cluster Together? (Compatibility and Cluster Name)
APs with matching capability (compat) strings and cluster name (cluster-name) strings in their configuration files will attempt to cluster together.
The clustering mechanism assumes that the configuration files are compatible across the devices in the group. If there are differences in your devices, then you must make a decision about whether you want them to be able to share any configuration settings when they are deployed on the same network. (Consider Which Settings are Shared by a Cluster? as part of this decision-making process.)
- APs of the same model are typically clear candidates for sharing compatibility (that is, you are likely to want to configure them with the same
compat strings during the development phase).
- APs of different models, with some differences in firmware or hardware details, may or may not be able to cluster together. Determine whether these devices are compatible enough and then make a decision about whether to set their
compat strings to the same or different values. If the compat strings are different, the devices will not cluster (regardless of whether they share the same cluster name).
The cluster name (cluster-name) string is can be left as "Default" during development time, and then re-set as needed by the Administrator when the wireless network is deployed.
Compatibility String in the AP Configuration File
A compatibility string in the AP configuration file is used to determine whether or not the devices are compatible. If you define the same compat string in the configuration files for two or more APs on the same subnet, those APs will attempt to cluster. If the compat strings are different, the clustering process will not be triggered.
A Cluster of One
With clustering enabled, a single Devicescape powered AP will form a cluster with itself (a "cluster of one") and with other Devicescape powered APs of the same model.
Cluster Name
You define whether you want new access points to join a particular cluster or not via the cluster name (defined by the value for cluster-name in the AP configuration file).
To set the cluster name as an Administrator, you can use either of these interfaces:
- Web UI: Cluster > Access Points page, "Cluster Name" field
- CLI:
set cluster cluster-name "SomeName"
Stopping and Starting Clustering
You can start or stop clustering on a access point via its Web UI Cluster > Access Points page or on the CLI:
- To start clustering from the CLI:
- To stop clustering from the CLI:
Cluster Formation
A cluster is formed when the first AP is deployed with clustering enabled.
The AP attempts to rendezvous with an existing cluster.
If it is unable to locate any other APs on the subnet with the same cluster name, then it establishes a new cluster on its own.
Cluster Size and Membership
Currently, there is no hard limit on the number of APs in a cluster. Validation testing has verified a dozen or more supported on the same subnet. You can include as many APs as needed in a cluster at any one time.
Cluster membership is determined by:
- Cluster Name - APs with the same name will join the same cluster (see Cluster Name)
Intra-Cluster Security
For purposes of ease-of-use, the clustering component is designed to let new devices join a cluster without strong authentication. However, communications of all data between access points in a cluster is protected against casual eavesdropping using Secure Sockets Layer (typically referred to as SSL). The assumption is that the private wired network to which the devices are connected is secure. Both the cluster configuration file and the user database are transmitted among access points using SSL.
Which Settings are Shared by a Cluster?
The Devicescape Reference AP is configured to propagate most AP settings to cluster members as a part of the cluster configuration. The few exceptions (settings not shared among clustered access points) are those which, by nature, must be unique; such as IP or MAC address. The following table shows the clustering strategy that ships with the reference design. APs developed with the Devicescape Wireless Infrastructure Platform will reflect this clustering strategy when clustering is implemented.
Table 1 Example AP Reference Design Clustering Strategy: Settings Shared or Not Across Cluster
|
Feature
|
Cluster Setting (Shared or Not)
|
|
Administrator password
|
shared
|
|
Configuration policy
|
shared
|
|
Ethernet (Wired) Settings, including enabling or disabling Guest access
|
not shared
|
|
Guest interface configuration
|
not shared
|
|
Guest Welcome screen settings
|
shared
|
|
IP address
|
not shared
|
|
Location description
|
not shared
|
|
Load Balancing settings
|
not shared
|
|
MAC address
|
not shared
|
|
MAC address filtering
|
shared
|
|
Network name (SSID)
|
shared
|
|
Network Time Protocol (NTP) settings
|
shared
|
|
QoS queue parameters
|
shared
|
|
Radio Beacon Interval
|
not shared
|
|
Radio Channel
Note: When Channel Planning is enabled, the radio Channel is not synched across the cluster.
|
shared
|
|
Radio Channel Fragmentation Threshold
|
shared
|
|
Radio DTIM Period
|
not shared
|
|
Radio Maximum Stations
|
not shared
|
|
Radio Transmit Power
|
not shared
|
|
Radio RTS Threshold
|
shared
|
|
Radio Rate Sets
|
shared
|
|
Security settings
|
shared
|
|
User accounts and authentication
|
shared
|
|
WDS bridges
|
not shared
|
|
Wireless interface settings
|
shared
|
Providing Cluster Capability in Your AP Devices
Set Compatibility String and Cluster Name in the AP Configuration File
Where to Find the Configuration Files to Edit
There are two ways to update the configuration file:
Setting Compatibility and Cluster Name Values
Two values in the AP configuration files determine whether the APs will attempt to cluster together:
<compat></compat>
By default, this value is set to null. If two or more APs have a null value for compat, or some other matching value for it, they will attempt to cluster (as long as they also have the same cluster name). The compat value should be set in the AP configuration files during development/manufacturing phase, and should reflect true hardware platform compatibility.
<cluster-name>Default</cluster-name>
By default, this value is set to Default. If two or more APs have a matching value for cluster-name, they will attempt to cluster (as long as they also have the same cluster name). If desired, the cluster name can be remain as Default during development/manufacturing phase. An Administrator can easily reconfigure cluster names via the AP Web UI or CLI once the network is deployed.
The cluster name and compatibility tag are both strings defined in the AP configuration file in the AP configuration file (rescueconfig.xml) and then read into the runtime configuration file (config.xml) at AP startup.
On a deployed AP, the compatibility string, cluster name, and other values configured here (rescueconfig.xml) are persisted across reboots or factory resets.
Code Listing 1 Cluster Compatibility String in AP Configuration File
<cluster-name>Default</cluster-name>
<start-manually>0</start-manually>
<compat>MyCompatString</compat>
<location>Vicky's Office - lower shelf</location>
Define Shared Settings in the Clustering Schema File
The clustering schema defines which AP settings are shared by clustered APs, and which must be set individually for each AP. The clustering schema files are separated into four packages:
- ap clustering (device-mgmt-agent-ap)
- cluster.clustering (clustering)
- ntp.clustering (device-mgmt-agent-ntp)
- las.clustering (las)
To define shared settings and details of cluster behavior, edit the appropriate Schema file.
|
Note
|
Modifying the shared setting of existing properties (also known as fields) in the Devicescape Reference AP schema is not recommended because this can result in the information associated with a particular feature being partially shared and partially unshared thereby causing unexpected or erroneous behavior.
If you do choose to change the shared setting of existing properties in the reference schema, be sure to test and validate your device thoroughly to make sure the feature for which you modified cluster schema definitions still functions correctly.
|
The following example clustering schema file is used in the Devicescape Reference AP that ships with the platform. (See Which Settings are Shared by a Cluster? for an explanation of how APs with these settings behave on a deployed network.)
In a nutshell; if a configuration option is included in this file, it will be shared among devices of the same type (model and protocol version number) with compatible configuration files. If an option is not included in this file, it will not be shared among clustered devices. Details of how to use this file follow.
The following sections explain how to define synchronize statements in the clustering schema file to implement your clustering strategy:
On a deployed AP, the clustering schema, as defined in the Schema file, is persisted across reboots or factory resets.
Example Clustering Schema File
Following is an example of the ap.clustering schema file, which is located in the device-mgmt-agent-ap source package. This is an example of the type of file that you will modify in order to customize your configurations and subsequently you clustering source package. Four schema packages are provided by default, for more information, see Schema Files Provided with Devicescape Reference AP
ssid,fd,hello,stp,priority,port-isolation,type,radio,bss,wep-key-
length,security,wep-default-key,wpa-personal-key,wep-key-ascii,wep-key-
1,wep-key-2,wep-key-3,wep-key-4
include singleton portal welcome-screen,welcome-screen-text
include name_and_field basic-rate,rate rate
include name_and_field supported-rate,rate rate
include name_and_field tx-queue,queue queue,data,aifs,cwmin,cwmax,burst
status,max-bss,channel-policy,static-channel,mode,fragmentation-thresh-
old,rts-threshold,station-isolation,ap-detection,rate-limit-enable,rate-
limit,rate-limit-burst,wme
status,radio,beacon-interface,ignore-broadcast-ssid,mac-acl-mode,mac-
acl,radius-ip,radius-key,radius-accounting,rsn-preauthentication,shared-
key-authentication,wpa-allow-non-wpa-stations,wpa-cipher-tkip,wpa-cipher-
ccmp,wpa-allowed,wpa2-allowed
include field mac-acl,mac mac
include singleton log relay-enabled,relay-host,relay-port
include singleton dot11 status,dot11d
include singleton system encrypted-password
drop object interface type vlan
drop object interface type bridge
drop object interface type wds
drop matching bridge-port interface wlan,wds
drop field bss status vwn
Schema Files Provided with Devicescape Reference AP
The following four schema files are provided as part of the Devicescape Reference AP:
|
Schema File
|
Source Package
|
|
ap.clustering
|
device-mgmt-agent-ap
|
|
cluster.clustering
|
clustering
|
|
ntp.clustering
|
device-mgmt-agent-ntp
|
|
las.clustering
|
las
|
These files can be found under the /usr/clustering/schema directory.
Syntax and Parameters of Schema
The schema file maps directly to the way classes and properties are defined and manipulated in the AP configuration file in the device-mgmt-agent package. (For full details on how classes and properties are defined in the AP configuration file, see the note just below this section and also refer to the The Device Management Agent.)
The parameters in a clustering schema file are:
Class Name
Instances of named classes are identified by a "name" attribute in the AP configuration, for example "interface" in the example shown in Example Clustering Schema File.
Identifying Information for Class Instances Based on Class Type
Class instances are identified in different ways, depending on the type of class and how class instances are identified in that type of class. Some instances have unique names, and are identified by those names. Other instances are unnamed (anonymous) or do not have unique names (that is, they have only a group name), and therefore must be distinguished by property values.
Properties Belonging to the Class
The list of properties belonging to the class must be explicitly specified in order to actually have the configuration shared. Properties that are not listed will not be shared. Properties that are listed will be shared as part of a cluster of compatible devices.
|
Rules
|
Description and Example in Schema File
|
|
include_by_name
(<class name>)
|
Instances of named classes are identified by a "name" attribute in the AP configuration. (For example, interface name="eth0").
An example of adding this type of class to the Schema file is:
include_by_name("interface")
|
|
include_singleton
(<class name>)
|
Instances of unnamed, singleton classes have only one instance of the class in the AP configuration. (If a class is labeled SINGLETON in the schema file and there is really more than one of these in the AP configuration file, then results are unpredictable. Be sure the class is really a singleton class when labeling it as such.)
An example of adding this type of class to the Schema file is:
include_singleton("portal")
with_field("welcome-screen")->
with_field("welcome-screen-text")->
|
|
include_by_field
(<class name>, <property>)
|
Instances of this class (non-singleton anonymous and group named) are distinguished from one another in the AP configuration by the value of the property. These should be unique within a class. The specified property is analogous to a primary key in a database. (If more than one instance of the class shares the same value for the given property, results will be unpredictable.)
An example of adding this type of class to the Schema file is:
include_by_field("basic-rate", "rate")
|
|
include_by_name_and_field (<class name>, <property>)
|
Instances of group classes or named classes with properties (fields) are distinguished in the AP configuration file by a unique pair consisting of their "name" attribute and the value of the associated field.
For these kinds of classes, you can have more than one instance with the same "name" or the same value for the field, but not both.
An example of adding this type of class to the Schema file is:
include_by_name_and_field("tx-queue", "queue")->
|
Examples of the Format used to Include Configurations in the Clustering Schema
|
#include
|
index-type
|
class
|
properties
|
|
include
|
name
|
interface
|
ssid, fd
|
|
include
|
singleton
|
portal
|
welcome-screen, welcome-screen-text
|
|
include
|
field
|
basic-rate, rate
|
rate
|
|
include
|
name_and_field
|
tx-queue, queue
|
queue, data
|
The table below shows examples of the configurations to be included in the Clustering Schema.
|
Note
|
Some rules to remember when you are editing the schema file:
- Lines beginning with "#" and empty lines are ignored.
- Each field in a line is separated by one or more tab characters ('\t')
- Multi parameters within a field should be separated by a comma (',')
|
|
Note
|
Classes in the AP Configuration
In the Devicescape Reference AP, different kinds of information uses different classes. For example, information about a network interface is represented by the "interface" class, while information about an NTP client is represented by the "ntp" class.
Depending on the type of class, there can be multiple instances of a class. For example, there is one instance of the "interface" class for each network interface the AP has (Ethernet, radio, and so on), while there is just a singleton instance of the "ntp" class, since an AP needs only a single NTP client. Some classes require their instances to have names to differentiate between them; these are called named classes. For example, one interface might have a name of eth0 to indicate that it is an Ethernet interface, while another interface could have a name of wlan0 to indicate it is a wireless LAN (WLAN) interface. Instances of singleton classes do not have names, since they only have a single instance. Classes that can have multiple instances but do not have a name are called anonymous classes. Together, singleton and anonymous classes are called unnamed classes. Some classes require their instances to have names, but the multiple instances can have the same name to indicate that they are part of the same group. These are called group classes.
Each class defines a set of properties (fields), that describe the actual information associated with a class. Each instance of a class will have a value for each property that contains the information. For example, the interface class has properties such as "ip" and "mask". For one instance, the ip property might have a value of 192.168.1.1 while the mask property has a value of 255.255.0.0; another instance might have an ip property with a value of 10.0.0.1 and mask property with a value of 255.0.0.0.
|
If you are adding your own classes to the device-mgmt-agent, you will need to follow the model described in the note above for creating new classes, and then choose the appropriate way of identifying them in the clustering schema.
If you are adding options to the clustering schema related to new classes you have created, you will have the information you need (class name, type, and properties). If you want to add or revise the schema based on existing classes in the Devicescape Reference AP, you must have the following kinds of information about each class to which you want to refer:
- Class name
- Type of class (for example, singleton, named class, and so on)
- Properties belonging to the class
The configurations to be replicated will be defined in a text schema file /usr/lib/clustering/schema.
There are several ways to get information about existing classes in the Devicescape Reference AP:
- Use the command line interface (CLI) to on a deployed version of the reference AP. On the CLI, type "get" and hit tab to get a list of classes. (This will give you most classes, although there are a few that are not included in the CLI.) To get the properties of a class from the CLI, type "get class <ClassName>" and then hit tab.
- At the CLI on a deployed AP, type "kill -HUP <ProcessID_of_DeviceManagmentAgent>". This will print out a list of classes and properties that the device management agent knows about, including class types. This "kill -HUP" command will also print out other debugging information such as the instances in the current running configuration and services.
- Look at the source code in the device-mgmt-agent-ap source package. This will show classes, class types, and class properties.
- Refer to the "CLI Class and Property Reference" in the Devicescape Reference AP Administrator Guide. Information on the CLI (including a Class and Property Reference) is provided with the documentation for Devicescape Wireless Infrastructure Platform as an Appendix to the Administrator Guide. (The Devicescape™ Enterprise-Managed AP is the Devicescape Reference AP, and these names are used interchangeably throughout the platform documentation.)
Specifying Exceptions to Schema Rules
There are two types of exceptions you can define to clustering Schema statements. These exceptions are used to drop particular configurations from your Clustering Schema file.
|
Exception Statement and Example
|
Description
|
|
Syntax:
dropObject ( "<ClassName>", "<FieldName>", "<FieldValue>")
Example:
dropObject( "interface", "type", "vlan" );
|
For a class whose objects are typically synchronized, use the dropObject statement to identify instance objects that should not be synched.
In the example, interface objects whose "type" property is equal to "vlan" will not be synched.
|
|
Syntax:
dropField ( "<ClassName>", "<FieldtoDrop>", "<Initial_Characters_Of_ObjectName>")
Example:
dropField( "bss", "status", "vwn" );
|
Use the dropField statement to enable individual properties to be eliminated from the clustering behavior.
In the example, for objects of type "bss", whose "name" attribute starts with the characters "vwn", the "status" property will not be synched. (That is for this particular object, we do not synchronize up/down status for "vwn" BSS's whereas the up/down status of other BSSs are synched.)
|
Examples of the Format used to Drop Configurations
The table below shows examples of the format of configurations to be dropped from the Clustering Schema.
|
#drop
|
drop-type
|
class
|
property
|
instance
|
|
drop
|
object
|
interface
|
type
|
vlan
|
|
drop
|
field
|
bss
|
status
|
vwn
|
Adding or Removing Objects from an AP Configuration
When an AP receives a configuration file from another AP via the clustering mechanism, it will add instances of the class that it cannot identify in its existing configuration. For example, if the incoming file contains a user that is not present in the AP's current configuration, the AP will add the new user. Similarly, if an incoming file is missing objects that are present in the AP's current configuration, those objects will be removed from the AP's configuration.
The clustering mechanism accomplishes this by generating LSQL statements which are sent to the device-mgmt-agent to either add or remove objects from cluster member AP configurations.
If You Modified Configuration Directly on the Target, Reset the Startup Configuration and Reboot
If you edited and saved the rescueconfig.xml file directly on the target AP (in /etc), you must then reset the configuration and reboot the AP to allow the changes to take effect properly
To do this, run the following commands in /etc/ on the target:
set config default rescue
set config startup rescue
|
Note
|
The first command (to reset the default configuration file) is only necessary if you manually created a default configuration file.
|
If You Modified the Configuration in a Source Package, Rebuild it and Recreate the RFS Image
If you edited and saved rescueconfig.xml file in the device-mgmt-agent-ap source package, you must rebuild that package into a binary RPM and include it, along with other clustering-related packages, in a new root file system (RFS) image file. Then you can upload the new RFS onto the target AP, and reboot the AP to see the new clustering configuration take effect. So, the steps are:
- Your updated device-mgmt-agent-ap source package (with the modified
rescueconfig.xml file in it)
- clustering package, which provides the clustering functionality
- las package, which provides an AP-embedded, "local" authentication server for user management when the AP is set to use IEEE802.11x or WPA Enterprise security modes with local authentication server (rather than external RADIUS server).
- libstdc++ package, which provides a GNU C++ runtime library used by the clustering functionality
If you have the original clustering package from previous releases of the Devicescape Wireless Infrastructure Platform, be sure remove it from the list of packages to include in the RFS image. The new clusrering2 package replaces it.
For a detailed list of packages to include in the RFS image, see Access Point Package List in the topic on building RFS images.
- Upload/flash the new RFS image (with your new clustering configuration included) to the target AP and reboot it, as described in the "Getting Started" guide for your board (in topics on loading and booting the kernel and RFS images). See the list of Getting Started Board Guides on the Devicescape Wireless Infrastructure Platform documentation home page at http://www.devicescape.com/docs/wip/.
Summary of Files and Packages
|
Source Package
|
Description
|
|
device-mgmt-agent--ap
|
Device management agent. For a detailed description, see the Device Management Agent topic in the Developer Guide.
This package includes the rescueconfig.xml file that contains the compat value, cluster-name, and other configuration settings you may need to modify if you plan to rebuild the DMAN package. (See If You Modified the Configuration in a Source Package, Rebuild it and Recreate the RFS Image.)
|
|
clustering
|
Clustering, user management, channel planning, sessions, and neighboring AP feature pack.
|
|
las
|
C-based local authentication server (LAS) available as an option for use with WPA Enterprise security mode.
|
|
libstdc++
|
GNU C++ runtime library
|
Related Information
Related Packages
See the following topics in the Package Reference Guide.
- clustering package
- device-mgmt-agent-ap package
- las package
- libstdc++ package (described in Package Overview only)
