OpenWiFi Gateway (OWGW)

This document tries to give the operator as good of a entry into the world of OpenWiFi as possible. For some, that will mean going directly to the How To section and setting up their deployment right away, and then reading theory section later. For others, reading the theory section first might be better.

As with other Wi-Fi ecosystems, the rXg provides high-level command and control interface for embedding operator intent into a network via database configuration.

The rXg enables the configuration of many types of OpenWiFi WLANs, including Open, Pre-Shared Key (PSK), multiple Pre-Shared Key via Remote Authentication Dial In User Service (mPSK-RADIUS), hidden, 2.4/5/6 GHz band with any SSID combination, WiFi Protected Access 2/3 (WPA2/3, including transitional mode), tunneling via Generic Routing Encapsulation (GRE) and Opportunistic Wireless Encryption (OWE), while supporting firmware management from the level of rXg.

The rXg deploys a packaged version of the OpenWiFi Gateway (OWGW) software in order to perform command and control actions on devices. RG Nets packages the OWGW software in a Linux VM image that is available to download and instantiate on an rXg using configuration templates distributed with the rXg software.

The rXg provides 4 primary types of operations upon devices such as devices, namely: - Discovery/Adoption - Configuration Synchronization - Monitoring/Telemetry. - Firmware Management

Discovery / Adoption

The rXg automates the process of discovery and adoption of many types of devices, including WAPs. In the case of WAPs, this process is accomplished through the means made available by TIP, i.e., a combination of shell access (SSH) and TLS certificates. The rXg supplies an adoption mechanism which scans IP-reachable networks for OpenWiFi APs and starts the process of adopting them into the rXgs bundled OWGW instance.

The adoption process involves creating TLS certificates on both the OWGW and on WAPs. These TLS certificates are signed on the rXg and transmitted back to the OWGW and WAPs. This creates a web of mutual trust between WAPs, the OWGW, and the rXg.

Once the adoption process is completed, the WAP is able to open an mTLS websocket connection to the OWGW and it can then be managed by the OWGW. The OWGW in turn is managed by the rXg, providing a single pane of glass for different network functions and elements.

Configuration Synchronization

Once the WAP has been adopted by the OWGW, it can be configured by the rXg, through the rXgs vendor-neutral single pane of glass configuration interface. Most, if not all, of this process is mediated through data exchanged between the following elements: rXgOWGWdevice. The rXg uses a JSON API to communicate with the OWGW and the OWGW uses a websocket API to communicate with the WAP. RG Nets expects both of those to be made available from TIP.

The rXg continuously checks for any discrepancies between running configurations on WAPs and the configuration implied by operator choices local to the rXG. When discrepancies are detected, the rXg attempts to resolve such discrepancies by re-applying the implied local configuration until no discrepancies are detectable. This process is continuously employed as long as there is any local configuration on the rXg in relation to the WAPs.

Monitoring and Telemetry

The rXg uses effective measures to detect when devices go offline and alert network operations staff via any combination of the following supported measures: health notices, emails, webhooks, custom backend scripts, etc. Additionally, the affected devices are marked offline in the internal rXg database.

The bundled version of the OWGW that the rXg uses contains RG Nets-maintained modifications to enable telemetry access intended for its host rXg. This gives the rXg access to KAFKA bus telemetry data created by devices which then the rXg uses in order to enhance its monitoring capabilities.

Firmware Management

The rXg contains capabilities to upgrade devices to new firmware versions via acquiring them onto the rXg and then instructing a device to upgrade to a specific firmware via API transaction with the OWGW. Then the OWGW tells the device to download the firmware from the rXg and upgrade itself to that firmware.

Theory

The rXg expects the operator to deploy its custom build of OWGW as a VM following the configuration process available in this KB document.

The OpenWiFi Gateway controller SDK is deployed as a set of docker containers inside the Ubuntu VM. This Ubuntu VM is prebuilt by RG Nets and pre-loaded with with OWGW software from the community as well as additional functionality to make it discover its command and control rXg. The OpenWiFi VM expects the rXg to be its IP gateway.

The rXg comes pre-loaded with templates to make setting up the reference architecture for running this VM very easy. Config template number 6 makes downloading the rXg IMG very very easy and config template number 7 makes deploying the IMG into a real VM very easy, but does require some attention from the operator in terms of its configuration parameters, EG who can log into it and which rXg interface it should be L2 bridged with.

This deployment requires an rXg node that supports virtualization and has sufficient storage, compute and memory to run the virtual machine. You should also have an admin account with a public SSH key defined.

For a small-scale OpenWifi deployment (< 50 APs), we suggest at least:

• 8 GB of memory
  
• 8 CPU Cores
  
• 40 GB of storage

Additional details on specific elements of the OpenWiFi subsystem elements, exceeding the everyday configuration of the system, are listed below.

