modified on 13 July 2011 at 18:53 ••• 567,409 views

AirControl

From Ubiquiti Wiki

Jump to: navigation, search

Contents

AirControl 1.4 User's Guide

Introduction

AirControl is a powerful and intuitive web based network management server application that allows operators to centrally manage entire networks of Ubiquti devices. It provides the following key features:

  • Discover Ubiquiti devices (access points and stations) within subnets associated to the server's network interface(s). The Discovery Scan works exactly as found in the existing Ubiquiti discovery tool. In addition, for non-local subnets, there is an option to add a device manually by specifying its IP address or an IP range to scan for devices.
  • Connect devices, report device status: Devices that are under "management" will periodically report runtime status to the AirControl server, which will monitor status updates.
  • Firmware update: Devices that are under management can be updated from AirControl. Multiple devices can be updated as a single, synchronized batch (with wireless association dependency between devices). Firmware images are uploaded by the administrator into AirControl prior to a device update.
  • Configuration changes: Change AirOS configuration from within AirControl with support for synchronized mass changes.
  • Tasks Scheduling: Automatically execute firmware update, reboot, IP range scan, device configuration backups, ping and shell commands. The start and end date/time of tasks can be defined as well as the interval period (minutes, hours, days).
  • Device configuration backup and restore: Remote backing up or restoring multiple device configurations. A new backup file will be made in case of changes between the latest backup and the actual configuration.
  • Device statistics/graphs: Report on any of the runtime attributes from the device in either the device list or the details view. The output can be customized. Attributes can be configured for history collection and plotted for a selected period (minute, hour, day) and number of data points. Amount of historic data to be retained can be configured for each interval.
  • Network Map: Show AP or Station locations on a Google Road, Terrain, or Satellite Picture Map. It allows display of device status on a map view, planning new AP location, see coverage and provide more information for installers about reference points for a new installation, to mention only a few possible uses.
  • Device Grouping: A device tree provides for easy navigation and device selection. Built-in auto-groupings categorize discovered devices by network ID (ESSID) and firmware version. The device tree can be customized adding custom device groups ("watch lists"). These can be either static groups or dynamic groups, based on reporting criteria.
  • Activity log/history: History for specific device in the details area, for the entire system in the log tab and for current activity with the "Live Log" popup. The main screen will also indicate in-progress activity.
  • Server application with access to the user interface through a Web browser (HTTP or HTTPS). Multiple users can access single server; no installation required on a client other than the web browser. Broad platform support (server runs on every platform for which Sun's Java 6 is available). Users can be assigned different access levels (read-only, manager, admin) and access to the system is password protected. HTTPS is recommended (and can be enforced) when accessing AirControl through a public address.
  • Automatic server updates as patches and new releases become available. These updates preserve your data (unlike uninstall/reinstall).
  • Speed Test: Launcher (compatible only with firmware 5.1 or higher), runs iperf speed test between compatible devices, or between AirOS device and the AirControl server or other host machine with iperf software separately installed.

Installation

The server installation requires Sun's Java 6 Runtime Environment (download latest version from http://www.oracle.com/technetwork/java/javase/downloads/index.html). AirControl requires version 6 of the JVM or higher and includes the Tomcat servlet container. Server installers are provided for Windows XP/Vista/7 (x86) and Debian Linux, plus a generic tarball for other platforms. Windows and Debian installers will install AirControl as service. To manually start/stop the server when not installed as service, use the scripts provided in the bin subdirectory of the installation folder.

Update: If you have previously installed AirControl using the service installer and want to upgrade, please update the installation with automatic update instead of reinstalling. Uninstall will remove your data. Back up your data periodically (directory <AIRCONTROL_HOME>/data).

Move Server: If you wish to move existing AirControl with managed devices to a different machine, migrate the data to ensure that references from managed devices back to the AirControl server are properly updated to the new server address. First install fresh AirControl on new machine, then shutdown old and new server, move data directory (directory <AIRCONTROL_HOME>/data) from old to new host/server (replace data directory on new server), then restart new server.

System Overview

AirControl is a server application, typically hosted on a machine within the private network, collocated with the managed devices. The user will access the application through the browser, from anywhere on the network or over the internet. There is no software other than the web browser required on the desktop (AirControl can be accessed from any host OS with recent web browser).

The server is meant to always run, to monitor and collect statistics about managed devices. It is possible to run browser and server on the same machine, and launch the server on-demand, but this is not the intended use of the system.

Another way to use AirControl is through web service API, again using HTTP(S) as transport. Instead of the browser, a custom application or utilities such as wget or curl could be the clients. The API is currently in a limited form but expected to grow over time to meet the need for integration with home-grown NMS/WISP management solutions.

System requirements for the server vary primarily with the number of managed devices and the frequency of statistic updates from those devices. Given a minimum footprint for the execution of the JVM, a single core machine with 512MB dedicated RAM may be able to serve around 50 devices while a few thousand managed devices may require a better performing multi-core machine with 2-3GB dedicated memory.

Management Protocol

Devices are discovered by initiating a scan on the AirControl server. A UDP discovery challenge is sent either as broad/multi-cast for local subnet scan or as unicast datagram for scan in routed subnets. The devices return a response (if configured to do so), containing basic information such as the interface addresses, device name, firmware and ESSID. Upon discover the device appears in the device list in AirControl.

Once discovered (or manually added), devices can be put under management, which will establish key based SSH access and periodic statistics reporting from the device to the server. SSH access is on demand and for control operations (firmware upgrade, restart, configuration change etc.). As part of the "heart beat" statistics reporting the AirControl agent running on the AirOS firmware will send data in configurable intervals over HTTP, encrypted using 128-bit AES-CBC. The device communication is secured based on symmetric key exchange through SSH.

The management protocol is layer 3 (TCP/UDP) and requires the following communication to be enabled on the network (see arrows depicting connection initiation in the diagram above):

  • UDP from AirControl server to port 10001 on the device, UDP response from device back to dynamically allocated port on AirControl
  • SSH from server to managed device, at configurable port.
  • HTTP from managed device to server at configurable port.

The "two way traffic" of the protocol requires routing from both the server to the managed device and vice versa. To support management of devices that are behind NAT, AirControl offers the option to tunnel control operations through SSH port forwarding into the "remote" network. Typically the entry port would be made available at the WAN head router for access over the internet or at the router performing NAT within a private network (for example AirOS device in AP/router mode to manage associated stations).

Checklist/Settings

  • Server can reach all devices at SSH port and SSH service enabled on the device. (SSH port can be set when connecting or in the device settings dialog. Default SSH port is 22.)
  • Devices must have firmware version 3.4 or higher installed (M-Series already include AirControl support). AirControl can automatically upgrade a/b/g units with older firmware versions and enable SSH through the web interface when they are put under management (see section connect/disconnect below).
  • Devices must reach server on the HTTP port specified at installation time. Make sure no firewall settings block this communication.
  • The default AirControl HTTP port is 9080, unless you’ve assigned a different port during installation or configured an external IP address/port under "System Settings". If the local interface address of your AirControl server is not visible to the devices you wish to manage (NAT, firewall, etc.), you must configure the address in system settings (public or routed private IP address, DNS not supported, HTTP port number if different from the local setting).
  • Server Sizing: System requirements for the server vary primarily with the number of managed devices that are online at the same time and the frequency of statistic updates from those devices. Given a minimum footprint for the execution of the JVM, a single core machine with 512MB dedicated RAM may be sufficient for around 100 devices while a few thousand managed devices may require a better performing multi-core machine with 2-3GB dedicated memory. As an example, for 10000 CPEs on a single AirControl server with ~1/3 of them online at the same time, sending statistics to the server every 5 minutes, consider a 2-4 CPU machine with 4 GB memory, Linux OS.

Server Tuning

The default server configuration will work for most systems with a few hundred devices. With larger device counts, or to optimize server performance in general:

  • Large number of CPEs: Adjust monitoring settings. CPEs may be turned off by the customer, there may be hundreds of devices offline at any point in time and AirControl should not attempt to connect to those via SSH in attempt to restore reporting (consumes server resources and generate irrelevant system log entries). Create a dynamic device group for Mode = 'sta' to filter CPEs. Then under Admin/Device Management Rules, create a rule that turns off retries for that group.
  • System log size: Under system settings, reduce the number of days logs are being kept for. You can drop this number if the system generates many events in the system log. Keeping too many entries in the log can slow down the user interface.
  • Reporting Interval: The more managed devices, the more statistics to process by the server every second. The default interval of 30s is fine for a few hundred devices. Consider increasing it to reduce server CPU usage depending on the size of your system. Also adjust the reporting timeout that triggers offline status to a value that best reflects conditions in your network.
  • Broadcast Scan: Review need for broadcast discovery, turn off this option under system settings if your devices are in routed subnets and you need to use range scan to find them anyways. Depending on your network setup the UDP broadcast can also lead to performance decrease or latency issues and must be turned off.
  • User Interface Navigation: Use device grouping and filtering to limit the amount of data pulled into the UI with thousands of devices (ideally don't use the "All Devices" group). Use Chrome or Firefox for better user interface performance (IE8 is much slower).

Installation on Microsoft Windows

System Requirements

  • A permanently running computer operating under Windows XP, Vista, 7, Server connected to your network
  • Java VM version 6 or higher installed (32-bit JVM only). The service launcher, when running on 64-bit Windows, will work as long as a 32-bit JVM is selected during installation.
  • A compatible Web browser, preferably Firefox 3.6 or later or Chrome, IE8 is supported (Internet Explorer 7 and older are not supported).
  • SSH service enabled on all the Ubiquiti devices you wish to manage. Also, these devices need to be layer 3 reachable.
  • Ubiquiti 802.11abg device(s) with AirOS 3.6 or higher and/or Ubiquiti M series device(s) running AirOS 5.2.1 or higher. (Firmware 3.4, 3.5 and pre 5.2.1 support AirControl with known limitations. One of the known issues is that after a device reboot, the device does not contact AirControl, and therefore management connection can be lost on extended downtime or IP address change.)

Installation: Step-by-Step

  • Download the latest AirControl version available from http://ubnt.com/aircontrol > Downloads > AirControl beta.
  • Run the installation file.
  • Follow the on-screen instructions (press Next to continue) and provided you agree to the License Terms, click I agree.
  • Select the installation type (Normal is recommended) and click Next.
  • Choose the desired installation folder and click Next.
  • Configure basic settings of AirControl, like: HTTP Port (by default: 9080), HTTPS Port (by default: 9443), Management Port (by default: 9005) and Administrator credentials (default username and password are ubnt). Click Next.

Note: It is strongly recommended to replace the default Administrator credentials.

  • Select the Java SE (JRE or JDK) already installed on your system and click Install to start the installation. On 64-bit Windows, make sure to select a 32-bit VM, typically found under C:\Program Files (x86)\Java\jre6
  • If you are running Windows Firewall, the install utility will ask if you want to add a firewall exception for AirControl. This is an imperative requirement for AirControl operation. Click Yes.
  • After a few seconds, installation should complete. Select the Run Ubiquiti AirControl check box and click Finish. The AirControl Web GUI will be displayed in your default browser.

Windows Service Launcher Configuration

If the AirControl server fails to start (browser does not respond or reports that the server is not found), a common issue is that the Java VM was not configured correctly. Check the log files in the installation directory (for example under C:\Program Files (x86)\Ubiquiti Networks\AirControl\logs), jakarta_service_YYYYMMDD.log for a message like this: "Failed creating java C:\Program Files (x86)\Java\jre6\bin\server\jvm.dll". If you find this error, it could be caused by:

  • Attempt to use a 64-bit JVM when a 32-bit JVM is required (on 64-bit Windows only)
  • The JVM is no longer at the path specified (it was removed or updated to a different location.

To correct the path to the JVM, open the AirControl service configuration panel from the AirControl program group and go to the "Java" tab. Enter the correct path to the jvm.dll.

In the same tab is also the setting for the maximum heap memory that the Java VM is allowed to use (default 1GB, option -Xmx1024M). If the system has very limited available memory and you do not plan to manage many devices through the server, change this setting (for example to -Xmx512M).

Installation on other platforms

AirControl can be installed on any host system that can run a Java6 JVM (Sun or OpenJDK) and provides the necessary system resources (plan with no less than 512M heap space for the JVM). Use the Debian package for installation on Debian based Linux (Ubuntu et al.). Otherwise use the generic tarball and see the README in the root directory.

Related forum threads:

First use

To access the application, start your Web browser and enter the URL into the address bar: For example, if the server runs on host "localhost" and uses HTTP port 9080 (the default unless changed during installation), the address will be http://localhost:9080. If you are accessing from another PC on the network you must enter the host name where AirControl is installed:9080.

For HTTPS, it would be https://localhost:9443. Note that while HTTPS is supported, you may get warnings or errors in the browser related to the non-trusted default SSL certificate (generated during the installation). To avoid these browser warnings, you can obtain a valid SSL certificate from a trusted authority. Once you have the new certificate file, you must replace the default system certificate with the new one. In case that you don’t want to get a “secure” SSL certificate; also you can add the default SSL certificate to your browser’s list of trusted certificates.

Once you access the application, you must sign in using the administrative credentials changed in the installation process (by default username: ubnt and password: ubnt). The initial login/password assigned during installation can be found in <ACHOME>/conf/catalina.properties (valid until password change though the application occurs).

If at time of installation there is an update available, a message box will appear after login asking you if you wish to upgrade to the newer AirControl version or not.

It is recommended to always upgrade to the latest version available. The system will download the new version and restart the AirControl process. If the update dialog remains on the screen after the server restarted, click the close button. If the screen does not reload, try to refresh the entire page and restart the AirControl service as a last resort.

After having successfully logged into the application, discover/scan for devices and start to manage them. See respective sections below.

AirControl and Remote Networks

A solution to manage non-routed remote networks through SSH tunneling is available. See http://www.ubnt.com/downloads/aircontrol/aircontrol-remote-networks.pdf for details.

AirControl API

AirControl currently does not offer a full featured API for all the functions available through the user interface. A limited web service to integrate with custom applications is available. It can be used with any scripting language that understands HTTP(S), including PHP, Python, HTML/JavaScript and command line tools like wget and curl.

http://www.ubnt.com/downloads/aircontrol/aircontrol-api-alpha.pdf

A few control operations are also supported (connect, upgrade, configuration, configuration restore). This support should be considered experimental and may change in future versions. The API will be expanded to eventually include all operations that are available through the task scheduling dialog in the UI and it is likely that new functionality will be supported through API first.

Navigation

Use the top level navigation tabs to access different areas of the system:

[Devices] page displays Ubiquiti devices managed by AirControl.

[Firmware] page allows to manage firmware files in AirControl.

[Schedule] page allows viewing and editing scheduling tasks

[Admin] page allows managing user accounts and system settings.

[System Log] page contains log information about controlled devices and AirControl system.

[My Settings] allows changing account password and managing some preferences.

[About] displays the current AirControl version installed on the system, and also allows checking for availability of new AirControl versions, in order to perform an update.

Devices

Scan: To add devices, click on the scan button or context menu Scan For New Devices from the device list. A dialog will open with scan options (see below). Discovered devices will be shown in the All Devices group with a grey status icon.

By default, the system performs broadcast discovery background scan, looking for new devices into the network (you can change this option under Admin -> System Settings).

Live Log: This option opens a new window with live log information, like devices in upgrade process.

Search (right side): Use the search filter control on top-right of device table for quick search of devices. Search will include all columns in the device list and perform a partial text match. To refine search (search on numeric fields etc.), click on the advanced search button on the right side.

Device Groups

Devices can be categorized into groups for ease of navigation. Built in are auto-groupings for network ID and firmware versions, the "All Devices" and "in-progress" dynamic groups. Two types of custom groups that can be created by the user and appear under "Watch" are supported: (1) user managed static groups for which devices are manually added and removed and (2) criteria groups for which group membership is determined by search criteria (consisting of any of the device attributes and an operator). This can be used to define groups like "signal strength < -60" etc. or "IP Address contains 192.1.168", for example. To create and delete groups, use the context menu located at the upper-right side of the device tree. To add devices to a static group, use “Add to” in the device list context menu, and select the destination group. To remove devices from a static group, select them and press the Remove Selected Devices button.

All devices: displays all Ubiquiti devices AirControl found within the subnet AirControl is a part of.

AP-Groups: displays UBNT devices in the network, but divided by subgroups based on AP (Access Point) name.

Watch: displays the in-progress devices (like the ones currently in upgrade process) and user created groups.

In-progress: displays the devices in progress for maintenance actions, such as device upgrades.

Firmware: displays the devices sorted by firmware version.

Customize groups via the context menu (handle on the top-right side of the Device Group tree).

Add/Edit Group: allows you to add or modify a custom group. These user created groups will be displayed in the Watch folder.

By checking “Dynamic Group”, the group will automatically contain devices based on criteria like Host Name, Product, etc. The example shows a group of all devices in "ap" mode. Please note that the list of attributes will only contain those that are selected for display in the device list. In this example, to reference wireless mode you would first need to add the same to the device list.

Remove Group: Remove the selected user created group.

Auto-Groupings: Default auto groupings shows as folders "AP-Groups" and "Firmware". You can customize these (delete or add other groupings, change display order, title). For example, you could add a "product" grouping or a grouping based on a user defined or mapped configuration attribute.

Device List

Table displays either the devices for the group that was selected in the group tree, or the search result, if a search was performed. Customize the columns of the table by using the Customize List button in the tool bar (change the fields displayed and order of the fields). Selections are stored for each user and apply to all device groups. To sort devices displayed, click on the table header (toggle sort order by clicking again). To change the size of table columns, drag the header separator. To change the vertical size of the table, drag the space between table and details area. Currently horizontal space distribution between group tree and table cannot be changed.

The status column shows and LED representing the device's management status. If the color is green, the device is reachable and reports status as expected. If the color is red, the device either cannot reach AirControl for reporting or is down. AirControl will periodically attempt to recover devices in error status (with exponential back-off for recovery attempts if device remains unreachable for long time). You can manually trigger recovery attempt for all error devices through the "Scan" button or by reconnecting a specific device (see connect below). Starting with firmware 3.5.1 and 5.2.1 devices will automatically contact the server on startup and therefore status of these devices will be more accurately reflected.

Discovered devices remain listed in AirControl, even when they are no longer online (AirControl does not know whether a device is just offline or no longer physically present). You can remove devices using "Remove Selected Devices" in the device list menu. Note that devices are automatically restored when they are found by discovery scan. The "Remove Selected Devices" function is only to remove devices that are no longer in the network.

Scan For New Device(s): click on this button to search for devices. The latest AirControl version allows for three types of searches: a) Discovery Broadcast, b) Scan IP Range and c) Retry Offline Connections.

