CoovaAP is a sub-project of Coova.org. It is custom firmware which can be installed on an Access Point to make the Access Point a Captive Portal based device. There are two generations of CoovaAP. The older generation is mainly used on Linksys Wrt-54x hardware and this is the firmware which will be covered here. There is also a version 2.x of the CoovaAP firmware available for people who would like to try new things.

Before we start; make sure you have the following in place.

• Configure CoovaAP in such a way to be able to:
  • Use the FreeRADIUS running on RADIUSdesk as a RADIUS server
  • Use the dynamic login pages on RADIUSdesk as login pages for the Captive Portal on CoovaAP

What would life be without challenges! With the advanced goal we assume a very common set-up where the CoovaAP sits behind a NAT firewall and our RADIUSdesk server is somewhere in the cloud. We will explore the following options:

• Using a heartbeat system to pass through the NAT firewall
• Using OpenVPN to establish a direct connection between CoovaAP and the RADIUSdesk server.
• Using PPTP to establish a direct connection between CoovaAP and the RADIUSdesk server.

We also need to be able to disconnect any of the connected users through the RADIUSdesk interface. We will explore the following options:

• Sending a COA instruction from RADIUSdesk to CoovaAP
• Using the heartbeat system to send a disconnect request to CoovaChilli daemon.

The Advanced goal has its own dedicated document here

When I started to create this document the first problem I encountered was one of my CoovaAP flashed devices which had a long forgotten password. Here is the basic instructions to get this Access Point CoovaAP-erized in no time.

• Connect power to the Access Point while watching the LEDs.
• The power LED will flash while the DMZ LED will be off initially.
• As soon as the DMZ LED comes on; press the reset button.
• The DMZ LED will start to flash. The device is now in Failsafe mode.
• Connect to the device through one of the LAN ports (1→4) with a machine that is configured with an IP Address on the 192.168.1.x subnet. e.g 192.168.1.100
• Telnet to 192.168.1.1
• You will now be connected without a password.
• To flash the latest CoovaAP firmware on the device:

cd /tmp
wget http://<web_server_with_trx_file>/openwrt-brcm-2.4-squashfs.trx
#Or use SSH
scp root@192.168.1.100:/tmp/openwrt-brcm-2.4-squashfs.trx ./
#Now flash it onto the memory
mtd -r write openwrt-brcm-2.4-squashfs.trx linux 

• This action usually does not restart the access point. You will have to power cycle after the write action completed. This is indicated by the Power LED stop flashing.
• To reset the NVRAM to factory defaults; you may have to reboot and go into Failsafe mode again. Then after you telnetted into the Access Poiont, issue the following command:

 mtd -r erase nvram

• Again wait for the Power LED to stop flashing and power cycle the Access Point.
• You should now be able to connect to the Access Point through the web interface running on: http://192.168.1.1

We will use the following values for our configuration. Adapt these to fit your environment.

• Ensure the Access Point is connected as shown in the Basic configuration diagram.
• Also ensure there is a server running RADIUSdesk with a known IP Address. We will use 192.168.1.11 in this document.

• The default configuration of CoovaAP assigns subnet 192.168.1.0/24 to the LAN.
• This subnet is however a typical default subnet and is most likely to also be used by the device to which you connect the WAN port.
• This is bound to cause problems and the best will be to move the LAN onto another subnet. We will use 192.168.100.0/24
• Connect a machine to the LAN on the Access Point. You should get an IP Address assigned to you from the 192.168.1.0/24 range.
• Open a browser to connect to http://192.168.1.1. If it is the first time you connect to CoovaAP; you will need to provide a password for the root user.
• After you are sucessfully connected; go to Status→Network to see what the IP Address is that the WAN port got (if any) during startup.
• On my system is was 192.168.1.107.

• Select Network → LAN and under LAN Configuration specify 192.168.100.1
• The DHCP pool will automatically also change to this new subnet. (Network → DHCP)
• If you click save, there will be a message about config changes pending. This means that you first have to commit these changes before they take effect.
• Click on the Changes pending text to get a page that will allow you to apply these changes.
• As soon as you apply these changes you will be disconnected. Remove the LAN cable and plug it back again to force your machine to get a new IP Address from the LAN (now 192.168.100.x) and connect to http://192.168.100.1
• Supply the username and password.
• Confirm that the new subnet is now used on the LAN.

• You may have to reboot the Access Point as well to correct the routing tables.

• FreeRADIUS work is such a way that it needs to know a client's IP Address as well as a shared secret between the two before it will serve requests from the client.
• For this reason; we will assign a fixed IP Address to the WAN port of the Access Point. We decided on 192.168.1.10.
• Click on Network → WAN
• Under WAN Configuration; change DHCP to Static IP.
• Now you can specify your values and click save after you are done.

