Skip to content

controller-install.org

Latest commit

 

History

History
270 lines (216 loc) · 11.1 KB

controller-install.org

File metadata and controls

270 lines (216 loc) · 11.1 KB
Raw

Install Unifi Controller

Network map

internet <--->   UniFi USG <-- LAN 2 --> UniFi Controller
                      ^
                      | LAN 1
                      v
participants <---> unmanaged switch <---> wireless AP

Most of the configuration takes place on the Unifi controller.

We run the controller ourselves on Debian, with the Unifi controller software installed.

Network configuration

As seen in the Network Map, the UniFi USG has two LAN ports. We use LAN2 for the ‘Corporate’ network, without captive portal. And we use LAN1 for the ‘Guest’ network.

Everyone, except for the controller and select circumstances, is in the LAN1 ‘Guest’ network. Which, by default, blocks all network access except for allowed users. Users will be allowed when the authenticate with a voucher.

Note that we will also put devices such as a steam cache in the LAN1 network. These instances should NOT be put in the LAN2 network, because the connection between the LAN1 and LAN2 ports on the USG is not very high-bandwith (there is no good switching hardware there). About the only reason to put hardware in the LAN2 network, is debugging.

Theory of operation

Participant flow

  1. Participant arrives at LAN, connects PC to network
  2. Participant goes to a webpage
  3. Participant is redirected to http://portal.gepwnage.lan
  4. Participant enters his voucher and clicks “Register on network”
  5. Participant is redirected to the status page
  6. Participant has access to the network

Portal <-> Unifi Controller communication

  1. When the participant visits http://portal.gepwnage.lan, the portal takes the IP of the user, and requests all the leases from the unifi controller. From here, the portal finds the MAC address of the user, which the controller needs to approve the lease.
  2. When the voucher is entered into the portal, the portal verifies the voucher. And if it is valid, the lease is approved.

API calls

  • list_clients(), to retreive all clients so we can get the MAC address from the local IP.
  • authorize_guest(), to authorize the participant on the LAN network.

How to install on Raspberry Pi 4

These instructions probably can be easily adapted to any Debian OS.

The first steps should be done connected to a network outside of the USG, or the network on port LAN1 of the USG. Especially if the USG has factory settings.

Install Raspbian Lite

Download raspbian from https://www.raspberrypi.org/downloads/raspbian/ and dd it onto an SD-card.

To enable SSH on first boot, create an emtpy file named ssh in the /boot directory of the SD-card.

SSH-ing in, the default username and password for Raspbian are pi and raspberry. Do not forget to change this!

An option is to create a different user using adduser and remove the pi user using sudo deluser pi.

Also, make sure that SSH will start in the future, by executing sudo systemctl enable ssh

Set the hostname to controller using:

echo "controller" | sudo tee /etc/hostname

And edit /etc/hosts and change the hostname there as well.

Note that we will not setup a static IP address. During the setup, we can find the controller IP using nmap. Later we will set an IP address for the controller using the controller software. Thus, the controller will get an IP with DHCP, but that will always be the same IP.

Install the UniFi Controller Software

Add the repository and GPG key:

echo 'deb http://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list
sudo curl -o /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ubnt.com/unifi/unifi-repo.gpg

Install the controller:

sudo apt update
sudo apt install openjdk-8-jre-headless unifi
sudo apt upgrade # so we also install all debian updates

Execute sudo systemctl reboot to reboot the Pi and get started.

Note that it is important that Java 8 is installed. The unifi software doesn’t work with different versions.

UniFi Network Settings

If you don’t know the controller IP, use: nmap 192.168.1.0/24 to find it (this is the factory default USG IP range, if this has been changed, use that IP range).

The controller will have ports 8080 and 8443 active. You should navigate to https://<controller-ip>:8443 in your browser and accept the certificate to continue to the setup.

UniFi setup

When the setup runs, choose GEPWNAGE LAN as the controller name.

In the second step, choose advanced setup. Disable cloud access and using the ubiquity account for local access. Instead, create a user on the controller itself.

During WiFi setup, choose GEPWNAGE LAN as SSID with the correct password.

You can immediately adopt the USG at the end of the setup.

Most other settings can be left at defaults, but check them to be sure.

First stage settings

In the first stage, the controller should be connected to the LAN1 port of the USG. We want to move it to the LAN2 port. Thus, we create a new network.