Manually Add Device(s): click on this button to add devices that were not discovered automatically (devices on a different subnet).

Add to: this option allows you to add selected device(s) to a previously user created group. Added devices will appear in the subgroups within the Watch group.

Remove Selected Devices: use this option to remove the selected devices from the Devices Table. Note that online devices are automatically restored when they are found by discovery scan. The Remove function is only to remove devices that are no longer in the network.

Connect/Disconnect: A management connection needs to be provisioned before a device can report status to AirControl and other management operations can be performed (see details below). An already managed device can be disconnected.

Update: Firmware upgrade (single device or bulk operation).

Execute/Schedule Device Operations: this option allows executing device's operations like backup the device’s config file, the Ping Watchdog, running commands or performing a Reboot.

Map: selected devices or device group may be seen on the Google Map view, you can also mark the correct position.

Customize Device List: Select the columns to be displayed in the Device table (stored as a user preference). This also controls the set of attributes available when creating dynamic device groups.

Attribute Configuration: Customize attribute titles, history settings, add mapped configuration attributes or custom fields.

Scan For New Devices

The AirControl server must be in the same sub-net to automatically discover devices. If you wish to manage devices that cannot be automatically discovered, you can scan for them by specifying an IP address range or add them manually.

NAT/port forwarding: Devices on the other side of NAT cannot be discovered automatically. You can connect those devices through forwarded ports: Add unit with IP number that forwards the SSH port and specify the mapped port when connecting the device (see below, you can also change the IP address when connecting). When adding the device manually, you can also configure the forwarded web UI port per device; this is required for the "Launch Web UI" link to work for port forwarded management connections.