• The results

• The results:

• Since our Access Point is behind a NAT firewall; we will open the WAN port. This will allow us to connect to it on the WAN port.
• Select System → Settings
• Then enable ssh and web access on the WAN port.

• Save and commit these changes.

• You should now be able (provided you are on the 192.168.1.x network) to access the Access Point through the WAN port.

• Select Network → Wireless and change the ESSID from Coova to RADIUSdesk
• Save and commit these changes

• Edit the /etc/network/interfaces file to assign a fixed IP Address to the RADIUSdesk server.

# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).
 
# The loopback network interface
auto lo
iface lo inet loopback
 
# The primary network interface
auto eth0
iface eth0 inet static
    address 192.168.1.11
    netmask 255.255.255.0
    gateway 192.168.1.1
    dns-nameservers 192.168.1.1

• Reboot the machine to make sure the settings are applied during start-up.

Now that the RADIUSdesk server has a fixed IP Address; we can add the CoovaAP as a client (NAS device) to RADIUSdesk.

• Go to http://192.168.1.11/rd and log into RADIUSdesk.
• Select Menu → NAS Devices → NAS Devices
• This will open the NAS Devices applet.
• Select the plus sign on the toolbar to add a new NAS device.
• Select the owner of this NAS device and click Next.
• For the connection type; select Direct (Fixed IP) and click Next.
• Supply the following:

• On the Realms tab; tick Make available to all realms.
• Click Next to complete the addition.

• Once the NAS device is added; you can activate active monitoring on this device.
• Select the NAS device and click on the pencil icon on the toolbar to edit the NAS device.
• This will open a new tab that contains the detail of this device.
• The NAS tab has a Monitor settings sub-tab where you can activate a ping test and also specify the interval of this test.

• After you added the NAS device you need to restart FreeRADIUS.
• Select Menu → Tools → Logfile viewer applet.
• The Logfile viewer applet's toolbar has a start and stop button.
• Click on the stop button and thereafter on the start button. Check the feedback of the logfile to confirm successful start-up.

The FreeRADIUS server should now be ready to accept request from the client 192.168.1.10.

Under the Hotspot tab is various sub-tabs. Most of these sub-tabs will only be activated once the hotspot is enabled under the first sub-tab (Configuration).

• Under the Hotspot→Configuration tab. Check the following items and their values:

Item	Value	Comment
Hotspot Configurations
Hotspot Type	CoovaChilli UAM	Default is Disabled. Change to CoovaChilli UAM
HotSpot Mode	Wireless Only	Keep default
HotSpot LAN Access	Deny	Keep default
Basic Configurations
Auto Configuration	Disabled	Keep default
UAM Hostname	10.1.0.1	Keep default. We will not use this service
UAM Secret	greatsecret	Should be the same as the value specified in rd_login_pages/services/uam.php in the webserver's document root on RADIUSdesk
NAS Identifier	RADIUSdesk-01	Use a value to uniquely identify the NAS

• Save these values once you are happy with them
• The following sub-tabs under Hotspot can remain untouched and needs no modification on them:
  • Location
  • Access Lists
  • DHCP
  • Portal
  • Proxy
• Under the Hotspot→RADIUS tab. Check the following items and their values:

Item	Value	Comment
AAA Configurations
AAA Mode	RADIUS	Default is HTTP(s). Change to RADIUS
Primary RADIUS Server	192.168.1.11	The IP Address of the RADIUSdesk server
Secondary RADIUS Server	192.168.1.11	The IP Address of the RADIUSdesk server
RADIUS Auth Port	1812	Keep default
RADIUS Acct Port	1813	Keep default
Shared Secret	testing123	Make it something secure and obscure
Administrative-User
RADIUS Admin Username	(blank)	Keep default
RADIUS Admin Password	(blank)	Keep default
Optional Configurations
MAC Address Authentication	Disabled	Enable this if you want to make use of the RADIUSdesk BYOD applet to manage davices based on their MAC addresses
Allow Accounting Updates	Enabled	Default is Disabled. Enable this option
RADIUS Send DHCP Info	Disabled	Keep default
RADIUS Send Oringial URL	Disabled	Keep default
Admin Reauth Interval	0	Default is 3600. We will disable it by setting it to zero
Default Session Timeout	0	Keep default
Default Idle Timeout	0	Keep default
Default Interim Interval	300	Keep default
Allow WPA Guests	Disabled	Keep default
Allow OpenID Authentication	Disabled	Keep default

• Save these values once you are happy with them

• Under the Hotspot→Advanced tab. Check the following items and their values:

Item	Value	Comment
Advanced ChilliSpot Configurations
Internal UAM Port	3660	Keep default
HotSpot Services Provider	Coova	Keep default
HotSpot Services Provider URL	http://www.coova.org/	Keep default
UAM URL Format	http://192.168.1.11/cake2/rd_cake/dynamic_details/chilli_browser_detect/	IP Address of the RADIUSdesk server
UAM Homepage (splash page)	(blank)	Delete the default value and keep empty
UAM Service (for Javascript)	(blank)	Keep default
WISPr Login URL (optional)	(blank)	Keep default
Local Content Directory	/etc/chilli/www	Keep default

• Save these values once you are happy with them

• Connect with a browser to the Access Point (http://192.168.1.10) and confirm that CoovaChilli is running by checking the status under Status → Hotspot
• If it is running; you should now be able to connect with a device to the Access Point's WiFi SSID and be redirected to a login page as soon as you attempt to go onto the Internet using the device's browser.
• The login page may or may not be displayed correct. Configuring RADIUSdesk to be able to display the login page correct is covered in the next section.

This section assumes the following has been completed already:

• CoovaAP has been configured with:
  • Fixed IP Address on WAN port
  • Set with SSID RADIUSdesk in the WiFi interface with a hotspot (captive Portal) already configured as per instructions on this document.
  • Using RADIUSdesk as a server to serve the login page (no splash page)

• Connect with a device to the RADIUSdesk ssid and attempt to go onto the Internet through the browser on the device.
• You will notice that the page will be redirected and the URL will look like the following from a desktop / laptop:
• http://192.168.1.11/rd_login_pages/desktop/CoovaChilli/build/CoovaLogin/production/index.html?q=/cake2/rd_cake/webroot/dynamic_details/chilli_browser_detect/&res=notyet&uamip=10.1.0.1&uamport=3990&challenge=7f625f36be5fb76f1bba2e42805c5941&called=08-00-27-30-B3-C4&mac=08-00-27-90-61-AE&ip=10.1.0.2&ssid=RADIUSdesk&nasid=RADIUSdesk-01&sessionid=51ae925300000001&userurl=http%3a%2f%2f1.0.0.0%2f&md=158D9C4660DAA0AE15E31A40E959775F
• If you connect from a tablet or phone; it will look like this:
• http://192.168.1.11/rd_login_pages/mobile/CoovaChilli/index.html?q=/cake2/rd_cake/webroot/dynamic_details/chilli_browser_detect/&res=notyet&uamip=10.1.0.1&uamport=3990&challenge=7f625f36be5fb76f1bba2e42805c5941&called=08-00-27-30-B3-C4&mac=08-00-27-90-61-AE&ip=10.1.0.2&ssid=RADIUSdesk&nasid=RADIUSdesk-01&sessionid=51ae925300000001&userurl=http%3a%2f%2f1.0.0.0%2f&md=158D9C4660DAA0AE15E31A40E959775F
• As you can see there are two items in the query string which is a result of our configuration
  • ssid = RADIUSdesk
  • nasid = RADIUSdesk-01
• We can use one of these (or both) to associate the Access Point with a pre-defined login page on RADIUdesk.
• We will use the sample login page which comes standard with RADIUSdesk and add an association of ssid with value of RADIUSdesk to the list of Dynamic keys.
• Connect to the RADIUSdesk webtop (http://192.168.1.11/rd)
• Open the Dynamic login pages applet and select SA Coast - Struisbaai.
• Click on the pencil icon in the toolbar to start editing it. This will open a new tab which contains all the detail of SA Coast - Struisbaai.
• Select the Dynamic keys tab an add an entry for ssid → RADIUSdesk

This completes the basic configuration to connect the CoovaAP with RADIUSdesk in order to:

• Configure CoovaAP to be a client of the RADIUSdesk server.
• Use RADIUSdesk to manage the login pages of CoovaChilli centrally.

With the Debug output applet of RADIUSdesk it is now easy to run a debug trace on the FreeRADIUS daemon to see if everything works as intended.

• Connect to the RADIUSdesk webtop (http://192.168.1.11/rd)
• Open the Tools → Debug output applet.
• Select 192.168.1.10 in the NAS IP Address select control on the toolbar to limit the debug trace to packets from 192.168.1.10.
• Click on the start button in the toolbar to start a debug trace.
• Click on the duster button in the toolbar to clear the screen.
• On a new window or tab, connect to the CoovaAP's web interface and select Reboot under the Status tab (to the right).
• Confirm this action.
• Go back to the window or tab that has RADIUSdesk open while checking the debug feedback on the Debug output applet.

• Try to connect with a WiFi device to the RADIUSdesk SSID and authenticate through the login page. The debug feedback should include this action as well.