UniFi--How to

Controller Installation

Is there a user guide?

Yes, check http://www.ubnt.com/download#doc:unifi. You will find the latest Datasheet, Quick Start Guide, and User Guides.

Supported Platforms for UniFi Controller software

Currently UniFi can be installed on Windows XP, 2003, Vista, 7, and Intel Mac 10.5 and after. For Linux, we release debian packages (APT). A generic zipped package is also introduced since 1.3.2

Do UniFi APs require the controller to be running all the time?

UniFi APs can run by themselves without the controller unless features like guest portal is enabled (as UniFi controller also functions as a captive portal). Restarting the controller won't restart your APs.

How do I install the controller on another PC/machine?

The best way is to backup your original configuration (Admin->Backup), shutdown the original controller and restore it into the new controller. Your access points will be seamlessly managed by the new controller.

What are included in the backup file (*.unf)?

The Backup functionality provided in the UniFi controller preserves the settings and the database. It does NOT include portal, system.properties (for customized ports configuration) and config.properties (for NTP, U-APSD specialized configurations).

Is there anyway to automatically backup the configurations?

Take a look at Controller API and use the unifi_backup function.

I saw "Start-up failed" or "Server taking too long to start". What happened?

Mostly likely one or more ports needed by UniFi are being used by other programs. Take a look at <unifi_base>/logs/server.log and you'll spot something like:

[2011-06-01 22:09:14,145] <UniFi> ERROR StandardServer  - StandardServer.await: create[8081]: 
java.net.BindException: Address already in use: JVM_Bind
        at java.net.PlainSocketImpl.socketBind(Native Method)
        ...

Please follow the instructions below to change the ports and fix the issue.

How can I run UniFi Controller on different ports

1. By default, UniFi controller runs on these ports
   • unifi.shutdown.port=8081 (for management purpose)
   • unifi.http.port=8080 (device inform)
   • unifi.https.port=8443 (controller UI / API)
   • portal.http.port=8880 (portal redirect port for HTTP)
   • portal.https.port=8843 (portal redirect port for HTTPs)
   • unifi.db.port=27117 (local-bound port for DB server)
2. Follow these steps to change the default settings
   • Make sure UniFi is not running
   • modify <unifi_base>/data/system.properties and make sure all ports needed by UniFi are available
   • restart UniFi

How can I customize how AP is provisioned (e.g. NTP server, U-APSD)

1. create/modify <unifi_base>/data/config.properties
   • config.ntp_server=0.ubnt.pool.ntp.org (in case you would like to use your own)
   • config.uapsd_enabled=false (some devices may have problem with or without it)
2. do anything that triggers AP to re-provision (re-provision is not equal to reboot). One way to do that is to change a WLAN config or by disable/enable status "Uplink Connectivity Monitor" from controller "Settings" > "System" > "Uplink Connectivity Monitor" check box.

There are a few options we implemented to customize some of the controller's behaviors. As controller evolves, the options may or may not be available across versions. (no AP re-provisioning is needed)

config.redirect_via_host=www.ubnt.com

Can I run UniFi Controller as a Windows Service?

Can I run UniFi Controller as a Windows Service? Yes, we added the support since 2.2.0.

1. Make sure UniFi is not running
2. Locate your java installation directory.
3. On 64-bit, it's usually at "C:\Program Files (x86)\Java\jre6\bin"; otherwise "C:\Program Files\Java\jre6\bin". (replace jre6 for jre7 if you have the latest Java)
4. Add the dir above to the PATH (from Computer->Properties->Advanced system settings)
5. run a command prompt (as an Administrator, right click on 'Command Prompt' and choose 'Run as administrator'. THIS IS IMPORTANT ON WIN2008/7+, otherwise the service may not get created)
6. cd <unifi_base> (cd "%userprofile%/Ubiquiti Unifi" will usually do the trick, including the quote marks)
7. java -jar lib\ace.jar installsvc
8. Start the service: net start "Unifi Controller"

Note: there's a known bug against 2.2.X. The service shuts down the the administrator logs out.

Where is UniFi installed (or where is the <unifi_base>)?

• Mac -- /Applications/UniFi.app, the <unifi_base> is at /Applications/UniFi.app/Contents/Resources
• Windows -- "%userprofile%/Ubiquiti Unifi", which is the same as <unifi_base>
• Linux -- /usr/lib/unifi

On Windows, can I choose another installation directory?
We chose to install it under user profile for Auto Upgrade to work across all Windows platforms. You can move it anywhere you'd like, though, by stopping UniFi, move it, and fix the shortcut.

I forgot my username and password to the controller?

1. download mongodb for your platform from http://www.mongodb.org/downloads
2. execute bin/mongo --port 27117 from your controller
3. type 'use ace'
4. type 'db.admin.find()'

How does UniFi check for updates? What information was collected?

UniFi controller checks for updates daily and upon start-up. The information we collect:

• OS / Architecture
• Java Version
• UniFi version
• Number of APs
• a randomly generated ID (e.g. 246de3fa-fc6c-47d1-89aa-d97cdc694cb1) for the installation
• IP Address

Operation and Deployment

How do I start from scratch? (i.e. re-install the controller, re-discover the AP)

1. In some scenarios (e.g. restarting a demo to prospective customers), you can easily press the reset button of the AP for more than 7 seconds (or until the LED turns brighter then turns itself OFF) and it will be restored to factory default.
2. The UniFi discover utility, also has the "reset" button next to a found AP (you will not see this button if the AP is already in the default state)
3. If an AP is "Connected" in controller, by clicking "Forget this AP" in the AP dialog > Configuration panel, you also send it back to factory default state.
4. In the case where AP is inaccessible, you may SSH into the AP (with the same username/password as the controller) and issue this command:

syswrapper.sh restore-default

Cannot see / adopt my device anymore? What should I do?

As there's a binding between controller and AP. A newly installed UniFi controller will not adopt a non-default AP. You an either:

