Requirements:
- Unifi Controller v5 running on a Unifi CloudKey (UCK)
- A Unifi USG
- A Unifi Access Point such as the UAP-AC-LR, UAP-AC-Lite, UAP-AC-Pro (UAP)
- Your own valid purchased Domain Name (in order to purchase an SSL Certificate)
- Your own DNS Provider (This can be through your domain registrar or through a third party such as CloudFlare or Hurricane Electric)
- The ability to purchase SSL Certificates (or use Let's Encrypt with DNS Validation)
This document is written for Unifi Controller Software v5. Configuring the Unifi Controller Guest Network, the Hotspot Portal and SSL is actually fairly involved and requires modifying the configuration in several locations-as well as adding the SSL certificate via SSH. So this will consist of several discrete procedures to achieve the end goal.
This document assumes you're using a full Unifi stack of devices (e.g. Unifi Cloudkey, Unifi Access point, Unifi USG). Some steps such as step 2 can be substituted if you're not using a USG.
This document also assumes you have previously performed the required adoption of USG and UAP on the UCK as well that you have configured the credentials required to log into the UCK via SSH.
- Plan out your Network
- Configure the Cloudkey
- Modify the USG DNS
- Setting up the Guest Network
- Configuring the Hotspot Portal
- Setting up SSL
Unifi's Controller software is very friendly with a lot of capabilities. It has continued to develop at a healthy-pace over the last several years. There are still some rough spots compared to other products that we do have to work around to accomplish our goal of a completely Unifi-based set up with no dependency on other hardware or services hosted on other machines.
In this guide, I am going to assume you will want the following:
- A URL for accessing your controller (e.g. unifi.mydomain.com)
- A URL for the hotspot to use which is different from your URL for your controller (e.g. portal.mydomain.com)
- Use the USG for Local DNS Resolution
In order to reliably set up the handling for the Guest Portal, we need to ensure that the CloudKey is configured to use a static IP. As IP Address planning is outside the scope of this document, I urge you to check the internet for various How Tos on how to plan things out. By default, Unifi USG hands out IPs in the 192.168.1.0/24 CIDR (or range). So, assuming that you do not have any other devicesd on your network with static addressing, we will plan arbitrarily decide to have the CloudKey use a static IP of 192.168.1.250. To configure this, we need to do the following:
If you did not previously set the UCK to use a static IP address, the below steps should be followed.
-
Open a browser and visit the current IP address that your CloudKey is using (e.g. https://192.168.1.83) to which we will be greeted by the Controller/CloudKey Splash Page. Click on "Configure" beside CloudKey. Now log in with the account you configured for managing the CloudKey (this is the same credentials you use to SSH into the UCK).
-
At the left-side you will see three navigation options: Main, Configuration and Maintenance. Click on "Configuration".
-
From this page you can configure the name of the CloudKey, time zone, whether the reset button is enabled or disabled and lastly the Network Settings. By default, DHCP is enabled. Set it to Static and configure it as follows:
IP Address: 192.168.1.250 Netmask: 255.255.255.0 Gateway: 192.168.1.1 Primary DNS: 192.168.1.1 Secondary DNS: 8.8.8.8 -
Click "Apply Changes"
-
You should lose your connection to the UCK at this point as it modifies its IP address. If it does not, then simply click on "Maintenance" at the left and click the "Reboot" button under the "Maintenance" section.
Setting the Hostname via the Controller didn't appear to do much in my test network. We set it anyways for good measure. We'll also configure a few additional options to be thorough.
- Log into your controller software (e.g. https://192.168.1.250:8443)
- Navigate to Settings (gears symbol bottom left)
- Under the Settings Navigation bar, click "Controller"
- Under "Controller Settings" Set your "Controller Name" (this is the name you see in the address tab of your browser OR that you see in the Unifi mobile app)
- In the same section, set your "Controller Hostname/IP" to the hostname you want to use to reach your controller over the Local Area Network (LAN). (e.g. unifi.mydomain.com)
- In most situations, you should leave the next two checkboxes un-checked. (See Page 41 of the Unifi Controller User Guide v5 for details.)
- Scroll to the bottom and click "Apply Changes"
For this part of the process, you need to have already planned out which URLs you want to use. In this guide, the assumption is that you are using the built-in DNS on the USG for your network.
To modify the USG DNS to your specification, you must first create the configuration file (See this gist for a bit more info). You will need to SSH in to the CloudKey and either use Vi, install another editor via apt-get or create your configuration file on another system (ensuring your line breaks are Unix format and NOT Windows format). The file on the cloudkey is located at /usr/lib/unifi/data/sites/default/config.gateway.json.
Below are two examples of potential configuration files. You would only use one of these (never both). If you copy either, you will have to update the hostname field (e.g. unifi.mynet.mydomain.com) to reflect your actual internal network name. You will also have to update the IP address to match what you chose previously for the specific device (in the first example it is only the cloudkey that we're wanting to access via the URL unifi.mynet.mydomain.com.
Single DNS Entry:
{
"system": {
"static-host-mapping": {
"host-name": {
"unifi.mynet.mydomain.com": {
"alias": [
"unifi"
],
"inet": [
"192.168.1.30"
]
}
}
}
}
}
Double DNS Entry:
{
"system": {
"static-host-mapping": {
"host-name": {
"mynas.mynet.mydomain.com": {
"alias": [
"mynas"
],
"inet": [
"192.168.1.99"
]
},
"unifi.mynet.mydomain.com": {
"alias": [
"unifi"
],
"inet": [
"192.168.1.30"
]
}
}
}
}
}