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.

Theory

The rXg expects the operator to deploy its custom build of OWGW as a VM. This is what is in the example templates. From there, the OWGW is used as a reverse proxy that translates JSON HTTPS API commands from the rXg to the APs. The OWGW runs a set of microservices in docker containers and it expects to use many ports for those services to communicate with each other and the outside world.

APs

• OpenWiFi Access Points will not accept private IPs in DNS
• OpenWiFi Access Points must be scanned and approved from the rXg to be onboarded

CLI

• Factory Reset: 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. When it succeeds, 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 must be present for the AP to know how to find its controller. EG: {"server":"openwifi.wlan.local","port":15002}

• /usr/share/ucentral/ -- .uc files for commands eg wifiscan

• /etc/hosts -- DNS rebinding for NAT'd OWGWs.

DNS

• By default, the APs fail to resolve private addresses for FQDNs. Therefore we have to rebind their DNS in /etc/hosts
• The OWGW reconfigures its own DNS server to be its gatway because otherwise ubuntu behaves strangely.

OWGW

• Everything 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.
• 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 WLAN 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

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.)

Topology

• It is not required for the APs to be in the same L2 domain as the OWGW.

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.

Discovery

• In both casees, the Device Firmware must still have vX.Y.Z in the name and X.Y.Z must be of higher version number than what is on the AP currently.

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

Virtualization

• 8 Cores / 8 GB / 40 GB HD min req for OWGW guest VM
• RG Nets' build of OWGW that is used by the template expects to deploy itself as a guest VM of the rXg that will command and control it

How to ...

Setup an OWGW Deployment on rXg

Overview

The following steps will guide you through building the OpenWiFi Controller SDK as a virtual machine within the rXg application.

Environment

OWGW Ecosystem: 3.2 or later rXg: Current Official

Architecture

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. It expects this rXg to be its layer 3 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.

Network Topology

Prerequisites

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 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
  

Configuration

1. Setup Virtualization Hosts

To install the OpenWiFi controller in Bhyve first we must ensure we have a Virtualization Host to install to. Navigate to Services::Virtualization, if a host does not exist create a new Virtualization Host.

Give the Virtualization Host a name, the name field is an arbitrary string used to identify the host here I've set the name as the FQDN. Autostart Delay, and Reserved CPU count will be left at default values. Next name the Virtual Switches to make it easier to identify. Here I name my WAN and LAN connections, we will only need the LAN connection for our OpenWiFi controller. Click Create.

2. Install OpenWiFi Controller as a Virtual Machine

We will use a built in Config Template to automatically download the OpenWiFi controller software. Navigate to System::Backup and find the Config Template named "Example: 06 Download rXg Openwifi Image Config". If you do not see any example config templates click the "Show Examples" link.

We do not need to modify this template, it is going to download the openwifi img file and make it available as a disk image. Click apply to have it download the image.

After clicking apply we should get a Success message.

We can verify that the image was downloaded by navigating to Services::Virtualization and clicking Disk Images on the record for our Virtualization host.

Now that we have confirmed that the image has been downloaded we are ready to create the Virtual Machine. We will utilize another config template to automatically deploy the VM. Navigate to System::Backup, and find the config template named "Example: 07 Deploy Virtual Openwifi Controller Config". Do not click apply, instead click Edit. We will need to modify the template to match our networking.

Adjust the name variable if desired, I will leave the name as "openwifi". Next I am looking for the line with "mapped_switches". I am going to change this line from: "mapped_switches = ["igb0", "igb1", "igb2"]" to; "mapped_switches = ["vmx4 LAN"]

This is NOT the name of the interface but rather the name of the virual switch, I named mine "vmx4 LAN" so I need to make sure that matches. To verify the name navigate to Services::Virtualization and look at the Virtual Switches scaffold and find the name of the switch the OpenWiFi controller will be connected to.

You may also need to adust the IP address asigned to the controller. Look for the cidr, gateway, and nameservers variables, and adjust accordingly. This controller in this setup will be on the 192.168.5.x network.

I have adjusted the variables to match my network below.

