Installing TP-Link EAP Controller 3.0.5 on a Raspberry Pi

Are you also looking for a way to use the more advanced functions of our TP-Link Omada EAP Series “Business Wi-Fi”? The Omada Cloud Controller OC200 seems to be a reasonably priced option, but for us using a Raspberry Pi 3 we weren’t using was cheaper. Sadly, TP-Link only provides files to install the EAP Controller software on x64 hardware (and x86 on Windows), while the Raspberry Pi is ARMv8 based:

  1. Omada_Controller_V3.0.5_Linux_x64.deb
  2. Omada_Controller_V3.0.5_Windows32bit
  3. Omada_Controller_V3.0.5_Windows64bit
  4. Omada_Controller_v3.0.5_linux_x64.tar.gz

Luckily, the TP-Link EAP Controller software uses a combination of Java and MongoDB. Both run just fine on ARM hardware and after some tinkering it turned out quite easy to set up the EAP Controller on the Raspberry Pi. We’ve documented the steps we took. After you’ve unpacked the software it’s just 10 small commands to run, so it should be straightforward enough.

In figuring out the best way to run the software we found a topic at the TP-Link forum. It is a good initiative and an insightful write-up, but it is non-official software. We’re cautious about installing software from people on the internet, so we decided not to use it. We also found a blog post that was very helpful to us. The difference with our method is that the blog post fixes the controller software after the install fails. This while we configure the files before installing (and add privilege separation), which we like a bit better.

Step 0: We assume you’ve already done this

  1. Download the latest Raspbian Stretch Lite, from the official website.
  2. Install it on your Raspberry Pi. If you don’t know how, follow the official guide. (We’ve flashed 2018-11-13-raspbian-stretch-lite.img with Etcher)
  3. Update and configure your Raspberry Pi how you like it.


Step 1: Download and unpack the required software

We’ll run the commands in all steps as root, which is why we start with sudo -i. Also, for some reason TP-Link provides a zipped .tar.gz file. So we’ll have to unzip that before unpacking the .tar.gz file.

sudo -i && cd ~
tar -zxf Omada_Controller_v3.0.5_linux_x64.tar.gz


Step 2: Install MongoDB

Now we’ll install MongoDB, remove the included MongoDB and create a symlink to the MongoDB instance we installed.

apt-get install mongodb
rm Omada_Controller_v3.0.5_linux_x64/bin/mongod
ln -s /usr/bin/mongod Omada_Controller_v3.0.5_linux_x64/bin/mongod


Step 3: Install Java

Now we’ll install Java (specifically jsvc) and edit the file so it does not use the Java and portt software TP-Link included, as these are compiled for the x64 architecture. We’ll also use the client VM, as the server VM is not included in our version of Java.

apt-get install jsvc
sed -i -e 's/JRE_HOME="${OMADA_HOME}\/jre"/JRE_HOME="\/usr\/lib\/jvm\/default-java"/g' Omada_Controller_v3.0.5_linux_x64/bin/
sed -i -e 's/JAVA_OPTS="-server/JAVA_OPTS="-client/g' Omada_Controller_v3.0.5_linux_x64/bin/
sed -i -e 's/${PORTT_TOOL} ${HTTP_PORT} 500/netstat -plnt | grep :::${HTTP_PORT}/g' Omada_Controller_v3.0.5_linux_x64/bin/


Step 3.1: Create Java Symbolic Link

The code alteration we just made assumes /usr/lib/jvm/default-java is a symbolic link to your Java directory. To check if this is the case, we’ll do the following.

cd /usr/lib/jvm
ls -hl

This shows a list of all files and folders located at /usr/lib/jvm. If there is a line “default-java -> ***” line, where *** is your Java installation location, please continue with Step 4. If not, we’ll have to create this symbolic link here:

The output from the previous command should contain at least one folder with a name something like “java-8-openjdk-armhf” or “java-1.8.0-openjdk-armhf”. This is the folder we need to create a symbolic link to. Replace *** in the following command with the name of your Java install folder to create a symbolic link.

