How to install + update Omada Controller on Raspberry Pi 4B in 2023

 

Update on 2023-10-12 : Raspberry Pi OS updated their main list of OS. So this page will only work on older Raspberry Pi OS Bullseye.

 

Preface: This guide only covers Raspberry Pi 4B  2GB RAM+ with Raspberry Pi OS (Debian Based - Bullseye) on 64-bit architecture. NOT BOOKWORM.

I did this on Windows 10 connected to Raspberry Pi 4B through Ethernet cable and SSH.

 

This guide is very specific in order avoid bugs and stability by
- 64-bit OS
- compiling JSVC 1.1.0
- commons-daemon-1.3.4-src
- mongodb version 4.4.18.

- Omada_SDN_Controller_v5.9.31_Linux_x64.deb
 

Requirement:
- Use 64-bit version (arm64 or aarch64)
- MicroSD card >= 32GB
- Internet connection
- Download Raspberry Pi Imager

 

Step 1: Raspberry Pi - install Raspberry Pi OS on the MicroSD card

 

A. plug in the MicroSD card to your PC

B. download Raspberry Pi Imager from Raspberry Pi Imager.

- download for Windows 10 if you are Windows like me.
- install "imager_x.x.x.exe" with the wizard
- open Raspberry Pi Imager as Admin > click on CHOOSE OS > select Raspberry Pi OS (other) > select Raspberry Pi OS (64-bit)
- under Storage > select your MicroSD card
- go into the Advanced option that looks like a Cog wheel >
 + Set hostname: *whateveryouwant*.local - for me: Omada.local
 + Enable SSH > using public-key authentication

 