Scan Type: Select one of the three kinds of types available.

Discovery Broadcast: This is a method for device discovery through UDP broadcast. It sends a message to all local sub-nets the AirControl server is connected to. When receiving replies from online Ubiquiti devices, they will be added to the All Devices Group and dynamic user created groups. Note: The AirControl server must be in the same sub-net/broadcast domain for UDP broad/multicast discovery to work (there may also be firewall, routing restrictions etc.). If you wish to add devices that cannot be discovered with this method, use IP range scan or add devices manually (when using port forwarding).
Scan IP Range: Here you need to specify a range of IP addresses which AirControl will scan for devices, say between 192.168.5.10 and 192.168.5.50, in which case you would write 192.168.5.10 -192.168.5.50. You can also use CIDR and subnet mask syntax and individual addresses. Multiple ranges can be combined, for example: 192.168.0.1/24, 192.168.1.0/255.255.255.0, 192.168.1.0-192.168.1.10, 192.168.1.20 Typically scans of large ranges are best scheduled for off-peak hours. Individual devices addresses are typically used to add a single for which the address is already known on-demand.
Retry Offline Connections: this scan retries to check the actual status of the devices appearing as offline on the Device page.

Manually Add Device(s)

Use this option for devices that cannot be found using scan. You need at least to specify the device’s IP address or host name (and SSH and HTTP ports in case devices are not using defaults). You can optionally enter the Device Name, WLAN MAC. It is recommended to mark the button “Use Global Default” if the device uses the standard ports. Otherwise, unmark the “Use Global Default” button, select the protocol (HTTP or HTTPS) and enter the SSH and HTTP(s) ports used by the device.