ln -s *** default-java
ls -hl

This should now show a line stating “default-java -> ***”, where *** is your Java install directory.

Step 4: Add privilege separation

It’s bad form to run programs with root privileges when they don’t need them. If you wish to run as root you can skip this step, although it is not recommended. This creates the user eapc, whose home will be the directory we’re going to install the EAP Controller in, /opt/tplink/EAPController.

cd ~
adduser --system --disabled-login --group --no-create-home --home /opt/tplink/EAPController --gecos "EAP Controller user" --shell /bin/false eapc
sed -i -e 's/OMADA_USER=${OMADA_USER:-root}/OMADA_USER="eapc"/g' Omada_Controller_v3.0.5_linux_x64/bin/
sed -i -e 's/chmod 755 ${INSTALLDIR}\/jre\/bin\/\*/chown -R eapc:eapc ${INSTALLDIR}/g' Omada_Controller_v3.0.5_linux_x64/


Step 5: Install

Now that we installed Java and MongoDB, and configured and to use the proper software, we can install the EAP Controller.

cd ~/Omada_Controller_v3.0.5_linux_x64/

After accepting the install directory this runs the installation and starts the software, which can take several minutes. Especially starting the software can take quite some time, although TP-Link did apparently lower the starting time by 30% with v3.0 compared to v2.7.

The result

root@raspberrypi:~/Omada_Controller_v3.0.5_linux_x64# ./
Omada Controller will be installed in [/opt/tplink/EAPController] (y/n): y
Installation start ...
Install Omada Controller succeeded!
Omada Controller will start up with system boot. You can also control it by [/usr/bin/tpeap].
Starting Omada Controller....................................................................................................................................................................................tcp6       0      0 :::8088                 :::*                    LISTEN      9684/omada
tcp6       0      0 :::8088                 :::*                    LISTEN      9684/omada
Start successfully.
You can browse URL http://localhost:8088 for more.

You can now remove the files used to install the EAP Controller software, and browse to the appropriate IP address at port 8088 to enjoy your newly installed EAP Controller 🙂

Also useful information, to start/stop/check the status of the Omada Controller you can run one of the following commands:

tpeap start
tpeap stop
tpeap status


FAQ: “Cannot locate Java Home” error

If you get the “Cannot locate Java Home” error when starting the Omada Controller, Java cannot be found at “/usr/lib/jvm/default-java”. The easiest fix is to check where your Java install is located and create a symbolic link to that folder.

cd /usr/lib/jvm
ls -hl

This shows a list of all files and folders located at /usr/lib/jvm. There should be at least one folder with a name something like “java-8-openjdk-armhf” or “java-1.8.0-openjdk-armhf”. This is the folder you need to point default-java to. Replace “java-8-openjdk-armhf” in the following command with the name of your Java install folder to create a symbolic link.

ln -s java-8-openjdk-armhf default-java
ls -hl

This should now contain a line stating “default-java -> java-8-openjdk-armhf”. If so, start the Omada Controller:

tpeap start


Useless fact: Not every support page of TP-Link is as up-to-date as another. The English website has version 3.0.5, but the Dutch website has version 3.0.2 of the EAP Controller software even though version 3.0.5 is already almost 2 months old.

