Analytics and

LocationEngine 1.1
U
s
e
r
a
n
d
A
P
I
G
u
i
d
e
0511459-00v2 | November 2013 Analytics and Location Engine 1.1 | User and API Guide
Copyright Information
2013 Aruba Networks, Inc. Aruba Networks trademarks include , Aruba Networks

, Aruba
Wireless Networks

, the registered Aruba the Mobile Edge Company logo, Aruba Mobility Management System

,
Mobile Edge Architecture

, People Move. Networks Must Follow

, RFProtect

, Green Island

. All rights reserved.

All other trademarks are the property of their respective owners.
Open Source Code
Certain Aruba products include Open Source software code developed by third parties, including software code
subject to the GNU General Public License (GPL), GNU Lesser General Public License (LGPL), or other Open
Source Licenses. Includes software fro Litech Systems Design. The IF-MAP client library copyright 2011 Infoblox,
Inc. All rights reserved.This product includes software developed by Lars Fenneberg et al. The Open Source code
used can be found at this site
http://www.arubanetworks.com/open_source
Legal Notice
The use of Aruba Networks, Inc. switching platforms and software, by all individuals or corporations, to terminate
other vendors VPN client devices constitutes complete acceptance of liability by that individual or corporation for
this action and indemnifies, in full, Aruba Networks, Inc. fromany and all legal actions that might be taken against it
with respect to infringement of copyright on behalf of those vendors.
Warranty
This hardware product is protected by the standard Aruba warranty of one year parts/labor. For more information,
refer to the ARUBACARE SERVICE AND SUPPORT TERMS AND CONDITIONS.
Analytics and Location Engine 1.1 | User and API Guide Contents | 3
Contents
Copyright Information 2
Contents 3
About this Guide 7
Conventions 7
Related Documents 8
Contacting Aruba Networks 8
About ALE 9
Setting Up and Installing ALE 9
Setting Up the Virtual Machine 9
Setting Up ALE 10
Configuring the Controller and the Airwave Server with ALE 10
In the WebUI 10
In the Command Line 11
Configuring the Meridian Analytics Engines with ALE 12
Configuring the Controller 13
Starting the ALE Server 13
About the ALE Licenses 13
Viewing your Evaluation License 13
Obtaining a Permanent License 14
Integrating ALE with Instant AP 14
Enabling IAP for ALE Support 14
Syntax 14
Example 15
Interval Configuration 15
Syntax 15
Example 15
About ALE and Firewalls 15
About Anonymization 15
Anonymization Basics 16
4 | Contents Analytics and Location Engine 1.1| User and API Guide
ALE APIs 17
Polling APIs 17
Stations API 17
Access Point API 18
Application API 19
Destination API 20
Campus API 20
Building API 21
Floor API 22
Presence API 22
Location API 23
Publish/Subscribe APIs 24
Events 25
Presence 26
RSSI 26
Location 26
Station 26
Access Point 27
Radio 27
Virtual Access Point 27
Destination 28
Application 28
Visibility Records 28
Campus 29
Building 29
Floor 29
Security and Troubleshooting 30
About SSL Bridge 30
Integration with Meridian 30
Using SSL Bridge 30
Example 30
Troubleshooting 31
Viewing and Downloading the ALE Diagnostics 31
ZeroMQ Application Sample Code 32
Analytics and Location Engine 1.1 | User and API Guide Contents | 5
Analytics and Location Engine 1.1 | User and API Guide About this Guide | 7
About this Guide
The wireless network has a wealth of information about unassociated and associated devices. The Analytics and
Location Engine (ALE) is designed to gather that information fromthe network, process it and share it through a
simple and standard API. ALE includes a location engine that calculates associated and unassociated device
location every 30 seconds by default. ALE needs the AP placement data to be able to calculate location for these
devices. This map data must be imported fromVisualRF.
For every device on the network, ALE provides the following information through the Northbound API:
l Client Username,
l IP address
l MAC address
l device type
l Application firewall data, showing the destinations and applications used by associated devices.
l current location
l historical location
Personal identifying information (PII) can be filtered out of the data, allowing you to view standard or anonymized
data with or without MAC addresses, client user names, and IP addresses.
This guide describes how to install and configure ALE and includes information about ALE polling APIs, push and
subscribe APIs, security (SSL bridge),and troubleshooting tips.
Conventions
The following conventions are used throughout this manual to emphasize important concepts:
Type Style Description
Italics This style is used to emphasize important terms and to mark the titles of books.
System items This fixed-width font depicts the following:
l Sample screen output
l System prompts
l Filenames, software devices, and specific commands when mentioned in the text
Commands In the command examples, this bold font depicts text that you must type exactly as shown.
<Arguments> In the command examples, italicized text within angle brackets represents items that you
should replace with information appropriate to your specific situation. For example:
# send <text message>
In this example, you would type send at the system prompt exactly as shown, followed by
the text of the message you wish to send. Do not type the angle brackets.
[Optional] Command examples enclosed in brackets are optional. Do not type the brackets.
{Item A |
Item B}
In the command examples, items within curled braces and separated by a vertical bar
represent the available choices. Enter only one choice. Do not type the braces or bars.
Table 1: Typographical Conventions
8 | About this Guide Analytics and Location Engine 1.1| User and API Guide
The following informational icons are used throughout this guide:
Indicates helpful suggestions, pertinent information, and important things to remember.
Indicates a risk of damage to your hardware or loss of data.
Indicates a risk of personal injury or death.
Related Documents
The following documents are part of the complete documentation set for the ALE:
l Analytics and Location Engine 1.1 Release Notes
l Aruba Instant 6.3.1.1 - 4.0 User Guide
l ArubaOS 6.3 Quick Start Guide
l ArubaOS 6.3.x User Guide
l ArubaOS 6.3 .x Command-Line Reference Guide
l ArubaOS 6.3.1 Release Notes
l Airwave 7.7 User and API Guide
Contacting Aruba Networks
Website Support
Main Site http://www.arubanetworks.com
Support Site https://support.arubanetworks.com
Airheads Social Forums and Knowledge
Base
http://community.arubanetworks.com
North American Telephone 1-800-943-4526 (Toll Free)
1-408-754-1200
International Telephone http://www.arubanetworks.com/support-services/aruba-support-
program/contact-support/
Support Email Addresses
Americas and APAC [email protected]
EMEA [email protected]
Wireless Security Incident Response
Team (WSIRT)
.
[email protected]
Table 2: Contact Information
Analytics and Location Engine 1.1 | User and API Guide About ALE | 9
Chapter 1
About ALE
This topic discusses ALE setup and installation instructions. Information includes:
l Setting Up and Installing ALE on page 9
l About the ALE Licenses on page 13
l Integrating ALE with Instant AP on page 14
l About ALE and Firewalls on page 15
l About Anonymization on page 15
ALE is designed to gather client information fromthe network, process it and share it through a standard API. The
client information gathered by ALE can be used for analyzing a clients internet behavior for business such as
shopping preferences.
ALE is delivered as an open virtual appliance (OVA) file supported on VMware ESX/ESXi 5.x. This OVA file can be
deployed using VMware vSphere. This procedure above automatically creates a virtual machine (VM) with the
following specifications:
l Guest Operating System= Linux, Version = Centos 6 64 bit
l Number of Virtual Sockets = 1, Number of cores per virtual socket = 2
l Memory Configuration = 6 GB
l Number of NICs = 1
When deploying the OVA file, you can size the VMbased on Aruba Networks, Inc. technical support
recommendations. Additionally, after deployment, you can change the VMCPU, memory, and hard drive if you run
into any performance issues.
Setting Up and Installing ALE
Setting Up the Virtual Machine
You can set up the VMusing the Ova file.
The following steps describe how to set up ALE using the OVA file.
1. Save the downloaded OVA file in a location accessible by the vSphere application.
2. Launch vSphere. In the vSphere application:
a. Navigate to File >Deploy OVF Template.
b. Select the downloaded ALE OVA file.
c. Click Next.
d. Accept the end-user license agreement to deploy the OVA file.
e. Verify installation details and click Next.
f. [Optional] This installation screen allows you to change the name of the installation file. Enter a new name, or
skip this step to keep the default ALE-1.1.0.0-xxx.
g. Click Next .
h. Select the datastore where this VMwill be deployed, based on your ESX/ESXi setup. The disk space for the
VMwill be allocated in this datastore, and the format should be left to the default Thick Provision Lazy
Zeroed setting.
10 | About ALE Analytics and Location Engine 1.1| User and API Guide
i. Click Next.
j. Verify the final installation settings are accurate. f you need to make any changes, click the Back button and
update the settings. Otherwise, click Finish.
3. If you want to change the default VMsettings for CPU, memory or hard disk, do that before powering on.
4. On the login screen, log in as the admin user with the default admin user ID and password: User ID= root,
password = admin
You must change the default password after logging in the first time.
5. Configure the network interface based on your local LAN settings, ALE needs a static IP address.
Setting Up ALE
To set up ALE, do the following:
l Configure the controller fromwhich the ALE receives updates
l Configure the Airwave server fromwhich ALE downloads floor maps
l Configure communication between the ALE and Meridian/Analytics Engines
Configuring the Controller and the Airwave Server with ALE
Follow the procedure below to set up the ALE with controller and AirWave settings. For controller setup, configure
the controller fromwhich the ALE receives updates. For the Airwave server setup,configure the Airwave server from
which ALE is required to download the floor maps.
You can configure setup fromthe command line or the WebUI.
ALE requires a read-only controller username and password. Do not use an administrator user name or password.
In the WebUI
For configuration, the WebUI is not enabled by default.
1. Log in to the VMas root and run the following command:
/opt/ale/bin/htpasswd.py -b /opt/ale/html/.htpasswd <userid> <password
where <userid> and <password> are the new user ID and password that you want to create. You can pick any
username.
2. Open your browser and type the following URL:
http://<ale VM IP Address>
The ALE UI page displays with the Configuration tab on top.
3. Fromthe drop-down Configuration tab menu, select either Controller feeds or Airwave feeds to configure a
controller or an Airwave server, respectively.
Make sure that the correct floor plan with accurate AP locations is uploaded to the Airwave server before configuring
Airwave on the ALE.
Figure 1 ALE UI Configuration tab
4. The New Controller Feed or New Airwave Server Feed dialog displays.
5. Enter the controller or Airwave server IP address or host name, login name, and password.
Enter a read-only controller username and password. Do not use and administrator username or password.
Figure 2 ALE UI Configuration tab - New Controller Feed dialog box
6. Click Add and then Apply.
In the Command Line
1. Access the VMand navigate to the directory /opt/ale/etc.
2. Edit the locationserver.conf text file using any text editor.
a. Add the following controller information under the <controllers> tag.
n controller hostname=<controller-ip-addr>
n port=4343
Analytics and Location Engine 1.1 | User and API Guide About ALE | 11
12 | About ALE Analytics and Location Engine 1.1| User and API Guide
The port number is fixed.
n username=< controller-readonly-username>
n password=< controller-readonly-username>
n cacert=<cert> (this parameter is optional, and can be left blank.)
For example:
<controllers>
<controller hostname=10.1.50.3 port=4343 username=admin password=admin cace
rt=/>
b. Add the following AirWave information under the <sitefetch> tag:
n airwave host="<AirWave-ip-addr>""
n username="<username>"
n password="admin
Passwords must be escaped properly for XML. For example if your password is r&&t, then it must be written as
r&amp;&amp;t . In future, this file will contain the encrypted passwords
The AirWave username/password must be a user which has access to the VisualRF in Airwave (either read-only or
read-write) and the Access Points located on that floor. See your AMP admin guide for details on user roles and
privileges.
3. After configuring the controller and ALE server fromthe CLI, restart the location server module of ALE using the
following command to initiate the initial HTTP fetch fromthe controller and to download floor maps fromAirwave:
[root@ale ~]# /etc/init.d/locationserver restart
Configuring the Meridian Analytics Engines with ALE
Each ALE instance has a unique ID that is carried with every message it sends. The unique ID allows Meridian to
distinguish the traffic that arrives fromeach customer and is used when configuring communication with the Meridian
Analytics Engines.
In the ALE UI, select the About tab in the ALE U to view the ALE ID.
Figure 3 ALE UI About tab - ALE ID
Configuring the Controller
To configure your Arubacontrollers to send information fromthe controllers to ALE complete the below steps. ALE
processes automatically start at systemboot time.
After configuration changes are complete, you must restart the ALE.
1. Access the controller CLI in enable mode.
2. Run the CLI command:
(host) (config)#mgmt-server type ale primary-server <ALEIP>
profile default-ale
Starting the ALE Server
1. ALE processes are automatically started at systemboot time. After the configuration changes are done, you
must restart the processes.
2. Access the VMand navigate to the directory /etc/init.d.
3. Run these commands:
./iap-webapp restart
./ale-webapps restart
./locationserver restart
The VMdisplays a message indicating that the server has started.
About the ALE Licenses
ALE ships with an evaluation license that expires after 90 days. You can use an unlimited number of APs during the
evaluation license time period.
Viewing your Evaluation License
To view your evaluation license select the License tab in the ALE UI.
This tab indicates the license type (evaluation or permanent), total amount of licenses, number of licenses used and
the remaining number available. Each AP requires its own license. You can use an unlimited number of APs with an
evaluation license, but once the evaluation license expires you must buy a permanent license.
Figure 4 ALE UI License tab - Evaluation license
Analytics and Location Engine 1.1 | User and API Guide About ALE | 13
14 | About ALE Analytics and Location Engine 1.1| User and API Guide
Obtaining a Permanent License
To obtain a permanent license:
1. On the ALE UI License tab, select the URL link https://licensing.arubanetworks.comto request a license.
2. Paste the ALE license key you receive by email into the license field on the License tab.
Figure 5 ALE License tab - license key
3. Click Submit. If the license is valid a confirmation message appears.
Integrating ALE with Instant AP
ALE supports integration with IAP. The ALE server acts as a primary interface to all third-party applications and the
IAP sends client information and other status information to the ALE server. To integrate with ALE, the ALE server
address must be configured on an IAP.
Enabling IAP for ALE Support
To enable an IAP for ALE support, run these commands:
(host) configure terminal
(host) (config) ale-server <server:port>
(host) (config) exit
(host) commit apply
Syntax
Command/Parameter Description
ale-server <server:port> Allows you to specify the Fully Qualified Domain Name (FQDN) or IP
address of the ALE server.
no Removes the specified configuration parameter.
Example
The following example enables ALE on an IAP:
(host)(config)# ale-server AleServer1:8088
Interval Configuration
To configure the interval at which an IAP sends data to the ALE server, use this command:
ale-report-interval <seconds>
no
Syntax
Command/Parameter Description Range Default
ale-report-interval
<seconds>
Configures an interval at which the
Virtual Controller can report the IAP
and client details to the ALE server.
660 seconds 30
no Removes the specified con-
figuration parameter.

