Install TP-Link Omada Controller 3.0.2 on Debian 9.6 Stretch

I recently performed this setup for a client who runs EAP access points in an enterprise environment. Naturally while TP-Link offers a version of the Omada controller for Windows, said client experienced multiple issues with running it on a Windows Server 2016 install…

I thought “What’s the best way to go about this setup?” and it dawned on me – this client uses Linux-based virtualization, what could be better than to have this running in an LXC container? A fully virtualized Windows Server 2016 setup running the controller took up 35GB of disk space and about 4GB of RAM (to be honest, not a big deal, but why waste?). Compare that with the 2GB of disk space and 260MB of RAM that is possible using Debian in an LXC container and the winner is pretty clear… Obviously, the instructions below will work on any standard Debian 9.6 installation, regardless of whether it’s running in a LXC container, in a VM, or on bare-metal.

When I went about the task of getting everything set up, I tried to follow the guide at https://community.tp-link.com/en/business/forum/topic/150123, however I ran into enough problems along the way that I decided it would be worth doing this write-up for Debian specifically. All credit for the Community Edition of the Omada files goes to them. That being said there are a few ways you can go about the setup.

General Disclaimer: No one other than yourself is responsible for anything bad that may happen by following anything contained here in this article. Now you know.

Method 1: Use my pre-built installer/configurator.

The package includes the Omada files (Community Edition) from the forum mentioned above, Java 8 Update 201 (64-bit), and an install script that can automate the setup. If you’re reading this I’ll assume you know the risk that comes with running scripts written by random internet geckos – and also that you know enough about bash to check through some scripts to ensure they won’t text your nudes to your grandma or cause your hardware to grow limbs and kick your dog.

Method 2: Build and configure everything yourself line by line.

Essentially the same as above, but more hands-on.

Method 3: Go to the original forum post and follow their directions.

Maybe you’ll have better luck than I did – and if not there’s always the chance that the community will be able to help you quicker than I can.

Let’s get started, Method 1:

To start we’ll want to enter our (completely fresh) Debian installation and download the pre-built installer. This site uses a CDN so the download time should mostly depend on your internet connection (though the archive is about 124MB in size, so keep that in mind). From the terminal type:

wget -O omada3.0.2-debian6.9.tar.gz https://tech-jungle.com/download/omada-3-0-2-for-debian-9-6

If for whatever reason that doesn’t work as smoothly as it should, you can download the archive below.

Omada 3.0.2 for Debian 9.6 (278 downloads )

After the package has finished downloading, the next step is to ensure it matches it’s checksum.

sha256sum -b omada3.0.2-debian6.9.tar.gz

If the above command returns “e9ffce3452d2da21c1b85ef5ef57217c0ff685b8e450a6cbb85258e3e5e63a7e *omada3.0.2-debian6.9.tar.gz” then we are good to proceed.

Unpack the archive with tar and then cd into it:

tar zxvf omada3.0.2-debian6.9.tar.gz
cd omada3.0.2-debian

Sane practice dictates you open the install.sh file in the text editor of your choice before running it (and checking for malicious code therein). After you’ve done that, make the installer executable and run it by issuing:

chmod u+x install.sh
./install.sh

The installer will ask you a few questions about how you want things set up, and will notify you when everything has completed. Congratulations!

Mandatory Plug: If this helped you, please leave me a comment. If you really want to show me some love (because of the implication), maybe consider downloading the Brave browser using my affiliate link – it’s a great browser that has (among other features) Ad-Block and Private Browsing over the Tor network built in. Not only that but it doesn’t send every ounce of your business to the Google overlords. 🙂

Method 2:

For method #2 we’ll need to start by installing the dependencies. This is fairly straight forward:

apt-get install psmisc mongodb net-tools

Next we’ll need to download the Omada files and Java (both to the same directory we intend to work from). The Omada files we can get from the community forum like so:

apt-get install ftp
ftp ftp.rent-a-guru.de

When prompted for a username, enter “ftp”.
When prompted for a password, enter your email.

Next we’ll start the download, keep in mind it can take some time, so just be patient.

