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

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