Connect/Disconnect Device(s)

Click "Connect" to associate devices with the management server. The server will prompt for the device authentication details and establish a (key based) SSH control channel for management operations. There is an option to remember the credentials entered for future connect operations (the credentials entered are not required once the management connection is established and not stored on the server otherwise). If many devices share the same you can check this option to avoid entering the information repeatedly. AirControl will use the SSH connection on demand to issue control operations and perform firmware update only. Periodic communication for device status reporting goes through HTTP from the device to the server, not through SSH. If the IP address reported from discovery scan is not the IP address under which the device can be reached from the server for whatever reason, expand the device details, you can override the IP address prior to connecting or replace it with a host name.

View/Override details per selected device: Check this option to view additional details to connect/disconnect the selected device(s).

SSH port: specify SSH port of the device to be managed.
Username: specify Administrator username of the device to be managed.
Password: specify Administrator password of the device to be managed.
Remember Authentication Details: enable this option to remember the Authentication credentials information.

Device Details

Name: displays the host name of the selected device.
Address: displays/change the management address of the selected device.
MAC: displays the MAC address of the device to be managed.
Authentication details: This option is only available when you have selected multiple devices to be connected. If you check the Override checkbox you can change the default authentication details (upstairs defined) for this (these) device(s). If you don't check this checkbox, the default credentials will be used. For an already connected device, you would see "stop management" as default check box, which you can uncheck if you wish to reconnect.

Press Continue button to manage this device, or press Cancel to exit from the pop-up box.

Note: If devices change IP address and the address is visible to AirControl, it should automatically update the IP address. However, if for any reason it is not recognized by AirControl; you’ll have to change the device's IP address in AirControl. To do it, select the device to be modified, and change the IP address under Device Settings. Alternatively repeat Connect/Disconnect, check the "View/Override details per selected device" checkbox, uncheck the Stop management for this device checkbox, enter the new IP address. Finally, press the Continue button.

If you find devices after initial connection with error status in the device table, look at the log to determine whether network connectivity could be the cause and check the AirControl HTTP port is reachable from the device.

For correct operation, be sure relevant ports are open in your firewall(s). When in doubt manually check SSH connection from AirControl host to device and reverse HTTP connection from device to AirControl host outside of AirControl (on AirOS 5.x the easiest way to do that is by using wget with the AirControl URL as output by mca-ctrl -t status or mca-provision-list).

If managed devices stop reporting to AirControl (timeout in system settings), status will change to error (red status indicator) and entries generated in the system log, indicating that a device is offline (or not able to reach AirControl). Starting from firmware versions 3.5.1 and 5.2.1 devices will contact AirControl on start up and reporting will be restored immediately. It is therefore recommended to use those firmware versions if you rely on the status reported in AirControl for your monitoring.

Device showing as offline after connect?

If the status indicator in AirControl shows red and you see an error message in the log stating

"No communication from device, check connectivity from device for http://x.x.x.x:9080/heartbeat/"

The device is not able to reach the server under the given address for status reporting. You may need to set the reporting address in AirControl if it cannot be auto-detected and/or make sure there is a route from the managed device to the AirControl server. On AirOS 5.x and later, use traceroute or wget to verify.

To see the status of the management connection, issue the following on the AirOS command line:

XM.v5.3# mca-ctrl -t status
| 15:43:43 | 30 | 0 | 1192 | http://x.x.x.x:9080/heartbeat/

Third column is the the number of successful status updates. If it is 0, the device cannot contact AirControl.

Connect devices with firmware lower than AirOS 3.4

The firmware requirement for management of devices through AirControl is AirOS 3.4 or higher. If you have devices with firmware older than AirOS 3.4, following steps can be used upgrade your devices from the legacy firmware to the required version from AirControl through HTTP:

  • Upload firmware image to the AirControl server. Preferably keep only one firmware image in AirControl during this process to be sure which one will be used for the legacy upgrade. More information is available on Firmware page.
  • Go to devices page, select the units to be upgraded and managed. We recommend that you verify the upgrade with a few units before running a larger batch. Press Connect/Disconnect button. It will launch the expanded view with detailed information for each device. Carefully review. To go ahead and upgrade the selected devices press Continue button.

In case you are running a firmware older than AirOS 3.3 the device will reboot prior to upgrade. This operation takes a few minutes. After the process finishes devices will be loaded with the selected firmware and will appear in the All Devices group. You may find the device back online with new firmware while AirControl still shows as waiting, this may be due to the timeout handling in AirControl and does not imply a problem with the upgrade as such.

Update Device Firmware

This allows upgrading the firmware, when this button is clicked a dialog opens a windows that shows the selected devices, grouped by target firmware version. If multiple versions are available, the highest version is selected in the drop-down by default. All devices that are part of one update group will be updated as a single batch. Each batch it will be synchronized so that wireless connections don't cut off before all the stations have received the upgrade command.

Updates are executed in the background. To see current activity, select the In-Progress device group. All devices with pending operations are shown there. To see the detailed status for a particular device, select the device and see the progress indicator in the left hand panel, above the product logo. It shows completion percentage and detail about the current activity.

By selecting the Schedule Execution button, an update task can be scheduled for a specific date/time, e.g. upgrade a device coming Monday at midnight. You must define Task Name (used for identification) and Date.

Device Configuration

The feature is available under "Device Configuration" in the context menu. Single device selection:

  • Dialog opens showing the configuration backup list.
  • Click "Current Configuration" to load the latest configuration from the device.
  • Make changes in the tree view. Click "Continue".
  • Review Changes, optionally schedule the change and then apply.

