How do I use Basking WLAN Connector?

The Basking Connector for WLAN Controllers enables occupancy analytics by analyzing log data from WLAN controllers. It includes built-in MAC address anonymization with dual encryption for privacy, and supports data auditing via direct output logging.

Overview

The WLAN Connector module enables occupancy analytics directly from WLAN controllers, where location data is otherwise unavailable.

The module analyzes WLAN controller logs and collects roaming events between access points, as well as device registrations on the network, using the location of access points to approximate the location of occupants.

As with all Connector input modules, client device mac anonymization is built-in and can be toggled via a configuration file.

Terminology

• client device: an occupant’s device - typically a phone or a personal computing device - counted towards occupancy.
• Controller: a WLAN controller, or otherwise a centralized device collecting events from access-points.
• Connector: a pairing of an input module such as this one and the Basking Submitter.

Requirements

1. an x86 Linux machine capable of executing the Connector binary
   1. additional architectures may be available on request
2. access to the Controller’s logs
   1. if the connector runs on a separate machine, that machine must be reachable from the log machine
3. an up-to-date Connector binary from Basking, along with its configuration file
4. an ORG_SECRET from Basking, to be set as an environment variable on the executing machine

Transmitting the logs

The Connector exposes a server that accepts POST messages of the text/plain MIME type. There is no limitation on the payload size, but it is proportional to the memory consumption of the Connector.

A basic example of log transmission would include:

1. configure log-rotation on the WLAN controller or directly on the logging machine, rotating every 5 minutes
2. build a bash-based command to send the contents of a log file in a payload to the Connector
   (e.g cat latest.log | grep ROAMING | curl -XPOST -H'content-type:text/plain' --data-binary @- basking-connector.my-network.com:8081)
3. configure a crontab job on the logging machine to execute every 5 minutes, running the above command

Encryption and auditing

MAC addresses for all client devices are double-encrypted using a combination of a customer key (delivered by Basking and set up as an environment variable on the executing machine) and a Basking key (obfuscated inside the compiled binary).

The correct combination of keys allows Basking to match clients between Connector-based and server-based implementations where possible (i.e where the same MAC address is provided to the network device).

The encryption can be toggled on or off via the configuration file.

To audit the extracted data or the anonymization of PII, the compiled binary can simply be executed. It outputs all of its findings to STDOUT by default where it can be reviewed directly or piped into a file for later review.

Ex. 1

./input-snmp > audit.log

Deployment

1. copy the Connector binary and configuration file to the same folder
2. modify the configuration file based on the included instructions
3. set the environment variable ORG_SECRET to the secret key provided by Basking
4. run the binary
   1. note the port the Connector’s server is listening on
5. transmit logs to the Connector’s executing machine and audit the Connector’s output
6. [optional] set logging level to WARNING by setting the environment variable LOG_LEVEL to WARNING
7. pipe the output of the connector to the submitter (submitter configuration to be done separately)

Shorthand

$ LOG_LEVEL=WARNING ./connector | ./submitter