OpenWiFi
Bhyve Setup
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 accordingling. 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 is because in a later step we will need to hit that URL 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. This is important without this we will not be able to login to the controller as we will see in a future step.
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. Create new user on controller
Now that the controller is installed we need to login using the default credentials and create a new user and remove the default user (if desired). To do this navigate to https://openwifi.wlan.local:8443 and login with the default username password.
Username: [email protected] Password: openwifi
At this point if you login and get an invalid credentials message, even though you are using the correct username/password. This is because its trying to hit a different port and will get stopped by the certificate since it is not valid. You can direct your browser to the following URL https://openwifi.wlan.local:16001/api/v1/oauth2?requirements=true and accept the certificate and then login again.
When you login for the first time it will prompt you to change the password.
After changing the password you will be logged in. We will want to create a new user, to do this select users from the menu on the left.
Next click the "+" sign in the upper right corner.
Fill out the email, name fields, and set a password. Toggle force Password Change off otherwise you will be prompted to change the password you just set again upon first logging in. Toggle Email Validation off. Then click the disk icon in the upper right.
Next logout and log back in with new user and delete the default user.
3. Add OpenWiFi as infrastucture Device
Now that we have installed the OpenWifi Controller and we have created a user we can add it as an infrastucture device. Navigate to Network::Wireless and create a new WLAN Controller.
Give the controller a name, change the Type field to OpenWifi. Enter the controllers IP address in the Host field. Change the username field from admin to the email address of the user created in the previous step and enter the password in the password field below. Change the Timeout field from 5 to to 30. 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.
Next click on "Sync not enabled".
Click on Generate Diff.
After clicking Generate Diff any changes will show up in the Synchonize field. The first time you join the AP it will have more than what we see here, regardless, the next step is to click Enable Config Synchonization.
After this step the Openwifi controller should be online and in sync.
Notes
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.