1. use the backup feature of the original controller and restore it to the new controller
2. remove the AP (AP dialog > Config > Remove) when the AP is in Connected state. Controller will help you restore the AP to default state, then remove it from the DB. You'll see AP reboots and comes back up with amber/orange LED.
3. also check out this section http://wiki.ubnt.com/UniFi_FAQ#L3_.28Layer_3.29_Management for other adoption methods.

AP status stucks at "adopting". What do I do?

1. make sure AP has access to Internet (e.g. SSH into the AP and ping unifi, it should come back right away, even if it fails)
2. install 2.2.5 or after
3. go through the wizard and use ubnt/ubnt as admin's username/password
4. connect UniFi APs and laptop (with controller installed) to the same router
5. check the router and write down the IPs of the APs. Most home routers have it listed under DHCP client table
6. SSH into each problematic AP and issue 'syswrapper.sh restore-default'

If above doesn't help and your AP always show IP as 192.168.1.20. Check your DHCP server or router, if it did assign an IP to the AP yet the AP still shows 192.168.1.20, you may have a faulty AP. If all attempt fails, try the following:

1. from the UI, make sure AP does obtain the IP from DHCP, note the IP
2. from Controller PC, SSH into the AP (using the IP, default username/password is ubnt/ubnt)
3. tail -f /var/log/messages
4. copy the text along with your support info (Admin->Support Info) to support@ubnt.com

The adoption process was designed with DHCP in mind. We do not encourage adoption through the default IP. However, if you are more used to that way, there is one rule: we do NOT recommend (at all) directly connecting your controller to the AP through a power adapter. Always put a switch in between your controller and the target AP. The reason is that the adoption process involves AP rebooting, therefore if you directly connect AP to the controller Ethernet, this link will become up-and-down during the adoption process. In that case, there is a remote chance that the controller may not populate the correct inform IP address to the AP which will cause adoption stuck. In short, don't adopt this way: "directly connecting your controller to the AP through a power adapter".

v2 -> v3 migration

Starting from v3, the controller will NOT force a v2 AP upgrading unless the automatic upgrade checkbox is checked (unchecked by default). However, for a v2 AP on a v3 controller, this AP will enter into a "Connected (needs upgrade)" interim state. Under such a state, the AP will continue serve whatever config it has before (that provisioned from the v2 controller), however the v3 controller cannot manage nor collect statistics from it. In other words, the WLAN service is still up but it is not managable until the user upgrades the v2 AP to v3. As the state suggests, it "needs" upgrade before fully funtional. A very careful user can then manually "upgrade" one AP, verify if it is working properly in her/his environment, and then repeat this manual upgrade process until all APs are upgraded to v3. The reason behind this design is for a safer upgrading process that is critical in an enterprise environment.
Upgrade Steps:

1. On v2.3.9 controller, in the "Admin" panel, Click "Download Backup Settings"to save the .unf file.
2. Close controller
3. Uninstall the v2.3.9 controller
4. Install the v3.1.x controller
5. Controller starts. In the first browser page, restore the config from the previsouly saved .unf file.
6. After some time, all APs will be adopted by the newly upgrade v3 controller and put into the "Connected (needs upgrade)" state.
7. The v2 APs continuously serve WLANs configured previously, but they are not manageable until being upgraded to v3.
8. To upgrade these APs:
   • For adventurous administrators, check "Automatic Upgrade"
   • For a safer upgrade, check "rolling upgrade" on top right corner. For this method, the controller will automatically upgrade APs one after one.
   • For a careful administrator, manually click "Upgrade" button for an AP, check if it upgrades/works fine, then upgrade the other. Repeat this until all APs are upgraded.

Downgrade Steps:

1. "Download Backup Settings"to save the .unf file.
2. Close and uninstall the v3.1.x controller
3. Click "No" when the uninstaller asked about keeping configurations (don't mess controller, v2 controller will NOT recognize v3 configs)
4. Install the v2.3.9 controller
5. Restore the previously saved v2.3.x config file (.unf)

How do I manually upgrade an AP

• If the "Automatic Upgrade" is checked, the controller will automatically upgrade AP firmware
• If the "Automatic Upgrade" is unchecked, there will be an "Upgrade" button next to each AP in the controller AP list. Clicking that button will bring the AP to the same version that the controller runs. If the AP is in the same version as the controller, the button is hidden.
• You can also do this from CLI interface. To do so, please refer to the "Use SSH" section in the http://wiki.ubnt.com/UniFi_FAQ#L3_.28Layer_3.29_Management

I'm having trouble uploading maps, what's wrong?

The map upload goes through the HTTP port (usually 8080) instead of the HTTPS one (8443) used for management. Check your firewall or NAT settings to see if they're blocked or not forwarded correctly.

How do I create floorplan images?

The map accepts many common image formats like png, jpg, gif, ... (but it does NOT support .bmp) I've seen people doing all kinds of things to create the floorplans:

• taking screenshots from Google Map
• draw on a napkin and take picture using cellphone

If you're up to some art work, try this online floorplan creator

How does vlan traffic get tagged?

UniFi AP tags packets when it goes out from WLAN to wire. When tagged traffic comes in from the wire, it will untag it and forward it to WLAN. We have compiled a deployment example using 4 different switch brands for you configuration references. See http://wiki.ubnt.com/UniFi_and_switch_VLAN_configuration

How does VLAN tagging work with guest portal?

1. traffic initiated from AP is untagged (sent through br0)
   1. AP <-> Controller (management traffic)
   2. AP <-> RADIUS (if WPA-Enterprise is used)
2. traffic from WLAN without vlan configured is untagged (the athX is bridged to br0)
3. traffic from WLAN with vlan configured is always tagged (athX bridged to br0.VLAN to eth0.VLAN)

Whether it's redirected (to the guest portal) doesn't matter. When WLAN is configured with VLAN, the traffic will be tagged when it leaves the AP. However, how to forward the tagged traffic to where it should go is something you'll have to figure out.
Here's an example:

My management network: 10.0.0.0/24
Guest VLAN network: 15.0.0.0/24

Switch:
AP connected to port 5 (vlan1-untagged and vlan5-tagged)
Ubuntu connected to port 1 (vlan1-untagged and vlan5-tagged)
Controller connected to port 8 (vlan1-untagged)

Ubuntu (act as a Router)
eth0: 10.0.0.2/24, routable to the Interet (gateway 10.0.0.1)
eth0.5: 15.0.0.1/24, NATed to eth0

Controller is at 10.0.0.26

What happens if the controller goes offline when guest portal is enabled?

When an AP cannot reach the controller, it goes into a so-called SELFRUN state.
In this state, it doesn't make sense to redirect the guests to the portal (controller) which is not reachable, AP will automatically allow the guest to use the network without redirecting. Moreover,

1. the guest access policies are still effective (L2/L3 isolation) along with the restricted subnets feature
2. the user group (bandwidth limiting, etc) associated with this WLAN is still effective
3. when the controller comes back online (and AP goes into MANAGED state), the guest portal redirection will restore automatically

Starting from 2.3.9, you'll be able to add/modify <unifi_base>/data/config.properties

# config.selfrun_guest_mode=pass        # when controller is offline, automatically 
#                                         authorize all guests (all guest isolation / policy is still enforced)
#                                       # "off" to disable all the guest SSIDs when controller is not reachable

How do I use WPA-Enterprise?

Usually this involves

• set up RADIUS server (Windows IAS, FreeRADIUS, etc)
• tell RADIUS server where the RADIUS request may come from (i.e. the IP address/subnet/range of the APs)
• set up wireless clients with configuration and, if necessary, certificates (e.g. EAP-TLS)

You can configure the type of EAP you'd like to use and UniFi APs do not get involved.

How do I configure WPA1 / WPA2

By default, when WPA is used, UniFi will enable WPA1/WPA2 (or mixed mode) as well as TKIP/CCMP(AES). Release 2.2.0 and after enables you to limit/force specific security settings.

I cannot get Google Map API key to work, what's wrong?

For "My web site URL:", make sure you use https://unifi_ip/

Is Bandwidth Limiting Per User, Per SSID, or Per AP?

Bandwidth / Rate limiting applied to each user.

I use DNS for my L3 management, why does AP shows disconnected when I configure it to use Static IP?

When you use DHCP, resolv.conf will have "search yourdomain". As you have configured the DNS serverresolve unifi.yourdomain to the controller-ip, all is good. However, when you set the AP to use Static IP, there won't be a "search yourdomain" in the resolv.conf. "unifi" can no longer be resolved by your DNS server.
The solution is to use DHCP with static IP mapping.

Specifications

What Hardware Models Are Available

For detailed information, please see UniFi AP Datasheets
UniFi AP - Standard

• Two integrated antennas -- supports 2x2 MIMO with spatial diversity
• 1 Passive PoE port
• 20dBm Max transmit power
• Antenna radiation targets a dome-shaped coverage area where the height is slightly shorter than the radius

UniFi AP - Long Range Similar to UniFi Standard, with these differences:

• 27dBm Max transmit power
• 2-3dB higher receive gain

UniFi AP - Outdoor Rugged outdoor AP with two omni antenna (included) - 2x2 MIMO

• 28dBm Max transmit power

UniFi AP - Professional

• Faster processor, more RAM
• Concurrent dual-band radio: 2.4Ghz 3x3 450Mbps, 5Ghz 2x2 300Mbps
• Gigabit Ethernet
• 802.3af PoE
• Dual firmware image
• Security Lock

What is the gain of the UniFi internal antennas?

The peak antenna gain for the indoor UniFi APs is around 6dBi

How Many SSIDs / VLANs are supported

4 SSIDs (and corresponding VLAN IDs)

Do you support roaming?

Yes. Roaming is supported per 802.11. Starting from v3.1.x, UniFi supports PMK-Caching and introduced a seamless roaming feature - Zero-Handoff.

Do you support WMM?

Yes, and WiFi-certified.

How is QoS implemented?

UniFi AP considers either DSCP or COS. It compares COS with DSCP (the first 3 bits) and takes whichever has higher value to map to WMM AC according to the table below (this also can be referred at http://wiki.ubnt.com/Main_Page/QoS_DSCP/TOS_Mappings).
DSCP values (Decimal) => WMM AC

• 0 to 7 => BE
• 24 to 31 => BE
• 8 to 23 => BK
• 32 to 47 => VI (except 46)
• 48 and above => VO

Starting from v2.3.6, DSCP 46 is considered as a special case that will be mapped to VO.
On the AP receiving end, 802.11 is on top of ethernet frame. AP thus sends packets onto the wire the way it receives over-the-air (without 802.11 header of course). For example, a VoIP phone sends VO packets in DSCP 46 and that will be the DSCP value of the ether frames that AP sends out on wire.
reference: http://forum.ubnt.com/showthread.php?t=57880

Why do I never see 300Mbps even if HT40 is enabled?

I don't want to bore you with technical details but check the Data Rates Table here. UniFi APs are capable of 300Mbps _if_ the client can and want to use it. Here are common numbers you can see (all assuming good signal)

• 65Mbps (client only has 1 receiving antenna, MCS7)
• 130Mbps/144Mbps (client has 2 receiving antenna, MCS15. 40Mhz not supported or disabled)
• Macbook does have multiple antennas; however, it only supports HT20 on 2.4Ghz and by default enables HT40 on 5Ghz

Do you support auto channel selection?

By default AP will find a best channel when it powers up. You can overwrite it in the per-AP config. Background-scanning and automatic runtime channel change is on the road map.

What's the maximum number of clients can an AP support

This is a question that's hard to answer. The implementation supports 127 clients (per band) simultaneously but in reality it depends on what these clients do (just email/web/chats? streaming? downloading?) In our office, we constantly have 20+ (30+ at times) various kind of devices without any issues. We had reports about problems with more than 60 clients but haven't reproduced it yet. Currently in our lab, we have ~100 clients stressing one AP.

What does the icon next to the signal strength mean?

The (b), (g), (n) icon indicates the type of client/connection (11b, 11g, 11n) When it turns gray with a lightening bolt, it means the device is currently in power-saving mode

What are the different LED state

UAP/UAP LR/UAP Outdoor:

• Blinking Amber/Orange - initializing
• Steady Amber/Orange - factory defaults
• Steady Green - adopted
• Steady green with occasional flashing (once every 3 or 4 seconds) - isolated (This means that AP cannot reach to the gateway. Starting from v2.3.x, uplink monitor can be disabled under "Settings" > "System" > uncheck "Uplink Connectivity Monitor").

UAP Pro:

• Flashing White - Initializing.
• Steady White - Factory default, waiting to be integrated.
• Alternating White/Blue - Device is busy; do not touch or unplug it. This usually indicates a process such as a firmware upgrade is taking place.
• Quickly Flashing Blue - This is used to locate an AP. When you click Locate in the UniFi Controller software, the AP will flash. It will also display the location of the AP on the map.
• Steady Blue - Indicates the device has been successfully integrated into a network and is working properly.
• Steady Blue with occasional flashing (once every 3 or 4 seconds) - Indicates the device is in an isolated state (all WLANs are brought down until an uplink is found).

What mobile devices have you tested?

We recognised that mobile devices in a wireless network is a big thing and we've been constantly working on testing and fixing issues. In our lab, we had iPads, iPod 3G/4G's, Andriod phones (HTC Desire, DesireHD, Surround, Mozart, Motorola Driod X, Samsung Galaxy S2, Galaxy Tab, Galaxy Nexus), Blackberry Torch and Bold, Nokia N8, Amazon Kindle.
People also bring their mobile devices to connect our UniFi wireless networks: iPhones (all generations), iPads, Android (Samsung GalaxyS, i9000, Epic, Motorola Driod, Droid2...), and Andriod tablets (Galaxy Tab)

Features

Many of the features are well-documented in UniFi User Guide.

Wireless Uplink

Overview

Instead of offering WDS (difficult to setup and change) or Mesh (unpredictable uplink selection), we simply provide a feature called 'Wireless Uplink'.
It allows you to well, use wireless as AP's uplink. And more importantly, it allows you to change your topology on the fly. This design provides:

• easy to setup/change: you don't see configuration about Mac addresses, passphrase as it's all done by UniFi. Therefore, you can focus on topology, etc.
• predictable: once you've picked the uplink and satisfied with the quality, it will work today, tomorrow, and thereafter

Wireless Uplink Setup

Note: For a video walkthrough of configuring a wireless uplinks, see this video tutorial.

The Wireless Uplink is designed to be reliable rather than quick/dynamic. Please be patient for the isolated state change, the discovery, and the link setup. A general topology will be something like below:

• Switch -----(wire)--------- Uplink AP )))))))(wireless))))))))) Island AP

