Skip to content

TP-Link Omada Controller

Overview

The Omada Software Defined Networking (SDN) platform is TP-Link's centralized management solution. It manages all your TP-Link hardware from a single interface.

I have not gotten too into the deeper settings of omada, but this is basics from what I did.

Installation

1. Data directories

State lives in bind mounts under the appdata disk, like every other stack, so it's covered by the normal backups:

sudo mkdir -p /mnt/appdata/omada/{omada-data,omada-logs,omada-work}

2. Docker Compose

This setup uses the community-standard mbentley/omada-controller image. The container runs with network_mode: host so the controller can discover devices on the local network via Layer 2 broadcasts (and so adoption ports like 29810-29817 don't each need publishing).

compose.yaml

# https://github.com/mbentley/docker-omada-controller
services:
  omada-controller:
    image: mbentley/omada-controller:5.15.24.19@sha256:<DIGEST>   # version tag + digest; Renovate keeps both current
    container_name: omada-controller
    restart: always
    # Embedded MongoDB needs time to flush on stop; upstream recommends 60 s (Docker's default is 10 s, then SIGKILL).
    stop_grace_period: 60s
    network_mode: host
    environment:
      - MANAGE_HTTP_PORT=8088
      - MANAGE_HTTPS_PORT=8043
      - PORTAL_HTTP_PORT=8088
      - PORTAL_HTTPS_PORT=8843
      - SHOW_SERVER_LOGS=true
      - SHOW_MONGODB_LOGS=false
      - TZ=<TZ>
    volumes:
      - /mnt/appdata/omada/omada-data:/opt/tplink/EAPController/data
      - /mnt/appdata/omada/omada-logs:/opt/tplink/EAPController/logs
      - /mnt/appdata/omada/omada-work:/opt/tplink/EAPController/work

Why the tag and the digest

The digest makes the image immutable; the version tag in front tells a human (and Renovate) which release it is. Read upstream's notes before a major bump (e.g. 5.x → 6.x) and take a controller backup first.

Stopping it cleanly

Without stop_grace_period, Docker kills the container 10 s after a stop and the embedded MongoDB may not finish writing. Set the same expectation at the daemon level ("shutdown-timeout": 60 in /etc/docker/daemon.json) so host reboots give it time too.

Start the controller:

docker compose up -d

Initial Setup & Adoption

Once the controller is running, follow this workflow to bring the network online.

1. Access the Interface

  • URL: https://<YOUR_SERVER_IP>:8043 (or a <SERVICE>.<YOUR_LOCAL_DOMAIN> name through NPM)
  • Note: You may receive a security warning because the SSL certificate is self-signed. This is normal; proceed past it.
  • First Login: The default is often admin / admin, but the setup wizard will force a password change immediately.

2. Device Adoption

The controller does not automatically manage devices plugged into the network; they must be explicitly "Adopted".

  1. Go to the Devices tab (Access Point icon).
  2. Devices (Gateway, Switches, APs) should be listed as "Pending".
  3. Click the Adopt button on the right.
  4. The status will cycle: Provisioning -> Configuring -> Connected.

3. WAN/LAN Configuration

If using an Omada Gateway (like the ER605):

  • Navigate to Settings (Gear icon) > Wired Networks > Internet.
  • Configure the WAN type provided by the ISP (DHCP, PPPoE, or Static).

Configuration Features

Wireless Networks (SSIDs)

  • Location: Settings > Wireless Networks.
  • Usage: Create multiple SSIDs here (e.g., Main, IoT, Guest).
  • Guest Network: Checking the "Guest Network" box automatically applies isolation rules, preventing those clients from accessing the internal LAN.

VLANs (Virtual LANs)

To segment traffic (e.g., separating IoT devices from the main PC):

  1. Create Interface: Settings > Wired Networks > LAN. Create a new Interface with a VLAN ID (e.g., 20).
  2. Tag Ports: Ensure managed switches utilize the correct profiles to pass this VLAN tag to the APs.
  3. Assign to Wi-Fi: In Wireless settings, assign an SSID to use that specific VLAN ID.

ACLs (Access Control Lists)

  • Location: Settings > Network Security > ACL.
  • Usage: Use "Switch ACLs" or "Gateway ACLs" to block traffic between VLANs (e.g., Block the IoT VLAN from accessing the Main VLAN).

Maintenance

  • Backups: Go to Settings > Maintenance > Backup & Restore. Set up "Auto Backup" to save the config locally. Auto backups land in the omada-data bind mount, so the host's backup picks them up.
  • Roaming: Enable Fast Roaming (802.11r) in Site Settings to help devices switch between APs smoothly. Note: Test this first, as some older IoT devices struggle with it.
  • AI Optimization: The "AI WLAN Optimization" tool scans the RF environment and automatically adjusts channels and transmit power to reduce interference. Run this once after the initial deployment.

Sources & further reading