Multiple devices can be changed as a single operation (Always verify configuration changes first on devices that you can easily access/reset before applying to multiple units or units that are difficult to access!)

  • Select multiple devices, then "Device Configuration"
  • Dialog will prompt to select one unit to make the change for, review/confirm changes, changes will then be applied to all radios.
  • Keep batch sizes as small as possible. The current behavior of multiple device configuration is to always change all devices at once (synchronized soft restart). This will take care of changes that affect both sides of links but will work less efficient in terms of AC server resources/load for changes to parameters that have no effect on wireless association. Outcome is all or nothing, either all devices will succeed or fail, ensure to only select online units before making changes.

Firmware dependencies:

  • As of release 1.4, supports only AirOS 3.6 and 5.3 configuration. Does not work with 5.5. Unsupported firmware version will cause AirControl to cancel the operation.
  • AirOS 5.3 has a known problem with soft restart after configuration changes (whether made from the AirOS UI or through AC). You may find devices requiring a power cycle if soft restart fails. AirOS 5.3.2 should have resolved this issue.

Execute/Schedule Device Operations

Here you can execute device operations, like reboots, backups of the config file for selected devices, commands runs and pinging. In order to schedule an operation, first select the device(s) you want to add to this task, then press the “Execute/Schedule Device Operation” button, finally select the “Schedule Operation” and define a time period and interval. All the scheduled tasks can be modified or deleted over the Schedule Page.

Configuration Backup: This option performs a backup of the device(s)’s config file(s). ’’Backup Count’’ specifies the maximum number of backups saved for each device. AirControl will only create new backups in case of changes since the latest backup saved and the current device configuration. You can access (restore/download) existing backups through the "Configuration Backups" dialog in the device details drop down menu, when selecting a single device.

Ping: Run the ping command and record average RTT as attribute "Ping RTT". Parameter count to specify the number of ICMP “echo response” requests. If no ICMP “echo response” packet is received, -1 is recorded for reporting (you can use this "magic" value as ping loss filter). Otherwise the average RTT is recorded.

Reboot: Select this operation in order to initiate a full reboot cycle of the selected device(s). Reboot effect is the same as the hardware reboot, which is similar to the power off - power on cycle. (Any non-applied configuration changes will be lost.)

Execute Command: Enter a valid AirOS shell command to be executed on the device selection. Use this feature with caution and at your own risk. AirControl does not verify or in any way process the command you enter. Test any modifying operation outside of AirControl before applying it to multiple devices.

By selecting Schedule Execution, a task can be scheduled for a specific time interval, e.g. every day at 03:00AM. This feature is useful to perform the task at a specific time (e.g. on a weekday past mid-night), thus won’t allow disturbing customers with downtime periods during daytime hours. You must define Task Name (used for identification), Start Date (From), End Date (To) – if no date is specified, the operation will go on indefinitely – and an Interval (= periodicity of task performance).

Note: For scheduling of recurring tasks, it is recommended to use device groups (instead of selecting specific devices or creating duplicates of the same task).

Device groups can be managed through the left side groups panel. You can use it to create your own device groups and use them for scheduling tasks. As an example, if you wanted to specify a backup task for all devices, select the "All Devices" group and then schedule. Alternatively, create a custom group called "Backup Devices" with all the units you want to run the backup task for. Another example would be the creation of a "Ping Devices" group, and then schedule a task for that group.

You will see the group name displayed in the schedule dialog and whenever the specified task runs, it will run for all valid members of the group at the time of execution. By using this method the list of devices becomes dynamic and can be changed by adding or removing devices from the group rather than recreating duplicate device tasks. Using device groups optimizes the processing of tasks in the system and will provide a single line summary in the system log.

Google Network Map

Select a device group or select devices in the device list for display on the map. A typical choice would be to look at all units belonging to an SSID, but any grouping or selection can be used to decide what to view on the map. Click the map control on the device list tool bar to open the map.

Once the map window opens, you will find all devices in the "unplaced device list", indicating the absence of location data. Any devices running firmware 3.6 or 5.3 and higher for which the location info was entered in the system tab would display at the respective map location. Otherwise AirControl cannot place the devices, it does not know the GPS location and you will need to position the devices manually. To move the map and all devices to another location (default determined from browser with Geolocation support, Firefox 3.6 and Chrome), zoom out and drag one of the device to that location or enter the desired map center address in the toolbar. Now position devices by dragging or entering the address in the info window that opens when clicking the marker.

Devices on the map appear either as a product icon or optionally as the smaller standard color-coded markers indicating the status (red, green, gray) and the wireless mode (A or S). Clicking on a marker will open the info window with device statistics as configured for list one in the details panel. For managed devices, you will also see connecting lines indicating the wireless association between units, with links color coded by signal strength.

Marker's color: indicates the current status of the device, green meaning that the device is online and connected to AirControl. Red means that the device is currently offline, but that there are recent events concerning the device. Gray means that the device is offline with no recent events concerning it.

Marker's Letter: indicates the device’s operation mode. S means that the device is operating as a Station or Station WDS. A means that the device is operating as an AP or AP-WDS.

The info window contains a "remove" button that will delete the location info for the device and move it back into the unplaced device list. It also has a location tab that lets you manually enter either the GPS coordinates or the address for location lookup.

Tools:

  • Placed Devices lists devices on map; selecting entry will move the map center to that device. Use this to quickly find a specific device on the map when zoomed in.
  • Custom Defined Areas to add polygon shaped colored overlays with labels (for user defined covered and dead areas etc.)
  • Ruler tool to measure distance
  • Show coverage: calculated coverage radius, very basic indicator, not considering external antenna specifics etc.
  • Link Calculator can be used for installation planning by placing a theoretical device on the map and calculating the link to existing device or between existing devices and compare against actual statistics. Calculation currently is based on Google Maps API elevation data and limited when it comes to obstruction checking.
  • KML Export for use with Google Earth etc.

Use calculations for rough estimation only and in conjunction with other tools/techniques for further verification.

Attribute Configuration/Settings

History Settings Expand to configure how much data AirControl should gather for graphs.

Add Attribute: Add custom fields or fields that are mapped from the AirOS configuration.

Mapped Configuration Settings:

  • Can be used to identify devices with particular configuration settings (bandwidth control, channel settings etc.)
  • Values automatically kept in sync for AirOS 3.6/5.3 devices, requires configuration backup schedule for older firmware versions.
  • To add new attribute, select device with existing configuration backup prior to opening the dialog.
  • Select property from configuration file, specify a display title, add to make available as reporting attribute.

Custom Device Attributes (maintained in AirControl):

  • Can be used to store small notes, location info or other memo
  • Behave like all other fields with respect to grouping, search, sort etc.
  • Set values in "Device Settings" dialog.

List of current attributes to change titles or define for which attributes the system should gather a history for.