24 thoughts on “Installing TP-Link EAP Controller 3.0.5 on a Raspberry Pi

  1. Hi,
    I’m getting a error when installing.

    root@raspberrypi:~# sed -i -e ‘s/JRE_HOME=”${OMADA_HOME}\/jre”/JRE_HOME=”\/usr\/lib\/jvm\/default-java”/g’ Omada_Controller_v3.0.5_linux_x64/bin/
    root@raspberrypi:~# sed -i -e ‘s/JAVA_OPTS=”-server/JAVA_OPTS=”-client/g’ Omada_Controller_v3.0.5_linux_x64/bin/
    root@raspberrypi:~# sed -i -e ‘s/${PORTT_TOOL} ${HTTP_PORT} 500/netstat -plnt | grep :::${HTTP_PORT}/g’ Omada_Controller_v3.0.5_linux_x64/bin/
    root@raspberrypi:~# adduser –system –disabled-login –group –no-create-home –home /opt/tplink/EAPController –gecos “EAP Controller user” –shell /bin/false eapc
    Waarschuwing: De home-directory /opt/tplink/EAPController die u specificeerde is niet toegankelijk: No such file or directory
    Toevoegen systeemgebruiker `eapc’ (Groepsnummer 111)…
    Toevoegen nieuwe groep `eapc’ (Groepsnummer 115).
    Toevoegen nieuwe gebruiker `eapc’ (Gebruikersnummer 111) met groep `eapc’.
    Gebruikersmap `/opt/tplink/EAPController’ is niet aangemaakt.
    root@raspberrypi:~# sed -i -e ‘s/OMADA_USER=${OMADA_USER:-root}/OMADA_USER=”eapc”/g’ Omada_Controller_v3.0.5_linux_x64/bin/
    root@raspberrypi:~# sed -i -e ‘s/chmod 755 ${INSTALLDIR}\/jre\/bin\/\*/chown -R eapc:eapc ${INSTALLDIR}/g’ Omada_Controller_v3.0.5_linux_x64/
    root@raspberrypi:~# cd Omada_Controller_v3.0.5_linux_x64/
    root@raspberrypi:~/Omada_Controller_v3.0.5_linux_x64# ./
    Omada Controller will be installed in [/opt/tplink/EAPController] (y/n): y
    Installation start …
    Install Omada Controller succeeded!
    Omada Controller will start up with system boot. You can also control it by [/usr/bin/tpeap].
    Starting Omada Controller.Cannot locate Java Home

    What i’m doing wrong?

    1. First question: What operation system are you running?

      I see two errors in your log.
      1. The “No such file or directory” one doesn’t seem like a problem. During the creation of the eapc user the specified home directory does not exist yet and the command is told not to create it. It then states it cannot access the non-existent directory. However, it seems like the eapc user is created and that directory is created later during the installation.

      2. Could you check if /opt/tplink/EAPController was created during the installation?

      3. The real issue seems to be the “Cannot locate Java Home” message. It looks like the Omada Controller cannot find a Java instance to run from. Did you install jsvc? If not, could you run “apt-get install jsvc” as root and post the results?

  2. Following your steps, first I get “jsvc not found, please install jsvc”, once I install jsvc as root then try to restart service i get the error “Cannot locate Java Home”. Any ideas? I have the latest full raspbian install.

  3. I had the “Cannot locate Java Home” error too, I fixed it by correcting the code to match the location of JAVA in Raspbian…

    In the following piece of code replace /default-java with /jdk-8-oracle-arm32-vfp-hflt\/jre

    sed -i -e ‘s/JRE_HOME=”${OMADA_HOME}\/jre”/JRE_HOME=”\/usr\/lib\/jvm\/default-java”/g’ Omada_Controller_v3.0.5_linux_x64/bin/

    1. Welllll, I’m fairly certain you didn’t follow the steps above :p I opted for OpenJDK, you have the Oracle version of Java. I assumed “default-java” was created as a symlink to the actual Java install in “/usr/lib/jvm/” for every install, but apparently that’s not the case. I’ve updated the post to take this into account.

  4. Thanks for that “useless” fact at the bottom, gave me a chance to get the latest version.

  5. I followed all steps to the letter, from start to finish…, but “Start Failed”, is all I get. No error message. I’ve rebooted to no avail. When I check the status of the controller, it’s not started. tpeap start results in Starting Omada Controller…. (which lasts approx 2 minutes) and then Start failed again.

  6. On what hardware did you run this? And did you copy/paste the commands? Or also follow the text on what parts of the commands have to be edited?

  7. Hi job,

    thank you very much for your guide, it worked perfectly on my Raspi 3!
    Just a little hint for those (like me) who just copy & paste: In step 3.1 you jump to “/usr/lib/jvm” and in step 5 back to “cd Omada_Controller_v3.0.5_linux_x64/”. Then an error occurs, because the “~/” is missing. Just add it to your path: “cd ~/Omada_Controller_v3.0.5_linux_x64/” and you can almost blindly copy & paste.

    Thanks again and best regards

    1. You’re welcome 🙂
      Thanks, I’ve added the ~/ to step 5. I added “cd ~” to step 4 as well, since two of those commands should also be executed from that directory.

  8. I used these instruction to install 3.1.4 on a Debian (Raspbian)/Raspberry Pi 2B and it worked flawlessly. Just replace all 3.0.5 with 3.1.4 in the paths and you are good to go (and I also had to remove a few Chinese characters at the end of the folder name after unpacking).
    Thank you guys! You saved me hours of work and frustration.

  9. Starting Omada Controller.Invalid JVM name specified client

    I got this error. Can you tell me where im doing wrong? 🙁

    1. It sounds like your JVM (Java Virutal Machine) does not support the client VM, maybe it uses the server VM? You could try to change step 3, so you won’t change the “server” reference into “client” in the file.

      1. Thanks for your reply. Maybe I got this error bec. I’m using Raspbian stretch with desktop and recommended software that I think has already java installed. I succeeded all the step but have a error :). I will try your advise in step 3. This is my first time using raspberry pi 3b+ and I liked it.

        sed -i -e ‘s/JAVA_OPTS=”-client/JAVA_OPTS=”-server/g’ Omada_Controller_v3.0.5_linux_x64/bin/

        That’s the code I need to change?

        1. The line “sed -i -e ‘s/JAVA_OPTS=”-server/JAVA_OPTS=”-client/g’ Omada_Controller_v3.0.5_linux_x64/bin/” tells to use the client VM in stead of the server VM. You can just skip that line if your installed JVM supports the server VM.

  10. Tried to follow the instructions to install v3.1.4 on a Raspberry Pi 2B by changing all 3.0.5 to 3.1.4. All steps went okay until the last line: ./
    The error is : -bash ./ cannot execute binary file: Exec format error
    Any idea how to fix it? Thank you

    1. That sounds like you’re trying to install a piece of x86-64 (Intel/AMD) achitecture software on an ARM cpu. That won’t work :p

  11. I tried to install v3.1.4 on a Raspberry Pi 3. All steps went okay, but I’m getting the following error after starting the controller:
    Starting Omada Controller. Please wait.Cannot find any VM in Java Home /opt/tplink/EAPController/jre
    The /usr/lib/jvm directory:
    lrwxrwxrwx 1 root root 24 Jan 6 2017 default-java -> java-1.8.0-openjdk-armhf
    lrwxrwxrwx 1 root root 20 Oct 22 2018 java-1.8.0-openjdk-armhf -> java-8-openjdk-armhf
    drwxr-xr-x 5 root root 4.0K Apr 23 23:26 java-8-openjdk-armhf

    How can I fix this?

  12. Hello I have problem.
    Everything went fine until
    root@raspberrypi:~/Omada_Controller_v3.1.4_linux_x64# ./
    -bash: ./ Permission denied

  13. Installation of v3.1.13 on a freeshly installed pi2 went fine using above guide, I do encounter a problem however:
    After installation I was able to login to Omada and restore settings from back-up etc.
    However, after I rebooted the pi, i was no longer able to login to the webinterface of Omada. Neither from a win 10 pc connected by wire nor from my android phone.

    The error message i get is ‘request timed out’

    Setting up things via cloud acces using the Omada app on my phone seems to be working fine
    Is there some sort of timer i can adjust to solve this maybe?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.