Update 2020/04/30: Omada EAP Controller 3.2.10 community version has just been released.

There is now a .deb-package available for easy installation on Debian, Raspbian and any other Debian-based Linux. The steps below are not necessary anymore for the installation of Omada Controller using the dpkg package manager.

 

The following (now obsolete) post is still here for reference only:

 

By accident, I stumbled over Omada Controller 2.7.0 for Windows. Looks cool, introduces meshing for EAP225-Outdoor and uses JRE 8 instead of buggy JRE 7. Release notes from TP-Link are on the US support site. Here is the derived community release (»fan-made movie«) of

 

Omada Controller 2.7.0 for Linux

 

Latest update: 2018-08-21 20:50

 

Seems to run stable. By now it is in use on our main production site and two dozen servers of other users.

Usual disclaimer: Use at your own risk. This community version is neither released nor supported by TP-Link.
 

Prerequisites

 

To install Omada EAP Controller 2.7.0 on your Linux system you will need:

• JRE 8 at least, preferably from Oracle (but might probably work with OpenJDK, too)
• the native package of mongodb from the official repositories
• a role account (username eapc) for Privilege Separation.

 

In this version there are no binaries embedded with EAP Controller. This way, it should run on any flavour of Linux. Tested already with Debian, Devuan, Ubuntu and Raspbian.

 

Important Step 0: 

Before replacing your old EAP Controller (EAPC in short for the rest of the document) make a backup. This backup should include the EAPC software itself and the content of its database.

 

First method for backing up the EAPC's database

You can choose the backup function of the web UI, but then make note of the device passwords and EAP associations, since you will have to adopt all EAPs again. 

 

Second method

For me a copy of the complete data subdirectory worked much better: it did retain each and every setting, even the map files. Those steps are described below in step 7 after setting up the mongo database.

 

Third method

If you have installed EAP Controller v2.6.1 for Linux (community version) and did choose to use the native mongodb package from your system's repository, there is a third method for backup: using the mongodump utility. Execute the command:

 

        mongodump --out /opt/tplink/backup

 

This will create a directory backup with all collections of all databases in (binary) BSON format for later restoration later. The backup files contain everything except for the map and portal files, which are stored in EAP Controller's data/map and data/portal directories. Just copy those two directories to the new installation as outlined in step 7 below. 

 

If you did install EAPC v2.6.1 for Linux I posted in May this year, then updating the EAPC software is as easy as modifying some symlinks and copying over the whole data directory. If something goes wrong, you can easily downgrade to any older EAP Controller version – unlike the Windows users, whose installer will not let them do a downgrade once v2.7.0 has been installed. No mercy from me. 

 

 

Step 1: setting up a role account

 

Please note that at least you must create the role account before installing any files from the TAR archive. If not, file/directory permissions won't match and EAPC won't start at all. If you already did install my version 2.6.1, you can skip this step and proceed with step 2.

 

To add a role account with username eapc, execute the following command as root:

 

        adduser --system --disabled-login --group --no-create-home \

                --home /opt/tplink/EAPController \

                --gecos "EAPC privilege separation" \

                --shell /bin/false eapc

 

[Above command updated: we no longer need to assign the eapc user a shell: changed /bin/bash into /bin/false]

 

 

Step 2: Download the TAR archive with Omada Controller v2.7.0

 

Download the TAR archive from https://rent-a-guru.de/ftp/eapc-2.7.0.tar.gz

See, it's just 39 MB. The Windows version is more then three times as fat, just like Bill Gates today compared to his look in the late 1970s.

Small is beautyful, at least regarding software!

 

Check the SHA256 sum:

        $ sha256sum -b eapc-2.7.0.tar.gz
        0a482e7d129dd787ed40b38f109728db92653b2768b3979a53ab2abc8d9d51cc  *eapc-2.7.0.tar.gz

 

 

Step 3: Extract the TAR archive

 

Change into /opt/tplink and extract the TAR archive as root. You need to do this operation as root in order to retain file ownership from the archive. Most files are owned by root, but some are owned by eapc, the user ID the EAPC is running under. Did I tell you that it has privilege separation for enhanced security? I did.

 

        # tar xvzf eapc-2.7.0.tar.gz

 

This will create two directories - EAPController-2.7.0 and tpeap-1.2 - and a file README. Note that the start/stop script tpeap is already installed in the controller's directory, but included separately for your reference and for installation of its manpage.

 

