Creating an Omada Controller VM

This will outline how to create a VM for running the TP-Link Omada Controller software. These same steps can also be used to install the software to a physical machine.

1. Create the virtual machine (or physical box)

CPU: 2-cores
RAM: 4GB
Storage: 20GB min
OS: Ubuntu Server 20.04 LTS
Networking (VM): Bridged

Obviously first you need a VM to actually run the software. With version 5.7.4 of the TP-Link Omada Controller, you MUST use Ubuntu 20.04 LTS. The Omada Controller requires MongoDB which cannot be installed on Ubuntu 22.04 LTS due to one of its dependencies. (As of version 6.0.3, the most recent as of this writing.) I recommend the Server distribution as well since it’s lightweight. Make sure to install OpenSSH with it so you can just copy/paste the commands in the next steps.

And, of course, once you have Ubuntu installed, make sure to fully update it. You should also install and enable “avahi-daemon” so you can find the machine by hostname. I also recommend installing “nmon” or something similar so you can monitor CPU and memory usage to determine if you need to bump the core count or memory for the VM based on your use case and how many devices you’re trying to manage.

2. Add the MongoDB CE repository

These commands come from the MongoDB documentation.

wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
sudo apt update -y

3. Download and install the Omada Controller software

You can find it on TP-Link’s website.

From the directory where you copied the .deb package, run this command (obviously the filename will be specific to your version):

sudo apt install -y ./Omada_SDN_Controller_v5.7.4_Linux_x64.deb

This will pull down a lot of other packages. MongoDB will be pulled down from the repository installed in the previous step. It will also attempt to start the Omada Controller but fail due to this error that is displayed immediately: “Cannot find any VM in Java Home”. So next we’ll take care of that error once it aborts.

4. Setting up soft links for Java Home

Run these commands (source) to correct the error you got in the previous step:

sudo mkdir /usr/lib/jvm/java-11-openjdk-amd64/lib/amd64
sudo ln -s /usr/lib/jvm/java-11-openjdk-amd64/lib/server /usr/lib/jvm/java-11-openjdk-amd64/lib/amd64/

5. Start the Omada Controller

Now we can start the Omada Controller. You can do this either by rebooting the machine or running this command:

sudo /usr/bin/tpeap start

Note as well that when you do reboot the VM, it will take a little bit after the login prompt appears for the web interface service to be accessible.

Finish the setup

And with that, you’re done and should be good to go. You can log into it remotely by going to https://[omada_hostname]:8043/ to create the admin account and finish your setup, adopt devices, etc.

(Optional) Change out the self-signed certificates

If you want to get rid of the self-signed certificate error (and accompanying browser exception), and you’ve generated a certificate using your own CA, look for the Settings option down in the lower-left corner of the browser window. Then click on “Controller” in the left-hand menu and scroll down till you find “HTTPS Certificate”. By default “File Format” will be set to JKS – “Java Key Store”.

In my instance, the generated certificates (from my custom home CA) were in PEM format with a separate certificate and private key, so I changed the drop-down to PEM, then uploaded the corresponding files using the Import buttons.

Click “Save” down at the bottom to import the certificate. Then you’ll need to reboot the VM. Unfortunately you can’t do that from the Maintenance section.