As of: 2026-07-05 — migrated from `services/OMADA.md`

TP-Link Omada Controller

Version: 6.1 (mbentley/omada-controller) Status: ✅ CRITICAL INFRASTRUCTURE — Network controller for all APs Last Updated: 2026-05-11

Quick Reference

Item	Value
Container	omada-controller (mbentley/omada-controller:6.1)
Compose	`/library/omada-app/docker-compose.yml`
Data	`/library/omada-app/data/` (505MB)
Logs	`/library/omada-app/logs/`
Network	host mode (required for AP discovery via multicast)
UI Port	8043 (HTTPS), 8188 (HTTP)
Memory	~1.5GB (expected for MongoDB + Java controller)
Restart Policy	unless-stopped
Health Check	healthy (docker ps shows status)

What It Controls

Omada is the centralized management platform for TP-Link enterprise WiFi:

EAP610 (or other managed APs) — firmware updates, channel optimization, roaming
Network policies — SSID config, authentication, bandwidth limits
Analytics — traffic, client health, interference detection
Auto-HA (if configured) — automatic failover between controllers

Loss of Omada = Manual AP management only — devices will continue operating on last-known config, but no remote control.

Backup & Recovery

Current Backup Status

✅ Included in daily restic backup

Path: /data/omada in backup scope (docker-compose.yml line 37)
Data persists in: /library/omada-app/data/ (MongoDB + config)
Size: ~505MB (small, incremental backups efficient)
Database: embedded MongoDB (not separate container)

Restore Procedure

Single service restore (controller crashed): <syntaxhighlight lang="bash">

1. Stop the container

docker compose -f /library/omada-app/docker-compose.yml down

2. Restore data from latest snapshot

docker exec restic-backup sh -c \

 'export RESTIC_REPOSITORY=$HETZNER_REPO; export RESTIC_PASSWORD=$HETZNER_PASSWORD; \
  restic restore latest --target /tmp/restore --include /data/omada'

3. Copy restored data

sudo cp -r /tmp/restore/data/omada /library/omada-app/data.restored sudo rm -rf /library/omada-app/data sudo mv /library/omada-app/data.restored /library/omada-app/data sudo chown -R 508:508 /library/omada-app/data

4. Restart

docker compose -f /library/omada-app/docker-compose.yml up -d

5. Verify health

docker ps | grep omada-controller # should show "healthy" </syntaxhighlight>

Full Disaster Recovery

If hardware is lost, Omada config is recoverable via:

MongoDB backup in /library/omada-app/data/ — restores all device configs, SSIDs, policies
Re-adopt APs — once controller is back, press reset button on each AP, it rejoins the controller
Fabric IP recovery — if you have Omada Fabric configured, endpoints will auto-rejoin after controller restart

Memory Pressure

Why 1.5GB?

Omada bundles MongoDB 5.0 for config storage
Java-based controller (OpenJDK 11+)
Holds all device telemetry, client sessions, audit logs in memory
Normal for enterprise controller this size

This is expected and required — memory is justified by critical infrastructure role.

Key Ports

Port	Protocol	Purpose
8043	HTTPS	Web UI + API (admin.omada.local)
8188	HTTP	Portal (auto-redirects to HTTPS)
29810-29820	TCP	Device communication (APs, switches)
27001-27999	TCP	MongoDB internal replication

Operational Checks

Verify controller is healthy: <syntaxhighlight lang="bash">

Check container status

docker ps | grep omada-controller

Check web UI (if SSH tunneled to port 8043)

curl -k https://localhost:8043/login # should respond with login page

Monitor memory (expect 1.5GB)

docker stats omada-controller

View recent logs

docker logs --tail=50 omada-controller | grep -E "ERROR|WARN|Exception" </syntaxhighlight>

Verify APs are connected:

Open https://admin.omada.local:8043 (or via Tailscale if remote)
Go to Devices — should show all EAP610 APs as "Connected"
If AP shows "Disconnected", check:

- AP has network connectivity (ping it)
- AP is on same LAN or can reach controller IP:29810
- Controller logs for adoption errors: docker logs omada-controller | grep adopt

Upgrade Path

Current: 6.1 (latest as of 2026-05-11)

Watchtower (if enabled for this image) will auto-update. If manual: <syntaxhighlight lang="bash"> cd /library/omada-app docker compose pull && docker compose up -d </syntaxhighlight>

Caution: Always backup before upgrading (restic snapshot is enough).

Known Issues / Gotchas

Host network mode required — Omada needs raw access to network broadcasts for AP discovery. Cannot use bridge networking.
MongoDB locked on restart — If controller crashes mid-operation, MongoDB lock file may persist. Container entrypoint handles cleanup, but if stuck: rm /library/omada-app/data/db/mongod.lock
Fabric timeout during big config changes — if Fabric mesh is configured, topology recalculation can take 2-5 minutes. Don't panic if APs briefly disconnect.
TZ environment variable — set to America/Chicago for CST. Check via UI: Settings → General. If wrong, logs won't align with system time.

Documentation References

Omada API: https://documenter.getpostman.com/view/6114396 (community Postman docs)
TP-Link Omada SDN: https://www.tp-link.com/en/business/omada-sdn-controller/ (official)
Docker image: https://hub.docker.com/r/mbentley/omada-controller (custom image, better Linux support than official)

Alerting

Should monitor for:

✅ Container health check (Uptime Kuma can ping :8043)
✅ Memory spike (>2GB = investigate, might indicate memory leak)
✅ AP disconnects (if >50% offline, controller may be hung)

Current monitoring: None configured (add to Uptime Kuma if needed)

Suggested: Create http monitor for https://localhost:8043/login returning 200 status