Check ownership of the top-level directories, it should look like this:

 

        # cd /opt/tplink

 

        # ls -ld EAPController-2.7.0

        drwxr-xr-x 11 eapc eapc 139 Jul 26 07:53 EAPController-2.7.0

 

        # ls -l EAPController-2.7.0

        drwxr-xr-x 2 root root   55 Jul 26 01:18 bin

        drwxr-xr-x 6 eapc eapc   51 Jul 26 07:53 data

        drwxr-xr-x 2 root eapc   39 Jul 26 01:05 keystore

        drwxr-xr-x 2 root root 4096 Jul 26 01:05 lib

        drwxr-xr-x 2 eapc eapc   96 Jul 26 07:53 logs

        drwxr-xr-x 2 root root 4096 Jul 26 01:06 properties

        drwxr-xr-x 2 root root   36 Jul 26 01:07 webapps

        drwxr-xr-x 3 eapc eapc   32 Jul 26 07:53 work

 

 

Step 4: Replace the old EAPC

 

Now lets organize your EAPC home directory. Stop the Controller if it is running. If you want, make a backup before doing so.

 

– If you are upgrading from an older version (< v2.6.1), rename the directory EAPController and install a symlink to the new one. For example, for an EAPC v2.5.3 the commands are:

 

        # cd /opt/tplink

        # mv EAPController EAPController-2.5.3

        # ln -s EAPController-2.7.0 EAPController

 

– If you are upgrading from v2.6.1 and have installed it as recommended, just change the symlink:

 

        # cd /opt/tplink

        # rm EAPController

        # ln -s EAPController-2.7.0 EAPController

 

As you can see, we use the file system for version control. The name EAPController is just a symlink to the current EAPC version.

 

This is a non-destructive update; to downgrade at any time you like, just point the symlink to the appropriate target directory. It's that easy!

 

 

Step 5: Install the JAVA JRE

 

Probably you did note in the file listing above that the JRE normally embedded in EAPC is missing from the distribution. EAPC v2.7.0 uses Java JRE 8 and since this is available on many Linux distributions by default, I didn't embedd it in the TAR archive intentionally.

 

The EAPC version for Windows uses JRE 1.8.0_162. For my Debian Linux system I did install JRE 1.8.0_181. Find and download the JRE for your platform in the official software repository of your Linux distribution or download it directly from Oracle's website.

 

For example, the Linux x86_64 JRE can be found here:

 

        https://java.com/en/download/manual.jsp

 

Extract the files from the TAR archive to where you would like them. For example, you can extract them into /opt/jvm or into /usr/lib. If you extract the archive as root, specify the option --no-same-owner to tar in order to prevent assigning the files to the user from the archive. The extracted files should be owned by root, group root.

 

To set up the JRE, you can use the alternatives mechanism (useful if you want to try different JRE versions without having to change the tpeap start/stop script):

 

        # update-alternatives --install /usr/bin/java java /opt/jvm/jre1.8.0_181/bin/java 1000

 

or simply install a symlink manually:

 

        # cd /opt/tplink/EAPController-2.7.0

        # ln -s /opt/jvm/jre1.8.0_181/bin/java /usr/bin/java

 

Now check whether Java is installed correctly:

 

        # /usr/bin/java -version

        java version "1.8.0_181"

        Java(TM) SE Runtime Environment (build 1.8.0_181-b13)

        Java HotSpot(TM) 64-Bit Server VM (build 25.181-b13, mixed mode)

 

Finally, create a symlink to the JRE into the EAPController-2.7.0 directory:

 

        # cd /opt/tplink/EAPController-2.7.0

        # ln -s /opt/jvm/jre1.8.0_181 jre

 

Done!

 

 

Step 6: Set up the mongo database

 

In EAPC v2.6.1 I did recommend to use the native mongodb package from the official Debian/Devuan/Ubuntu/Raspbian repository. Therefore, there are only symlinks in directory EAPCotroller-2.7.0/bin pointing to the native mongodb binaries:

 

        # ls -l /opt/tplink/EAPController-2.7.0/bin

        lrwxrwxrwx 1 root root   14 Jul 26 01:17 mongo -> /usr/bin/mongo

        lrwxrwxrwx 1 root root   15 Jul 26 01:18 mongod -> /usr/bin/mongod

 

