📟 Retro Mode

Building a TP-Link Omada Software Controller on Linux: The Ultimate Guide

TP-Link’s Omada Software-Defined Networking (SDN) platform is a robust, enterprise-grade ecosystem that rivals Ubiquiti’s UniFi, often at a significantly lower hardware cost. While you can purchase a hardware controller (like the OC200), running the Software Controller on a Linux machine or VM offers unlimited scalability, faster database performance, and the ability to integrate into your existing backup infrastructure.

This guide covers installing the controller from scratch on a Debian/Ubuntu system, configuring the network, and adopting devices.

1. Prerequisites and Dependency Hell

The Omada controller is a Java application that relies on jsvc for daemonization and MongoDB for its backend database.

CRITICAL WARNING regarding MongoDB: Depending on the specific version of the Omada Controller you are installing (e.g., v5.x vs v6.x), TP-Link strictly requires older versions of MongoDB. Most Omada v5.x controllers only support MongoDB versions 3.4 up to 4.4. If you install the latest MongoDB v6.0+, the Omada controller will silently fail to start.

Step 1: Install Java and JSVC

Omada requires a headless Java Runtime Environment (JRE) and jsvc. For Omada v5.x, OpenJDK 11 is the recommended standard.

sudo apt update
sudo apt install openjdk-11-jre-headless jsvc curl wget -y

Step 2: Install MongoDB (v4.4)

Because MongoDB 4.4 is deprecated in newer Ubuntu repositories, you must add the official MongoDB legacy repository manually.

# Import the public key
curl -fsSL https://pgp.mongodb.com/server-4.4.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-4.4.gpg --dearmor

# Add the repository list
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-4.4.gpg ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list

# Install MongoDB
sudo apt update
sudo apt install -y mongodb-org

Enable and start the MongoDB service:

sudo systemctl daemon-reload
sudo systemctl enable mongod
sudo systemctl start mongod

2. Installing the Omada Software Controller

Go to the official TP-Link Omada Download Center, find the latest Linux .deb package, and copy the link.

# Download the package
wget https://static.tp-link.com/upload/software/2023/202311/20231114/Omada_SDN_Controller_v5.13.23_Linux_x64.deb

# Install via dpkg
sudo dpkg -i Omada_SDN_Controller_v5.13.23_Linux_x64.deb

Note: If dpkg complains about missing dependencies, run sudo apt --fix-broken install and try again.

The Omada installer automatically creates a systemd service called tpeap. You can verify the status:

sudo systemctl status tpeap

3. Initial Web UI Setup

With the service running, open a web browser and navigate to the controller’s IP address on port 8043 (HTTPS):

https://<YOUR-SERVER-IP>:8043

  1. Bypass the SSL Warning: The controller generates a self-signed certificate upon installation.
  2. Create Administrator Account: Set up your local admin username and a strong password.
  3. Cloud Access (Optional): You can bind your controller to a TP-Link ID. This allows you to manage your local network remotely via the Omada mobile app without needing a VPN or port forwarding.
  4. Site Setup: Create your first “Site” (e.g., “W4DXR-Shack”). Sites are logical boundaries; devices and VLANs created in one site do not cross over into another.

4. Network Configuration and Device Adoption

Step 1: Device Adoption (Layer 2 vs Layer 3)

If your Omada Access Points (APs) and Switches are on the same local subnet (VLAN 1) as your Linux controller, they will automatically appear in the Devices > Pending list via Layer 2 discovery. Simply click Adopt.

If your controller is on a different VLAN (Layer 3), you must use the Omada Discovery Utility, or configure your DHCP server to pass Option 138 (Controller IP) to the unadopted devices so they know where to report.

Step 2: Configuring VLANs (Wired Networks)

To segment your network (e.g., separating IoT devices from trusted computers):

  1. Go to Settings > Wired Networks > LAN.
  2. Click Create New LAN.
  3. Name it (e.g., IoT_Network), assign a VLAN ID (e.g., 20), and define the subnet (192.168.20.1/24).
  4. If using an Omada router, the controller will automatically deploy DHCP scopes and routing rules. If using OPNsense/pfSense, you only need to define the VLAN ID here so the APs are aware of it.

Step 3: Configuring WLANs (Wi-Fi)

  1. Go to Settings > Wireless Networks > WLAN.
  2. Click Create New Wireless Network.
  3. Set your SSID and WPA2/WPA3 password.
  4. Expand Advanced Settings and map the SSID to the VLAN ID you created in the previous step.

5. Advanced Tuning & Maintenance

Fast Roaming & Band Steering

To ensure modern devices (like smartphones) transition seamlessly between multiple Access Points:

  • Navigate to Settings > Site.
  • Enable Fast Roaming (802.11k/v).
  • Enable Band Steering (encouraging 5GHz capable clients to leave the congested 2.4GHz spectrum).

Automated Backups

Never rely on a single instance of a database. Set up automated controller backups:

  1. Go to Settings > Auto Backup.
  2. Enable it, set the frequency to Daily, and choose a retention period (e.g., 30 days).
  3. The controller dumps .cfg backup files into /opt/tplink/eap/data/autobackup. You should configure a cron job to rsync this folder to your NAS or offsite storage.