UniFi Network: Complete Homelab Setup Guide

Introduction

Ubiquiti’s UniFi ecosystem has revolutionized networking for enthusiasts and small businesses, delivering enterprise-grade features at prosumer prices with elegant, intuitive management. From humble beginnings with a single access point, UniFi has evolved into a comprehensive networking platform including switches, routers, security gateways, and sophisticated management software. This guide will walk you through deploying a complete UniFi network in your homelab, from initial controller setup through advanced optimization techniques.

What You’ll Learn

Installing and configuring the UniFi Network Controller
Adopting and managing UniFi devices
Creating VLANs and networks for segmentation
Optimizing WiFi performance and coverage
Setting up guest networks with portal authentication
Implementing network security and firewall rules
Advanced features: DPI, traffic shaping, and QoS
Monitoring network health and performance
Troubleshooting common UniFi issues
Integration with homelab infrastructure

Why Choose UniFi?

Unified Management: Single pane of glass for all network devices. No juggling multiple interfaces for switches, APs, and routers.

Enterprise Features, Prosumer Price: VLANs, advanced WiFi, detailed analytics, captive portals, and more - features typically costing thousands, available for hundreds.

Scalability: Start with one access point, grow to dozens of devices. The system scales seamlessly from home to small business to campus.

Active Community: Massive r/Ubiquiti community, comprehensive documentation, and regular firmware updates. When you have questions, answers exist.

Professional Appearance: Clean, modern hardware that looks at home in both residential and professional environments. WAF (Wife Acceptance Factor) is high.

API and Automation: Robust API enables scripting, automation, and integration with home automation platforms.

Prerequisites

Hardware Requirements:

Minimum Setup:

UniFi Network Controller (software - can run on various platforms)
One UniFi device (Access Point, Switch, or Gateway)
Computer for initial setup
Internet connection

Recommended Homelab Setup:

UniFi Dream Machine or Cloud Key for controller
1-3 UniFi Access Points (coverage dependent)
1-2 UniFi Switches (PoE capable for powering APs)
Optional: UniFi Gateway for advanced routing

Controller Hardware Options:

Cloud Key Gen2 Plus: Dedicated hardware, includes UniFi Protect
Dream Machine/Pro: All-in-one (router, switch, AP, controller)
Self-Hosted: Docker container, VM, or dedicated server
Cloud Hosted: Hostifi or similar (subscription service)

Knowledge Requirements:

Basic networking concepts (IP addressing, subnets, DHCP)
Comfort with web interfaces
Understanding of WiFi basics
Docker knowledge helpful for self-hosted controller

Time Commitment:

Controller installation: 30-60 minutes
Initial device adoption: 15 minutes per device
Network configuration: 1-2 hours
WiFi optimization: 1-2 hours
Ongoing management: 15 minutes weekly

Understanding UniFi Architecture

The UniFi Ecosystem

UniFi Network Controller

Brain of the system
Web-based management interface
Stores configurations and statistics
Handles device provisioning
Runs on various platforms

UniFi Devices

Access Points: WiFi coverage
Switches: Wired network connectivity, PoE delivery
Gateways/Routers: Internet connection, routing, firewall
All managed by single controller

Architecture Flow:

Internet
    |
UniFi Gateway (USG/UDM/UXG)
    |
UniFi Switch (PoE)
    |
    +-- UniFi Access Points (WiFi coverage)
    +-- Wired Clients
    +-- Additional Switches (cascaded)
    |
UniFi Controller (management)

Controller Deployment Models

Dream Machine Series (Recommended for Most)

Pros:
  - All-in-one: Router, switch, AP, controller
  - Zero external dependencies
  - Always-on controller
  - Easy setup

Cons:
  - Higher initial cost
  - Controller tied to hardware
  - Limited compute for other services

Self-Hosted (Docker/VM)

Pros:
  - Flexible platform choice
  - Cost-effective
  - Can run other services
  - Full control

Cons:
  - Requires dedicated hardware/VM
  - Must maintain uptime
  - More complex initial setup

