Deploying a TP-Link Omada Software Controller

TP-Link Omada Controllers

TP-Link offers three ways to deploy an Omada controller:

The software controller is the most flexible and cost-effective choice.

This guide deploys the software controller on Debian inside Proxmox, but the same approach applies to most hypervisors.

Installing the TP-Link Omada Controller

At a high level, the installation consists of:

1. Creating a virtual machine
2. Installing Debian
3. Assigning a static IP address
4. Updating the OS
5. Installing required dependencies
6. Installing the Omada controller package
7. Completing the initial web-based setup

Create the Virtual Machine

The recommended system specifications are below, although in this lab I will be using less:

This deployment uses Proxmox as the hypervisor. Comparable steps apply to other virtualization platforms.

Create a VM with the following, if its not included I will be using the default value.

General

• Name: “Omada-Controller”
• Start at boot: Enabled

OS

• ISO image: Debian 13.3

System

• Qemu Agent: Checked

Disks

• Storage: I will use my NAS iSCSI LUN

CPU

• Cores: 2
• Type: Host

Memory

• Memory (MiB): 2048 (2 GB)

These resources are sufficient for managing a modest number of Omada devices.

Operating System Installation

A minimal Debian installation is recommended to reduce resource usage and maintenance overhead.

Below is what I changed, everything else remains as the default values.

• Lanauge & Keyboard: English
• Hostname: “omada-controller”
• Domain: “homelab.lan”
• Root password: Skipped (leave blank)
• User: Username and Password of your account
• Partition disks:
  • Guided - use entire disk
  • All files in one partition
• Software selection (keep this as minimal as possible):
  • Debian desktop environment: Uncheck
  • GNOME: Uncheck
  • SSH server: Check

Make sure to remove the ISO after the installation completes.

Configure a Static IP & DNS

Infrastructure services should use a static IP address to avoid connectivity and device adoption issues.

Open the network interfaces configuration file:

sudo nano /etc/network/interfaces

Modify the file to set a static IP. Here’s an example configuration:

allow-hotplug ens18
iface ens18 inet static
address 192.168.1.124
netmask 255.255.255.0
gateway 192.168.1.1
dns-nameservers 192.168.1.1

Edit the resolver configuration file

sudo nano /etc/resolv.conf

Add the following line to add a name server:

nameserver 192.168.1.1

Restart the server

sudo shutdown -r now

Update the OS

Ensure we are using the most up-to date packages by updating the repositories then upgrading any installed packages.

sudo apt update && sudo apt full-upgrade

Install JSVC & OpenJDK

The Omada controller requires Java and uses JSVC for service management. Installing JSVC automatically installs openjdk-21-jre-headless as a dependency.

sudo apt install jsvc

Install MongoDB

MongoDB is used as the backend database for the Omada controller.

Install the required tool using this command:

sudo apt-get install gnupg curl

Import the MongoDB public GPG key

curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
   sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg \
   --dearmor

Create the source list

echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/debian bookworm/mongodb-org/8.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

Update and Install MongoDB

sudo apt-get update
sudo apt-get install mongodb-org

Install Omada Software Controller from package

You’ll find the latest deb package available on the Download Center for Omada Controller.

Download the Omada package.

wget https://static.tp-link.com/upload/software/2026/202601/20260121/Omada_Network_Application_v6.1.0.19_linux_x64_20260117100106.deb

Install

sudo dpkg -i Omada_Network_Application_v6.1.0.19_linux_x64_20260117100106.deb

Initial web portal setup

Once installation completes, access the controller web interface:

http://192.168.1.124:8088/

Follow the setup wizard. At minimum:

First page

• Owner Name (web username)
• Password
• Accept the Terms of Use

Second page

• Site Name
• Device Account Username
• Device Account Password

Remaining steps can be completed later as needed.

Device Onboarding

There are a few different options to onboard devices these include:

• Manually Add
  • Requires device management to be enabled
  • Requires Cloud access to be enabled
• Auto Find
  • Devices must be on the same LAN or configured with an inform URL (MSP mode)
• Import (CSV)
  • Requires device management to be enabled
  • Requires Cloud access to be enabled
• Scan to Add
  • Usable on the mobile app
  • Requires device management to be enabled
  • Requires Cloud access to be enabled

The Omada iOS or Android app allows for management and device onboarding through QR code or Auto Find.

Tweaks

Java tuning

We can apply a min and max memory value, which can help on systems with limited RAM

Edit the Omada control file

nano /opt/tplink/EAPController/bin/control.sh

Edit this section

JAVA_OPTS="-server -XX:MaxHeapFreeRatio=60 -XX:MinHeapFreeRatio=30  -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=${LOG_DIR}/java_heapdump.hprof -Djava.awt.headless=true -Djdk.lang.Process.launchMechanism=vfork"

Add -Xms512m -Xmx512m for example:

JAVA_OPTS="-server -Xms512m -Xmx512m -XX:MaxHeapFreeRatio=60 -XX:MinHeapFreeRatio=30  -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=${LOG_DIR}/java_heapdump.hprof -Djava.awt.headless=true -Djdk.lang.Process.launchMechanism=vfork"

WiredTiger storage engine

The wiredTigerCacheSizeGB is a configuration parameter in MongoDB that sets the size of the WiredTiger storage engine’s memory cache in gigabytes.

We can cap the MongoDB at 512 MB.

nano /etc/mongod.conf

Add

storage:
  wiredTiger:
    engineConfig:
      cacheSizeGB: 0.5

Updating the Controller

Its strongly recommended to backup your existing Oamda controller to avoid data loss.

The example below show upgrading from version 6.1.0.19 to 6.2.10.17.

You’ll find the latest deb package available on the Omada webinterface or Download Center for Omada Controller.

Download the Omada .deb package onto your Omada server.

wget https://ota-download.tplinkcloud.com/firmware/Omada_Network_Application_v6.2.10.17_linux_x64_20260428102045_1778119779543.deb

Install the update

sudo dpkg -i Omada_Network_Application_v6.2.10.17_linux_x64_20260428102045_1778119779543.deb

Clean up the install files once completed.

rm Omada_Network_Application_v6.2.10.17_linux_x64_20260428102045_1778119779543.deb

References

• Recommended Server Specifications for Omada Software Controller
• MongoDB documentation
• Discover and manage Omada Devices
• Omada Documents - Configuration Guides for Controllers
• Parameters Optimization of Omada SDN Controller
• How to upgrade the Omada Software Controller