cd /private
bin
get eapc-3.0.2.tar.gz
quit

Java can be a little more tricky to get because the user agreement on their site means simply using wget won’t work (at the very least not without a bit of a work around). The easiest way to accomplish this is probably to download Java for Linux (the .tar.gz file) on a desktop and scp it over to the Debian installation.

After that is done, create a directory for JRE and unpack it there. In this example, /usr/local/java is used (if you use a different location, keep that in mind for later).

mkdir /usr/local/java
tar zxvf jreXXX_XXX-linux-x64.tar.gz -C /usr/local/java/

*Note: Be sure to replace the “XXX_XXX” above with the actual name of the JRE archive*

For privilege separation, we will create a user for the controller software to run under. This can be done by running:

adduser --system --disabled-login --group --no-create-home --home /opt/tplink/EAPController --gecos "EAPC privilege separation" --shell /bin/false eapc

The next order of business is to create a directory for the Omada controller files and extract said files to it.

mkdir /opt/tplink
tar zxvf eapc-3.0.2.tar.gz -C /opt/tplink/

Now we’ll change into the tplink directory and create a symlink for our version of the controller.

cd /opt/tplink
ln -s EAPController-3.0.2 EAPController

Changing directories again, we’ll now create a symlink in the EAPController directory to our JRE.

cd EAPController
ln -s /usr/local/java/jreXXX_XXX/ jre

*Note: Again, you will need to replace the X’s above with actual name of the JRE folder, don’t forget to do the same below*

To ensure everything executes correctly, I also had to symlink the JRE to /usr/local/bin.

ln -s /usr/local/java/jreXXX_XXX/bin/java /usr/local/bin/java

To run the tpeap command from the command line (without having to cd into the /opt/tplink/EAPController/bin directory) we can symlink it up also.

ln -s /opt/tplink/EAPController/bin/tpeap /usr/local/bin/tpeap

Now that’s done, we need to edit the tpeap script to ensure it finds our JRE. After opening the file in your text editor (vim, nano, etc.) look for the line that starts with “JAVA_TOOL” and make sure it’s value is “/usr/local/bin/java”.

nano /opt/tplink/EAPController/bin/tpeap

The last thing we will need to do is to make sure the “mongod” service does not run at boot (by default it does, but this causes an error when running the controller because it attempts to spawn another instance). Because the daemon was started after we installed it, we’ll also kill the currently running instance.

systemctl disable mongodb
killall mongod

If another Omada controller is running on the network, you will need to stop it prior to trying to start the new one – otherwise the new controller will throw an error and stall. To fire up the controller simply type:

tpeap start

Give it a few minutes to start. Then you can check the controller’s status with:

tpeap status

When everything has loaded up, you can access the controller via a web browser by going to: https://<yourserverip>:8043

As a bonus

For my setup I wanted the controller to automatically start at boot – this was actually a bit more difficult to setup than I thought it would be, however I finally worked out a solution. Keep in mind that if you used Method 1 above to setup the controller, the installer script will have already set this up for you if you indicated it was something you wanted when prompted… Otherwise read on.

First we’ll create an autostart script which we will then set cron to run. To create the script:

nano /opt/tplink/EAPController/bin/autostart.sh

In that script we will enter the following:

#!/bin/bash

## Set working directory PATH=/sbin:/bin:/usr/sbin:/usr/bin:/opt/tplink/EAPController/bin

## Start EAP Controller
tpeap start &
disown

exit 0

Save and exit the script, then set the script to be executable.

chmod u+x /opt/tplink/EAPController/bin/autostart.sh

Now we’ll create an entry in cron to run our autostart script at boot.

crontab -e

At the very bottom, enter the following:

@reboot /opt/tplink/EAPController/bin/autostart.sh

Save the crontab and exit. Congrats, all done!

Mandatory Plug: If this helped you, please leave me a comment. If you really want to show me some love (because of the implication), maybe consider downloading the Brave browser using my affiliate link – it’s a great browser that has (among other features) Ad-Block and Private Browsing over the Tor network built in. Not only that but it doesn’t send every ounce of your business to the Google overlords. 🙂