Cloud Key

Pros:
  - Dedicated appliance
  - Low power consumption
  - Includes Protect (video management)
  - Official Ubiquiti hardware

Cons:
  - Additional cost
  - Limited to UniFi functions
  - SD card reliability concerns

Controller Installation

Method 1: Docker Deployment (Recommended for Homelab)

Prerequisites:

Docker and Docker Compose installed
Static IP for controller recommended
Ports: 8080, 8443, 3478, 6789, 10001 available

Step 1: Create Directory Structure

mkdir -p ~/unifi-controller/{data,logs}
cd ~/unifi-controller

Step 2: Create docker-compose.yml

version: '3.8'

services:
  unifi-controller:
    image: lscr.io/linuxserver/unifi-network-application:latest
    container_name: unifi-controller
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - MONGO_USER=unifi
      - MONGO_PASS=your_secure_password_here
      - MONGO_HOST=unifi-db
      - MONGO_PORT=27017
      - MONGO_DBNAME=unifi
      - MEM_LIMIT=1024  # MB - adjust based on network size
      - MEM_STARTUP=1024
    volumes:
      - ./data:/config
    ports:
      - "8443:8443"   # Web admin HTTPS
      - "3478:3478/udp"  # STUN
      - "10001:10001/udp"  # Device discovery
      - "8080:8080"   # Device communication
      - "1900:1900/udp"  # L2 discovery (optional)
      - "8843:8843"   # Guest portal HTTPS (optional)
      - "8880:8880"   # Guest portal HTTP (optional)
      - "6789:6789"   # Mobile throughput test
      - "5514:5514/udp"  # Remote syslog
    restart: unless-stopped
    depends_on:
      - unifi-db

  unifi-db:
    image: mongo:4.4
    container_name: unifi-db
    environment:
      - MONGO_INITDB_ROOT_USERNAME=root
      - MONGO_INITDB_ROOT_PASSWORD=your_root_password_here
    volumes:
      - ./db:/data/db
      - ./init-mongo.js:/docker-entrypoint-initdb.d/init-mongo.js:ro
    restart: unless-stopped

networks:
  default:
    driver: bridge

Step 3: Create MongoDB Initialization Script

cat > init-mongo.js <<'EOF'
db.getSiblingDB("unifi").createUser({
  user: "unifi",
  pwd: "your_secure_password_here",
  roles: [
    { role: "dbOwner", db: "unifi" }
  ]
});

db.getSiblingDB("unifi_stat").createUser({
  user: "unifi",
  pwd: "your_secure_password_here",
  roles: [
    { role: "dbOwner", db: "unifi_stat" }
  ]
});
EOF

Step 4: Deploy

# Start services
docker-compose up -d

# Monitor logs
docker-compose logs -f unifi-controller

# Wait for startup (approximately 2-3 minutes)
# Look for: "Unifi Network Application started"

Step 5: Access Controller

Navigate to: https://YOUR-SERVER-IP:8443

Accept SSL warning (self-signed certificate initially)

Method 2: UniFi Dream Machine Setup

Physical Setup:

Connect Hardware

Internet → WAN port (blue) on UDM
LAN port → Computer or switch
Power on UDM

Access Setup

Connect device to LAN port
Device receives IP via DHCP (192.168.1.x)
Browse to: http://unifi.ui.com or http://192.168.1.1

Initial Configuration

Create Ubiquiti account (required)
Name your network
Set WiFi SSID and password
Configure WAN connection (DHCP, PPPoE, Static)
Wait for adoption (approximately 5 minutes)

Method 3: Cloud Key Gen2 Setup

Physical Setup:

1. Power Cloud Key via PoE or included adapter
2. Connect to network switch/router
3. Cloud Key obtains IP via DHCP
4. Access via http://unifi.ui.com (auto-discovers) or direct IP
5. Follow setup wizard

Method 4: Manual Linux Installation

Ubuntu/Debian Installation:

# Add MongoDB repository (required for UniFi)
wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list