Next we need to specify an SSH key pair. For this I will leverage the ssh key tied to my admin account. In the real world it is best to make a new ssh keypair for this so it is not tied to an individual. Now that I have adjusted the config template I can click the update button.

Now we are ready to apply the template. When we click apply this will create a new VM, connected to the interfaces we specified in the template (just vmx4 LAN in this case), we can see that the VM will have 8GB of memory, 8 cpu cores, and a 10GB HDD.

We can confirm that the new VM was created by navigating to Services::Virtualization and review the Virtual Machines scaffold.

In addtion to creating the VM, the template also created a DNS override for "openwifi.wlan.local" this can be used if we need to access the controller and need it to resolve to the IP address of the controller. To verify that the DNS override is setup correctly, navigate to Services::DNS and review the DNS Records scaffold.

What this entry does is overrides any DNS for "openwifi.wlan.local", so that if I am behind this system and point my browser to the FQDN it will resolve to 192.168.5.9 and allow me to access the controller.

Now we must start the installation process on the VM, navigate to Servcies::Virtualization. The openwifi Virtual Machine has a commands link to the righthand side, select start from the list. This will turn on the machine and begin the installation process.

VM state will change from stopped to Running. Note that installation takes about 2 minutes.

To verify that the controller is up and running click the VNC viewer option and open the console window. Note that we do not need to login or do anything via the console window it can be closed.

3. Add Local CA and OpenWiFi as a WLAN Controller Infrastucture Device

Now that we have installed the OpenWifi Controller we can add it as an infrastucture device.

3.1 Add Local CA

Our OpenWiFi Infrastructure device will require a Local CA. The rXg will be taking over as the the Certificate Authority of the OW devices so that they can be onboarded efficiently. The CA can be created in System >> Certificates and you only need to create one. When you create your OWGW's WLAN Controller, you must associate it to this Local CA.

Navigate to Network::Wireless and create a new WLAN Controller.

3.2 Add WLAN Controller

Give the controller a name, change the Type field to OpenWifi. Enter the controllers IP address in the Host field. Leave the default Username [email protected], and enter a password of your choosing in the Password field. The password will be updated automatically in the OpenWifi controller. Click Create at the bottom of the record.

After creating the WLAN Controller record it will takea few seconds and then the Online field should change from offline to Online.

Next select Import on the far right of the WLAN Controller entry, and click on Import. Enter the CIDR of the network(s) the controller should look at for APs.

When the AP is detected in the scan, the rXg will SSH into it. From there the rXg will modify files on the AP as necessary to bring it under the command and control of the rXg. This comes down to a few things:

• DNS Rebinding: This is necessary because rXg deployments often run the OWGW on a NAT'd IP.
• Certificates: The rXg will run commands on the AP to generate and send a CSR to the rXg for signing. The operator must then click "Approve" on the AP in the Access Points scaffold in order to have the rXg sign the certificate and send it to the AP.

Key Files: DNS Rebinding:

• /etc/hosts

Key Files:

Notes

(These should no longer apply because we are generating the certs for the OWGW and the Devices)

If you click on the Generate Diff button and nothing seems to happen this is likely because the AP's are not configured correctly. In the above example I had to login to the tip portal and do an AP transfer. To do this I logged into the portal, and clicked on the Transfers option on the left menu.

Click the Create Transfer Button.

Enter the MAC address in the Serial Number field, the Redirector should be set to openwifi.wlan.local, and then enter a reason for the request. Then click Start Transfer. After completing this process I was then able to generate the diff and click enable sync after factory resetting the AP.

Firmware Updates

The rXg should automatically detect and download new firmwares without operator intervention. If the operator wishes to deploy a new firmware, they can navigate to Wireless >> Access Point Profiles. From there, they can configure Firmware Profiles. A Firmware Profile will have its firmware_compatibility overwritten by the firmware_ware compatibilty of its device firmware when it saves. The operator should configure one firmware profile per device type on their network. When that is configured, the rXg will try to upgrade the AP during its periodic check.

Additionally, the operator can set a higher priority Firmware<>Access Point association on the device firmware as well. The operator must avoid making associations across firmware compatibilities. This can be used to test a new firmware on a singular access point.