WAPs

• OpenWiFi WAPs will not accept private IPs in DNS
• OpenWiFi WAPs must be scanned and approved from the rXg to be onboarded (use the 'Import' function in the controller)

CLI

• Factory reset command: firstboot -yr
• Test Websocket AP<>OWGW TLS Connection: openssl s\_client -connect openwifi.wlan.local:15002 -cert /etc/ucentral/cert.pem -key /etc/ucentral/key.pem. If successful, you will see Post-Handshake New Session Ticket arrived: in the output. You should still make sure that /certificates/cas.pem is your rXg's root CA Cert, even when this succeeds.

Key Files / Directories

• /certificates - this location works in conjunction with /etc/ucentral to persist long term cert data
• /etc/ucentral/
• /etc/ucentral/gateway.json -- This file must be present for the WAP to know how to find its controller, e.g., {"server":"openwifi.wlan.local","port":15002}
• /usr/share/ucentral/ -- .uc files for commands e.g., wifiscan
• /etc/hosts -- DNS rebinding for NAT'd OWGWs.

rXg DNS

• By default, WAPs fail to resolve private addresses for FQDNs. Therefore we have to rebind their DNS in the WAP /etc/hosts file and adding private DNS records on the rXg, for example, for he default FQDN openwifi.wlan.local
• The OWGW reconfigures its own DNS server to be its gatway to overcome limitations of the Ubuntu image the OWGW is running on.

OWGW

• Every single function of the OpenWiFi controller on the accompanying VM build of OWGW is managed via systemctl <verb> docker-compose-openwifi
• The OWGWG attempts to use API endpoints on its gateway to discover its FQDN (the host of the WLAN Controller) and Local CA
• The OWGW can be linked to Infdev via Association for easy restart functionality

CLI

• sudo systemctl restart docker-compose-openwifi -- re-runs command and control server acquisition, and fixes DNS on OWGW, and restarts docker containers.

Key Files / Directories:

• /work_dir/wlan-cloud-ucentral-deploy/docker-compose
• /work_dir/wlan-cloud-ucentral-deploy/docker-compose/certs
• /usr/local/bin
• /etc/resolv.conf

PKI

• Make sure you have created a Local CA on your rXg. Make sure it is associated to your OpenWiFi WLAN Controller, per this KB document.
• Both the OWGW and the AP must get signed certs.
• Getting these signed certs is only implemented for the AP<>OWGW websocket traffic, but that is enough to operate the APs.
• This works without TIP PKI.

rXg

• If the OpenWiFi Controller is configured with an FQDN for host, the rXg wll tell it to try to use that FQDN. If the WLAN Controller is configured with an IP for host, the rXg will tell it to try to use openwifi.wlan.local. Either, way the controller will go through the same PKI process.
• The RG Nets Build of the OWGW will expose kafka on a port so that the rXg can connect to it and get telemetry information.
• If monitoring is enabled on the OWGW Wlan Controller, Kafka telemetry will not update or create wireless clients or access points, though it will create access point radios in all cases.

CLI

• tfltel to view the current telemetry traffix between the WAPs and rXg

SSH

• With cloudinit, the operator has the ability to add users, but only once, when the VM is first launched. We recommend creating a user for you to login to the OWGW with. (But it is optional.). The default user is created as per this KB document.

Topology

• It is not required for the APs to be in the same L2 domain as the OWGW. The KB document shows an example of WAPs and rXg operating on different L2 segments.

Firmware

• Which AP is compatible with which Firmware is tracked via a firmware_compatibility string on both access points and firmware. Ideally these should match, the rXg's UI expects them to match.

• When the firmware upgrade procedure is invoked on the rXg, the rXg generates a short term service URL, and sends that URL to the AP for the AP to download the firmware directly from the rXg.

• The firmware job also tries to detect APs that need dns/gateway rebinding, and automatically rebind them, including rebooting.

Firmware Installation Priority

• The sync firmware button on access point profiles will upgrade the firmware on the APs if and only if a firmware version can be detected on the AP(s), and on the target firmware(s), and the target version is higher.

• The upgrade firmware button on the AP in the Access Points Scaffold will always upgrade the AP to the target firmware, regardless of version.

• The AP's target firmware is visible in the AP Show view.

From TIP

• All OpenWiFi firmware from TIP comes from https://ucentral-ap-firmware.s3.amazonaws.com/
• First the OWGW indexes that s3 bucket continuously
• Then the rXg queries the OWGW for firmware relevant to device types it knows about from the access points
• Now that the rXg knows about the firmware, it downloads a local copy

Manual Firmware

• The operator should be able to create device firmware records manually via uploading a file or specifying a URI to download from
• In this case it is important for the operator to manually set the firmware compatibility to the correct value