# Add UniFi repository
wget -O /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ui.com/unifi/unifi-repo.gpg
echo 'deb https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list

# Install
sudo apt update
sudo apt install -y unifi

# Service management
sudo systemctl status unifi
sudo systemctl enable unifi
sudo systemctl start unifi

# Access
# https://localhost:8443

Initial Controller Setup

Step 1: Welcome Screen

Name: HomeLabNetwork
Country: Select your country
Agree to Terms
Next

Step 2: Sign In

Create Ubiquiti Account or Sign In
  Email: [email protected]
  Password: (strong password)

Or: Skip (local-only account - less cloud features)

Step 3: Device Detection

Controller automatically scans for UniFi devices on network.

Devices Found:
  - UniFi AP AC Pro (192.168.1.50)
  - UniFi Switch 8 POE-150W (192.168.1.51)

Select devices to adopt
Next

Step 4: Network Configuration

WiFi Setup:
  Network Name (SSID): HomeNetwork
  Password: (strong WPA2/WPA3 password - minimum 8 characters)

Advanced Options:
  Enable guest network: Optional (we'll configure later)
  Separate 2.4GHz and 5GHz: Unchecked (unified SSID recommended)

Next

Step 5: Device Configuration

Device Name Scheme: Optional customization
  Example: "Living Room AP", "Office Switch"

Time Zone: Select your time zone
Automatic Updates: Enable (recommended)

Finish

Controller is now ready!

Device Adoption

Automatic Adoption

If devices are on same network as controller:

1. Settings → System → Device Authentication
   Enable Auto-Adopt: Checked

2. Devices → Pending Adoption
   Devices appear automatically
   Click "Adopt" for each device

3. Wait for provisioning (1-3 minutes per device)
   Status changes: Adopting → Provisioning → Connected

Manual Adoption (Different Subnet)

Method 1: SSH Adoption

# SSH to device (default credentials)
ssh ubnt@DEVICE-IP
# Password: ubnt

# Set inform URL to controller
set-inform http://CONTROLLER-IP:8080/inform

# Exit SSH
exit

# Device appears in controller for adoption

Method 2: Controller Discovery Override

# If controller not auto-discovered
# SSH to device
ssh ubnt@DEVICE-IP

# Override discovery
mca-cli set-inform http://CONTROLLER-IP:8080/inform

# Check status
info

# Should show controller URL

Adoption Troubleshooting

Device stuck in “Adopting” loop:

# SSH to device
ssh ubnt@DEVICE-IP

# Factory reset
syswrapper.sh restore-default

# Wait for reboot
# Re-attempt adoption

“Unable to locate device” error:

Check:
1. Device and controller on same network or routable
2. Firewall allows ports 8080, 8443, 3478
3. DNS resolves controller hostname (if using hostname)
4. Try adoption via IP instead of hostname

Settings → System → Advanced
  Override Inform Host: Check
  Hostname: CONTROLLER-IP (not hostname)

Network Configuration

Creating VLANs and Networks

Use Case: Separate trusted, IoT, and guest networks

Step 1: Create Networks

Settings → Networks → Create New Network

1. Trusted Network (Default LAN)
   Name: Default
   VLAN: None (untagged)
   Gateway/Subnet: 192.168.1.1/24
   DHCP: Enabled
     Range: 192.168.1.100 - 192.168.1.200
   DNS: Auto (controller IP) or custom (1.1.1.1)

2. IoT Network
   Name: IoT
   Purpose: Corporate
   VLAN ID: 30
   Gateway/Subnet: 192.168.30.1/24
   DHCP Mode: DHCP Server
     Range: 192.168.30.100 - 192.168.30.250
   Content Filtering: None
   Multicast DNS: Enable (for Chromecast, AirPlay across VLANs)
   IGMP Snooping: Enable

3. Guest Network
   Name: Guest
   Purpose: Guest
   VLAN ID: 40
   Gateway/Subnet: 192.168.40.1/24
   DHCP Mode: DHCP Server
     Range: 192.168.40.100 - 192.168.40.200
   Guest Policy: Apply (isolates clients, blocks local access)
   Content Filtering: Optional (Family, Adult, etc.)

Save each network

Step 2: Assign Networks to WiFi

Settings → Wireless Networks

1. Main WiFi (Trusted)
   Name: HomeNetwork
   Password: (strong password)
   Network: Default
   WiFi Band: Both (2.4 + 5 GHz)
   Security Protocol: WPA2/WPA3

2. IoT WiFi
   Name: SmartHome
   Password: (different password)
   Network: IoT
   WiFi Band: 2.4 GHz only (many IoT devices don't support 5GHz)
   Security: WPA2 (WPA3 breaks some IoT devices)
   Client Device Isolation: Enable
   Multicast Enhancement: Enable

3. Guest WiFi
   Name: Guest
   Password: (simple, shareable)
   Network: Guest
   Guest Policy: Enable
   Hotspot Portal: Optional (see below)

Save

Step 3: Configure Switch Ports for VLANs

Devices → Select Switch → Ports

Port 1 (Uplink to router/firewall):
  Profile: All (trunk mode)
  Native Network: Default
  Tagged Networks: IoT, Guest

Port 2 (Workstation - Trusted):
  Profile: Default (access mode)

Port 3 (IoT Device):
  Profile: IoT (access mode)

Port 4 (PoE to AP):
  Profile: All (trunk to deliver all SSIDs)

Apply

Guest Portal / Hotspot Setup

Create captive portal for guest authentication:

Settings → Guest Control

Enable: Checked
Portal Customization:
  Greeting: "Welcome to our network!"
  Logo: Upload custom logo
  Terms of Service: Add if desired

Authentication:
  Method: Simple Password
  Guest Password: guestpass2025
  Or: None (click-through only)
  Or: Payment (requires gateway)

Access Control:
  Download Limit: 50 Mbps (throttle guests)
  Upload Limit: 10 Mbps
  Quota: 500 MB per device per day (optional)
  Duration: 8 hours (re-auth after)

Redirect:
  Redirect After: Original URL
  Or: Custom URL (your website)

Save

Test:

1. Connect to Guest WiFi
2. Open browser
3. Redirected to portal automatically
4. Enter password or accept terms
5. Access granted

WiFi Optimization

Site Survey and AP Placement

Planning Tool:

UniFi Design Center: https://design.ui.com

1. Upload floor plan or draw layout
2. Place virtual APs
3. Tool calculates coverage
4. Adjust placement for optimal coverage

General Guidelines:

AP Placement:
  - Central locations for maximum coverage
  - Ceiling mount preferred (omnidirectional radiation)
  - Avoid corners (wasted coverage)
  - Distance: 30-50 feet between APs in residential
  - Consider building materials (concrete/brick reduces range)

Avoid:
  - Near metal objects (file cabinets, HVAC)
  - In enclosed spaces (closets)
  - Behind TVs or large appliances

Channel Selection and Bandwidth

2.4 GHz Configuration:

Settings → Wireless Networks → Edit Network

Advanced:
  2.4 GHz Channel Width: HT20 (20 MHz)
    Why: Less interference, more stable
    Never: HT40 (causes interference)

  Channel: Auto (or manual if interference detected)
    Best channels: 1, 6, 11 (non-overlapping)

  Transmit Power: Auto (or Medium)
    Why: Lower power = less noise, better roaming

Save

5 GHz Configuration:

Advanced:
  5 GHz Channel Width: VHT80 (80 MHz)
    Or: VHT40 for crowded areas
    Or: VHT160 for WiFi 6 devices in clear spectrum

  Channel: Auto (DFS channels increase options)
    Enable DFS: Checked (regulatory permitting)

  Transmit Power: High (5 GHz attenuates faster)

Save

WiFi AI (Auto-Optimization):

Settings → WiFi → WiFi AI

Enable: Checked

Features:
  Auto-Optimize Network: Enable
    Adjusts channels and transmit power automatically

  Optimize Client Devices: Enable
    Steers clients to better bands/APs

  High Performance Devices: Auto (WiFi 6/6E)

Scan Interval: Daily at 2:00 AM

Save

Note: Allows UniFi to auto-tune based on real-world RF environment

Band Steering and Client Isolation

Band Steering:

Settings → Wireless Networks → Edit Network

Advanced Manual Settings:
  Band Steering: Prefer 5G
    Pushes dual-band clients to 5 GHz

  Minimum RSSI: -70 dBm (2.4 GHz), -75 dBm (5 GHz)
    Prevents weak connections
    Encourages roaming to better AP

Save

Fast Roaming (802.11r):

Settings → Wireless Networks → Edit Network

Advanced:
  Fast Roaming: Enable
    Reduces handoff time when moving between APs
    Essential for VoIP and video calls while walking

Save

Client Isolation (IoT/Guest):

Settings → Wireless Networks → IoT Network

Security:
  Client Device Isolation: Enable
    Prevents IoT devices from talking to each other
    Only allows communication to gateway

Multicast Enhancement:
  Enable: Checked
    Converts multicast to unicast for better reliability
    Important for Chromecast, AirPlay

Save

Firewall and Traffic Management

Creating Firewall Rules

Block IoT from Trusted Network:

Settings → Security → Firewall → Create Entry

Type: LAN In
Name: Block IoT to Trusted
Enabled: Yes

Rule Applied: Before Predefined Rules

Source:
  Network: IoT

Destination:
  Network Type: Network
  Network: Default (Trusted)

Action: Drop

Logging: Enable (for monitoring)

States: New, Established, Related (all)

Save

Allow Trusted to IoT (for control):

Create Entry:
  Name: Allow Trusted to IoT
  Source: Default
  Destination: IoT
  Action: Accept

Save

Block Guest from Everything Except Internet:

Note: Guest policy automatically handles this
Verify: Settings → Networks → Guest
  Guest Policy: Applied

Manual override if needed:
  Source: Guest
  Destination: Network Type: Address/Port Group
    Create group with RFC1918 addresses
  Action: Drop

Traffic and Device Identification (DPI)

Enable Deep Packet Inspection:

Settings → System → Traffic Identification

Deep Packet Inspection: Enable

Categories to Identify:
  - Streaming (Netflix, YouTube)
  - Social Media (Facebook, Instagram)
  - Gaming (Steam, Xbox Live)
  - VoIP (Zoom, Teams)
  - File Sharing (BitTorrent)

Save

View Insights:
  Dashboard → Traffic Routes
  Shows bandwidth by application type

Traffic Shaping and QoS

Smart Queues (Basic QoS):

Settings → Internet → WAN

Traffic Management:
  Smart Queues: Enable
  Upload Bandwidth: 900 Mbps (set to 90-95% of actual)
  Download Bandwidth: 900 Mbps

Save

Effect: Prevents buffer bloat, reduces latency under load

Advanced QoS (Traffic Rules):

Settings → Routing & Firewall → Traffic Rules

Create Rule:
  Name: Prioritize Video Conferencing
  Enabled: Yes

  Matching:
    Traffic Category: VoIP and Video Conferencing

  Action:
    Apply to: Upload and Download
    Priority: High
    Bandwidth Limit: None

Create Rule:
  Name: Limit BitTorrent

  Matching:
    Traffic Category: File Sharing

  Action:
    Priority: Low
    Download Limit: 50 Mbps
    Upload Limit: 10 Mbps

Save

Monitoring and Insights

Dashboard Overview

Key Widgets:

Dashboard Configuration:

1. Network Overview
   - Total clients
   - Throughput
   - Threats blocked

2. WiFi Experience
   - Client satisfaction score
   - Poor connection warnings
   - Interference alerts

3. Traffic Stats
   - Top applications
   - Top clients by usage
   - Traffic routes

4. Devices
   - Online/offline status
   - Uptime
   - Firmware versions

5. Alerts
   - Recent alerts/anomalies
   - Device issues

Customize: Drag widgets to reorder

Client Management

View Connected Clients:

Clients → Active

Per Client Details:
  - IP and MAC address
  - Connected device (AP or switch port)
  - Signal strength (WiFi)
  - Data usage
  - Traffic identification
  - Connection history

Actions:
  - Block client (prevent access)
  - Reconnect (force reauthentication)
  - Forget client (remove from history)
  - Create static IP reservation

Client Experience Score:

Clients → Select Client → Experience

Score: 0-100%
  90-100%: Excellent
  70-89%: Good
  50-69%: Fair
  0-49%: Poor

Factors:
  - Signal strength
  - Latency
  - Retransmissions
  - Channel utilization

Recommendation: Investigate scores under 70%

Performance Analytics

Speed Test:

Settings → Services → Speed Test

Configure:
  Provider: Auto
  Schedule: Daily at 3:00 AM

Run Manual Test:
  Devices → Gateway → Tools → Speed Test

View History:
  Dashboard → Speed Test widget
  Track ISP performance over time

Historical Stats:

Statistics → Historic Data

Available Metrics:
  - Client count over time
  - Bandwidth usage trends
  - Device uptime
  - WiFi utilization
  - Top talkers

Time Ranges:
  - Past hour / day / week / month
  - Custom date range

Export: Download CSV for external analysis

Alerts and Notifications

Configure Alerts:

Settings → Notifications

Categories:
  Device Connectivity:
    - Device connected/disconnected
    - Device upgrade available

  Network:
    - New guest authorization
    - High client count
    - Speed test complete

  Security:
    - IDS/IPS alert
    - Unknown device detected

  System:
    - Controller update available
    - Backup failure

Delivery Methods:
  - Email: configure SMTP
  - Push notification: UniFi mobile app
  - Webhook: for custom integrations

Save

Advanced Features

RADIUS Server for Enterprise WiFi

Built-in RADIUS:

Settings → Profiles → RADIUS

Create Profile:
  Name: HomeRADIUS
  Authentication: PEAP-MSCHAPv2

Add Users:
  Username: john.doe
  Password: (secure password)
  VLAN: Default (or dynamic VLAN assignment)

Save

Apply to WiFi:
  Settings → Wireless Networks → Enterprise WiFi
  Security: WPA2 Enterprise
  RADIUS Profile: HomeRADIUS

Save

Clients use username/password instead of PSK
More secure, individual accountability

VPN Server (L2TP)

Enable VPN:

Settings → VPN → VPN Server

Type: L2TP
Enable: Yes

Authentication:
  Pre-shared Key: (strong random key)
  RADIUS: Optional (or use manual users below)

User Accounts:
  Username: remote-user
  Password: (strong password)

IP Pool:
  Network: 192.168.255.0/24 (dedicated VPN subnet)

Save

Access from remote:
  Server: your-public-ip or DDNS hostname
  Type: L2TP/IPsec
  PSK: (pre-shared key)
  Username/Password: as configured

Dynamic DNS

Configure DDNS:

Settings → Internet → WAN

Dynamic DNS:
  Service: afraid, dyndns, no-ip, etc.
  Hostname: yourname.ddns.net
  Username: (DDNS account username)
  Password: (DDNS account password)

Save

Controller updates DDNS whenever WAN IP changes
Access network via consistent hostname

Port Forwarding

Forward ports to internal services:

Settings → Routing & Firewall → Port Forwarding

Create Rule:
  Name: HTTPS to Web Server
  Enabled: Yes

  From: Any (or limit to specific IPs)
  Port: 443

  Forward IP: 192.168.20.10 (internal server)
  Forward Port: 443
  Protocol: TCP

  Logging: Enable

Save

Access: https://your-public-ip
Forwards to internal server transparently

Firmware Management

Updating Devices

Automatic Updates (Recommended):

Settings → System → Maintenance

Auto Upgrade:
  Enable: Yes
  Upgrade Window: 2:00 AM - 4:00 AM
  Day: Any day (or specific day of week)

Device Upgrade:
  Upgrade Path: Official
  Pre-release: Unchecked (beta firmware)

Save

Devices update automatically during window
Minimal disruption

Manual Updates:

Devices → Select Device → Settings

Current Firmware: 6.5.55.12345
Available: 6.6.70.12500

Actions:
  Upgrade: Initiates upgrade immediately
  Custom Upgrade: Upload custom firmware file

Process:
  1. Click "Upgrade"
  2. Device downloads firmware
  3. Reboots (30-90 seconds downtime)
  4. Reconnects automatically

Monitor: Devices page shows progress

Update Controller:

Docker:
  docker-compose pull
  docker-compose up -d

Dream Machine:
  System → Updates → Check for Updates
  Download and install when available

Manual Linux:
  sudo apt update
  sudo apt upgrade unifi
  sudo systemctl restart unifi

Backup and Restore

Automatic Backups

Configure Auto-Backup:

Settings → System → Backup

Automatic Backups:
  Enable: Yes
  Frequency: Daily
  Retention: 7 days (or more)

Cloud Backup:
  Enable: Yes (requires Ubiquiti account)
  Backup to cloud for disaster recovery

Download Backups:
  Settings → System → Backup → Download
  Save locally for redundancy

Save

Manual Backup and Restore

Create Backup:

Settings → System → Backup

Manual Backup:
  Backup Now

Download .unf file
Store securely (includes all configurations)

Restore from Backup:

Settings → System → Backup

Restore:
  Choose File: (select .unf backup file)
  Upload

Controller restarts with restored configuration
Devices re-provision automatically

Disaster Recovery:

Scenario: Controller completely lost

1. Install new controller
2. Access setup wizard
3. Select "Restore from backup"
4. Upload .unf file
5. Devices auto-adopt to restored controller
6. Network restored

Troubleshooting

Device Won’t Adopt

Check 1: Network Connectivity

Ping device IP from controller:
  ping DEVICE-IP

If fails:
  - Check physical connection
  - Verify VLAN configuration
  - Check firewall rules

Check 2: Inform URL

SSH to device:
  ssh ubnt@DEVICE-IP
  Password: ubnt

Check inform URL:
  info

Should show:
  Status: http://CONTROLLER-IP:8080/inform

If wrong:
  set-inform http://CONTROLLER-IP:8080/inform

Retry adoption in controller

Check 3: Factory Reset

SSH to device:
  syswrapper.sh restore-default

Or: Hold reset button 10 seconds while powered

Device reboots to factory state
Re-attempt adoption

WiFi Performance Issues

Slow Speeds:

Check:
1. Client connected to 2.4GHz or 5GHz?
   - Prefer 5GHz for better speeds
   - Settings → Wireless Networks → Band Steering

2. Channel congestion?
   - WiFi AI → Scan Network
   - Manually set channels 1, 6, 11 (2.4GHz)
   - Try different 5GHz channels

3. Signal strength?
   - Clients → Select Client → Check RSSI
   - Target: -67 dBm or better
   - Add APs if coverage weak

4. Interference?
   - Settings → System → RF Environment
   - Look for interferers
   - Adjust channels or AP placement

Disconnections:

Check:
1. Firmware up to date?
   - Devices → Check for updates

2. Roaming aggressiveness?
   - Settings → Wireless Networks
   - Adjust Minimum RSSI
   - Enable Fast Roaming (802.11r)

3. Power save mode on clients?
   - Some clients disconnect when idle
   - Disable power save in client settings

4. DFS channel issues?
   - If using DFS, radar detection can cause channel change
   - Disable DFS or accept occasional disruption

Controller Connectivity Issues

Cannot Access Controller Web Interface:

Check:
1. Service running?
   docker ps (Docker)
   systemctl status unifi (Linux)

2. Correct URL?
   https://CONTROLLER-IP:8443
   Not http (port 8443 is HTTPS only)

3. Firewall blocking?
   sudo ufw allow 8443/tcp

4. Browser cache?
   Clear cache, try incognito mode

Devices Show as “Disconnected”:

Check:
1. Controller reachable from devices?
   - Verify network connectivity
   - Check inform URL (SSH to device, run info)

2. Clock sync issues?
   - Ensure devices have correct time (NTP)

3. Database corruption?
   - Restore from backup
   - Or: Remove device and re-adopt

Integration and Automation

API Access

Enable API:

Settings → System → Advanced

Enable API:
  - No explicit toggle (API always on)
  - Create local admin account for API access

Generate API credentials:
  Settings → Admins → Add Admin
  Username: api-user
  Password: (secure)
  Role: Administrator (or limited)

API Endpoint:
  https://CONTROLLER-IP:8443/api/

Documentation:
  Community-maintained: UniFi API Browser
  GitHub: Art-of-WiFi/UniFi-API-client

Example API Usage:

#!/usr/bin/env python3
import requests
import json

class UniFiAPI:
    def __init__(self, host, username, password):
        self.host = host
        self.username = username
        self.password = password
        self.session = requests.Session()
        self.session.verify = False  # Disable SSL verification
        self.login()

    def login(self):
        url = f"{self.host}/api/login"
        data = {
            "username": self.username,
            "password": self.password
        }
        response = self.session.post(url, json=data)
        if response.status_code == 200:
            print("Logged in successfully")
        else:
            print("Login failed")

    def get_clients(self):
        url = f"{self.host}/api/s/default/stat/sta"
        response = self.session.get(url)
        return response.json()

    def block_client(self, mac):
        url = f"{self.host}/api/s/default/cmd/stamgr"
        data = {
            "cmd": "block-sta",
            "mac": mac
        }
        response = self.session.post(url, json=data)
        return response.json()

# Usage
api = UniFiAPI(
    "https://192.168.1.2:8443",
    "api-user",
    "password"
)

clients = api.get_clients()
for client in clients['data']:
    print(f"{client.get('hostname', 'Unknown')}: {client['mac']}")

Home Assistant Integration

Add UniFi Integration:

Configuration → Integrations → Add Integration

Search: UniFi Network

Configure:
  Host: CONTROLLER-IP
  Port: 8443
  Username: homeassistant
  Password: (dedicated user password)
  Verify SSL: Uncheck (self-signed cert)
  Site: Default

Submit

Entities created:
  - Device trackers (presence detection)
  - Sensors (bandwidth usage)
  - Switches (block/unblock clients)

Example Automation (Presence Detection):

automation:
  - alias: "Welcome Home"
    trigger:
      platform: state
      entity_id: device_tracker.phone
      to: 'home'
    action:
      - service: light.turn_on
        entity_id: light.living_room
      - service: notify.mobile_app
        data:
          message: "Welcome home!"

Conclusion

UniFi transforms network management from a chore into an elegant, powerful experience. With centralized control, enterprise features, and prosumer pricing, it’s the ideal platform for serious homelabbers seeking professional-grade infrastructure without enterprise complexity.

Key Takeaways

Unified Management: Single interface for all network devices
Scalability: Start small, grow seamlessly
Visibility: Deep insights into network performance
Flexibility: VLANs, guest networks, advanced WiFi all included
Reliability: Enterprise-grade hardware and software

Next Steps

Immediate Actions:

Deploy UniFi controller
Adopt initial devices
Configure basic WiFi networks
Enable monitoring and insights

Advanced Projects:

Implement full VLAN segmentation
Set up guest portal with custom branding
Deploy RADIUS for enterprise authentication
Integrate with home automation
Build custom monitoring dashboards via API

Additional Resources

Official Documentation: https://help.ui.com/
Community Forums: https://community.ui.com/
Reddit: r/Ubiquiti - active community support
UniFi Design Center: https://design.ui.com - network planning tool
YouTube: Crosstalk Solutions, Willie Howe - excellent UniFi tutorials

Document Version: 1.0 Last Updated: December 16, 2025 Difficulty: Intermediate Estimated Setup Time: 2-4 hours for complete deployment Maintenance: Monthly firmware updates, minimal ongoing management