OpenWiFi Getting Started Technical Details
January 29, 2025
## APs
OpenWiFi access points default credentials
root
openwifi
When you are logged into the CLI, you may find the logread command useful.
logread -l100 -f
The /etc/hosts file on the AP should have an entry for the controller. Yes this sounds redundant, but in our experience, this is a great way to ensure things along.
If you need to factory reset an AP -
firstboot -yr
Upgrade by AP’s command line prompt - ssh to AP and login as root / openwifi
Transfer firmware file to the /tmp directory of the AP by SCP
Run sysupgrade command to upgrade the AP
# sysupgrade -o /tmp/firmware_file.bin
If you want to build your own firmware - https://github.com/Telecominfraproject/wlan-ap
To figure out what kind of AP:
cat /etc/ucentral/capabilities.json
## OWGW
OpenWiFi controller default credentials
[email protected]
openwifi
You must connect to the OpenWiFi controller using the FQDN. You will not be able to login if you connected via IP address.
When you connect to the OpenWiFi controller, if you get a popup for client side SSL certificates, hit cancel.
You may need to update the /etc/resolv.conf on your controller. (the configure-dns.sh script, which is supposed to run prior to starting the services, is now supposed to do this automatically)
ssh [email protected]
sudo vi /etc/resolv.conf
change the nameserver to be your rXg
This will allow your controller to grab firmware
## TIP
NOTE: This "should" no longer be needed because of how we are configuring the APs directly from the rXg now.
If you need to "transfer" an AP -
https://portal.keys.tip.build/#/certificates
There is a known issue where after 3-4 days, this starts popping up:
"Unable to load Zone list: RuntimeError: Error: 403 - {"ErrorCode":13,"ErrorDescription":"13: Security service is unreachable, try again later.","ErrorDetails":"GET"}"
Rebooting the OWGW is the best known way to recover from this.
## Recovering from bricked state
If the AP powers on but does not respond to SSH, configure a device on 192.168.1.0 / 24 and see if you can ping the AP at 192.168.1.1.
If that works, you should be able to ssh to the AP on 192.168.1.1.
## MISC
If you are using a RADIUS "OR" for OpenWiFi and you don't have a user policy selected, there is the possibility you can get an Access Accept with an empty Tunnel-Password. You would see this in the logs: (Tunnel-Password => %account.pre_shared_key% (*account unavailable*))
In that case, your AP will continue to send RADIUS request spam for multiple minutes (tens of thousands of requests). The fix is to make sure you either have an AND or OR policy with a proper user policy selected
## Onboarding Procedure and Debugging
Step -1: Configure your rXg with example templates 6 and 7. Make sure your rXg has a Local Certificate Authority, and that that cert authority is linked to your OW WLAN Controller. This association is enforced via validation, but if you made your OpenWiFi WLAN controller BEFORE upgrading to a latest version, it is possible to have an OpenWiFi WLAN Controller without this association, and it will fail. Associating your OW WLAN Controller in your rXg to its VM is optional, but recommended, this will enable a convenient restart action button.
Step 0: Figure out what firmware you are on, and probably upgrade to the latest firmware. If you are not on the latest firmware, you can do a science experiment of trying to get it to work with whatever firmware you are on, but in terms of having a functioning AP, it will probably be faster to just upgrade to the latest firmware. Right now, "latest firmware" means latest firmware from TIP which is 3.2.1. You will need the latest firmware for your particular model. The easiest way to get the latest firmware for your particular model is to go into your OWGW interface and choose your model. Then click on the 'copy' link. If the AP that you want to upgrade has internet access you can just directly wget the firmware from the AP into its /tmp directory and go from there, eg `# sysupgrade -o /tmp/firmware_file.bin`.
Step 1: Do a network scan of the CIDR that you want the rXg to look for APs on. If there are any troubles see steps 1.x.
Step 1.1: Verify /etc/hosts on the AP. There "should" be an entry for openwifi.wlan.local and it "should" be the IP of your OWGW. *IF* you are running your rXg NAT'd, there "should" also be an entry for your rXg's private IP. Please remember: **THE AP CAN NOT RESOLVE PRIVATE IP ADDRESSES FROM DNS*. *IF* you are running your OWGW on a custom domain, that custom domain should have an entry in /etc/hosts instead of openwifi.wlan.local. **Only 3 part domains will work eg owgw.xyz.com.**
Step 1.2 Verify /etc/ucentral/gateway.json. This is how the AP knows where its controller is. Example: `{"server":"openwifi.wlan.local","port":15002}`.
Step 1.3 Verify the cert that the AP has. Assuming your OWGW is reachable at openwifi.wlan.local, run this on your AP: `openssl s\_client -connect openwifi.wlan.local:15002 -cert /etc/ucentral/cert.pem -key /etc/ucentral/key.pem` It should produce something like this about 2/3rds into the output:
Step 1.4 Reboot the AP and use `logread` to see if it is connecting or not.
OpenWiFi access points default credentials
root
openwifi
When you are logged into the CLI, you may find the logread command useful.
logread -l100 -f
The /etc/hosts file on the AP should have an entry for the controller. Yes this sounds redundant, but in our experience, this is a great way to ensure things along.
If you need to factory reset an AP -
firstboot -yr
Upgrade by AP’s command line prompt - ssh to AP and login as root / openwifi
Transfer firmware file to the /tmp directory of the AP by SCP
Run sysupgrade command to upgrade the AP
# sysupgrade -o /tmp/firmware_file.bin
If you want to build your own firmware - https://github.com/Telecominfraproject/wlan-ap
To figure out what kind of AP:
cat /etc/ucentral/capabilities.json
## OWGW
OpenWiFi controller default credentials
[email protected]
openwifi
You must connect to the OpenWiFi controller using the FQDN. You will not be able to login if you connected via IP address.
When you connect to the OpenWiFi controller, if you get a popup for client side SSL certificates, hit cancel.
You may need to update the /etc/resolv.conf on your controller. (the configure-dns.sh script, which is supposed to run prior to starting the services, is now supposed to do this automatically)
ssh [email protected]
sudo vi /etc/resolv.conf
change the nameserver to be your rXg
This will allow your controller to grab firmware
## TIP
NOTE: This "should" no longer be needed because of how we are configuring the APs directly from the rXg now.
If you need to "transfer" an AP -
https://portal.keys.tip.build/#/certificates
There is a known issue where after 3-4 days, this starts popping up:
"Unable to load Zone list: RuntimeError: Error: 403 - {"ErrorCode":13,"ErrorDescription":"13: Security service is unreachable, try again later.","ErrorDetails":"GET"}"
Rebooting the OWGW is the best known way to recover from this.
## Recovering from bricked state
If the AP powers on but does not respond to SSH, configure a device on 192.168.1.0 / 24 and see if you can ping the AP at 192.168.1.1.
If that works, you should be able to ssh to the AP on 192.168.1.1.
## MISC
If you are using a RADIUS "OR" for OpenWiFi and you don't have a user policy selected, there is the possibility you can get an Access Accept with an empty Tunnel-Password. You would see this in the logs: (Tunnel-Password => %account.pre_shared_key% (*account unavailable*))
In that case, your AP will continue to send RADIUS request spam for multiple minutes (tens of thousands of requests). The fix is to make sure you either have an AND or OR policy with a proper user policy selected
## Onboarding Procedure and Debugging
Step -1: Configure your rXg with example templates 6 and 7. Make sure your rXg has a Local Certificate Authority, and that that cert authority is linked to your OW WLAN Controller. This association is enforced via validation, but if you made your OpenWiFi WLAN controller BEFORE upgrading to a latest version, it is possible to have an OpenWiFi WLAN Controller without this association, and it will fail. Associating your OW WLAN Controller in your rXg to its VM is optional, but recommended, this will enable a convenient restart action button.
Step 0: Figure out what firmware you are on, and probably upgrade to the latest firmware. If you are not on the latest firmware, you can do a science experiment of trying to get it to work with whatever firmware you are on, but in terms of having a functioning AP, it will probably be faster to just upgrade to the latest firmware. Right now, "latest firmware" means latest firmware from TIP which is 3.2.1. You will need the latest firmware for your particular model. The easiest way to get the latest firmware for your particular model is to go into your OWGW interface and choose your model. Then click on the 'copy' link. If the AP that you want to upgrade has internet access you can just directly wget the firmware from the AP into its /tmp directory and go from there, eg `# sysupgrade -o /tmp/firmware_file.bin`.
Step 1: Do a network scan of the CIDR that you want the rXg to look for APs on. If there are any troubles see steps 1.x.
Step 1.1: Verify /etc/hosts on the AP. There "should" be an entry for openwifi.wlan.local and it "should" be the IP of your OWGW. *IF* you are running your rXg NAT'd, there "should" also be an entry for your rXg's private IP. Please remember: **THE AP CAN NOT RESOLVE PRIVATE IP ADDRESSES FROM DNS*. *IF* you are running your OWGW on a custom domain, that custom domain should have an entry in /etc/hosts instead of openwifi.wlan.local. **Only 3 part domains will work eg owgw.xyz.com.**
Step 1.2 Verify /etc/ucentral/gateway.json. This is how the AP knows where its controller is. Example: `{"server":"openwifi.wlan.local","port":15002}`.
Step 1.3 Verify the cert that the AP has. Assuming your OWGW is reachable at openwifi.wlan.local, run this on your AP: `openssl s\_client -connect openwifi.wlan.local:15002 -cert /etc/ucentral/cert.pem -key /etc/ucentral/key.pem` It should produce something like this about 2/3rds into the output:
Step 1.4 Reboot the AP and use `logread` to see if it is connecting or not.