Example
The following example configures the ALE server details:
(host)(config)# ale-report-interval 60
About ALE and Firewalls
The following table displays firewall configuration information for ALE communication types.
Table 3: Firewall Configuration for ALE
Communication Port Protocol Notes
Controller > ALE 8211 PAPI For AMON feed from controller
Instant VC > ALE 8088 HTTPS Port is configurable
ALE > Controller 4343 HTTPS For fetching API data
ALE > Airwave 443 HTTPS Fetch floorplan data from Airwave
ALE > Meridian 443 SSL Location data to Meridian
ALE > Cloud 7779 SSL ZeroMQfeed
HTTP Client > ALE 8080 HTTP Restful APIs
User > ALE 80 HTTP ALE GUI
About Anonymization
Analytics and Location Engine 1.1 | User and API Guide About ALE | 15
16 | About ALE Analytics and Location Engine 1.1| User and API Guide
Direct use of a users personal unique identity information, which exists within specific message data fields on the
amon feed, raises privacy issues within ALE.
Serious privacy issues arise when personal network and mobile device identification information, which is saved by
ALE, is shared with outside applications. Therefore, information such as the devices MAC address, acquired
(associated) IP Address (or a history of it), a username, and other similar personal or sensitive and unique identity
information must be anonymized and the anonymization cannot be reversed.
Anonymization Basics
l Anonymization is a configurable option in ALE and is activated by default. Once activated, all subscribers get
anonymized data.
l The following fields are anonymized for both Publish/Subscribe and REST APIs: mac_addresses, ip_addresses
and usernames.
l When anonymization is activated, only the getALL option for all REST queries is supported. Filtering by MAC, IP
address or username will return an error.
l ALE uses a salted keyed SHA-1 hashing algorithmto generate the anonymized fields.
l Anonymization can be turned off by defining a new property in /etc/nbapi.properties. The property is named
ale.anonymization and accepts Boolean values true (default) and false.
l ZeroMQfeed anonymization can be turn off by changing the following XML property in /etc/nbapi-proxy.conf
From:
<proxy endpoint="tcp://*:7779" function="bind" strategy="anonymize"/>
To:
<proxy endpoint="tcp://*:7779" function="bind" strategy="passthru"/>
Analytics and Location Engine 1.1 | User and API Guide ALEAPIs | 17
Chapter 2
ALE APIs
The Analytics and Location Engine (ALE supports two types of APIs. One is a polling-based REST API, and the
other is a publish/subscribe API based on Google Protobuf and ZeroMQ. This section describes the format of the
information included in the API, the types of data each API can return, and the steps required to use these APIs to
view ALE data.
l The REST based API supports HTTP GEToperations by providing a specific URL for each query. Each query
can be modified to include one or more parameters to refine the types of data returned by the query. For more
information on ALE Polling APIs, see Polling APIs on page 17
l The publish/subscribe API is based on the MQtransport. A subscriber uses MQclient libraries to connect to
the ALE and receive information fromALE asynchronously. For more information on this group of APIs, see
Publish/Subscribe APIs on page 24
Polling APIs
The Representational State Transfer (REST) polling-based API supports HTTPS GEToperations by providing a
specific URL for each query. Refer to the following sections for details about each of the Polling APIs supported by
the ALE. Output format is in Google Protobuf, or JSON.
l Stations API on page 17
l Access Point API on page 18
l Polling APIs on page 17
l Application API on page 19
l Destination API on page 20
l Campus API on page 20
l Building API on page 21
l Floor API on page 22
l Presence API on page 22
l Location API on page 23
Stations API
The Stations API displays information about clients associated to the controllers that send information to ALE. Every
associated and authenticated user on the wireless network is represented by a station object. The XML response to
this query type can display the following types of information about a station.
Station APIqueries use the URL syntax:
http://localhost:8080/api/v1/station
Output Para-
meter
Definition
sta_mac_address MAC address of the client station.
Table 4: Station API Output
18 | ALEAPIs Analytics and Location Engine 1.1| User and API Guide
Output Para-
meter
Definition
username Client's user name, If a user name is not defined, this parameter will display the client's IP
address.
role Name of the user role currently assigned to the client. This is applicable to only authenticated
users..
bssid BSSID that to which this station is associated.
device_type Client's device type. The ALE can detect and return information for any of the following client
device types.
l Windows 7
l iOS devices
sta_ip_address IP address of the client.
hashed_sta_eth_
mac
This is the anonymized MAC address of the station, available when anonymization is enabled.
hashed_sta_ip_
address
This is the anonymized IP address of the station, available when anonymization is enabled.
http://10.4.250.10:8080/api/v1/station
This query displays output similar to the example below.
{
"Station_result": [
{
"msg": {
"sta_eth_mac": {
"addr": "F4F15AA2B8E0"
},
"username": "Vjammula",
"role": "Aruba-Employee",
"bssid": {
"addr": "D8C7C888D0D0"
},
"device_type": "iPhone",
"sta_ip_address": {
"af": "ADDR_FAMILY_INET",
"addr": "10.11.9.248"
},
"hashed_sta_eth_mac": "09097EA8F4DACD5A55F3A9D2F456EFE557D35F09",
"hashed_sta_ip_address": "436738A08110E88906F8A14CCEF66949A3DBAE01"
},
"ts": 1381977108
},
}
Access Point API
The access points (AP) API displays information about APs that terminate on the controllers configured to send
information to ALE.
AP APIqueries use the URL syntax:
http://localhost:8080/api/v1/access_point
The XML response to this query type can display the following types of information about an AP.
Output Parameter Definition
ap_eth_mac MAC address of the AP.
ap_name Name of the AP. If the AP does not have a name, this API will return the IP
address of the AP.
ap_group Name of the AP group to which the AP is assigned.
ap_model Model number of the AP.
depl_mode AP's deployment mode strings, displayed as an integer that corresponds to
a mode type.
ap_ip_address IP address of the AP.
Table 5: AP API Output
http://localhost:8080/api/v1/access_point
This query displays output similar to the example below.
{
"Access_point_result": [
{
"msg": {
"ap_eth_mac": {
"addr": "D8C7C8C0C7BE"
},
"ap_name": "1344-1-AL5",
"ap_group": "1344-hq",
"ap_model": "135",
"depl_mode": "DEPLOYMENT_MODE_CAMPUS",
"ap_ip_address": {
"af": "ADDR_FAMILY_INET",
"addr": "10.6.66.67"
}
},
"ts": 1382046667
}]}
Application API
The Application API is not available for Instant AP (IAP) deployment.
Queries using the Application API return a list of applications classified by the controller. The response to this query
type can display the following types of information.
Client Application APIqueries use the URL syntax:
http://localhost:8080/api/v1/application
Output Parameter Definition
app_id A unique number assigned to this application by the controller.
app_name Name of the application as assigned by controller.
Table 6: Application API Output
Analytics and Location Engine 1.1 | User and API Guide ALEAPIs | 19
20 | ALEAPIs Analytics and Location Engine 1.1| User and API Guide
http://10.4.250.10:8080/api/v1/application
This query displays output similar to the example below.
{
"Application_result": [
{
"msg": {
"app_id": 50331801,
"app_name": "Smarter Balanced Testing"
}
}]}
Destination API
The Destination API is not available for IAP deployment.
Queries using the Destination API return a list of client destinations; IP addresses to which traffic is sent. The
response to this query type can display the following types of information.
Destination APIqueries use the URL syntax:
http://localhost:8080/api/v1/destination
Output Parameter Definition
dest_ip IP address of a client receiving traffic through the network.
dest_name Name of client destination.
dest_alias_name An alias name assigned to this destination in controller.
Table 7: Destination API Output
http://localhost:8080/api/v1/destination
This query displays output similar to the example below.
{
"Destination_result": [
{
"msg": {
"dest_ip": {
"af": "ADDR_FAMILY_INET",
"addr": "98.175.77.106"
},
"dest_name": "adserving.autotrader.com",
"dest_alias_name": "autotrader"
}
}]}
Campus API
Campuses contain buildings which have individual floor maps. These maps must be defined using AirWave or Visual
RF before they are imported into the ALEconfiguration during setup and initialization. If the map is changed, it must
be reimported for the changes to take affect.
Campus APIqueries use the URL syntax:
http://localhost:8080/api/v1/campus
Output Parameter Definition
campus_id ID number identifying a specific campus location.
campus_name Name given to a campus location
Table 8: Campus API Output
http://localhost:8080/api/v1/campus
This query displays output similar to the example below.
{
"Campus_result": [
{
"msg": {
"campus_id": "6F9DEC79839D458B9F148D16A46A353E",
"campus_name": "GAP"
},
"ts": 1382046667
},]}
Building API
This API returns information about the buildings within each campus structure. These maps must be defined using
AirWave or Visual RF before they are imported into the ALEconfiguration during setup and initialization. If the map is
changed, it must be reimported for the changes to take affect. Each building name must be unique within a campus.
However, other campuses can also have a building with the same building name.
Building APIqueries use the URL syntax:
http://localhost:8080/api/v1/building
Output Parameter Definition
building_id ID number identifying a specific campus building.
building_name Name given to a building campus building.
campus_id ID number identifying a specific campus location.
Table 9: Building API Output
http://localhost:8080/api/v1/building
This query displays output similar to the example below.
{
"Building_result": [
{
"msg": {
"building_id": "83393A922FB249C1929B95393A2AAFDA",
"building_name": "3600-RFBOX",
"campus_id": "ECDDE4535C8E4723B8AF849B3F86E7BF"
},
"ts": 1382046667
}]}
Analytics and Location Engine 1.1 | User and API Guide ALEAPIs | 21
22 | ALEAPIs Analytics and Location Engine 1.1| User and API Guide
Floor API
This API retrieves floor definitions for each building in each campus. Campuses contain buildings which have
individual floor maps. These maps must be defined using AirWave or Visual RF before they are imported into the
ALEconfiguration during setup and initialization. If the map is changed, it must be reimported for the changes to take
affect. Each floor name must be unique within a building. However, other buildings can also have a floor with the
same floor name.
Floor APIqueries use the URL syntax:
http://localhost:8080/api/v1/floor
Output Parameter Definition
floor_id ID number identifying a specific building floor.
floor_name Name given to a building floor.
floor_latitude Latitude coordinate of top left corner of this floor, as defined in Visual RF.
floor_longitude Longitude coordinate of top left corner of this floor, as defined in Visual RF.
floor_img_path URL path to retrieve the background image for this floor.
floor_img_width Floor width in feet.
floor_img_length Floor length in feet.
building_id ID number identifying the building that contains this floor.
Table 10: Floor API Output
http://localhost:8080/api/v1/floor
This query displays output similar to the example below.
{
"Floor_result": [
{
"msg": {
"floor_id": "1C48EF7D78DC4B948F1A15D7CD14FDED",
"floor_name": "Floor 1",
"floor_latitude": 0,
"floor_longitude": 0,
"floor_img_path": "/images/plan/img_1c48ef7d-78dc-4b94-8f1a-15d7cd14fded.jpg",
"floor_img_width": 246.33,
"floor_img_length": 249.92,
"building_id": "DAD3A7092AC04AA4B2F5DAF266EBD81B"
},
"ts": 1382046667
}]}
Presence API
This API retrieves presence objects.
Presence APIqueries use the URL syntax:
http://localhost:8080/api/v1/presence
The Presence API supports several different query parameters. Focus your query on one or more individual presence
objects by including the following query parameters in your polling request. Queries that include multiple parameters
must format the query with an ampersand (&) symbol between each query parameter.
Query Parameter Definition
associated Returns a boolean values true or false. True, if the MAC address is associated or
False, if the MAC address is not associated anymore.
Table 11: Presence API Query Parameters
The output be filtered to include information only for the records that match your request.
Output Parameter Definition
stat_eth_mac MAC address of the client as seen by the Access Point.
bool_associated Indicates whether this client is associated or not.
hash_stat_eth_mac When anonymization is enabled, only this field is returned instead of the real MAC
address.
Table 12: Presence API Output
http://localhost:8080/api/v1/presence
This query displays output similar to the example below.
{
"Presence_result": [
{
"msg": {
"sta_eth_mac": {
"addr": "00FF00043DFF"
},
"associated": true,
"hashed_sta_eth_mac": "B9081DE2290A1670307F127D07935F788C7614DE"
},
"ts": 1381871586
}]}
Location API
This API retrieves Retrieves historical location objects for a specific MAC client. The last 1000 historical locations
are stored for each MAC address.
Location APIqueries use the URL syntax:
http://localhost:8080/api/v1/location?sta_eth_mac=AA:BB:CC:DD:EE:FF
The Location API only supports querying by MAC address.
Query Parameter Definition
stat_eth_mac Returns presence objects in context of a specific MAC address. For example,
AA:BB:CC:DD:EE:FF.
Table 13: Location API Query Parameters
The output will be filtered to include information only for the records that match your request.
Analytics and Location Engine 1.1 | User and API Guide ALEAPIs | 23
24 | ALEAPIs Analytics and Location Engine 1.1| User and API Guide
Output Parameter Definition
sta_eth_mac MAC address of the client.
sta_location_x X coordinate for location (in feet).
sta_location_y Y coordinate for location (in feet).
error_level This is experimental, this value indicates the error level associated with this location
calculation.
associated Whether this client is associated.
campus_id ID number identifying the campus.
building_id ID number identifying the building.
floor_id ID number identifying a campus building.
hashed_sta_eth_mac Anonymized value of the MAC address.
Table 14: Location API Output
This query displays output similar to the example below.
{
"Location_result": [
{
"msg": {
"sta_eth_mac": {
"addr": "00FF00043DFD"
},
"sta_location_x": 35.035,
"sta_location_y": 251.61499,
"error_level": 214,
"campus_id": "A491E73EA7D34DEBA876AA667CB8353B",
"building_id": "A6648B8087954F16B5562C6088434CDE",
"floor_id": "B3D65D36E5D449CAA483000000000016",
"hashed_sta_eth_mac": "6C4157F77D50D0C7C052B5094B6621B47BADC969"
},
"ts": 1381954509
}
]
}
Publish/Subscribe APIs
ALEpublish/subscribe API uses MQclient libraries to allow network administrators to connect to the ALE and
subscribe to selected topics. Once a user has subscribed to a topic, ALE starts publishing messages on these
topics, and sends themto the subscribers.
ALE manages access rights to personally identifiable information (PII) such as MAC addresses, client user names,
and IP addresses of network devices by removing this sensitive information fromdata feeds to subscribers who do
not have the appropriate credentials. All messages are encoded using Google Protocol Buffer and specified using a
.proto file. Network application developers, developing applications processing this data, use this .proto file and the
protocol buffer compiler,(protoc), to generate the message parsing code in the language of your choice (such as
C++, Java or Python).
Events
The Northbound API (NBAPI) publishes messages as events. An event message is the only message type NBAPI
will publish. The NBAPI embeds other message types depending on the event.
The event protobuf schema is as follows:
message nb_event {
enum event_operation {
OP_ADD = 0;
OP_UPDATE = 1;
OP_DELETE = 2;
}
enum license_info {
hb_Dhak = 10;
hb_ThresholdXNotice = 20;
hb_ThresholdOkNotice = 21;
hb_LimExceeded = 31;
hb_EvalStarted = 41;
hb_NewLimExceeded = 51;
hb_EvalDone = 61;
hb_ALSOnline = 71;
hb_ALSDieing = 81;
hb_CODE_RED_BLOCKIT = 91;
}
optional uint64 seq = 1;
optional uint32 timestamp = 2;
optional event_operation op = 3;
optional uint64 topic_seq = 4;
optional bytes source_id = 5;
//For now required license_info lic_info = 6 [default=hb_Dhak];
optional license_info lic_info = 6 [default=hb_Dhak];
// One of the following is populated depending on the topic
optional location location = 500;
optional presence presence = 501;
optional rssi rssi = 502;
optional station station = 503;
optional radio radio = 505;
optional destination destination = 507;
optional application application = 509;
optional visibility_rec visibility_rec = 510;
optional campus campus = 511;
optional building building = 512;
optional floor floor = 513;
optional access_point access_point = 514;
optional virtual_access_point virtual_access_point = 515;
optional geofence geofence = 516;
}
Global field definitions are as follows:
l lic_info: Current information about licensing status
l seq : Uniquely assigned global sequence number
l timestamp : Time since the Epoch (00:00:00 UTC, January 1, 1970), measured in seconds when this event
occurred
l op : Event operation code. Reflects the new object state. Possible values are: OP_ADD, OP_UPDATE, OP_
DELETE
l topic_seq : Per topic uniquely assigned sequence number
l source_id : Randomnumber of bytes used as a unique ID for the source ALE. This number is unique per ALE
instance. The unique source_ids are persisted across reboots.
Analytics and Location Engine 1.1 | User and API Guide ALEAPIs | 25
26 | ALEAPIs Analytics and Location Engine 1.1| User and API Guide
Presence
When a user is subscribed to the presence topic, the API publishes event messages with the optional sub message
presence. This message is sent as soon as an AP radio hears a selected client MAC address. If the client
associates to the network, then the associated field is set to true, otherwise false.
MQ endpoint tcp://localhost:7779
MQ message filter presence
Protobuf schema message presence {
optional mac_address sta_eth_mac = 1;
optional bool associated = 2;
optional bytes hashed_sta_eth_mac = 3;
}
RSSI
This topic sends the RSSI value for a selected station at a specific point in time, as heard by an AP radio identified
by radio_mac field.
MQ endpoint tcp://localhost:7779
MQ message filter rssi
Protobuf schema message rssi {
optional mac_address sta_eth_mac = 1;
optional mac_address radio_mac = 2;
optional uint32 rssi_val = 3;
optional bool associated = 4;
optional bytes hashed_sta_eth_mac = 5;
}
Location
The location topic sends updates for a specific station. This message will be sent as soon as the ALE calculates the
location of an associated or unassociated client with a specified MAC address. The X and Y station location values
in this topic indicate the number of feet that the station is away fromthe top left corner of the floor map..
MQ endpoint tcp://localhost:7779
MQ message filter location
Protobuf schema message location {
optional mac_address sta_eth_mac = 1;
optional float sta_location_x = 2;
optional float sta_location_y = 3;
optional uint32 error_level = 7;
optional bool associated = 8;
optional bytes campus_id = 9;
optional bytes building_id = 10;
optional bytes floor_id = 11;
optional bytes hashed_sta_eth_mac = 12;
repeated bytes geofence_ids = 13;
}
Station
This station topic returns information about a user associated to a particular station MAC address. This message is
only sent when a user authenticates to the network with a user name.
MQ endpoint tcp://localhost:7779
MQ message filter station
Protobuf schema message station {
optional mac_address sta_eth_mac = 1;
optional string username = 2;
optional string role = 3;
optional mac_address bssid = 4;
optional string device_type = 5;
optional ip_address sta_ip_address = 6;
optional bytes hashed_sta_eth_mac = 7;
optional bytes hashed_sta_ip_address = 8;
}
Access Point
This access point message is sent when a new access point (AP) is deployed in the network. The message will be
sent as soon as the AP joins the network, regardless of whether the AP has been logically placed on a floor map. It
will also be sent when an AP goes down and then comes back up and joins a controller.
MQ endpoint tcp://localhost:7779
MQ message filter access_point
Protobuf schema message access_point {
enum deployment_mode {
DEPLOYMENT_MODE_CAMPUS = 0;
DEPLOYMENT_MODE_REMOTE = 1;
}
optional mac_address ap_eth_mac = 1;
optional string ap_name = 2;
optional string ap_group = 3;
optional string ap_model = 4;
optional deployment_mode depl_mode = 5;
optional ip_address ap_ip_address = 6;
}
Radio
The radio topic sends information about each radio on a newly added AP.
MQ endpoint tcp://localhost:7779
MQ message filter radio
Protobuf schema message radio {
enum radio_phy_type {
RADIO_PHY_TYPE_A = 0;
RADIO_PHY_TYPE_A_HT = 1;
RADIO_PHY_TYPE_A_HT_40 = 2;
RADIO_PHY_TYPE_B_G = 3;
RADIO_PHY_TYPE_B_G_HT = 4;
RADIO_PHY_TYPE_B_G_HT_40 = 5;
RADIO_PHY_TYPE_AC_HT = 6;
RADIO_PHY_TYPE_AC_HT_40 = 7;
RADIO_PHY_TYPE_AC_HT_80 = 8;
}
enum radio_mode {
RADIO_MODE_AP = 0;
RADIO_MODE_MESH_PORTAL = 1;
RADIO_MODE_MESH_POINT = 2;
RADIO_MODE_AIR_MONITOR = 3;
RADIO_MODE_SPECTRUM_SENSOR = 4;
}
optional mac_address ap_eth_mac = 1;
optional mac_address radio_bssid = 2;
optional radio_phy_type phy_type = 3;
optional radio_mode mode = 4;
}
Virtual Access Point
The virtual accesspoint topic messages are sent for each virtual AP (VAP) associated with a newly added AP.
MQ endpoint tcp://localhost:7779
MQ message filter virtual_access_point
Analytics and Location Engine 1.1 | User and API Guide ALEAPIs | 27
28 | ALEAPIs Analytics and Location Engine 1.1| User and API Guide
Protobuf schema message virtual_access_point {
optional mac_address bssid = 1;
optional string ssid = 2;
optional mac_address radio_bssid = 3;
}
Destination
The Destination topic message is not available for IAP deployment.
The destination topic messages are sent when a new destination is classified by the controller firewall.
MQ endpoint tcp://localhost:7779
MQ message filter destination
Protobuf schema message destination {
optional ip_address dest_ip = 1;
optional string dest_name = 2;
optional string dest_alias_name = 3;
}
Application
The Application message is not available for IAP deployment.
This application message is sent when a new application is classified or otherwise recognized by the controller
firewall.
MQ endpoint tcp://localhost:7779
MQ message filter application
Protobuf schema message application {
optional uint32 app_id = 1;
optional string app_name = 2;
}
Visibility Records
The Visibility Records message is not available for IAP deployment.
This visibility records message represents a unique associated station session for each client MAC for a given
application or destination.
MQ endpoint tcp://localhost:7779
MQ message filter visibility_rec
Protobuf schema message visibility_rec {
enum ip_protocol {
IP_PROTOCOL_VAL_6 = 6;
IP_PROTOCOL_VAL_17 = 17;
}
optional ip_address client_ip = 1;
optional ip_address dest_ip = 2;
optional ip_protocol ip_proto = 3;
optional uint32 app_id = 4;
optional uint64 tx_pkts = 5;
optional uint64 tx_bytes = 6;
optional uint64 rx_pkts = 7;
optional uint64 rx_bytes = 8;
optional bytes hashed_client_ip = 9;
optional mac_address device_mac = 10;
optional bytes hashed_device_mac = 11;
optional string app_name = 12;
}
Campus
This campus message is sent when synchronization between ALE and updated VisualRFmaps creates when a new
campus.
MQ endpoint tcp://localhost:7779
MQ message filter campus
Protobuf schema message campus {
optional bytes campus_id = 1; // 16 bytes id
optional string campus_name = 2;
}
Building
This building message is sent when synchronization between ALE and updated VisualRFmaps creates when a new
building. Each campus can have multiple buildings, but a building can be located on only one named campus.
MQ endpoint tcp://localhost:7779
MQ message filter building
Protobuf schema message building {
optional bytes building_id = 1; // 16 bytes id
optional string building_name = 2;
optional bytes campus_id = 3; // 16 bytes id;
}
Floor
This floor message is sent when synchronization between ALE and updated VisualRFmaps creates when a new
floor. Each building can have multiple floors, but a floor can be located on only one named building.
MQ endpoint tcp://localhost:7779
MQ message filter floor
Protobuf schemamessage floor {
optional bytes floor_id = 1; // 16 bytes id
optional string floor_name = 2;
optional float floor_latitude = 3;
optional float floor_longitude = 4;
optional string floor_img_path = 5;
optional float floor_img_width = 6;
optional float floor_img_length = 7;
optional bytes building_id = 8; // 16 bytes id
optional float floor_level = 9;
optional string units = 10;
}
Analytics and Location Engine 1.1 | User and API Guide ALEAPIs | 29
Analytics and Location Engine 1.1 | User and API Guide Security and Troubleshooting | 30
Chapter 3
Security and Troubleshooting
This topic discusses how to use the SSL bridge and provides troubleshooting tips.
About SSL Bridge
Integration with Meridian
The ALE offers a tight integration with the Meridian way-finding application. In order to couple this integration, the
ALE provides location and user data to the Meridian cloud service.
To start the Meridian SSL tunnel, issue this command:
/etc/init.d/meridian-tunnel start
If you want to automatically start the tunnel on eventual reboot, issue this command:
/etc/init.d/meridian-tunnel install
To stop the tunnel:
/etc/init.d/meridian-tunnel stop
To uninstall the script:
/etc/init.d/meridian-tunnel uninstall
SSL bridge is used to encrypt and pass ALE data traffic to a MQsubscriber application hosted in the cloud.
The nbapisslbridge component is provided to simplify ALE deployments in data centers behind firewalls and NATs
in which the Northbound consumer of information is an application hosted in a public cloud. In these cases, a
connection back to the ALE is impossible fromthe cloud application, for example, an application running in Amazon
EC2.
Using SSL Bridge
Usage: ./nbapisslbridge [options]
Options:
-w Enable watchdog. Process will re-spawn when unexpectedly terminated
-f <endpoint> Frontend endpoint to connect to , this is the IP address:port of ALE
-b <endpoint> Backend endpoint to SSL connect to , this is the name/IP address:port of the cl
oud application
-c <ca path> ALE file path or directory, this is the certificate of Cloud Application SSL se
rver
Example
To forward traffic fromthe local ALE server with the IP address 192.100.1.10 and port 7779 to an AWS EC2 instance
at ec2.company.comport 4433 using a specific certificate.
nbapisslbridge -w -f 192.168.1.10:7779 -b ec2.company.com:4433 -c ./my-x509cert.pem
Note that the SSL bridge establishes the connection (socket connect) to the backend endpoint. In this configuration
the MQsubscriber has to listen (socket bind) for the incoming connection. SSL bridge is designed to handle socket
disconnections and retries to connect in a timely manner, thus enabling the subscriber to go up and down without
being concerned about reconnection.
31 | Security and Troubleshooting Analytics and Location Engine 1.1| User and API Guide
Troubleshooting
This section discusses common ALEdebugging, startup, and runtime issues that you can troubleshoot.
Viewing and Downloading the ALE Diagnostics
You can view ALE diagnostic information, such as server status and activity statistics, and download it as a file and
send it to Aruba Tech Support.
To do this:
1. Fromthe ALE UI, select the Diagnostics tab to view diagnostic data.
2. Click Download and save the file to your desktop.
Figure 6 ALE UI Diagnostics tab
Analytics and Location Engine 1.1 | User and API Guide ZeroMQApplication Sample Code | 32
Chapter 4
ZeroMQ Application Sample Code
This section includes sample code for the ZeroMQapplication.
#include <stdio.h>
#include <string>
#include <iostream>
#include <iomanip>
#include <typeinfo>
#include <zmq.h>
#include "objects/schema.pb.h"
namespace gpb = google::protobuf;
namespace
{
const char* g_appName = NULL;
const char* const DEFAULT_ZMQ_ENDPOINT = "tcp://localhost:7779";
const char* const DEFAULT_ZMQ_SUB_FILTER = "";
void usage()
{
printf("\n");
printf("Usage: %s [options]\n", g_appName);
printf("Options:\n");
printf(" -e <endpoint> ZMQ endpoint to connect/bind to. Default: %s\n", DEFAULT_ZMQ_ENDPOIN
T);
printf(" -f <filter> Message filter to apply on a ZMQ_SUB socket. Default: %s\n",
strlen(DEFAULT_ZMQ_SUB_FILTER) ? DEFAULT_ZMQ_SUB_FILTER : "<empty>");
printf(" -b Listen for ZMQ endpoint on port 7779. Default: connect\n");
printf("\n");
exit(1);
}
bool readMsgs(void* skt, zmq_msg_t& topic, zmq_msg_t& zmsg)
{
bool success = false;
int more = 0;
size_t more_size = sizeof(int);
if (zmq_msg_recv(&topic, skt, 0) >= 0)
{
/* Determine if more message parts are to follow */
if (zmq_getsockopt(skt, ZMQ_RCVMORE, &more, &more_size) == 0)
{
if (more)
{
if (zmq_msg_recv(&zmsg, skt, 0) >= 0)
success = true;
else
perror("zmq_msg_recv zmsg");
}
else
std::cerr << "No more Zmq message to read" << std::endl;
}
else
perror("zmq_getsockopt ZMQ_RCVMORE");
}
else
perror("zmq_msg_recv topic");
33 | ZeroMQApplication Sample Code Analytics and Location Engine 1.1| User and API Guide
return success;
}
std::ostream& operator<<(std::ostream& os, const ce::nbapi::event& ev)
{
return os << ev.DebugString();
}
}
int main(int argc, char* argv[])
{
g_appName = argv[0];
std::string endpoint(DEFAULT_ZMQ_ENDPOINT);
std::string filter(DEFAULT_ZMQ_SUB_FILTER);
int c;
bool doBind = false;
while((c = getopt(argc, argv, "hf:e:b")) != -1)
{
switch (c)
{
case 'f':
if (optarg && optarg[0])
filter.assign(optarg);
break;
case 'e':
if (optarg && optarg[0])
endpoint.assign(optarg);
break;
case 'b':
doBind = true;
break;
default:
usage();
break;
};
}
void* ctx = zmq_ctx_new();
if (!ctx)
perror("zmq_ctx_new");
assert(ctx);
void* sub = zmq_socket(ctx, ZMQ_SUB);
if (!sub)
perror("zmq_socket");
assert(sub);
if (doBind)
{
endpoint.assign("tcp://*:7779");
printf("Attempting to 'bind' to endpoint: %s\n", endpoint.c_str());
if (zmq_bind(sub, endpoint.c_str()) != 0)
{
perror("zmq_bind");
assert(0);
}
}
else
{
printf("Attempting to 'connect' to endpoint: %s\n", endpoint.c_str());
if (zmq_connect(sub, endpoint.c_str()) != 0)
{
perror("zmq_connect");
assert(0);
}
}
printf("Connected to endpoint: %s\n", endpoint.c_str());
if (zmq_setsockopt(sub, ZMQ_SUBSCRIBE, filter.c_str(), filter.size()) != 0)
{
perror("zmq_setsockopt");
assert(0);
}
printf("Subscribed to topic: \"%s\"\n", filter.c_str());
zmq_msg_t topic;
zmq_msg_t zmsg;
if (zmq_msg_init(&topic) != 0)
{
perror("zmq_msg_init topic");
assert(0);
}
if (zmq_msg_init(&zmsg) != 0)
{
perror("zmq_msg_init zmsg");
assert(0);
}
std::string strTopic;
size_t cnt = 1;
ce::nbapi::event ev;
while (readMsgs(sub, topic, zmsg))
{
strTopic.assign(static_cast<const char*>(zmq_msg_data(&topic)), zmq_msg_size(&topic));
printf("[%zu] Recv event with topic \"%s\"\n", cnt, strTopic.c_str());
if (ev.ParseFromArray(zmq_msg_data(&zmsg), zmq_msg_size(&zmsg)))
{
std::cout << ev << std::endl;
}
else
{
printf("[%zu] Protobuf failed to parse event\n", cnt);
}
cnt++;
}
std::cout << "Cleaning..." << std::endl;
if (zmq_msg_close(&topic) != 0)
perror("zmq_msg_close topic");
if (zmq_msg_close(&zmsg) != 0)
perror("zmq_msg_close zmsg");
if (zmq_close(sub) != 0)
perror("zmq_close");
if (zmq_ctx_destroy(ctx) != 0)
perror("zmq_close");
return 0;
}
Analytics and Location Engine 1.1 | User and API Guide ZeroMQApplication Sample Code | 34