NameAdmin
PurposeCorporate
Network GroupLAN2
PortWAN 2 / LAN 2
Gateway / Subnet10.13.42.1/24Note: click update DHCP range when asked
Domain Nameadmin.gepwnage.lan
DHCP ModeDHCP Server

Leave all other settings to their defaults.

Save and wait until the USG has finished provisioning (can take a few minutes) and move the controller to the WAN 2 / LAN 2 port.

Setup DNS and fixed IP for controller

Go to Clients and select the controller. Under Configuration > Network, set Use fixed IP address and give it the IP address 10.13.42.3 in the Admin network.

Using SSH on the controller, edit /usr/lib/unifi/data/sites/default/config.gateway.json (create the directories if they don’t exist) and configure as follows for static DNS:

{
    "system": {
        "static-host-mapping": {
            "host-name": {
                "portal.gepwnage.lan": {
                    "inet": [
                        "10.13.42.3"
                    ]
                }
            }
        }
    }
}

Then force provision the USG by going to Devices, select the USG and go to Config, under manage device click the Provision button under Force provision.

Second stage settings

After the controller is reconnected, find it again using nmap 10.13.42.0/24 and connect to it. This assumes that the current computer is connected on the LAN1 port and the controller on the LAN2 port.

We change the network on the LAN1 port:

NameGEPWNAGE LAN
PurposeCorporateNote: this will become Guest later, but not yet
Network GroupLAN
PortLAN1
Gateway / Subnet10.13.37.1/24Note: click update DHCP range when asked
Domain Namegepwnage.lan
DHCP ModeDHCP Server

Leave all other settings to their defaults.

Again, save and wait for provisioning.

Create an (API) user on the controller for the portal

Under Settings > Admins, add a new admin. Manually set and share the password. Generate a secure password somehow. Should not be read-only, and does not need additional permissions.

Install the portal

First install all requirements:

sudo apt update
sudo apt install nginx npm php-fpm php-curl php-sqlite3 composer build-essential

Clone this repository to /var/www/lan:

cd /var/www
sudo chown -R www-data:www-data .
sudo -u www-data git clone https://github.com/gepwnage/lan-portal.git

Go into the portal directory, configure the environment and install dependencies:

cd /var/www/lan-portal

sudo -u www-data cp .env.example .env
# edit the .env file, and set the UNIFI_USERNAME and UNIFI_PASSWORD to the API user created earlier
sudo -u www-data vim .env

sudo -u www-data composer install --no-dev -o
sudo -u www-data php artisan key:generate

sudo -u www-data touch database/database.sqlite
sudo -u www-data php artisan migrate

sudo -u www-data npm install
sudo -u www-data npm run production

Edit the nginx config /etc/nginx/sites-enabled/default and apply the following changes:

  • Change the root to /var/www/lan-portal/public
  • Add index.php to the index list
  • In the try_files directive under location / change =404 to /index.php?$query_string
  • Uncomment the PHP FastCGI section (except for the TCP socket line).
  • Add a listen directive for port 8000 (to keep the portal reachable for admin purposes)

Edit the nginx config file /etc/nginx/snippets/fastcgi-php.conf and change the try_files directive. Replace =404 with /index.php.

Test the nginx config and if it succeeds, restart php-fpm and nginx:

# only continue if this succeeds
sudo nginx -t
sudo systemctl restart php7.3-fpm nginx

Now going to http://portal.gepwnage.lan should show the GEPWNAGE portal. Make sure that it is not just waiting for data. It should also show client details.

UniFi Captive Portal configuration

Under Guest Control, check Enable Guest Portal. Under Authentication, select External portal server and set the IP address to 10.13.42.3. Set Redirect using hostname to http://portal.gepwnage.lan and add 10.13.42.3 to Pre-authorization access and remove all post-authorization restrictions.

In the GEPWNAGE LAN (LAN1) network, change the purpose to Guest.

After applying all this, anyone on the LAN1 port should not have internet access, and have to visit http://portal.gepwnage.lan and fill in a voucher to get internet access.

Troubleshooting

Mating UniFi Controller and USG

The UniFi controller and USG may not mate (connect) automatically. For this to work, SSH into the USG (default username and password is ubnt:ubnt), and execute the following:

mca-cli
set-inform http://ip-of-controller:8080/inform
# go to the controller web interface, login, go to the devices tab, approve the connection, and again:
set-inform http://ip-of-controller:8080/inform

Sources