OpenWiFi

Deploy OpenWiFi Controller SDK as VM on rXg (5/29/2024)

Overview

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

Environment

This document was written and tested using the following components from the RG Nets and OpenWifi ecosystem.

Architecture

In this lab example, we will be using a virtual Ubuntu instance on a bare metal rXg node. The OpenWiFi controller SDK is deployed as a set of docker containers inside the Ubuntu VM.

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
  
• 4 CPU Cores
  
• 80 GB of storage
  

Configuration

Deploy Ubuntu Virtual Machine

1. Browse to Services >> Virtualization >> Virtualization Hosts
   1. If a host record does not already exist, click "Create New", otherwise you can skip this step.
   2. Provide a name for the host record. All other values can be left default.
   3. Click "Create".
2. Now that the host record has been created, we need to add the ubuntu disk image. This can either be uploaded from your local machine, or you can provide a link for the rXg to download it directly. In this lab example we will have the rXg download the .img file directly from the ubuntu website.
   1. On the Virtualization Hosts scaffold, click the "Disk Images" link.
   2. Click "Create New"
   3. Either select "Choose File" and upload the disk image, or paste the URL for the rXg to directly download. https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
   4. Click "Create"
      
   5. Once the download is complete, the status will change from "Pending" to "Exists."
3. With the disk image loaded, we can deploy the Ububntu VM using cloud-init.
   1. Browse to Services >> Virtualization >> Virtual Machines.
   2. Click "Create New"
   3. Update the fields as indicated below and click "Create."
      Name: Select a name that represents what the VM will be used for.
      Bootloader: For OpenWiFi this should be set to "Uefi-csm"
      Memory: 8
      Cores: 4
      Virtual Interface Name: Name this interface.
      Virtual Switch: Based on our network topology for this lab, I am going to select my LAN switch bge3.
      Virtual Disk Name: This can be left blank and a name will automatically assigned.
      Virtual Disk Image: Select the uploaded Ubuntu image.
      Virtual Disk Size(GB): 80
      Cloud Init: This section of the configuration will preconfigure the ubuntu machine with the specifed IP address, gateway, DNS server, hostname, and public SSH key.
4. The final step will be to start the VM.
   1. Select "Start" from the "Commands" link on the VM record within the Virtual Machines scaffold.
      

SSH Access

You can access the Ubuntu machine via SSH after the VM shows a state of "Running." You will need to use the key pair specified in the cloud-init configuration from the previous step. ssh [email protected]

DNS Record for OpenWiFi Controller

The OpenWiFi access points must have a certificate installed that allows them to talk to the OpenWiFi controller. For this to work, the OpenWiFi controller must be accessible via the FQDN specified in the certificate.

In our lab environment we will use "openwifi.wlan.local" as the dns record for the OpenWiFi controller. This DNS entry will be pointed to the ubuntu machine previously created. It is important that both the access point and the client device used for administration are able to resolve this DNS entry.

1. In the rXg browse to Services >> DNS >> DNS Record (Create New)
2. Fill out the form as indicated below. Use the IP address that you configured in the previous step.
3. Click "Create"
   
   Name: Select a name that represents the purpose of the DNS entry.
   Type: A
   Host: Domain to be resolved.
   Dynamic Data: Empty
   Data: IP that the domain will resolve to.
   

Install OpenWiFi SDK on Ubuntu VM

1. SSH to the Ubuntu VM
2. Install Docker sudo apt update sudo apt install docker-compose
3. Clone the OpenWiFi Controller SDK git clone https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy
4. Start the OpenWiFi Controller SDK cd wlan-cloud-ucentral-deploy cd docker-compose sudo docker-compose up -d Note: Download time will vary based on the quality of your internet connection.

OpenWiFi SDK Initial Config

There are two main methods for accessing the GUI:

1. The Provisioning GUI is available on port 8443 and provides a high-level overview of the deployment. From this portal you will be able to organize your deployment into venues, entities, and offices with each having associated policies.
   https://openwifi.wlan.local:8443
   
   

2. The Controller GUI is available on port 443 and provides granular control over each device that is being managed as well as access to AP firmware among other things.
   https://openwifi.wlan.local:443
   
   Note: At this point of the installation process, there are no certificates installed. You can bypass those warnings.

3. Using https://openwifi.wlan.local:8443 log in to the provisioning portal using the default credentials.
   Email: [email protected] Password: openwifi
   

4. You will be prompted to set a new password upon first login.

Note: If you are getting invalid credentials, ensure that you have used the DNS entry and not the IP address to access the portal.

EdgeCore EAP 101

Prerequisites

1. Certificate

To create the certificate you will need the AP serial number, MAC Address, and the exact DNS entry created in the previous steps.

Example:

Serial Number: EC2117003345
MAC Address: 903CB32D370B
DNS Entry: openwifi.wlan.local

1. Browse to https://portal.keys.tip.build/
2. Log in using your credentials.
3. Select "Certificates" from the menu on the left.
   
   
4. Click the "+" on the upper right hand side.
   
   
5. Fill in the relevant details and click save.
   
   
6. Download the certificate.
   
   
7. The downloaded certificate should replace the certificate on the AP located in the /certificates/ folder. The only method I have found to get the certificate to the AP is to load it on a web server and use wget from the AP.
8. Once you have downloaded the certificate in the .tar.gz format, you can use the following command to unzip the files. tar -xvzf 903CB32D370B.tar.gz <-- This is an example for my lab environment. Your file name will be different.
9. Once the files are unzipped, you can remove the original tar.gz file leaving just the contents.
   
   
10. reboot

Configuration

1. SSH to the AP using the credentials root/openwifi.
2. Using your favorite text editor, adjust the 'option server' in the following two files to be openwifi.wlan.local. I have used VIM in the example below:
   vim /etc/config/ucentral
vim /etc/config-shadow/ucentral
   
   
3. Reboot
4. Adjust /etc/hosts to include a line that resolves openwifi.wlan.local to 192.168.5.23 in the case of this lab example. Your IP will most likely be different.
   

Note: To verify if the AP receives response from the controller you can run the following command from the AP CLI: logread | grep ucentral. Look for the line connection established