WARNING - For system upgrade, disable "automatic upgrade" and always manually upgrade the isolated AP first.

To enable wireless uplink:

• Adopt all APs through wire first (using Ethernet cable). In other words, adopt both uplink and island APs.
• Put the island AP to the intended location and connect its power. This means connect power adapter POE port to the island AP, but leave power adapter LAN port empty.
• After the island AP is up, on the controller, wait until it becomes "Heartbeat Missed" and then "Disconnected" or "Isolated" state (takes about 6+ minutes). It will _not_ service any configured WLANs at this moment.
• Go to AP dialog->Configure->Wireless Uplink, select the uplink AP of your choice (click on "Find more" if no uplink AP is shown)
• The controller establishes wireless uplink between the selected uplink AP and the island AP. The island AP is now wireless connected and serving.

Technical details - Isolated AP

A new status, Isolated, is introduced. When the AP is unable to reach the gateway, it goes into Isolated state. In this state,

• all servicing WLANs are disabled (if we cannot reach the gateway, wireless clients won't either)
• has different LED pattern - steady green (managed) with occasional dims
• AP will send out beacon over the air and can be found by nearby APs
• Only the wired APs under the same controller can establish a downlink to this isolated AP
• by default, wired APs don't go off-channel to look for isolated APs. "Find more" trigger wired APs to do so. And after wireless uplink is set up, the isolated AP will always find and follow the same channel use by its uplink AP

L3 (Layer 3) Management

Overview

In many deployments where it's not possible/desired to have controller running at the premise, you can run the controller in the cloud or your NOC.
Say we got an new project, we could

• on amazon, create a Ubuntu controller instance on Amazon
• configure/stage a few APs in our lab and customize the guest portals
• when we're at the customer's site, open a browser to the cloud-based controller
• either configure DHCP server, DNS server, or simply use the UniFi Discovery Utility to make all local APs inform back to the controller
• on-going management/monitoring can be done anywhere and Amazon would provide us with great firewall configurations

Setup

Please make sure you're familiar with how UniFi works (e.g. where AP and Controller is in the same L2) before you attempting L3 Management. L3 management adds many moving parts in the mix (i.e. added complexity).
UniFi AP has a default inform URL http://unifi:8080/inform. Thus, the purpose of using DHCP option 43 or DNS is to allow the AP to know the IP of the controller.

To use DHCP Option 43

To use DHCP Option 43 You'll need to configure your DHCP Server. For example:
Linux's ISC DHCP server: dhcpd.conf

# ...
option space ubnt;
option ubnt.unifi-address code 1 = ip-address;

class "ubnt" {
        match if substring (option vendor-class-identifier, 0, 4) = "ubnt";
        option vendor-class-identifier "ubnt";
        vendor-option-space ubnt;
}

subnet 10.10.10.0 netmask 255.255.255.0 {
        range 10.10.10.100 10.10.10.160;
        option ubnt.unifi-address 201.10.7.31;  ### UniFi Controller IP ###
        option routers 10.10.10.2;
        option broadcast-address 10.10.10.255;
        option domain-name-servers 168.95.1.1, 8.8.8.8;
        # ...
}

Cisco CLI

# assuming your UniFi is at 192.168.3.10
ip dhcp pool <pool name>
network <ip network> <netmask>
default-router <default-router IP address>
dns-server <dns server IP address>
option 43 hex 0104C0A8030A # 192.168.3.10 -> CO A8 03 0A

# Why 0104C0A8030A ?
#
# 01: suboption
# 04: length of the payload (must be 4)
# C0A8030A: 192.168.3.10

Mikrotik CLI (from rclewis)

/ip dhcp-server option add code=43 name=unifi value=0x0104C0A8030A
/ip dhcp-server network set 0 dhcp-option=unifi

# Why 0104C0A8030A ?
#
# 01: suboption
# 04: length of the payload (must be 4)
# C0A8030A: 192.168.3.10

Cisco has a good write-up for DHCP option 43 setup.

To use IP of controller

• You can also use the IP of the controller in the inform URL instead of the domain name.

To use DNS

• You'll need to configure your DNS server to resolve 'unifi' to your controller's IP address. Make sure that AP can resolve controller's domain name. For example, if you are setting http://XYZ:8080/inform, then ping from AP to determine if XYZ is resolvable/reachable.
• Or, using FQDN for the controller inform URL, http://FQDN:8080/inform
• Troubleshooting - AP (with static IP) fails to connect to the L3 controller
  • when configured an AP from DHCP to static in the controller UI, make sure you have put the IP of DNS. If not, then the AP cannot contact DNS to resolve controller domain name.
  • if the AP has been reset (by pushing reset button), make sure that you have informed AP twice (using discovery utility) about the controller's location (this will be improved in the coming release 2.3.0)

To use UniFi Discovery Utility

Not many environments can have a DHCP server that's configurable, even less likely with a DNS server.
That's where UniFi Discovery Utility comes in. It listens to the multicast/broadcast packets from UniFi APs and allow you to tell the AP to inform any URL you'd like. (only APs in default state or not in contact with any controller will be displayed)
UniFi Discovery utility is installed along with your UniFi controller.

• On Windows, it's in Start Menu->Ubiquiti UniFi->UniFi-Discover
• On Mac, /Applications/UniFi-Discover.app (or use Spotlight to find it)
• run "java -jar <unifi_base>/lib/ace.jar discover"

To perform L3 adoption with the discovery utility:

1. wait until the AP shows up
2. if the AP is not in default state. click "reset", specify the SSH username/password and click "Apply"
3. click on "manage", modify the inform URL and leave the SSH username/password as ubnt/ubnt and click "Apply"
4. open a browser to your remote UniFi controller and you should see it being "Pending Approval"
5. Click on "approve". You'll see it going to "Adopting" state, ignore it as it'll eventually become "Adoption Failed" or "Disconnected"
6. perform [3] again (no need to wait for [5] to finish)
7. AP is now managed by the controller

Discovery Utility works with APs with firmware 1.2.3 and 1.3.2 as well. Once adopted by the 2.0 Controller, it will upgrade these units automatically.

To use SSH

If you can SSH into the AP, it's possible to do L3-adoption via a under-construction CLI command:

# 1. make sure the AP is running the latest (or 2.1.0+)
#    if it's not, do
#    syswrapper.sh upgrade http://ip-of-controller:8080/dl/firmware/BZ2/version-of-ap-see-ref-table-below/firmware.bin
# 2. make sure the AP is in factory default state
#    if it's not, do
#    syswrapper.sh restore-default
# 3. ssh into the device and type
mca-cli
# the CLI interface:
set-inform http://ip-of-controller:8080/inform

Controller Version	AP Upgrade URL
2.3.9	http://ip-of-controller:8080/dl/firmware/BZ2/2.3.9.1693/firmware.bin
2.3.8	http://ip-of-controller:8080/dl/firmware/BZ2/2.3.8.1597/firmware.bin
2.2.5	http://ip-of-controller:8080/dl/firmware/BZ2/2.2.5.1080/firmware.bin
2.2.4	http://ip-of-controller:8080/dl/firmware/BZ2/2.2.4.1072/firmware.bin
2.2.3	http://ip-of-controller:8080/dl/firmware/BZ2/2.2.3.1055/firmware.bin
2.2.2	http://ip-of-controller:8080/dl/firmware/BZ2/2.2.2.1049/firmware.bin
2.2.1	http://ip-of-controller:8080/dl/firmware/BZ2/2.2.1.1045/firmware.bin
2.2.0	http://ip-of-controller:8080/dl/firmware/BZ2/2.2.0.996/firmware.bin
2.1.0	http://ip-of-controller:8080/dl/firmware/BZ2/2.1.0.942/firmware.bin

Guest Access

Overview

We understand guest access is an important part of wireless system offering. In release 1.x, we're targeting a few groups of users. In release 2.x, we'll provide a customizable guest portal with billing system integrated.
Here are the targeted scenarios for 1.x:

I just want to provide free and simple guest access
Recommendation: In Wireless Configuration, enable "Apply Access Policies".
This turns on guest isolation and subnet restrictions (which can be customized in Settings->Guest Control), etc. - making sure guest cannot access your corporate network. If you choose Open for security, it's pretty much a connect-and-go, no guest portal, no "Terms of Use" or anything. UniFi controller doesn't even have to be running! You still have the option to choose WPA-Personal - just need to have a way to tell the guests the Passphrase.

I think I need to show "Terms of Use"... just to play safe
Recommendation: In Wireless Configuration, enable "Apply Access Policies". In Settings-> Guest Control, enable Guest Portal and choose "No authentication".
Enabling "Guest Portal" puts the guest in a walled garden. In plain English, the connected guest can get an IP, do DNS lookup; however, all other traffic is blocked. The HTTP/HTTPS traffic will be redirected to the guest portal (in this case, the UniFi controller) _before_ they're authorized. After they get authorized, they'll have access to the networks not restricted by the "Restricted Subnets" configuration.
This works very much like what you usually see in Starbucks or Airports. You connect to a open wireless network, open a browser and go to www.google.com, gets redirected, accepts Terms of Use, and you go! You may get redirected to a Promotional URL or the original URL you intended. Moreover, you get a few hours of free access depending on the operators' policies.

• After 1.3.2, you also have the option of specifying the Expiration time. After the 'authorization' expires, the guest will be prompted with the Guest Portal again.

I don't want just anyone to get in. How do I limit the access?
Recommendation: In Wireless Configuration, enable "Apply Access Policies". In Settings-> Guest Control, enable Guest Portal and choose "Simple Password".
When the guest is prompted with the guest portal, s/he will not only need to accept the Terms of Use but provide a password. There's nothing fancy/flexible but we see this is a quick-and-easy way.
Another way is to use WPA-Personal and disable guest portal all together as you need to tell the guests a password anyway.

I need to customize the portal page and use my own way to authorize the user (e.g. making the user pay)
Recommendation: In Wireless Configuration, enable "Apply Access Policies". In Settings-> Guest Control, enable Guest Portal and choose "External Portal Server". Then take a look at portal_sample.zip (if running 1.3.2) or portal_sample.zip (if running 2.2.0)
Out of the gate we know our guest portal feature is limited. External Portal Server is for advanced integrators who can install/program their portal web server. UniFi will set up the policies so guests will be redirected to the specified External Portal Server (traffic-wise, port 80 and 443 will be forwarded). An API is provided to tell the controller something like "authorize guest[00:15:34:93:e3:f2] for 4 hours". UniFi controller will take it from here.

I already have my own L3 implementations for this
Recommendation: well... some may opt to use UniFi AP to serve WiFi and have their own walled-garden/guest portal implementation already. I believe these folks know what they're doing.

VLAN

It's more than natural to think of VLAN when guest access is mentioned. However, there are a few technical details to talk about.
Let's start with the basic VLAN deployment where guest portal is not enabled:

1. UniFi AP tags wlan->wire traffic
2. AP-controller is untagged
3. controller is likely running on untagged interface
4. configured inside the AP:

guest --- br0.3 --- eth0.3 --3--+
          br0 ------------------+--u,3---port1
corp  -----+ 

Deployment example:

• port8 connecting to router's DMZ port, add port8 as member of vlan3 and untagging. enable DHCP server on your DMZ
• port5 connecting to internal network, have port5 untagged.

What happens when Guest portal enabled with VLAN
When guest portal is enabled, the controller acts as a portal server and the guests will be redirected to http://unifi_ip:unifi_http_portal_port/guest/. This is where the issues may arise - guest is on vlan3, bridged to DMZ, there's no way it can reach unifi_ip:unifi_http_portal_port.
In the scenario above, one solution to the problem is to add rules to your router

1. add route for traffic from DMZ->unifi_ip
2. allow DMZ->unifi_ip:unifi_http_portal_port

Another solution, where we envision this moving up in scale, is to have the controller running at NOC or cloud.

Hotspot

Overview

UniFi's hotspot system is a self-contained, full-featured and fully-customizable solution that you can deploy easily.

Setup

1. Settings->Guest Control, enable Guest Portal
2. Select "Hotspot" for authentication and you'll see a new section for Hotspot config
3. Two authorization scheme can be used (at least one has to be selected)

Hotspot Manager

Hotspot Manager is for people like hotel receptionists to service the wireless guests in case any issue comes up. It's also used for voucher creation/maintenance.
The hotspot manager is at https://<unifi-ip>:<port>/hotspot
Try creating a hotel operator account:

• click on the Hotspot Manager link
• in Operator Accounts tab, add operator account
• logout and login again with the operator account you just created
• this is the view hotel operators can see
• hotel operators won't be able to access UniFi admin interface

Hotspot - Portal Customization

Overview

Many guest portal implementations allow you to change logo, text, and maybe styles. Some allow you to do more but with their mediocre UI and you can only hope it will come out OK after each modification. Some have disk space limitations, fixed directory structures, and all sorts of restrictions.
Not with UniFi! We pretty much open up the whole portal/ directory (i.e. put as much or as little graphics, videos as you'd like), use plain .html format (i.e. use any editor of your choice), and allow instant testing (i.e. once the file is saved, reload the page from the guest's browser and you see how it looks).
Moreover, you can create multiple hotspot packages - each with different payment, name, duration of use, bandwidth limit.

Setup

1. In Settings->Guest Control, enable Guest Portal and Portal Customization, Apply
2. a copy of the portal pages (ones that's being served) will be copied to <unifi_base>/data/portal
3. use another PC to connect to the guest network and and use the browser to go to any website
4. you will see the default portal pages
5. modify the pages (e.g. the <title>) and reload the browser on the client

<unifi_base> is at

• Mac:/Applications/UniFi.app/Contents/Resources
• Windows:"%userprofile%/Ubiquiti Unifi",
• Linux:/usr/lib/unifi.

Sample Portal

The sample portal is, while useful by itself, written in a way that it demonstrates most features in the simplest format.

# directory structure
index.html    : the main landing page
bundle/messages.properties: for localization and hotspot package specification
payment.html  : for credit card information submission. requires https, also served as an example of additional .html page
fail.html     : default page when there's error handling guest login

supporting files: 
images/
js/
reset-min.css
styles.css

Notes:

1. all .html pages goes through the rendering engine and can be a target of form's POST action
2. all the supporting files are not required and you can roll your own

And to explain further, let's go through some scenarios:

Scenarios

Scenario: can I just modify something and see if it works?

1. on controller: enable Guest Portal, select No Authentication
2. modify index.html: find

   "<h2>Terms of Use</h2>"

   and change it to

   "<h2>Welcome to Joe's Guest Portal!</h2>"

3. have another device connects to the guest wireless network and open the browser to any URL

Scenario: I just need to show a Terms of Use with customized portal
on controller: enable Guest Portal, select No Authentication

1. look at the bottom portion of index.html and you can delete everything not related
2. all that's required is the form POST to /guest/login to authorize the user
3. the sample page requires the user to accept Terms of Use by disabling the submit button if they don't check the "I accept the Terms of Use"

Scenario: How do I do the password authentication
on controller: enable Guest Portal, select Simple Password

1. Find the section enclosed by <unifi if="auth_password"> ... </unifi>
2. requires the form POST ("password")
3. the hidden "page_error" indicates which page will render the error, in the sample, index.html
4. that leads us to look at the secion of <unifi if="has_error"> where either the localized error <unifi error="error" /> or a welcome title <unifi txt="PasswordRequiredForWirelessAccess" /> will be shown

Scenario: How do I integrate UniFi controller with Paypal Pro or Standard accounts
We have compiled step-by-step examples that demonstrate how UniFi hotspot can be integrated with Paypal Pro and Standard accounts. UniFi and Paypal Integration

voucher customization

Currently the voucher customization is not implemented yet. However, you can try to modify webapps/ROOT/pages/voucher.jsp before we enhanced this.
NOTE: make sure you have this file backup somewhere as it will be wiped out during controller upgrade/reinstall.
The JSP code is HTML-like and modifiable. The current implementation prints 4 vouchers per row with minimum formatting.

<td>
    <p class="valid">Valid for <%=valid%></p>
    <p class="code"><%=code%></p>
</td>

Another approach is to use API to create vouchers, and naturally you'll get the details of the voucher in JSON for custom formatting/printing (e.g. sending it to a receipt printer).

portal page syntax and variables

unifi tags

<unifi var="name" />

a few vars are populated where you can use <unifi var="varnames" /> to render it in the HTML page

• auth: none | password | hotspot
• auth_none: false | true
• auth_password: false | true
• auth_hotspot: false | true

• voucher_enabled: false | true
• payment_enabled: false | true

• package: the package id (from POST or GET)
• mac: guest's MAC address
• ap_mac: AP's MAC address
• ap_name: AP's name
• map_name: AP's location (name of the map)
• ssid: the SSID of the wireless network

• error: error message
• has_error: false | true

<unifi include="header.html" />

to include another HTML page

<unifi if="name" eq="value"> ... <unifi else="var" /> ... </unifi>

the simple if/then/else logic to determine if a section of the page should be shown use <unifi if="!name" eq="value" > ...</unifi>

<unifi txt="InvalidPassword" />

text localization, see bundle/messages.properties

<unifi url="payment.html" https="true" />

generates the URL (and possibly change it to HTTPs) relatively

/guest/login

this is the URL the user will POST to get authorized, it takes the following parameters:

• by: type of authentication (for hotspot): voucher | credit | paypal
• package: package id (for hotspot)
• voucher: voucher code (for hotspot/voucher)
• cc_xxxxx: credit card information (for hotspot/credit):
• landing_url: use a dynamic landing URL (which can be constructed by using vars)
• page_error: relative URI when error occurs (fail.html is the default)

credit card related fields: cc_firstname, cc_lastname, cc_number, cc_year, cc_month, cc_ccv2 cc_addr1, cc_addr2, cc_city, cc_state, cc_zip, cc_country, cc_email

bundle/messages.properties:package definitions

## package 1
# amount is in US dollars
package.1.amount=5.99
# default currency is USD
package.1.currency=USD
package.1.hours=8
# what's shown in the Hotspot Manager
package.1.name=Basic 8HR
# what's shown on the credit card statement
package.1.charged_as=Hotspot 8-hour WiFi

## package 2
package.2.amount=8.99
package.2.hours=24
package.2.name=Premium Daypass
package.2.charged_as=Hotspot 1-day WiFi

## package 3
# this is a free trial package (with amount 0)
package.3.amount=0
package.3.hours=2
package.3.name=Free Trial
# whether to overwrite the user group policy per WLAN/User, default is false
# only available in release-2.1.0
package.3.limit_overwrite=true
# kbps, default is unlimited
package.3.limit_down=4096
# kbps, default is unlimited
package.3.limit_up=1024
# Mbytes, default is unlimited
package.3.limit_quota=1024

I see "Certificate Error" when redirected to PayPal website. What's wrong?

According to here which links to here
"Starting September 12, 2012, www.paypal.com will start resolving to a dynamic list of IP addresses and as such cannot be whitelisted."
People using Website Payment Pro with Direct Payment (Credit Card payment) are not affected. However, if you use Express Checkout, setting up guest portal firewall rules is getting much more challenging.

For people using PayPal payment in UniFi, we would suggest

• Stick with Credit Card Payment Only (it works flawlessly as controller is the one talking to Paypal's payment gateway)
• Configure DNS so it resolves www.paypal.com to a handful of IPs that you can configure in the controller's Allowed Subnet
• combining the new config.properties:captive_portal_subnets in 2.3.9 (to be released), add

config.captive_portal_subnets=173.0.80.0/20 66.211.160.0/19 64.4.240.0/20 66.235.128.0/19 66.135.192.0/19 66.151.153.9 [...]

[...] would be
1. individual IPs from the list paypal published or the fixed IP(s) you added in your DNS config
2. paypalobjects.com (see below)

paypalobjects.com

Paypal.com has references to paypalobjects.com and, unfortunately, resolves to different IP/subnets in different countries. You may

• do a "nslookup www.paypalobjects.com" at the region where it will be used, you'll get something like "184.51.102.85"
• do "whois 184.51.102.85" on Linux or http://networking.ringofsaturn.com/Tools/whois.php like the following:

NetRange:       184.50.0.0 - 184.51.255.255
CIDR:           184.50.0.0/15
...

• add "184.50.0.0/15" to Allowed Subnets in Settings->Guest Control

I see incomplete PayPal website screen. What's wrong?

see above.

Can I have my portal page on HTTPS?

Change your index.html to the following:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
    <title>Redirecting...</title>
    <meta http-equiv="REFRESH" content="0;url=<unifi url="index_secure.html" https="true"/>">
</head>
<body>
</body>
</html>

and have your real index.html in index_secure.html

Install the controller in "the cloud" -- Amazon Web Services (AWS)

Overview

With L3 Manageability, we've essentially enabled the capability of running the controller in the cloud. We believe this makes UniFi the most versatile enterprise WiFi system in terms of deployment options.
This post will be describing how you can run your controller on AWS (Amazon's Web Service) and how you can get your APs managed by the controller hosted on it.

Setup

It's assuming that you have some understanding about AWS and have tried it. If not, don't worry, go to the end and get a quick tutorial.

Create the controller instance
There's a AMI created for you - ami-ca2ef3a3 (or you can search for UniFi 2.2.5).
Note: this AMI is current available only in US-East region, will copy it over to others soon.

1. launch AWS Management Console
2. Images->AMI, search for the ami by 'ami-ca2ef3a3'
3. Click "Launch", a micro instance will do. Click "Continue"
4. In "Instance Details", use the default options. Click "Continue"
5. for keys/values, do nothing, Click "Continue"
6. Select a Key Pair you'd like to use or create a new one
7. Create a new Security Group, UniFi, with
   1. TCP 8080
   2. TCP 8443
   3. TCP 8880
   4. TCP 8843
   5. TCP 22
   6. UDP 3478
8. Click Launch
9. Go to Instances->Instances, after the instance is Up, select the instance find the "Public DNS" at the lower panel. This is the hostname that you can use to manage the controller and the one that APs will use for inform (something like ec2-50-19-7-124.compute-1.amazonaws.com)

AP Adoption and management

1. Open a browser to URL like "https://ec2-50-19-7-124.compute-1.amazonaws.com:8443/", go through the wizard
2. With your 2.x.x AP in their default state in the same L2, launch the UniFi Discovery Utility
3. Click Manage and change the inform URL to something like "http://ec2-50-19-7-124.compute-1.amazonaws.com:8080/inform". Click "Apply"
4. You'll see the device showing up as pending on the controller UI. Click "Adopt".
5. (Controller will attempt to SSH right away and fail, ignore the status)
6. On the Discovery Utility, you should still see the AP showing up as Pending, perform (3) again
7. This time the AP will be adopted successfully.

Where to go from here?
Note that the AMI is for testing purpose, for production, you may want to:

• get a domain name and/or elastic IP - as the public DNS will change once you stop/start the instance
• create bigger EBS or mount additional volumn for UniFi

Amazon AWS
Amazon AWS is probably the most versatile hosting platform you can ask for. They're even offering a free tier for people to try for a year. Signing up is easy and you can use the amazon.com account you're using (http://aws.amazon.com/free/)
After sign up, go to https://console.aws.amazon.com/ec2 and follow the steps mentioned above.

Advanced

Custom SSL certificate

On Linux using apt:

sudo su -
# cd <unifi_base> 
# on Windows, "%USERPROFILE%/Ubiquiti Unifi"
cd /usr/lib/unifi 

# create new certificate (with csr)
java -jar lib/ace.jar new_cert <hostname> <company> <city> <state> <country>

# your CSR can be found at /var/lib/unifi
# - unifi_certificate.csr.der
# - unifi_certificate.csr.pem

# have this CSR signed by a CA, you'll get a few certificates back...
# copy the signed certificate(s) to <unifi_base>

# import the signed certificate and other intermediate certificates
java -jar lib/ace.jar import_cert <signed_cert> [<other_intermediate_root_certs>...]

UniFi Controller API

While we offered a few scripts for people to use API to perform some actions against the controller, we haven't publicly announced yet.
However, we think it's time to start something. Be aware, though:

• backup your DB often and stay with those we included. At the current state, not all parameters are checked.
• Treat the APIs experimental and subject to change

Overview

To perform API operations, download unifi_sh_api and here's a sample script to authorize a guest for X amount of time

#!/bin/sh

## define required variables
username=admin
password=admin
baseurl=https://localhost:8443

## include the API library
. unifi_sh_api

unifi_login
# unifi_authorize_guest <mac> <minutes> [up=kbps] [down=kbps] [bytes=MB]
unifi_authorize_guest $1 $2
unifi_logout

Polycom SpectraLink Phones support

Polycom SpectraLink 8440 phones does NOT support TKIP/AES mixed mode. The phone, if set to WPA2-PSK, connects when the WLAN is configured in Both and AES-only; the phone, if set to WPA-PSK, connects when the WLAN is configured in Both and TKIP-only. U-APSD also needs be enabled as described in earlier posts.
This setup can be verified by the configuration guide published by Polycom for Cisco. http://support.polycom.com/global/do...co_unified.pdf
In page 30,

• For WPA2-PSK, under WPA+WPA2 Parameters:
  1. Select the WPA2-Policy check box.
  2. Select the AES check box for WPA2-Encryption.
• For WPA-PSK, under WPA+WPA2 Parameters:
  1. Select the WPA-Policy check box.
  2. Select the TKIP check box for WPA Encryption

Note that these essentially imply to enable only one mapping encryption method on WLAN. Same configuration also needs to be applied on Ubiquiti Unifi.
Regarding permanent changing U-APSD, please follow the instructions in this section, http://wiki.ubnt.com/UniFi_FAQ#How_can_I_customize_how_AP_is_provisioned_.28e.g._NTP_server.2C_U-APSD.29

Under The Hood

AP - Controller Management Protocol

Overview

AP discovery is done with L2 multicast/broadcast in order for controller to see it. The adoption is done by controller SSH into AP to tell the AP where the controller is. After that, it's all AP calling home to perform tasks controller asks it to do. All the AP-controller management traffic goes un-tagged.
The design has L3-management in mind where you can set up controller in the clouds.

Adoption

Initial Handshake

• When an AP is in factory default (LED shows steady amber/orange), it will obtain an IP from DHCP server and send out beacons - "I'm at factory default settings. Who can manage me?"
• Controller hears the beacon. As this device is in default state, shows the AP as PENDING.
• When the user decides to adopt the AP, controller will adopt the AP via SSH (using the IP information in the beacon and the default username/password)
• AP sends initial inform to http://controller_ip:8080/inform, the binding of controller-AP is now completed

When the AP is already adopted

• When an AP has been adopted (LED shows steady green) but the controller is not present, the AP sends a slightly different beacon - "I'm here. When you (the controller) are up/ready. Come pick me up."
• When the original controller comes up, it hears the AP's beacon and finds that the AP is under its management. It will readopt the AP automatically via SSH (using the IP information in the beacon and with the non-default credential).

Management

The Controller manages the AP using a proprietary TR-069-like management protocol. The main idea, for scalability, is for AP to phone home periodically via L3. And to support instant notifications from controller->AP, STUN is also used.

Is the proprietary communication between APs and the Controller encrypted?

Yes, the protocol is encrypted.

Can I put the controller in a different subnet?

See L3 Management

Posted in: Wifi