If you want to use the old mongodb embedded in EAPC v2.6.1 (which actually came from TP-Link's official EAPC v2.5.3), you can try this, but I have not tested it.

 

If you have not installed mongodb yet, do this now:

 

        # apt-get update

        # apt-get install mongodb --no-install-recommends

 

Disable automatic startup of mongod on boot. mongod will be started by EAPC, which is no good idea, but since it's hardcoded in EAPC's Java code, you have no choice at all:

 

        # systemctl stop mongodb.service

        # systemctl disable mongodb.service

or:

        # update-rc.d mongodb stop

        # update-rc.d mongodb disable

or:

        # service mongodb stop

        # service mongodb disable

 

 

Important note:

Before proceeding with next step, check the version of mongodb just installed. To do so, manually run the command:

 

        # mongod --version

 

– If your mongodb version is < 3.6, continue with step 7.

 

– If your mongodb version is >= 3.6 you need to edit the argument list EAPC uses to start the mongod daemon. The option --nohttpinterface, which is set by EAPC, has been removed in mongodb version 3.6 and newer. To get rid of this option, you will have to delete it from the file mongodb.properties.

 

To do so, make a backup of and edit the file /opt/tplink/EAPController/properties/mongodb.properties using your favorite editor. Search for the line starting with eap.mongod.args= (should be line 15) and remove the --nohttpinterface option from the list of arguments.

My favorite editor for doing such stuff is sed, the good old UNIX stream editor: 

 

        # cd /opt/tplink/EAPController/properties

        # cp mongod.properties ../mongod.properties.ORIG

        # sed -i 's/^\(eap.mongod.args=.*\) --nohttpinterface \(.*\)$/\1 \2/' mongodb.properties

 

Thanks to miked315 for reporting this bug found on Ubuntu systems with mongodb 3.6.3.

 

 

Step 7: Restoring configuration from EAPC v2.6.1

 

As mentioned above, to restore settings from an old installation in the new one copying the data directory did work for me, so you might try this, too. Make sure that the files are owned by the eapc user, else mongod won't be able to write into those files:

 

        # cp -r EAPController-2.6.1/data/ EAPController-2.7.0/

        # chown -R eapc.eapc EAPController-2.7.0/data

 

WARNING

On my system the existing database from TP-Link's older mongodb embedded in EAPC v2.4.8 for Linux was not useable with latest mongodb from the Debian package repository. I had to delete all files below EAPController/data to make EAPC v2.6.1 starting up successfully. Almost certainly, this is also true for upgrades from older versions < v2.6.1 to v2.7.0 and even from v2.6.1 to v2.7.0 if you did not use the native mongodb package back then.

 

If in step 0 above you did save the database content of v2.6.1 using mongodump, you can now restore the DB using mongorestore. Execute the command:

 

        # mongorestore --drop /opt/tplink/backup/

 

The option --drop is important, it will drop all colelctions before installing the saved ones. This will restore all collections of all databases, but not the map and portal files. To make the database consistent again, copy the directories data/map and data/portal from your old EAPC to the new version. Again, make sure the files are owned by the eapc user:

 

        # cp -r EAPController-2.6.1/data/map EAPController-2.6.1/data/portal EAPController-2.7.0/data/

        # chown -R eapc.eapc EAPController-2.7.0/data

 

 

Now you probably got the idea why I did recommend to use the official mongodb package with EAP Controller rather than an embedded version. If upgrading to a new mongodb version, your database will be retained by apt-get. In addition, you can easily make a backup using mongodump and restore it using mongorestore at any time, even as a scheduled task.

 

 

Step 8: Do you read manuals? Sure you do.

 

The tpeap start/stop script is already installed in EAPC v2.7.0. But you might want to install the manpage, too. You find the man page of tpeap

in the subdirectory tpeap-1.2 from the TAR archive:

 

        # cd /opt/tplink/tpeap-1.2

        # cp tpeap.man  /usr/share/man/man8/tpeap.8

        # gzip -v --best /usr/share/man/man8/tpeap.8

 

If you did upgrade from an older (< 2.6.1) version, you might want to install symlinks for automatic start at system boot. To do so, run those commands:

 

        # ln -s /opt/tplink/EAPController/bin/tpeap /etc/init.d/tpeap

        # update-rc.d tpeap defaults

 

Note that /etc/init.d/tpeap links to EAPController/bin/tpeap, not to EAPController-2.7.0/bin/tpeap, so further upgrades won't require any modification.

 

If you want, you can also add a symlink into /usr/bin, so that the command can be run independent of your position in the directory tree:

 

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

 

 

That's all. Now start EAPC by running tpeap and watch the blinkenlights:

 

        # tpeap -w start

 

 

Two final notes:

 

– If tpeap fails with an error message, but EAPC appears to be running after a while, your system needs more time to start the EAPC. Yes, it's Java, even on modern systems slow as a snail. tpeap has a new option -W sec, which let's you set the time-out in seconds, after which tpeap will abort if EAPC seems not to be running. If you found the best value for the time-out on your platform, you can change it permanently by modifying the variable WAIT_TIME in the tpeap script.

 

– If tpeap is started on boot time, it will not wait for completion of the EAPC startup, but rather start the controller in the background and return immediately so that it will not delay the start of other services. The new version of tpeap will even indicate the startup period if you interactively check for the current status of EAPC:

 

        # tpeap status

        EAP Controller is still initializing, please wait 51.734.945.283.421.835.268.775 more CPU cycles¹

 

¹ Just kidding, the number is much smaller and is not displayed.

 

After a while, this changes to:

 

        # tpeap status

        EAP Controller is up and running.

 

Have fun!