Wikibot: Migrated from services/OMADA.md

2026-07-05T18:16:20Z

Migrated from services/OMADA.md

New page

''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 ==

{| class="wikitable"
|-
! Item
! Value
|-
| '''Container'''
| omada-controller (mbentley/omada-controller:6.1)
|-
| '''Compose'''
| <code>/library/omada-app/docker-compose.yml</code>
|-
| '''Data'''
| <code>/library/omada-app/data/</code> (505MB)
|-
| '''Logs'''
| <code>/library/omada-app/logs/</code>
|-
| '''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: <code>/data/omada</code> in backup scope (docker-compose.yml line 37)
* Data persists in: <code>/library/omada-app/data/</code> (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 <code>/library/omada-app/data/</code> — 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 ==

{| class="wikitable"
|-
! 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: <code>docker logs omada-controller | grep adopt</code>

----

== 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: <code>rm /library/omada-app/data/db/mongod.lock</code>
# '''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 <code>America/Chicago</code> 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

Services/Omada - Revision history

Wikibot: Migrated from services/OMADA.md