Guide to Installing Omada Software Controller on Raspberry Pi OS - V5
Update - 4 October 2025
The latest Raspberry Pi OS (Debian Base Pixie) broke some of the install repo's and the install instructions have been updated and tested to work wih a fresh install of the current Raspberry Pi OS as of this date.
The Raspberry Pi OS (Legacy) based on Debian Bookworm was tested and does not work out of box either, so does not offer any benefit - the installation instructions is now based on the default Raspberry Pi OS version available at this date.
This is a bare metal install on 64 bit Raspberry Pi OS - no Ubuntu server, no Docker. Tested with version 5.15.24 of the Controller software. I have it running on a Model 4B and Model 5 Pi. The recent versions of the Omanada SDN Controller does not run on the Model 3B, 3B+
To update the Controller version on a working Raspberry Pi without updating Raspberry Pi OS, do the following
sudo tpeap stop
sudo apt remove omadac
- During the uninstall process select the option to save the current settings. This allows the existing settings to be applied automatically to the updated version
wget https://static.tp-link.com/upload/software/2025/202508/20250802/omada_v5.15.24.19_linux_x64_20250724152622.deb
sudo dpkg -i omada_v5.15.24.19_linux_x64_20250724152622.deb
Links have been updated and verified on most recent install
Instructions:
1. Download & install latest 64 bit LITE version of Raspberry pi OS to new sd card of your choice from the link below. Note - the legacy version of Raspberry Pi OS will not work
https://downloads.raspberrypi.org/raspios_lite_arm64/images/
This is not a guide to installing Raspberry Pi OS so I won't provide detailed instructions on that.
2. Download and install libssl1.1 manually
wget http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl1.1_1.1.1w-0+deb11u4_arm64.deb
sudo dpkg -i libssl1.1_1.1.1w-0+deb11u4_arm64.deb
3. Download and install version 4.4.18 of MongoDB mongodb-server from https://www.mongodb.com/download-center/community/releases/archive
wget https://repo.mongodb.org/apt/ubuntu/dists/focal/mongodb-org/4.4/multiverse/binary-arm64/mongodb-org-server_4.4.18_arm64.deb
sudo dpkg -i mongodb-org-server_4.4.18_arm64.deb
Note this post explaining that MongoDB V4.4.19 will not work.
3. Check that curl is installed
apt list curl
5. Download and install openjdk-21
sudo apt install openjdk-21-jdk-headless
6. Install jsvc
sudo apt install jsvc
7. If you have multiple versions of OpenJDK installed then you need to tell system which java to use
sudo update-alternatives --config java
Selection Path Priority Status
------------------------------------------------------------
0 /usr/lib/jvm/java-11-openjdk-arm64/bin/java 1111 auto mode
1 /usr/lib/jvm/java-11-openjdk-arm64/bin/java 1111 manual mode
* 2 /usr/lib/jvm/java-8-openjdk-arm64/jre/bin/java 1081 manual mode
Press <enter> to keep the current choice[*], or type selection number:
Now select the option pointing to the version of OpenJDK you want to use.
8. Download and install latest version Omada SDN controller
wget https://static.tp-link.com/upload/software/2025/202508/20250802/omada_v5.15.24.19_linux_x64_20250724152622.deb
sudo dpkg -i omada_v5.15.24.19_linux_x64_20250724152622.deb
If all went well the controller should start and you should get the following message
Install Omada Controller succeeded!
==========================
Omada Controller will start up with system boot. You can also control it by [/usr/bin/tpeap].
check omada
Starting Omada Controller. Please wait.........................................................................................................................
Started successfully.
You can visit http://localhost:8088 on this host to manage the wireless network.
========================
Now you can access the web interface of the Omada Controller by pointing you web browser from any PC on the same network to
http://<IP_address_of_Omada_Controller>:8088
- Copy Link
- Subscribe
- Bookmark
- Report Inappropriate Content
@kilovar Solid guide. I am getting stuck on the very last part. When I put in
sudo apt install /home/pi/Omada_SDN_Controller_v5.7.4_Linux_x64.deb
I receieve the following output:
Reading package lists... Done
E: Unsupported file /home/pi/Omada_SDN_Controller_v5.7.4_Linux_x64.deb given on commandline
Any assitance here would be appreciated.
- Copy Link
- Report Inappropriate Content
Howdy @kilovar
What version of the Pi OS do you have?
Can you run the following - $ uname -m and $ lsb_release -a
It should show 64 bit "aarch64" and "Debian bullseye"
- Copy Link
- Report Inappropriate Content
- Copy Link
- Report Inappropriate Content
Have you tried:
$ sudo dpkg -i Omada_SDN_Controller_v5.7.4_Linux_x64.deb
I don't think it will work back it may give more details on what the problem is.
You may also want to try installing it in Debian for Ras Pi I installed 5.9.31 and on 64 bit Debian and it works 100%
- Copy Link
- Report Inappropriate Content
- Copy Link
- Report Inappropriate Content
64 bit Debian 11 on a Pi 4B /w 4 Gig. It runs flawlessly with Omada, Pi-Hole (a great dns sinkhole) and PI-VPN all installed.
- Copy Link
- Report Inappropriate Content
- Copy Link
- Report Inappropriate Content
- Copy Link
- Report Inappropriate Content
Hi everyone,
Thanks for this thread! Anyone interested in a raspbery pi image for omada? If so Ive just made one. Highlights:
- MongoDB 4.4.26
- OpenJDK 17
- Plug and play - just burn the image ssh in on ethernet (look for IP address on router)
- For raspberry pi 4
Build is based on pi-gen so you get a full bookworm raspbery pi OS.
So far it boots through to the login page but I havent used it yet - any volunteers to help me test?
Docs: https://github.com/GeoffWilliams/omadapi
Image: https://github.com/GeoffWilliams/omadapi/releases/tag/v5.12.7-0 (broken release)
Update:
Image: https://github.com/GeoffWilliams/omadapi/releases/tag/v5.13.22
Has been working good since deployed. Able to backup, restore, setup APs, update firmware, etc...
- Copy Link
- Report Inappropriate Content
Thank you so much for this thread.
I was able to successfully install v5.13.23 on Raspberry Pi OS Bookworm (Debian 12).
However, in attempting to migrate from my old controller (2011 Mac Mini running Ubuntu 22.04.3 LTS), I've consistently run in to errors on the upload.
The first errors in the Omada log look like this:
01-18-2024 17:56:59.899 ERROR [restore-work-group-0] [] c.t.s.o.b.c.r.d(): omadacId=OmadacId(20e0d6f42df8f6f5214762661cde22fa) restore failed with Exception
java.lang.reflect.InaccessibleObjectException: Unable to make field private static final long java.util.LinkedHashMap.serialVersionUID accessible: module java.base does not "opens java.util" to unnamed module @1a942c18
As I was only running java-17-openjdk-arm64 on the raspberry pi I decided to go an try to install java-11-openjdk-amd64 through bullseye oldstable repo.
I've been playing around with different permutations of java 17, 11, and 8 on the two machines to see if I can get them to export/import properly, but still no luck.
Adding here in case you, or others, come across this and have a solve or an idea.
Thanks!
- Copy Link
- Report Inappropriate Content
Information
Helpful: 12
Views: 116928
Replies: 143
Voters 3
