Omada Controller

Installs and configures TP-Link's Omada Network Application (formerly "Omada SDN Controller") as a native service (tpeap) on Debian/Ubuntu from TP-Link's official .tar.gz installer — no Docker, no TP-Link cloud dependency.

Requirements

• Debian 12/13 or Ubuntu 22.04/24.04/26.04 (Proxmox LXC container or VM). Note: as of omada_version: 6.3.0.44, TP-Link only lists Debian 11/12 and Ubuntu 20.04/22.04/24.04 as officially validated — Debian 13 and Ubuntu 26.04 aren't confirmed yet.
• Outbound internet access to download the Omada archive and the MongoDB apt repository (unless using omada_package_source: local)

Variables

Variable	Default	Description
omada_version	6.3.0.44	Descriptive only — see Upgrades. Used for the files/ fallback filename.
omada_archive_url	TP-Link static URL for omada_version	Download URL of the Omada .tar.gz archive. Ignored when omada_package_source is local.
omada_checksum	~	Checksum of the archive, e.g. sha256:abcd.... Skipped when unset.
omada_package_source	upstream	upstream downloads omada_archive_url; local copies omada_archive_filename from this role's files/ directory.
omada_archive_filename	Omada_Network_Application_v{{ omada_version }}_linux_x64.tar.gz	Filename used for the downloaded/copied archive, and the expected filename under files/ when omada_package_source is local.
omada_download_dir	/var/tmp/omada_install	Staging directory the archive is extracted into before running the installer. Not the install target.
omada_non_root	true	Reconfigures the controller to run as a dedicated omada system user instead of root. See Notes.
omada_java_package	openjdk-21-jre-headless	Java runtime package installed for Omada. TP-Link requires 17+; override to openjdk-17-jre-headless where that's preferred and still available (not on Debian 13).
omada_mongodb_version	8.0	MongoDB release line installed from the official MongoDB apt repository. Not 7.0 — see Notes.
omada_mongodb_gpg_key_url	MongoDB's official key URL for omada_mongodb_version	GPG key used to sign the MongoDB apt repository.
omada_mongodb_repo_os	{{ ansible_facts.distribution | lower }}	MongoDB apt repo OS component. Override for a host this doesn't map onto debian/ubuntu correctly.
omada_mongodb_repo_release	facts, trixie mapped to bookworm	MongoDB apt repo release codename. Override if a release isn't in MongoDB's repo yet — see Notes.
omada_bind_address	0.0.0.0	When set to a specific address/CIDR, restricts omada_listen_port to that source. See Bind address.
omada_listen_port	8043	HTTPS management port (manage.https.port in omada.properties).
omada_uninstall	false	Stops the controller, runs its uninstaller, and purges MongoDB.
omada_purge	false	Also removes /opt/tplink/EAPController (all site data). Requires omada_uninstall: true. Irreversible.

Usage

Minimal setup:

- hosts: omada_controller
  roles:
    - role: omada_controller

Pinning a specific release — check the current download link at tp-link.com/support/download/omada-software-controller, since TP-Link's URLs are upload-date paths that can't be derived from the version number alone:

omada_version: "6.3.0.44"
omada_archive_url: "https://static.tp-link.com/upload/software/2026/202608/20260828/Omada_Network_Application_v6.3.0.44_linux_x64_20260824155543.tar.gz"

Restricting the management port to the management network:

omada_bind_address: "10.0.0.0/24"

Installing from a local mirror instead of TP-Link's servers:

omada_package_source: local
omada_archive_filename: "Omada_Network_Application_v6.3.0.44_linux_x64.tar.gz" # placed in files/

Upgrades

This role only ever installs Omada onto a clean host — it detects an existing install via /usr/bin/tpeap and skips the installer entirely if that's present, it never re-runs the installer to upgrade an existing one. TP-Link's installer is interactive: a fresh install only needs a scripted "y" confirmation, but installing over an existing controller shows a different, arrow-key-driven upgrade dialog that can't be driven the same way — attempting it risked hanging the play or mis-answering a prompt on a host holding live site data.

To upgrade, follow TP-Link's own upgrade guide (back up first) by hand, or manually.

Bind address

Omada doesn't expose a native "bind to this interface" setting, so omada_bind_address is enforced with a narrowly scoped iptables rule on omada_listen_port only — it never touches the default chain policy or any other port (SSH included), so it can't lock you out. Leave it at 0.0.0.0 (default) when the host's only network is already the management VLAN.

Rules are applied in-memory and are not persisted across reboots; install iptables-persistent (or equivalent) separately if you need them to survive one.

Uninstall

To stop the controller, run its uninstaller, and purge MongoDB:

omada_uninstall: true

To also remove all site data (irreversible):

omada_uninstall: true
omada_purge: true

Notes

• The service is tpeap; the controller UI is reachable at https://<host>:8043 (or omada_listen_port) once the role completes. Other ports Omada uses for device adoption/discovery (8088, 27001, 27002, 29810–29814) are left at their installer defaults — open them on the management VLAN as needed.
• Warning: this role does not manage TP-Link cloud binding, Open API / remote access, or Omada ID login — there's no variable for it because none of the role's tasks touch it. The controller ships with cloud binding available from its own web UI; if you don't want it, leave it off there yourself after first login. That, along with all other post-boot Omada configuration (sites, WLANs, VLANs), is outside this role's scope.
• omada_non_root (default true) only applies once, right after a fresh install: it stops the controller, points control.sh at a dedicated omada user, and hands it Omada's data/logs/work/properties directories. Set it to false before the first run to keep TP-Link's default of running as root.
• omada_mongodb_repo_os/omada_mongodb_repo_release derive from the target's own OS facts, which works as long as MongoDB actually has a repo for that codename. Set them explicitly for a release MongoDB doesn't support yet, e.g. Ubuntu 26.04. One case is already handled: trixie is mapped to bookworm, since MongoDB's trixie/8.0 repo currently only ships mongodb-mongosh, not mongodb-org — bookworm's packages install fine on trixie.
• omada_mongodb_version defaults to 8.0, not 7.0: MongoDB's 7.0 apt repo is signed with a key whose self-signature uses SHA-1, which Debian 13 (trixie, and any apt enforcing the same policy) rejects outright. The 8.0 key uses SHA-512. Omada supports MongoDB up to v8 as of omada_version: 6.3.0.44.
• omada.properties is edited in place (only the port line) rather than templated wholesale, since TP-Link's installer writes other keys this role doesn't track.
• Re-running the role is safe: MongoDB, Java, and config changes only apply/restart when something actually changed. The installer itself only ever runs once — see Upgrades.