[Update 11/2020] Omada SDN Controller 4.2.4 for Devuan, Debian and other Linux systems
First Version: 2020-07-15
Last Update: 2020-11-20
In good old tradition of the community version of Omada Controller I just re-packaged latest Omada SDN Controller 4.2.4 for installation on Devuan, Debian and any other Linux system providing the dpkg installer.
There have been massive changes in the omadactl script and I took the opportunity to re-introduce switching between controller versions as introduced with Omada SW Controller V2.7 years ago. This means that you can install Omada SDN Controller without overwriting your existing controller and you can switch between all installed versions on the fly w/o the need to downgrade. I think this is handy if you want to just preview Omada SDN Controller for now.
However, it has its price: Omada Controller V3.2.10 needs to be updated, too, if you want to use this feature. What's more, only V3.2.10 is supported for switching, but future versions of SDN Controller community version will support this function, too (for this to work the version number of the software package needed to be moved to the package name). This means that the old versions will not automatically be removed when installing a new version. You can manually remove the old version if the newly installed one runs to your satisfaction.
Standard Disclaimer
The community version contains the original Omada SDN Controller from TP-Link, but with Privilege Separation enabled by default, as well as omadactl, which is an enhanced shell script used to start/stop and to manage the Omada SDN Controller server process. For a full list of the differences between the community and the official version see the section at the end of this post. TP-Link only supports their official version of the controller, but naturally this will affect the controller software in this community version, too. As for omadactl, this shell script is supported by me (R1D2) and bugs are fixed when reported.
Note that I can not give any support for installation of the software on a particular Linux system.
Please don't ask for step-by-step instructions or even videos on how to install the software. Every information needed to install the software is described in this post. If you cannot manage to get the software running on your Linux system, consider use of the OC200 or OC300 controller, which both also use Linux, but hide the details of the software setup.
Prerequisites
There are a few things to consider before installing Omada SDN Controller:
- As usual, you need Oracle JRE8, jsvc, mongodb, netstat (package net-tools) and curl.
Make sure you have those utilities installed before installing Omada SDN Controller. See the notes below.
- Important: If you want to adopt your EAPs, you need to update their firmwares.
See the posts from TP-Link in this forum and the Omada Controller Upgrade Guide which is included in the Omada SDN Controller package as well as attached to this post for your convenience.
MongoDB database
Omada SDN controller requires at least mongodb V3.2 or newer. The following packages are known to work (note the different package names!):
OS |
Package name |
Version (dpkg) |
---|---|---|
Devuan ASCII |
mongodb |
3.2.11-2+deb9u1 |
Debian 8 |
mongodb-org |
3.2.22 |
Debian 8 |
mongodb-org |
3.6.22 |
Note that only mongodb V3.2 or mongodb-org V3.2 supports both, the old Omada Controller V3.2.10 and the new SDN Controller V4.
- On Devuan ASCII just install the package mongodb from the repository.
- On Debian and related distributions follow the installation instructions on mongodb.org for either V3.2.22 if you want to switch between Omada Controller versions:
https://docs.mongodb.com/v3.2/tutorial/install-mongodb-on-debian/
- If you want run only Omada SDN Controller and need no compatibility of mongodb with Omada Controller V3.2.10, install mongodb-org V3.6 (or higher):
https://docs.mongodb.com/v3.6/tutorial/install-mongodb-on-debian/
Java Runtime Environment
It's recommended to use Oracle JRE. Some platforms offer a package in their repository, others don't. I prefer to donwload JRE8 from Oracle's website directly and to use the update-alternatives(8) mechanism to install the latest version. This is how it works:
- Download the 64-bit JRE for Linux (you don't need the full JDK).
- Extract the TAR archive into a directory of your choice (e.g. /opt/jvm).
- Install the JRE using update-alternatives:
update-alternatives --install /usr/bin/java java /opt/jvm/jre1.8.0_261/bin/java 261
Over the time your installed JRE packages might look like this:
# update-alternatives --list java
/opt/jvm/jre1.8.0_171/bin/java
/opt/jvm/jre1.8.0_181/bin/java
/opt/jvm/jre1.8.0_251/bin/java
/opt/jvm/jre1.8.0_261/bin/java
#
You can configure the version to use with the command update-alternatives --config java.
See the manpage of update-alternatives for more information.
Commons Daemon (jsvc)
You can try to install jsvc from the repository of your Linux distribution. However, last time I checked on Debian 8 jsvc required OpenJDK, which – if being installed – will configure itself as the default JRE using the update-alternatives mechanism. In this case I recommend to download the jsvc source and compile it instead of installing it via apt/apt-get. The jsvc binary actually does not require the OpenJDK, just the package jsvc is contained in depends on OpenJDK for whatever reasons.
Now for Omada SDN Controller: donwload the all-architectures .deb package
- Download the SDN controller from https://rent-a-guru.de/ftp/omada-sdn-controller-4.2.4_1_all.deb. Note the new package name, which starting with v4.2.4 contains the version number as part of its name.
- While you're at it, download the update for V3.2.10 from https://rent-a-guru.de/ftp/omada-controller_3.2.10-3_all.deb if you want to use switching between controllers. You can either install this update before or after installing the SDN Controller (see also the above note about mongodb versions supported by both, Omada Controller V3.2.10 and SDN Controller V4).
- Compare the checksums of the downloaded .deb files for integrity:
$ md5sum -b omada-sdn-controller-4.2.4_1_all.deb
a1d825befbb126dd9b868058205078a0 *omada-sdn-controller-4.2.4_1_all.deb
or:
$ sha256sum -b omada-sdn-controller-4.2.4_1_all.deb
d8414d75597322ecb7ca57cb293dfdfe7343f4e60365f8a6e6da09788ecfa77a *omada-sdn-controller-4.2.4_1_all.deb
- For the Omada Controller V3.2.10-3 package update:
$ md5sum -b omada-controller_3.2.10-3_all.deb
6b986ee67828d4c1e55d8dc6af1e8cbc *omada-controller_3.2.10-3_all.deb
or:
$ sha256sum -b omada-controller_3.2.10-3_all.deb
ef77aa88a3196d7663f35e59357a67833b86fa783923df480f56318ea84e5de2 *omada-controller_3.2.10-3_all.deb
Installation
Since SDN Controller has a new package name, your existing Omada Controller will not be overwritten, so it will retain all data. Again, read the Omada Controller Upgrade Guide to migrate your existing site to the new controller if you desire so.
Installing the V3.2.10 package update will also keep all settings, but to be on the safe site, make a backup before installing it. Please note that copying the database from an old controller to the new SDN Controller does not work; you need to migrate your site if you want to see the settings in the new controller.
Optional step (can be left out or executed at a later time if you're in a hurry): upgrade Omada Controller V3.2.10 if you have installed it:
dpkg -i omada-controller_3.2.10-3_all.deb
Now install Omada SDN Controller with the following command:
dpkg -i omada-sdn-controller-4.2.4_1_all.deb
Note that installing this package will overwrite the files /usr/bin/omadactl, /etc/init.d/omadad and /etc/default/omadad in an existing V3.2.10 installation if you left out the optional step above. Due to changes in Omada SDN Controller the locations of those files needed to be changed, too. They are now contained in Omada Controller's home directory (/opt/tplink/OmadaController).
In order to allow different versions of the Omada SDN Controller installed at the same time, the version number is now part of the package name. For example, your list of installed controller versions might look like this:
$ dpkg -l | fgrep omada
ii omada-controller 3.2.10-3 all Omada Controller for TP-Link's ...
ii omada-sdn-controller 4.1.5-2 all Omada SDN Controller for ...
ii omada-sdn-controller-4.2.4 1 all Omada SDN Controller for ...
$
Version switching
Now for the switching part. Try the following command (you can shorten »version« to just »v«):
$ omadactl -l version
Currently installed versions:
EAP Controller 2.7.0
Omada Controller 3.2.10
Omada Controller 4.1.5
Omada Controller 4.2.4 (current)
$
Next, try the switch command (as root):
# omadactl stop
Stopping Omada SDN Controller
# omadactl switch 3.2.10
Switched to 'OmadaController-3.2.10'. Now restart Omada Controller to activate it.
# omadactl switch 4.2.4
Switched to 'OmadaController-4.2.4'. Now restart Omada Controller to activate it.
#
That's my way of doing »downgrades« in just no time.
Starting/stopping the controller
You can start the controller synchronously (option -w) or asynchronously (no option) with omadactl:
# omadactl -w start
Starting Omada SDN Controller .................................................................................................
Omada SDN Controller started successfully after 43 seconds.
Direct your browser to http://your_hostname:8088 for accessing Omada SDN Controller.
#
On my embedded system it needs ~94 to ~99 seconds to start, on my Debian server it needs ~43 seconds, YMMV. You can specify a timeout with option -W sec when starting the controller synchronously and you can set the default timeout permanently with option -S sec (w/o starting the controller). The default timeout has been raised to 120 seconds for the SDN controller. The initial setup of the database will require more time at the very first start of Omada Controller.
To stop the controller use the stop command. To show it's status use the status command (obvious, isn't it?):
# omadactl stop
Stopping Omada SDN Controller
# omadactl status
Omada SDN Controller is not running
# omadactl start
Starting Omada SDN Controller
# omadactl status
Omada SDN Controller is still initializing, please wait ...
#
The script /etc/init.d/omadad will start the controller asynchronously at boot time to avoid delaying the boot sequence. You could use this command to start or stop the controller, too, but omadactl gives you much more functions. See the manpage for more information.
Changes in package omada-sdn-controller-4.2.4_1
- Moved version number to the package name to allow different versions of the same software to co-exist.
- Fixed double sourcing of OmadaController/CONFIG and /etc/default/omada in omadactl.
- Removed obsolete code from omadactl.
Changes in package omada-sdn-controller-4.1.5-2
- Fixed non-working verbose option (-v) in omadactl.
- Fixed dump and restore options of omadactl.
- Fixed bug in omadactl for getting properties.
- Fixed version dependencies for mongodb: The SDN Controller requires the package mongodb-org v3.2 or better.
Changes in package omada-sdn-controller-4.1.5-1
- Initial version.
- Modified omadactl to work with Omada SDN Controller.
Changes in package omada-controller-3.2.10-3
- Fixed non-working verbose option (-v) in omadactl.
- Fixed version dependencies for mongodb: The (old) Omada Controller requires either the package mongodb v2.4 or mongodb-org v3.2.
Changes in package omada-controller-3.2.10-2
- Changed location of duplicate files in different controller packages.
- Fixed version dependencies for mongodb to accept package mongodb-org.
Changes in package omada-controller-3.2.10-1
- Initial version.
More information
- For help with omadactl see its manpage: man omadactl
- For customization of omadactl see the config file CONFIG in the controller's home directory (/etc/default/omadad is gone).
- For a list of all files installed by the .deb package use the command: dpkg -L omada-controller
- If you want to uninstall this .deb package (except the database and other files created at run-time), use the »remove« option of dpkg: dpkg -r omada-controller
- If you want to uninstall this .deb package (including the database and other files created at run-time), use the »purge« option of dpkg: dpkg -P omada-controller
- For the release notes of Omada SDN Controller, the Omada Controller Upgrade Guide and the changelog for omadactl see the directory /usr/share/doc/omada-controller-4.1.5.
Differences and commonalities between official SDN Controller and Community Version (CV)
- The CV uses exactly the same JAVA class files from the official version, but is architecture-independend, that means it does not include any bundled binaries. Therefore you have to use up-to-date binaries for the required utilities which are most often installed on your Linux system anyway (curl, netstat, mongod, jsvc, java and a JRE of your choice). SDN Controller V4.1.5 finally removed previously bundled binaries as well as I always did suggest for its predecessors V2.x/V3.x.
- Official version 4.1.5 released 2020-07-13 has two bugs which prevent the controller from starting if Privilege Separation is used. If Privilege separation is not used, both bugs cause creation of a directory outside the Omada Controller's home directory with root ownership. Those bugs have been fixed in the CV already and have been reported to TP-Link.
- The CV automatically creates a role account »omadad« when installing the .deb-Package in order to enforce Privilege Separation, which is standard on UNIX/Linux for every server process started at boot time. To avoid the risk of potential root exploits you do not want to run the controller with admin privileges once it has been started.
- The CV uses improved shell scripts omadactl(8) and /etc/init.d/omadad for starting/stopping and managing the server. Both scripts replace the control.sh script found in the official version, which since version 3.x has incorporated a few critical, but not all mechanisms offered by omadactl.
- The CV's directory tree has much stricter file permissions which deny access for ordinary users to sensitive data such as certificates, properties, the controller's database and backups created with omadactl.
- The CV allows to have several controller versions installed at the same time and omadactl offers an easy way to switch between those instances on the fly.
- The CV uses the file CONFIG in Omada Controller's home directory for version- and system-dependend settings used by omadactl.
- omadactl allows to create backups from the command line using the mongodump(1) and mongorestore(1) utilities, thus enabling scheduled backups using the cron(8) daemon.
- omadactl allows to copy the database files from one version to another version, thus cloning the settings. Note: Direct database copies do not work for the transition from Omada Controller (V3) to Omada SDN Controller (V4).
- omadactl allows to raise or lower the Linux kernel's scheduling priority (niceness) for the Omada server process at start time or for an instance already running.
Enjoy! Sunshine!
Attached file: Omada Controller Upgrade Guide (also included in the package).
- Copy Link
- Subscribe
- Bookmark
- Report Inappropriate Content
Hi guys
Sorry for the newbie questions, but I'm attempting to install this on my RPi3
I've checked the java version...which is:
openjdk version "1.8.0_212"
OpenJDK Runtime Environment (build 1.8.0_212-8u212-b01-1+rpi1-b01)
OpenJDK Client VM (build 25.212-b01, mixed mode)
I assume that's correct?
But running dpkg I get:
(Reading database ... 65474 files and directories currently installed.)
Preparing to unpack omada-sdn-controller_4.1.5-1_all.deb ...
[info] Omada SDN Controller is not running.
Unpacking omada-sdn-controller (4.1.5-1) over (4.1.5-1) ...
Setting up omada-sdn-controller (4.1.5-1) ...
[....] Starting Omada SDN Controller:Invalid JVM name specified server
. ok
Processing triggers for man-db (2.8.5-2) ...
What am I doing wrong?
Thanks!
- Copy Link
- Report Inappropriate Content
@MiloWiles Problem is jsvc doesn't like you openjdk runtime probably. Could also be you need to do a export JAVA_HOME first.
But unlike the requirements says I have it running in my docker container but not using jsvc tho.
So if you start it manually with:
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-armhf/jre
/usr/lib/jvm/java-8-openjdk-armhf/jre/bin/java -server -Xms128m -Xmx512m -XX:MaxHeapFreeRatio=60 -XX:MinHeapFreeRatio=30 -XX:+HeapDumpOnOutOfMemoryError -XX:-UsePerfData -Deap.home=/opt/tplink/OmadaController -cp /opt/tplink/OmadaController/lib/*: com.tplink.omada.start.OmadaLinuxMain
it probably will run. (you need the adjust the java home directory maybe)
- Copy Link
- Report Inappropriate Content
One thing I also noticed. When you start it first time. The mongodb takes some time to create the databases. Too long for the Omada SDN controller.
I fixed that by just let it run until you see in the mongodb.log is has finished creating the databases and journals. Then stop and start it again.
- Copy Link
- Report Inappropriate Content
@Milo just found /etc/default/omadad
you might wanna check that file and correct it and try it again.
- Copy Link
- Report Inappropriate Content
Ronald1965 wrote
But unlike the requirements says I have it running in my docker container but not using jsvc tho.
Please note that running Omada Controller without Privilege Separation done by jsvc bears a high risk of root exploits due to possible bugs in the Java JRE.
Don't expose a controller running w/o Privilege Separation to the Internet, run it only in an isolated, fully trusted network!
As for jsvc issues: they are probably caused by dependencies with Oracle JRE8. When I have more spare time, I will take a look to other methods for Privilege Separation in order to get rid of jsvc and its dependencies. But if this would require modifications of TP-Link's Java classes, we're unfortunately out of luck.
Also note that /etc/default/omadad was used only by old controller versions, while in V3.2.10-2 and V4.1.5-1 this file has been merged with file CONFIG in Omada Controller's home directory /opt/tplink/OmadaController.
- Copy Link
- Report Inappropriate Content
@Ronald1965 Thanks for that.
It does indeed start...however, the mongoldb never seems to fully initialise.
I don't get a mongodb.log file generated either...so I suspect a problem with that.
2020-07-19 11:38:57 [log4j-thread] [INFO]-[SourceFile:29] - success to load configuration omada.properties
2020-07-19 11:38:58 [main] [INFO]-[SourceFile:75] - going to start local mongod.
2020-07-19 11:40:38 [main] [WARN]-[SourceFile:142] - Fail to start mongo DB server
2020-07-19 11:40:38 [main] [WARN]-[SourceFile:78] - com.tplink.omada.start.a.a: Fail to start mongo DB server
com.tplink.omada.start.a.a: Fail to start mongo DB server
at com.tplink.omada.start.b.d.a(SourceFile:143) ~[omada-start.jar:?]
at com.tplink.omada.start.b.b.e(SourceFile:75) [omada-start.jar:?]
at com.tplink.omada.start.OmadaBootstrap.d(SourceFile:209) [omada-start.jar:?]
at com.tplink.omada.start.OmadaBootstrap.q(SourceFile:273) [omada-start.jar:?]
at com.tplink.omada.start.OmadaBootstrap.a(SourceFile:86) [omada-start.jar:?]
at com.tplink.omada.start.OmadaBootstrap.e(SourceFile:231) [omada-start.jar:?]
at com.tplink.omada.start.OmadaLinuxMain.b(SourceFile:80) [omada-start.jar:?]
at com.tplink.omada.start.OmadaLinuxMain.main(SourceFile:25) [omada-start.jar:?]
2020-07-19 11:42:20 [main] [WARN]-[SourceFile:142] - Fail to start mongo DB server
2020-07-19 11:42:20 [main] [WARN]-[SourceFile:78] - com.tplink.omada.start.a.a: Fail to start mongo DB server
com.tplink.omada.start.a.a: Fail to start mongo DB server
at com.tplink.omada.start.b.d.a(SourceFile:143) ~[omada-start.jar:?]
at com.tplink.omada.start.b.b.e(SourceFile:75) [omada-start.jar:?]
at com.tplink.omada.start.OmadaBootstrap.d(SourceFile:209) [omada-start.jar:?]
at com.tplink.omada.start.OmadaBootstrap.n(SourceFile:202) [omada-start.jar:?]
at com.tplink.omada.start.OmadaBootstrap.q(SourceFile:276) [omada-start.jar:?]
at com.tplink.omada.start.OmadaBootstrap.a(SourceFile:86) [omada-start.jar:?]
at com.tplink.omada.start.OmadaBootstrap.e(SourceFile:231) [omada-start.jar:?]
at com.tplink.omada.start.OmadaLinuxMain.b(SourceFile:80) [omada-start.jar:?]
at com.tplink.omada.start.OmadaLinuxMain.main(SourceFile:25) [omada-start.jar:?]
2020-07-19 11:42:22 [mongo-check-thread] [INFO]-[SourceFile:298] - mongod was shutdown, restarting it
2020-07-19 11:43:23 [main] [WARN]-[SourceFile:342] - Mongo Client connect error while init Jetty.com.mongodb.MongoTimeoutException: Timed out after 30000 ms while waiting to connect. Client view of cluster state is {type=UNKNOWN, servers=[{address=127.0.0.1:27217, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused (Connection refused)}}]
2020-07-19 11:43:23 [main] [ERROR]-[SourceFile:306] - warApps are not exist
2020-07-19 11:43:23 [main] [WARN]-[SourceFile:20] - WebApplicationContext has not been initialed, failed to get bean dataInitService
2020-07-19 11:43:23 [main] [ERROR]-[SourceFile:51] - Failed to get WebApplicationContext, MetaDataInitTask execute failed!
2020-07-19 11:43:23 [main] [ERROR]-[SourceFile:18] - Failed to start omada controller, going to exit
2020-07-19 11:43:24 [device-discovery-server] [INFO]-[SourceFile:54] - Start device discovery server
2020-07-19 11:43:24 [device-manage-server] [INFO]-[SourceFile:111] - Start device manage server
2020-07-19 11:43:24 [device-adopt-server] [INFO]-[SourceFile:82] - Start device adopt server
2020-07-19 11:43:27 [Thread-1] [INFO]-[SourceFile:166] - success to shutdown mongodb database
2020-07-19 11:43:27 [Thread-1] [INFO]-[SourceFile:171] - Omada Controller exited
Ronald1965 wrote
@MiloWiles Problem is jsvc doesn't like you openjdk runtime probably. Could also be you need to do a export JAVA_HOME first.
But unlike the requirements says I have it running in my docker container but not using jsvc tho.
So if you start it manually with:
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-armhf/jre
/usr/lib/jvm/java-8-openjdk-armhf/jre/bin/java -server -Xms128m -Xmx512m -XX:MaxHeapFreeRatio=60 -XX:MinHeapFreeRatio=30 -XX:+HeapDumpOnOutOfMemoryError -XX:-UsePerfData -Deap.home=/opt/tplink/OmadaController -cp /opt/tplink/OmadaController/lib/*: com.tplink.omada.start.OmadaLinuxMain
it probably will run. (you need the adjust the java home directory maybe)
I might just give up at this point and try and get the new build working on my QNAP NAS instead! :)
Over in the QNAP forums a user had the previous version built as a QPKG for it.
- Copy Link
- Report Inappropriate Content
@MiloWiles Did you check directory permissions? And if its running as omadad user or root.
In docker I use gosu omadad "java....."
- Copy Link
- Report Inappropriate Content
@Ronald1965 - thanks again.
I su'd to root to run it (after I found the permissions were set for "omadad" on the directories in /opt/tplink/OmadaController
EDIT: maybe I was too quick to assume errors earlier.
It's now starting the mongodb.
However, I suspect we're now in to the versioning issue of MongoDB as reported earlier in the thread.
The default for Buster is v2.4.14 and obviously not compatible.
I don't want to rebuild the Pi given that I'm using it for other stuff.
Back to the QNAP!
- Copy Link
- Report Inappropriate Content
MiloWiles wrote
The default for Buster is v2.4.14 and obviously not compatible.
Sure, as I wrote in post #1: SDN Controller needs at least V2.6 of mongodb, while Raspbian Jessie, Stretch and Buster stick with V2.4.
That's why Ronald did build a docker image for Raspbian which uses a modern mongodb package.
- Copy Link
- Report Inappropriate Content
- Copy Link
- Report Inappropriate Content
Information
Helpful: 4
Views: 48986
Replies: 139