Name: displays the attribute’s system name.
Display Name: allows specifying a customized attribute name.
Enable History: check to enable history gathering for the attribute.

Device Details

Device details view shows the details for the current selection in the device list. If a single device is selected, the details for that device are shown. If multiple devices are selected, a group summary is shown. If no selection was made in the device list the group summary for the current device group in the tree will be shown. Group summary shows aggregate run time statistics (attribute total or average, depending on whether the attribute reported from the device is an up-time aggregate or current value). Group summary shows the average of current statistics for selected devices. Use the statistics graph panel to view historic data.

For a single device view, product logo, device attributes and history are shown in separate panels. Use the separators between the panels to change the size or collapse the panel (single click on the middle part of the divider). For the middle and right hand panel, select what content you wish to see by clicking on the drop-down handle at the upper right panel corner (current statistics, graph, log events).

Current Statistics: Shows the latest statistics as reported by AirOS. The list is customizable. The attributes will refresh every 5-10 seconds when the device is online.

Recent Events Section: shows the recent events related with this device, like reboots, updates, etc.

Statistics Graph: View graph for metrics such as signal level, CCQ, throughput, latency etc for the currently selected device. Graph options (saved as user preferences):

Metric: select parameter to be displayed (3). This will only show attributes for which history has been enabled (see attribute configuration section). For interface statistics, TX/RX will be shown as series in the same graph automatically, as long as they have been configured for history collection. The same applies for Signal/Noise Floor.
Period: specify the time period to be displayed (minute, hour, day, week). For longer time trends use graphs with daily/weekly aggregation. See screen shot which shows minute and daily graph for same device at the same time.
Intervals: the number of data points displayed, determines the scale/range represented by the x-axis (30 intervals in daily graph will result in 30 days worth of data displayed etc.). The graph can only show as much data as the system stores. If the x-axis covers a time range larger then what the system is configured to store data for, portion of the graph will be "blank". See screen shot (2,3). There is currently no option to define the start time of the x-axis, you can only specify the number of intervals relative to the most recent entry.
Refresh: press this button to refresh the graph.
""Export"": save the data used to generate the graph as TSV file (can be used to import into spreadsheet application or for other offline analysis). One possible use case is to export the usage data for last X days for a group of devices for billing purposes etc.

Before using graphs, you need to enable historic data collections for the statistics you wish to see on the graph. As of release 1.3.3, this configuration is found in the "Attribute Configuration" dialog, reachable from the device list context menu (right click on device list or drop down handle in tool bar).

Singe Device Selection Toolbar/Menu Options

Launch Web GUI: this option allows launching the Web GUI page for the selected device. The page will open in a separate browser window or tab (depends on your browser settings) for each device. For managed devices with AirOS 5.x, AirControl will automatically authenticate. Please note that your browser needs to have connectivity to the device itself, AirControl only performs a redirect and no proxy function. You can change the HTTP(S) port setting for the device in the "Device Settings" menu (see below).

One-click Reboot: this toolbar button will perform an immediate full reboot of the selected device (without extra confirmation). Reboot for multiple devices (with scheduling) can be done through the device list operations menu.

Device Settings: Here you can edit some connection parameters, like changes in the IP Address associated by AirControl to a particular device.

Device Name: specifies a name for identification.
IP Address/Host Name: specifies the IP Address or Host Name of the Ubiquiti device connected to AirControl.
WLAN MAC: specifies the MAC address of the device’s Wireless Interface (the radio board MAC printed on the product package).
SSH Port: specifies the device’s SSH Port used for management ("Use Global Default" for port 22 or whatever is configured under system settings).
Protocol: specifies the protocol AirControl will use to launch the device web UI, it can be HTTP (default) or HTTPS.
HTTP(s) Port: specifies the port used by the HTTP(s) Protocol, by default is port 80 (HTTP).

Speed Test: Launch iperf speed test between AirControl server and discovered devices or any 2 hosts with SSH service and iperf capability. See details below.

Configuration Backup: Shows the device´s available config file backup. Press the "download" button to download the selected file to your computer. Or press "Restore" button in order to restore the selected backup into the corresponding device.

Speed Test

This feature allows performing an iperf speed test between AirOS 5.x devices or with the AirControl Server (using iperf third-party tool), without having to log into multiple devices. This is particularly useful for testing multiple units in sequence. The interface is designed to launch the iperf client and optional server on local or remote hosts (via SSH). A typical usage scenario would be to launch the server on the AirControl host and the client on AirOS 5.x, or on a host connected to the wireless device for 3.x firmware.

AirControl does not implement the speed test, it only launches iperf and redirects its output to the UI. Therefore, client/server communication and interpretation of console output and test results are specific to iperf and can be reproduced by running iperf manually when in doubt.

Note: AirControl does not contain or install iperf. This needs to be already installed on both hosts that the test runs for. AirOS 5.x includes iperf, older AirOS versions don't. Distributions are available for Linux (often already installed), Windows, etc.

Note: This feature is not available for devices running AirOS 3.x (firmware does not contain iperf).

Server Host: specifies the Server’s IP Address. If the address is not valid/reachable, an “INVALID CLIENT CONNECTION” message will appear.
Server Port: specifies the Port used for the Speed Test, default is port no. 5001.
Duration (seconds): specifies the total time during which the test will be executed.
Parallel Threads: indicates the number of Threads used in the test. It’s recommended to use a value higher than 3 to take advantage of the Aggregation feature of 802.11n.

Launch Client/Server: defines the device mode, where one must be the Server and the other the Client, e.g. you can use AirControl (Local Process, using a third-party Iperf client) as the Server and a CPE as the Client.

Local Process: this option uses a third-party Iperf app located in the computer running AirControl. You need to specify the patch of the iperf.exe file (Executable Patch), otherwise no test will be performed.
SSH: this option uses a remote host through SSH, for example an AirOS 5.x device.
Host: specifies the client’s IP Address.
User: specifies the client’s Admin Username.
SSH Port: specifies the client’s SSH Port; default is port no. 22.
Authenticate with: defines which method used to authenticate the connection. It may be the Admin Username password (‘’Password’’) or the ‘’Server Key’’.
Switch Client/Server: by pressing this button client and host will switch their roles.
Start Test: press this button to start the Speed Test. Before pressing start, make sure that all the parameters are correct, especially if running local processes. You can easily get a Iperf.exe file by googling it.

Device Statistics Reporting

Statistics displayed by AirControl in the device list and detail panels can be changed/customized (user settings). Please use the column/attribute customization dialog to see/select available attributes. A few attributes are AirOS firmware version specific and may be available in more recent versions only.

AMC: (only for M series): This is an index that evaluates the AirMax Connection Quality. The level is based on a percentage value where 100% corresponds to a perfect link state.

AMQ: (only for M series): This is an index of maximum data rate the link is operating at. A Lower Capacity number indicates a unit that is bogging the system down.

Host Name: displays the host name of the selected Ubiquiti device.

IP Address: displays the IP address of the device selected.

MAC: displays the MAC address of the device selected.