OPTIONAL: SSH-gen key pair (you can do this on whatever OS you want. I'm doing it on Linux so use.

 

    ssh-keygen -t rsa -b 4096

 

Note: 2 keys are made. 1 is public key, 1 is private key. You send the public key to the machine you want to log in(Raspberry Pi). You keep the private key on the machine you use (your PC) to prove who you are. I named them `nameofthekey` and `nameofthekey.pub`.

- I named the key omada and omada.pub

- Use SSH username and password that you made within `Raspberry Pi Imager`.

IMPORTANT: Before writing the OS onto the MicroSD card, Enable the SSH option with Allow public-key authentication only, so you don't have to use password to SSH.

- Copy the long string inside of omada.pub that you made in ssh-keygen. Paste it into the Setting (Cog wheel) inside of Raspberry Pi Imager.
- Use the username pi if you want.
- The IP address of the pi on my network is 192.168.16.105 or hostname omada. Your IP address for the Pi depends on your network.

 + Set username > username: yourname > password: yourpassword
 + for me username: omada and password: omada.
 
NOTE: Please change these names and password to your own choosing to enhance the security.

SSH will the main method that you will interact with Raspberry Pi in the back end. So proper configure this step or you will have to re-flash the MicroSD card.

 

 

- hit Save
- click Write
- warning box pop up: select YES
- now wait for the writing to complete before ejecting the MicroSD card.
- select Continue after Write Successful popup. You can eject the MicroSD card now.
- put the MicroSD card into the Raspberry Pi 4B now.
- power on the Pi and use the Ethernet cable to connect to your network.
- check within your router to see what IP address did the Raspberry Pi use. For me: 192.168.16.105

 

Step 2: SSH into the Pi

I'm using Terminal on Windows 10 to SSH into the Raspberry pi. I left the private key in Home user folder of Windows 10.

 

    ssh -i /Users/admin/nameofthekey omada@192.168.16.105

It should looks like this when you have successfully SSH into the Pi

 

 

Step 3: Update and upgrade - to avoid older repo and old bugs

 

    sudo apt update && sudo apt upgrade -y

 

Step 4: Download and install MongoDB - please use MongoDB 4.4.18

A. Install MongoDB

 

    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 apt install /home/omada/mongodb-org-server_4.4.18_arm64.deb

 

B. Check if Mongodb is running

 

    sudo systemctl daemon-reload

    sudo systemctl enable mongod

    sudo systemctl start mongod

 

Step 5: Install curl

 

A. check if Raspberry Pi OS already has curl

    
    apt list curl

B. If not, install curl

    sudo apt install curl

Step 6: Install OpenJDK 11 and JVSC 1.1.0, fix a symbolic link

Background: Debian and Ubuntu removed repositories related to Java 8 so you cannot easily install Java 8 with a simple apt command. Java 11 still works with Omada SDN controller so we will proceed with Java 11.

A. Install the dependencies first: autoconf, make, gcc, JDK 11.

 

    sudo apt install autoconf make gcc

    sudo apt install openjdk-11-jdk-headless

    sudo apt remove jsvc

 

B. Compile and install JVSC 1.1.0

 

Download the source codes from Apache official website, ,then compile and install.

Note: that the following links are for reference only and may be invalid due to version update, you can visit the website to confirm the current version and download link.

Do not download the common-daemon-1.3.4-native-src.tar.gz. Use the commons-daemon-1.3.4-src.tar.gz instead.

 

You can read the INSTALL.txt in unix folder if you want to understand how to compile and install.

 

    wget https://dlcdn.apache.org/commons/daemon/source/commons-daemon-1.3.4-src.tar.gz

 

    tar -xzf commons-daemon-1.3.4-src.tar.gz

    cd commons-daemon-1.3.4-src/src/native/unix

    sh support/buildconf.sh

Note: You must cd outside of support directory to run sh as is above. Otherwise it won't run. Running `sh buildconf.sh` WILL NOT WORK inside of support directory.

Note: "/usr/lib/jvm/java-11-openjdk-arm64" is the default installation path of OpenJDK-11.

 

    ./configure --with-java=/usr/lib/jvm/java-11-openjdk-arm64

then you can run

    make

 

Create a soft link from your JSVC path

    sudo ln -s /home/omada/commons-daemon-1.3.4-src/src/native/unix/jsvc /usr/bin/

C. Fix a symbolic link in Java 11

 

    sudo mkdir /usr/lib/jvm/java-11-openjdk-arm64/lib/aarch64

    sudo ln -s /usr/lib/jvm/java-11-openjdk-arm64/lib/server /usr/lib/jvm/java-11-openjdk-arm64/lib/aarch64/

 

All this to avoid TP-Link Omada Controller Install Java Home Error. It might stop the Omada Controller from starting when it reboots.

It looks something like this

    Starting Omada Controller. Please wait.Cannot find any VM in Java Home /usr/lib/jvm/java-11-openjdk-arm64/

Step 7: Download and install latest version Omada SDN controller from TP-Link Official Download list

Note: We're going to use Omada_SDN_Controller_v5.9.31_Linux_x64.deb

 

    cd ~

    wget https://static.tp-link.com/upload/software/2023/202303/20230321/Omada_SDN_Controller_v5.9.31_Linux_x64.deb

    sudo dpkg --ignore-depends=jsvc -i Omada_SDN_Controller_v5.9.31_Linux_x64.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 use the IP Address of the Raspberry Pi to setup the controller in your browser of choice.

 

 

e.g. : http://192.168.16.105:8080 or https://192.168.16.105:8043

 

Step 8: Hold back packages so you don’t accidentally update the Mongodb to a newer version.

To list packages that can be upgrade

    apt list --installed | grep "mongodb"

Hold back mongodb packages

    sudo apt-mark hold mongodb-org-server

    sudo apt-mark hold mongodb-org-shell

    sudo apt-mark hold mongodb-org-tools

    sudo apt-mark hold mongodb-org

    sudo apt-mark hold mongodb-org-mongos

    sudo apt-mark hold mongodb-org-database-tools-extra

 

To check if they are held back

    apt-mark showhold

To cancel the hold

    sudo apt-mark unhold mongodb

 

 

OPTIONAL - Step 9: use these commands to check if everything is working correctly

If you happen to lose power or reboot the Raspberry Pi, after SSH into the Pi to check if everything booted properly, use the follow commands

 

Note: It takes around 60s before RPi allows you to SSH. It takes around 2 minute 30 seconds before Omada Software Controller fully run.

Check the running status of the controller

 

    sudo tpeap status

 

Start the controller

 

    sudo tpeap start

 

Stop the controller

    sudo tpeap stop

 

Check if mongodb is running

 

    sudo service mongod status

 

or

 

    ps -ax | grep mongo

Fix a bug because I missed a package required by Java

    sudo apt --fix-broken install

after the first reboot to check if apt is working properly.

 

Update from 5.9.31 to 5.12.7

 

To update from 5.9.31 to 5.12.7

 

Important: You will need to backup your config files and export all data in case this step fails midway.

 

Step 1: Backup your precious data and configs

 

- log into your web management page on port 8043 with your credentials

- click the bottom-left COG symbol > Maintenance > under Backup > Select the time range of data you want > EXPORT

to download the file that needed to restore your configuration.

 

 

Its name is "omada_backup_5.9.31_NoLimit_202x-xx-xx_xx-xx-xx"

 

+ export Running Logs and Configuration Data in case you encounter a bug and need to submit those logs to TP-Link Support if you can.

 

Step 2: Stop the processes ran by Omada Controller before updating on the Pi

 

    sudo tpeap stop

 

 

Wait for the controller to stop before doing anything.

 

Step 3: Download 5.12.7 from the TP-Link Official page

 

 

    cd ~

    wget https://static.tp-link.com/upload/software/2023/202309/20230920/Omada_SDN_Controller_v5.12.7_Linux_x64.deb

    sudo dpkg --ignore-depends=jsvc -i Omada_SDN_Controller_v5.12.7_Linux_x64.deb

 

 

 

Log back in from the web management page and check for Controller version.

 

 

Resources: