This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

Wireless Networks

NetXMS models a managed wireless network as a wireless domain object. The access points of the network are child objects of the domain. The domain gets its access point list from one of two sources:

  • Wireless controller nodes — nodes in the domain that a network device driver identifies as wireless controllers.

  • A wireless controller bridge — the wlcbridge server module reads the controller’s HTTP API (see Wireless Controller Bridges). No controller node and no SNMP access to the controller are necessary.

Wireless Domains

To create a wireless domain, right-click Infrastructure Services, a container, or a collector and select Create > Wireless domain. A wireless domain can contain access points and nodes.

The wireless domain has its own configuration and status polls:

  • The configuration poll reads the access point list and creates an access point object for each new access point. Access points are matched by MAC address, or by name when the reported MAC address is not valid. For each new access point and each access point that is up, the poll updates the radio interfaces, vendor, model, and serial number.

  • The status poll reads the state of each access point that is not unmanaged.

When the controller no longer reports an access point, the access point goes to the down state and a grace period starts. The access point object is deleted when the grace period exceeds the Objects.AccessPoints.RetentionTime server configuration variable (hours, default 72). When the variable is 0, the object is deleted immediately.

To start a poll manually, right-click the wireless domain and select Poll > Configuration or Poll > Status.

Wireless Controller Nodes

A node gets the Wireless Controller capability during its configuration poll when its network device driver reports that the device is a wireless controller (see Network Device Drivers Reference).

To add a controller node to a wireless domain, right-click the domain and select Add controller node…​. A node can belong to only one wireless domain. To remove it, select Remove controller node…​.

Without a bridge, the configuration poll of the domain reads the access point list from each controller node in the domain. The status poll reads the state of each access point through SNMP from its controller. When the controller cannot report the state of an access point that has an IP address, the server pings the access point.

Wireless Controller Bridges

A wireless controller bridge gets access point data from a controller’s HTTP API instead of from a controller node. The Ruckus bridge is an exception: it reads the data from a separate helper service. The bridges are in the wlcbridge server module.

The wlcbridge custom attribute on the wireless domain selects the bridge. Do not set it on a node. The value is not case-sensitive:

wlcbridge value Controller

UniFi

Ubiquiti UniFi Network Application, on a UniFi OS console or server, or the standalone application (see UniFi)

HFCL

HFCL wireless controller (see HFCL)

Aruba or Aruba-Instant

Aruba Instant virtual controller (see Aruba Instant)

Ruckus

Ruckus controller, through an external helper service (see Ruckus)

When the wlcbridge attribute has a value:

  • The configuration poll of the domain gets the access point list only from the bridge. Controller nodes in the domain are not used for the access point list.

  • The status poll gets the state of each access point from the bridge. When the bridge cannot report the state, the server does not ping the access point.

  • The list of wireless stations of an access point comes from the bridge. The station list of the domain contains the stations from the bridge and from the controller nodes in the domain, if any.

The bridge reads all other settings from custom attributes on the same wireless domain. The bridge does not verify TLS certificates or host names, so a controller with a self-signed certificate works. The HTTP request timeout is 180 seconds.

Credentials and Sessions

The unifi.password, hfcl.password, and aruba.password attributes accept a plain text password or a password obfuscated with nxencpasswd. The obfuscation uses the login name as the key. Use the same login name that you set in unifi.login, hfcl.login, or aruba.login:

nxencpasswd <login> <password>

After a login, the bridge keeps the session in a script-only custom attribute on the wireless domain: $unifi.cookie, $hfcl.token, or $aruba.sid. When the controller rejects the session, the UniFi and HFCL bridges log in again within the same request. The Aruba bridge clears its session ID and logs in on the next request.

Setting Up a Bridge

  1. Add the module to the server configuration file netxmsd.conf and restart the server:

    Module = wlcbridge
  2. Create a wireless domain (see Wireless Domains).

  3. Open the properties of the wireless domain and go to the Custom Attributes page.

  4. Add the wlcbridge attribute with the bridge name, and the attributes that the bridge needs (see Bridge Attributes Reference).

  5. Right-click the wireless domain and select Poll > Configuration. The poll output shows Reading access point list via bridge interface <name> and the number of access points reported.

Table 1. Example: UniFi OS console with an API key
Custom attribute Value

wlcbridge

UniFi

unifi.base-url

https://192.0.2.10

unifi.token

API key generated on the UniFi controller

unifi.site

default (optional, this is the default value)

Do not set unifi.isAppliance for a UniFi OS console (see UniFi).

Bridge Attributes Reference

All attributes are custom attributes of the wireless domain.

UniFi

Attribute Description

unifi.base-url

Required. Base URL of the controller. When the URL has no scheme, https:// is added. Trailing slashes are removed.

unifi.token

API key. The bridge sends it in the X-API-KEY HTTP header. When this attribute is set, unifi.login and unifi.password are not used.

unifi.login

Login name, used when unifi.token is not set.

unifi.password

Password, plain text or obfuscated with nxencpasswd.

unifi.site

Site name in the API paths. Default: default.

unifi.isAppliance

Selects the login and API paths, see below. 1, true, yes, and on (not case-sensitive) mean true. Any other value, or no attribute, means false.

The name unifi.isAppliance is the opposite of what it does. Set it to true only for the standalone UniFi Network Application, which is installed without UniFi OS. For UniFi OS consoles and UniFi OS Server, do not set it:

unifi.isAppliance Controller Login request (when no API key) API requests

Not set or false

UniFi Network Application on UniFi OS

POST <base-url>/api/auth/login

<base-url>/proxy/network/api/s/<site>/…​

true

Standalone UniFi Network Application

POST <base-url>/api/login

<base-url>/api/s/<site>/…​

The bridge reads devices from stat/device and wireless clients from stat/sta. Only devices of type uap (access points) become access point objects. Wired clients are not included in the station list.

HFCL

Attribute Description

hfcl.base-url

Required. Base URL of the controller, with the scheme (for example https://192.0.2.20). The bridge uses the value as is and sends requests to <base-url>/api/…​.

hfcl.login

Login name.

hfcl.password

Password, plain text or obfuscated with nxencpasswd.

The HFCL bridge supports the WLCBridge() internal metric (see Access Point Metrics from a Bridge).

Aruba Instant

Attribute Description

aruba.base-url

Required. Base URL of the virtual controller REST API. When the URL has no scheme, https:// is added. Trailing slashes are removed.

aruba.login

Required. Login name.

aruba.password

Required. Password, plain text or obfuscated with nxencpasswd.

aruba.iap-ip

IP address of the Instant access point, sent as the iap_ip_addr parameter of the show commands. Default: the host part of aruba.base-url.

The bridge logs in through /rest/login and runs the show summary, show aps, and show clients commands through /rest/show-cmd.

Ruckus

The Ruckus bridge has no attributes. It reads access point and client data from a helper service at http://127.0.0.1:5000 on the NetXMS server host. This helper service is not part of NetXMS. Without it, the Ruckus bridge does not report access points. Because the address is fixed, all wireless domains that use the Ruckus bridge get data from the same helper service.

The Ruckus bridge supports the WLCBridge() internal metric (see Access Point Metrics from a Bridge).

Access Point Metrics from a Bridge

A DCI on an access point with origin Internal can read a value from the data that the bridge has for the access point. Use the metric WLCBridge(<path>), where <path> is the path to the value in the access point’s JSON document, with elements separated by /. String and number values are returned as is, Boolean values as true or false.

Only the HFCL and Ruckus bridges support this metric. The bridges keep the access point document for a short time (HFCL: 30 seconds, Ruckus: 10 seconds), so several DCIs on the same access point use one request. For the UniFi and Aruba bridges, the metric is not supported.

Troubleshooting

  • Cannot find wireless controller bridge interface "<name>" in the poll output means that the wlcbridge module is not loaded or the wlcbridge attribute value is not a bridge name.

  • Cannot retrieve access point list means that the bridge could not get data from the controller. Turn on the bridge debug tags to see the reason.

Each bridge logs with its own debug tag: wlcbridge.unifi, wlcbridge.hfcl, wlcbridge.aruba, or wlcbridge.ruckus. To see all of them, use wlcbridge.*:

DebugTags = wlcbridge.*:7

At level 7, the bridges log the request URLs and the HTTP response codes. The polls of the wireless domain log with the poll.conf and poll.status tags at levels 5 and 6. See Enabling Debug Logging.

At debug level 9, the UniFi and HFCL bridges write the login request, including the password in plain text, to the server log.