Product: displays the product name (ex: NanoStation M5, PicoStation 2) of the device selected.

Last Contact: indicates the last connection between the selected device and AirControl.

ESSID: is the name of the wireless LAN 802.11 Service Set ID of the selected device.

Uptime: This is the running total of time the device has been running since last power up (reboot) or software upgrade. The time is expressed in days, hours, minutes and seconds.

wlanTxRate: displays the current 802.11 data transmission (TX) rate, in Mbps, of the last transmitted packet

wlanRxRate: displays the current 802.11 data reception (RX) rate, in Mbps, of the last received packet

wlanTxErrors: displays the number of errors on transmitted packets and forces them to be resent.

wlanRxErrors: displays the number of errors on received packets and forces them to be resent.

wlanTxLatency: transmit latency of the wireless link in milliseconds. This statistic is a byproduct of the traffic passed on the wireless layer, in contrast to ICMP ping, which measures layer 3 latency.

Signal: displays the received wireless signal level. The represented value coincides with the graphical bar. Use antenna alignment tool to adjust the device antenna to get better link with the wireless device. The antenna of the wireless client has to be adjusted to get the maximum signal strength. Signal Strength is measured in dBm (the Decibels referenced to 1 miliwatt). The conversion is defined as dBm=10log10(P/1mW). So, 0dBm would be 1mW and –72dBm would be .0000006mW. A signal strength of –80dBm or better (-50..-70) is recommended for stable links.

CCQ: This is an index of which evaluates the wireless Client Connection Quality. The level is based on a percentage value where 100% corresponds to a perfect link state.

Noise Floor: displays the current value of the noise level in dBm. Noise Floor is taken into account while evaluating the signal quality (Signal-to-Noise Ratio SNR, RSSI) while value mean depends on signal strength above the noise floor.

Firmware Build: displays the version of the AirOS firmware that is currently operating in this device.

Ping RTT: average ping round trip time in milliseconds (requires scheduled ping task, see Execute/Schedule Device Operations).

Firmware


AirControl simplifies firmware upgrade for multiple devices. In order to use the feature, you need to upload firmware images into the server. First, download the firmware image to your computer just as when upgrading individual units through AirOS. Then select the firmware file and upload it to the AirControl server. You are now ready to update units.

Select the devices to update in the device table and click the update link in the table toolbar. A dialog opens that shows the selected devices, grouped by target firmware version. If multiple versions are available, the highest version is selected in the drop-down by default. All devices that are part of one update group will be updated as a single batch.

Updates are executed in the background. To see current activity, select the "In-Progress" device group. All devices with pending operations are shown there. To see the detailed status for a particular device, select the device and see the progress indicator in the left hand panel, above the product logo. It shows completion percentage and detail about the current activity. This is the place to look when there is no progress and the update operation does not complete. Update history and results can be seen in the system log, once complete. If multiple units are updated in a single batch, the last entry will provide a summary.

Browse: activate this button to navigate to and select the new firmware file. The full path to the new firmware file location can be specified there.

Upload Firmware: This option transfers the firmware file to the AirControl system.

Remove selected Firmware: Select the firmware file to be deleted from AirControl system.

Schedule


Tasks can be scheduled for a specific time with repeat interval, for example, backup the device config file every 3 days, or upgrade customer device firmware at mid-night. On the devices page you can schedule some tasks, sub-divided in three main groups: a) Scheduling a Scan, b) Scheduling a Firmware Update and c) Scheduling a Device Operation. On the Schedule Management Page you can view, edit and/or delete some of these previously created tasks.

Filter Schedule: this section allows searching Scheduled tasks using filtering criteria: Task Name (Name), Schedule Type (All, Device Scan, Firmware Update), modified from/to. After defining the parameters, when pressing the ‘’Search button’’ a search will be performed. On the other hand, by pressing the ‘’Clear’’ button, all the previously defined search parameters will be reset.

Name: displays the task name, used for task identification.

Start Date: displays the date when the scheduled task was started.

End Date: displays the date when the scheduled task will end. In case no date is specified (= field remains blank) the task will be performed indefinitely.

Interval and Period: displays the performance periodicity of the task scheduled.

Process Count: displays the number of times the task has been performed.

Status: displays the current status of the task, for example: Success or Pending

Last Modified: displays last time the task was performed or modified.

Edit/View: by pressing this button you can modify the tasks scheduling parameters.

Delete: by pressing this button the scheduled task will be removed.

Note: Be careful not to press this button accidentally, since once it is pressed the task will be immediately deleted without prompting.

Admin

User Management

This page allows creating or editing user accounts. You can assign different privileges to different users, by cataloging them into groups (Admin, Manager or Read-Only).

The latest AirControl version includes a password recovery feature. In case you’ve lost your password, and configured the following parameters: user’s email address and MAIL settings (in System Settings section), you will be able to easily recover your lost password.

Note: By default, the “default admin” account doesn’t have any email address specified. Thus, you need to specify an email address for it by pressing the account name once and then pressing the Edit Use button.

User Name: shows the login username of the user account.

User ID: shows the ID of this particular user account.

Email-ID: shows the email address of this user account.

Group: shows the group the user is a member of.

Active: indicates the status of the user account. If the status is True, the account is activated. If it is False, it means that the account is disabled and the user will not be able to login into AirControl using these credentials.

Add User

Add new users through this section. It is recommended to create a separate account for everyone using the system, since this way you may assign different privileges to different users.

Login (User Id): specifies the login username of the user account.

Username: specifies the name, so that you may identify this particular user account.

Password: password used for user authentication should be specified.

Re-type password: password should be re-entered to verify its accuracy.

Group: You must catalog each user account in three different kinds of accounts, since this assigns different privileges.

Admin: This user group has all privileges, like accessing to the Admin section, upload or delete firmware and edit Scheduled tasks.
Manager: This user group has limited privileges; they can connect devices to the system, upgrade device firmware, access all the functions of the Device page, and also view the System Log. However, they cannot access the Admin, Firmware and Schedule sections.
Read-only: This user group has limited privileges and can view only the devices and System Log, but cannot connect devices to the system, upgrade device firmware, nor access all Device page functions. They have no privileges to access the Admin, Firmware and Schedule sections.

Email ID: specifies the user account’s email address. You must have defined an email address in order to be able to recover the user password.

Edit User: This section offers basically the same parameters as the Add User section. Here you can modify user details, except the LOGIN (User ID).

Deactivate User: press this button to disable the user account specified. Once deactivation has been performed, Status will appear as “False”.

Reactivate User: press this button to re-enable a disabled user account. Once activation has been performed the user’s Status will appear as “True”.

Click "Save" button to register the new user account or "Cancel" button to discard the changes.

System Settings

Enforce Login through HTTPS: If checked AirControl will use secure HTTPS mode. HTTPS mode is unchecked by default.

Enable Device Discovery Background Scan: If checked AirControl automatically scan the local sub-net for new devices to manage.

Purge Log Threshold (days): specifies the maximum of days log entries will be stored in the system before being deleted.

Device Heartbeat Interval Seconds: time interval between statistics reports sent via HTTP from device to AirControl (in seconds).

Device Heartbeat Timeout Seconds: specifies max time (in seconds) elapsed since the last received device-to-AirControl report before timeout.

Device Web GUI: Use secure connection (HTTPS): specifies that the Web GUI link in AirControl should use HTTPS rather than HTTP. Check this when Web GUI on all devices was set to HTTPS.

Device Web GUI: Default HTTP(S) Port: Devices' HTTP or HTTPS port setting.

AirControl Server Address: enter the IP address of your network the AirControl server resides in (DNS name is not supported currently). Fill in this field only if devices are to use an external address/port to communicate with the AirControl server. This is mandatory when AirControl server is not directly reachable from the device (like behind NAT).

AirControl Server Port: states the HTTP port AirControl uses. By default the port is 9080, unless you’ve changed this during AirControl setup.

Mail Server Name: specifies the SMTP server to be used by the system. Note: valid SMTP settings are required for password recovery to work. You can test the SMTP settings by doing a "false" password recovery from the login screen.

Mail Username: specifies the SMTP username. It usually appears in the format username@youremailprovider.com, but that depends on your mail service provider.

Mail Password: specifies the SMTP password.


Click Save button to save the changes made in System Settings.

Device Management Rules

Configure how AirControl should manage devices for specific device groups. This also allows to override some of the system wide settings. Each entry will be associated to a previously created device group to identify the devices that you wish the rule to apply to. Assign meaningful names to rules that will allow to easily identify them and keep rules to a minimum. The order of rules matter, they will be evaluated in the order defined (a control to reorder them will be added). There is the option to edit the configuration source directly, which will of course also let you reorder rules.

Status Change Triggers

Define actions that are triggered unattended on device status changes, for example:

  • Upgrade CPE device when it comes online
  • Auto connect newly discovered devices
  • Send email when specified device(s) go offline

Affected devices are specified as device group. Use dynamic groups to limit the action to IP address pattern, SSID, host name, wireless mode (CPE vs. backhaul/base station) etc.

Supported Actions:

  • email: send email notification when the specified trigger occurs, with configurable recipient (multiple addresses comma separated) and subject line.
  • connect/manage: automatically provision a device. Note the security implication of having to store the device login in AirControl, which is not the case for manual connect.
  • upgrade to a specific firmware version

Support for actions will be expanded in the future to include configuration restore, configuration change etc.

Example: Offline email notification

Note that for this to work, you must have configured SMTP connection under system settings. (You can use the password recovery mechanism on the login screen to verify your email settings.)

  • Define a dynamic group that identifies the devices for which you wish to receive notification (usually only for those that are critical and require immediate attention, not CPEs etc.). In this case we define a group that selects all units in 'ap' mode.
  • The trigger should be status transition from 'MANAGED' to 'ERROR'.
  • The action is email, with a subject line of your choice.

Currently there is no configuration option for the message body and the subject will have the device identification appended.

Example: Auto-upgrade

When rolling out upgrades to CPEs, usually some of the units will be offline. Instead of having to catch them later online to get the update out, define a group based on current firmware and let AirControl trigger the upgrade when the status changes from offline back to online.

Whenever a device with version 3.5 or 3.5.1 (dynamic group criteria) comes back online, upgrade will be triggered. The firmware selection will show you the images that were uploaded through the firmware tab. Ensure through the group criteria that matching devices are compatible with the firmware image specified. Unlike interactive upgrade through the UI, AirControl cannot limit the firmware selection to specific devices at the time of rule definition. Similar to auto-manage you could upgrade non-managed devices when they are discovered (delete the non-managed devices from AC, let scan find them as they are online and trigger the upgrade). Login and password are only necessary for non-managed devices and left blank here.

Management Connection Settings

This rule defines how AirControl establishes management connections to devices. It can be used to override system wide settings for specific groups of devices. Parameters:

  • AirControl Address[:Port]: The HTTP port of the AirControl server that devices report to. Depending on your topology some devices may require a different "heart beat" reporting address, this setting can be used to define the exception.
  • SSH reconnect attempts (disable): Check to turn off automatic connect retries by AirControl to restore reporting. Use this when all devices are on latest firmware as they will contact AirControl when online and especially in situations where radios are on dynamic IP and/or expected to be offline at certain times (CPEs) as retries by AirControl won't succeed in restoring reporting anyways.
  • Tunnel SSH: For management of devices in "remote" (non-routed) networks where individual devices cannot be reached directly (NAT). The server typically needs to be on a public IP (or have external public IP forwarded to it) so that the devices can reach it.
    • address: Tunnel entry point into the remote network for SSH. Any host that is in the remote private network and has a public address or address reachable from AirControl. It needs to have SSH service that supports key based authentication and SSH port forwarding. You should be able to SSH into that port from your AirControl machine.
    • user: The login to establish SSH connection to above address. SSH authentication will require the AirControl public key in authorized_keys. You can extract the public key from any already managed device from ~mcuser/.ssh/authorized_keys. If you are using an AirOS device as SSH gateway, connect it first in AirControl through the public IP, then enter that public IP as "address" and “mcuser” as "user" in the tunnel definition. No need to manually setup the SSH public key in this case.
SSH Tunneling

Scan through Tunnel: Once tunneling is configured, you can scan for devices through that gateway. In the “Scan” dialog, you will find an additional drop-down to select the tunnel.

System Log

Every log entry contains a Type, Date, Device name, IP address, MAC address, and a Message. Usually, errors, warnings or informational system service messages are reported. However, more detailed Debug level messages can be reported also.

TSV Export toolbar icon: Allows downloading the current system log view. The export file format is TSV, which can be loaded into Excel etc. for further processing.

The columns in this view can be customized through the toolbar icon.

Log can be searched through the expandable filter section. For example, this can be used to search for specific error messages, task names, event log categories etc. The log can be sorted by clicking the column headers.

System resources for a fully searchable and sortable log are limited. By default, logs are purged after 10 days (configurable under "System Settings"). If due to problems in your network the system generates many connection and device status related errors, you may want to reduce the retention threshold for better performance.

My Settings

Change your password

Login: specifies the login username of the user account.

Username: specifies the name, so that you may identify this particular user account.

Old password: enter the current password associated with this username. It is required for Password or Administrator Username change routine.

New password: new password used for user authentication should be specified.

Confirm new password: new password should be re-entered to verify its accuracy.

Click Change button to save made in this area.

Preferences

Enable Device Group Summary: this option allows displaying summaries about each devices group defined on the Devices page.

Device Table Refresh Delay (secs): specifies the periodicity of Device Table refreshments.

Click Save button to save the changes made in User Preferences.

About


Current Version: displays the current version of AirControl installed on the system.

Check for Updates: by pressing this button, the system will search for AirControl updates.

Note: in order to check for updates, the system must be connected to the Internet.