dominik/hermes-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
01bd921ced398a0913eb3d06050e0ca8b5c52f87
hermes-skills/devops/omada-controller-administration/SKILL.md
T

41 KiB
Raw Blame History

name, description, tags
name description tags
omada-controller-administration Class-level skill for TP-Link Omada Cloud Controller administration via browser automation. Covers login flow, SPA navigation quirks, iframe-based site management, VLAN configuration, ACL rules, inter-VLAN mDNS limitations, WLAN/channel optimization, device management, and firmware updates. Applies to cloud-based Omada controllers at omada.tplinkcloud.com. device management, and firmware updates. Applies to cloud-based Omada controllers at omada.tplinkcloud.com.
tp-link
omada
wlan
channel-optimization
network-management
browser-automation

TP-Link Omada Cloud Controller Administration

When to Use

Any task involving TP-Link Omada Cloud Controller — WLAN configuration, channel optimization, device management, firmware updates, site settings, or viewing logs/alerts.

Environment

  • URL: https://omada.tplinkcloud.com/
  • Credentials: 1Password vault "Hermes", item "omada - Netzwerkverwaltung"
  • Controller name: "Schön" (Cloud Based System)
  • Site name: "Rohr"
  • Devices (all on VLAN 1 / 172.16.1.x management subnet):
    • Router: DR3650v-4G HW v1.0, FW 1.1.1, IP 172.16.1.1 (also 10.0.30.1 on VLAN 30)
    • Switch: SG3428MP HW v6.20, FW 6.20.26 (update 6.20.27 avail), IP 172.16.1.2
    • AP Erdgeschoss: EAP683 UR v1.0, FW 1.4.0, IP 172.16.1.3 (switch port 16)
    • AP Obergeschoss: EAP683 UR v1.0, FW 1.4.0, IP 172.16.1.4 (switch port 14)
    • AP Garage: EAP615-Wall v1.0, FW 1.5.4, IP 172.16.1.5 (switch port 21)
    • AP Garten: EAP225-Outdoor v3.0, FW 5.2.2, IP 172.16.1.6
  • Local router fallback: http://172.16.1.1/webpages/login.html (login blocked when managed by controller — see "Known Issue" section)
  • Local switch UI: http://172.16.1.2 (accessible but requires unknown device-specific credentials)
  • Monitoring stack: CT 141 (proxmox7), Docker-based: prometheus (:9090), grafana (:3000), alertmanager, blackbox, pve-exporter, telegram-bridge (:9099). snmp_exporter runs as systemd binary (:9116) — Docker deployment fails on CT 141.
  • Grafana dashboard: network-infra (uid: network-infra) — Proxmox nodes, guests, HA state, blackbox probes. Omada metrics NOT included (no exporter available for cloud controller).
  • Local Omada Controller (in progress): CT 142 (omada-controller, 10.0.30.142/24, VLAN 30, proxmox7, vm_disks storage). Will replace cloud controller to enable SNMP + API exporters.
  • Docker hosts in cluster: Only CT 141 (6 containers: monitoring stack) and CT 121 (1 container: portainer). All other CTs/VMs run services natively without Docker.

Login Flow

Steps

  1. Navigate to https://omada.tplinkcloud.com/#/login
  2. Wait 5-8 seconds — the SPA loads slowly, initial snapshot shows (empty page) with 0 elements
  3. Take snapshot to confirm login form is visible
  4. Type TP-Link ID into the "TP-Link ID (Partner ID)" textbox
  5. Type password into the "Password" textbox (nested inside a generic wrapper — use the inner textbox ref, not the outer one)
  6. Press Enter (do NOT click the "Sign In" link — it redirects to tp-link.com marketing site instead of submitting the form)
  7. Wait 5-8 seconds for redirect
  8. Dismiss cookie banner if present ("Alle Cookies akzeptieren")
  9. Dismiss any notice dialogs ("OK" or "Do not remind again")

Alternative: Console-Based Login

Instead of browser_type + browser_press, you can fill the login form via browser_console:

(async function(){
  const sleep = ms => new Promise(r => setTimeout(r, ms));
  const inputs = document.querySelectorAll('input');
  if (inputs.length >= 2) {
    inputs[0].focus();
    inputs[0].value = 'dominik@familie-schoen.com';
    inputs[0].dispatchEvent(new Event('input', {bubbles: true}));
    const pwInputs = document.querySelectorAll('input[type="password"]');
    if (pwInputs.length > 0) {
      pwInputs[pwInputs.length - 1].focus();
      pwInputs[pwInputs.length - 1].value = '<password>';
      pwInputs[pwInputs.length - 1].dispatchEvent(new Event('input', {bubbles: true}));
    }
  }
  await sleep(500);
  // Submit via Enter keydown event
  document.dispatchEvent(new KeyboardEvent('keydown', {key: 'Enter', code: 'Enter', keyCode: 13, which: 13, bubbles: true}));
  // Also click Sign In link as backup
  for (const el of document.querySelectorAll('a, button')) {
    if (el.textContent.trim() === 'Sign In' && el.tagName === 'A') { el.click(); break; }
  }
  return 'login submitted';
})()

Note: This approach dispatches React-compatible input events. The browser_type + Enter approach is simpler and equally reliable for the login form.

Critical Pitfalls

  • Empty page on navigate: The Omada SPA frequently returns (empty page) with element_count: 0 right after navigation. Always wait 5-8s then re-snapshot before concluding the page failed to load.
  • "Sign In" link vs form submit: The "Sign In" element (@e9 in observed session) is a link, not a submit button. Clicking it navigates to https://www.tp-link.com/de/support/. Use browser_press with Enter while focused in the password field to submit the form.
  • Password field nesting: The password input is wrapped in a generic div containing two textboxes — use the one with aria-label "Password" (the inner ref), not the outer wrapper ref.
  • Multiple dismissable dialogs: After login, expect up to 3 sequential dialogs: cookie consent, regional isolation notice, and firmware/system update announcement. Dismiss each before proceeding.
  • Session expiry / white screen: After extended interaction (especially after clicking buttons inside the iframe), the SPA may go completely blank/white. The iframe disappears from the DOM entirely (document.querySelector('iframe') returns null). Recovery: re-navigate to https://omada.tplinkcloud.com/#/login and repeat the full login flow. The session does NOT persist across browser navigations.
  • browser_console variable re-declaration: Repeated browser_console calls that declare variables (e.g., const fr = document.querySelector(...)) fail with SyntaxError: Identifier 'xxx' has already been declared because the execution context persists between calls. Always wrap code in an IIFE: (function(){ ... })() to avoid polluting the persistent scope.
  • browser_click refs for iframe content: Refs from browser_snapshot for elements inside the iframe (e.g., @e14 for "Optimize Now") sometimes fail with "Unknown ref". Fall back to browser_console with IIFE-scoped DOM queries to click iframe-internal elements directly.

Navigation: Controller → Site → WLAN

Structure

Omada Cloud Landing
  └─ Dropdown: "On Premise Systems" / "Cloud Based Systems" → select "Cloud Based Systems"
      └─ Controller card ("Schön") → click to enter
          └─ Global View (org overview, site list)
              └─ Site "Rohr" → click site name cell
                  └─ Site Dashboard with left nav:
                      ├─ Management: Dashboard, Devices, Clients
                      ├─ Monitoring: Map, Logs
                      ├─ Configuration: Network Config, Device Config
                      ├─ Hotspot
                      └─ Maintenance: Network Tools, IntelliRecover

Switching to Cloud Based Systems

The top-left dropdown defaults to "On Premise Systems". Click the combobox, then use browser_console to find and click the "Cloud Based Systems" <li> inside .ant-dropdown-menu.

Switching Back to a Site from Global View

After performing actions in Global View (e.g., checking org-wide logs), returning to a specific site requires navigating through the Dashboard site list:

  1. Click Dashboard in the Global View sidebar
  2. Find the site name in the Site List table
  3. Click the span.text-link.cursor-pointer inside the site name cell (NOT the <td> itself — it has no click handler)
  4. Verify by checking the sidebar: site-level menus (Management, Monitoring, Configuration, Hotspot, Maintenance) should appear instead of Global View menus (Dashboard, Devices, Logs, SD-WAN, Accounts, Settings)

Pitfall: Combobox Does Not List Sites The top-left combobox (showing controller name "Schön") opens a dropdown with controller/system options (e.g., "SchönEssentials") but does NOT list individual sites. It cannot be used to switch between sites. Always use the Dashboard → Site List table to navigate to a specific site.

Entering a Site

Click the site name in the Site List table. Pitfall: clicking the <td> cell itself does NOT navigate into the site — the cell has cursor: auto and no click handler. The actual clickable element is a span.text-link.cursor-pointer inside the cell. Double-clicking the cell also does not work. Use browser_console:

(function(){
  const fr = document.querySelector('iframe');
  if (!fr || !fr.contentDocument) return 'no iframe';
  const spans = fr.contentDocument.querySelectorAll('span.text-link, .cursor-pointer');
  for (const s of spans) {
    if (s.textContent.trim() === 'Rohr') { s.click(); return 'clicked Rohr text-link'; }
  }
  return 'not found';
})()

Verification: After clicking, the sidebar should show site-level menus (Management, Monitoring, Configuration, Hotspot, Maintenance) instead of Global View menus (Dashboard, Devices, Logs, SD-WAN, Accounts, Settings). If you still see "SD-WAN" or "Accounts" in the sidebar, you're still in Global View — the click didn't work.

Iframe Navigation

Reference: See references/navigation-css-structure.md for detailed CSS class hierarchy of the Omada site iframe navigation.

Once inside a site, all content is rendered inside an <iframe>. Standard browser_click refs from the outer snapshot may not work for iframe-internal elements. Use browser_console with document.querySelector('iframe').contentDocument to find and click menu items:

(function(){
  const fr = document.querySelector('iframe');
  if (!fr || !fr.contentDocument) return 'no iframe';
  const items = fr.contentDocument.querySelectorAll('li');
  for (const item of items) {
    if (item.textContent.trim() === 'WLAN') {
      item.click();
      return 'clicked WLAN';
    }
  }
  return 'not found';
})()

Full Menu Structure (inside site iframe)

  • Configuration → expands to:
    • Network Config → General Settings (Site Settings, SSH, VoIP), Network Settings (Internet, LAN, WLAN), Authentication (Portal), VPN, Security (ACL), Transmission (Routing, NAT, DHCP Reservation, Bandwidth Control, Gateway QoS), Profile (Groups, Time Range, Rate Limit, APN Profile)
    • Device Config → Gateway (DNS), Switch (Switch Ports)

VLAN Configuration

VLAN Inventory (site "Rohr")

Navigate to Configuration → Network Config → Network Settings → LAN tab.

VLAN Name Subnet Purpose
1 CatchAll(Default) 172.16.1.1/24 Default/untagged
10 Infrastructure 10.0.10.1/24 Network infrastructure
20 Server / Hypervisors — PVE hosts (10.0.20.x)
30 Server / VMs & LXCs — Containers & VMs (10.0.30.x)
40 Clients — Client devices (Mac, PC, mobile)
50 IoT 10.0.50.1/24 IoT devices
60 DMZ 10.0.60.1/24 Demilitarized zone
192 192.168.100.x 192.168.100.x Special purpose

Pitfall: The VLAN list in the LAN tab only shows 4 VLANs by default (1, 10, 50, 60). VLANs 20, 30, 40, 192 are visible in the Isolation Settings view but not in the main VLAN table. They may be configured elsewhere or inherited from the switch/gateway.

VLAN Isolation Settings

Navigate to Configuration → Network Config → Network Settings → LAN → Isolation Settings button.

Two zones:

  • Isolated Network — can only access internet, no inter-VLAN communication
  • Interconnected Network — can communicate with each other

As of 2026-07-05: 0 isolated, all 8 VLANs are interconnected (all can reach each other). Inter-VLAN routing is handled by the DR3650 gateway.

ACL Rules (Gateway)

Navigate to Configuration → Network Config → Security → ACL.

Key rules (LAN→LAN direction, relevant for inter-VLAN access):

# Description Direction Proto Source → Destination
1 Permit Internet to everyone LAN→WAN All All VLANs → Any
5 Allow Hypervisors from Clients LAN→LAN All Clients → Hypervisors
6 Allow Clients to VMs LAN→LAN TCP Clients → VMs & LXCs
8 Allow Access to IoT LAN→LAN All Clients/Hyper/VMs/192 → IoT
9 DENY Botnet Stuff for IoT LAN→LAN Deny All IoT/CatchAll → Clients/Hyper/VMs/Infra
10 Deny Ingress to VLANs WAN IN Deny All Any → Client/Hyper/Infra/IoT/VM IPs

Important: Rule 6 allows TCP only from Clients (VLAN 40) to VMs (VLAN 30). UDP and ICMP are NOT explicitly permitted — they may be allowed by default (no deny rule for LAN→LAN between these VLANs), but if you need UDP services (e.g. mDNS, SNMP) from VLAN 40 to VLAN 30, verify with a packet capture.

mDNS / Bonjour Across VLANs

Omada does NOT provide mDNS/multicast relay or IGMP proxy functionality.

mDNS broadcasts (224.0.0.251:5353) are confined to their originating VLAN. Bonjour service discovery (AirPlay, Time Machine, printer discovery) does NOT cross VLAN boundaries.

Workarounds:

  1. Manual connection — clients specify the IP/path directly (e.g. smb://10.0.30.21/share for Time Machine)
  2. External mDNS repeater — run mdns-repeater or avahi-reflector on a host with interfaces in both VLANs (e.g. a CT with trunk or dual NIC)

Deployed Solution: CT 127 (avahi-reflector) on proxmox6 runs avahi-daemon in reflector mode with interfaces in VLAN 30 (10.0.30.5, eth0), VLAN 40 (10.0.40.5, eth1), and VLAN 50 (10.0.50.5, eth2). Configured with a directional matrix via iptables:

  • 30→40 ✅ (server services visible to clients)
  • 50→30 ✅ (IoT services visible to servers)
  • 50→40 ✅ (IoT services visible to clients)
  • 40→30, 40→50, 30→50 ❌ (blocked by iptables INPUT/OUTPUT rules)

See the proxmox-ve-administration skill, references/avahi-reflector-setup.md for full setup details including the multi-VLAN iptables rule pattern.

The DR3650 gateway does not expose multicast forwarding or IGMP proxy settings in the Omada controller UI. This is a firmware limitation.

Navigating to VLAN/ACL Views

VLAN list: Configuration → Network Config → Network Settings → LAN tab. Shows only 4 VLANs by default (1, 10, 50, 60). VLANs 20, 30, 40, 192 are hidden — visible only in Isolation Settings.

Isolation Settings: Click the "Isolation Settings" button on the LAN tab (next to "Add"). Shows all 8 VLANs grouped into Isolated vs Interconnected. As of 2026-07-05: 0 isolated, all interconnected.

ACL Rules: Configuration → Network Config → Security → ACL. Shows Gateway ACL rules table with INDEX, ENABLED, DESCRIPTION, DIRECTION, POLICY, PROTOCOLS, SOURCE, DESTINATION, ACTION columns.

WLAN Management

SSID Overview

Navigate to Configuration → Network Settings → WLAN. Shows tabs: SSID, WLAN Optimization, Optimization History.

Observed SSIDs (site "Rohr"):

SSID Security Bands VLAN
Schön WPA-Personal 2.4/5/6 GHz 40
Schön - Gäste WPA-Personal 2.4/5/6 GHz —
IoT WPA-Personal 2.4/5 GHz 50
2Schoen WPA-Personal 2.4/5 GHz 40

WLAN Optimization (Channel Optimization)

  1. Navigate to WLAN → "WLAN Optimization" tab
  2. Click "Optimize Now" link
  3. Optimization Mode dialog appears with two radio options:
    • Partial (default) — scans and optimizes only channels needing adjustment
    • Global — full scan and reassignment of all wireless configuration
    • Select mode, then click "Confirm" to start
  4. Warning: Internet connectivity drops for several minutes during optimization. Schedule during low-traffic periods.
  5. Progress can be tracked under "Optimization History" tab
  6. "Excluded Devices List" allows excluding specific APs from optimization

Per-SSID Channel Configuration

To manually set channels (instead of auto-optimization):

  1. Go to WLAN → SSID tab
  2. Click the SSID name or the action icon in the row
  3. Edit the wireless network settings — channel selection is per-band (2.4 GHz, 5 GHz, 6 GHz)
  4. Available 5 GHz channels observed: 36, 40, 44, 48, 149, 153, 157, 161

Async Console Automation Pattern

For multi-step flows (login → dismiss dialogs → navigate to page → action), chaining individual browser_snapshot + browser_click calls is fragile and slow due to iframe ref instability and session expiry. Instead, use a single browser_console call with an async IIFE that sleeps between steps:

(async function(){
  const sleep = ms => new Promise(r => setTimeout(r, ms));
  // Step 1: close notice
  for (const el of document.querySelectorAll('a, button')) {
    if (el.textContent.trim() === 'OK') { el.click(); break; }
  }
  await sleep(1000);
  // Step 2: click site cell
  let fr = document.querySelector('iframe');
  if (!fr || !fr.contentDocument) return 'no iframe';
  for (const c of fr.contentDocument.querySelectorAll('td, [role="cell"]')) {
    if (c.textContent.trim() === 'Rohr') { c.click(); break; }
  }
  await sleep(5000);
  // Step 3: expand Configuration + click WLAN
  fr = document.querySelector('iframe');
  for (const li of fr.contentDocument.querySelectorAll('li')) {
    if (li.textContent.trim() === 'Configuration' && li.classList.contains('title')) { li.click(); break; }
  }
  await sleep(1000);
  fr = document.querySelector('iframe');
  for (const li of fr.contentDocument.querySelectorAll('li')) {
    if (li.textContent.trim() === 'WLAN' && li.classList.contains('navigator-li-effective')) { li.click(); break; }
  }
  await sleep(3000);
  // ... continue with tab click, Optimize Now, mode selection, Confirm
  return 'done';
})()

Why This Works Better

  • Atomic: All steps run in one execution context — no risk of session expiring between tool calls
  • No ref fragility: Direct DOM queries inside iframe don't depend on snapshot refs staying valid
  • Sleep-based timing: await sleep(ms) gives SPA time to render between steps
  • Early return on failure: Each step checks for iframe existence and returns descriptive error if missing

Triggering WLAN Optimization (Full Async Flow)

To run the entire optimization (site click → WLAN → Optimization tab → Optimize Now → Global → Confirm) in one shot:

(async function(){
  const sleep = ms => new Promise(r => setTimeout(r, ms));
  // ... (site click + Configuration expansion + WLAN click as above)
  // Click "WLAN Optimization" tab
  fr = document.querySelector('iframe');
  for (const el of fr.contentDocument.querySelectorAll('span, div, a, li')) {
    if (el.textContent.trim() === 'WLAN Optimization' && el.children.length <= 1) { el.click(); break; }
  }
  await sleep(3000);
  // Click "Optimize Now"
  fr = document.querySelector('iframe');
  for (const el of fr.contentDocument.querySelectorAll('a, button, span')) {
    if (el.textContent.trim() === 'Optimize Now' && el.children.length <= 2) { el.click(); break; }
  }
  await sleep(2000);
  // Select "Global" radio
  fr = document.querySelector('iframe');
  for (const el of fr.contentDocument.querySelectorAll('label, span, div, input')) {
    if (el.textContent.trim().startsWith('Global')) { el.click(); break; }
  }
  await sleep(1000);
  // Click "Confirm"
  fr = document.querySelector('iframe');
  for (const el of fr.contentDocument.querySelectorAll('a, button')) {
    if (el.textContent.trim() === 'Confirm') { el.click(); return '✅ Global optimization started!'; }
  }
  return 'Confirm not found';
})()

Reading Optimization Results

After the optimization starts, the SPA typically goes blank (session expires). To check results:

  1. Re-login (navigate + login flow)
  2. Navigate to site Rohr → Configuration → WLAN → "Optimization History" tab
  3. Read the iframe body text:
(async function(){
  const sleep = ms => new Promise(r => setTimeout(r, ms));
  // ... (navigate to Optimization History tab as above)
  fr = document.querySelector('iframe');
  return fr.contentDocument.body.innerText.substring(0, 3000);
})()

The history table shows: TIME, TYPE (Manual/Adaptive), DEVICES, DURATION, MODE, RESULT (score before→after), and ACTION.

Observed result (Global mode, 2026-06-29):

Jun 29, 2026 08:36:34 am    3    4m 21s    Manual
86 → 88 (+2)

Score scale: 0-100. Improvements of +2-4 points per optimization run are typical. 3 of 4 APs were optimized (one may have already been on an optimal channel).

Post-optimization: The optimization generated 2 "monitor link down" alerts (see "Pitfall: Optimization Causes Monitor Link Down Alerts" below). These were batch-resolved, bringing the total to 20 resolved / 0 unresolved.

Full Optimization Flow (Confirmed Working)

The entire flow — from Global View to optimization confirmation — can be executed as a single async IIFE after login. This was confirmed end-to-end on 2026-06-29:

  1. Login (Enter key in password field)
  2. Dismiss notice dialog (OK button)
  3. Click site "Rohr" cell in iframe
  4. Expand Configuration → click WLAN
  5. Click "WLAN Optimization" tab
  6. Click "Optimize Now" link
  7. Select "Global" radio in the optimization mode dialog
  8. Click "Confirm"

Steps 3-8 can all run in one browser_console async IIFE (see "Triggering WLAN Optimization" code block above). After Confirm, the SPA goes blank — re-login to check results via Optimization History.

Session Expiry After Confirm

Clicking "Confirm" in the optimization dialog causes the SPA to go blank — the iframe disappears entirely. This is expected: the optimization disrupts connectivity (including the controller's own management plane). Recovery requires a full re-login cycle.

Device Detail Pages

Opening Device Details — Two Levels

There are TWO ways to open device details, producing different views:

1. Simple View: Click device name (span.device-name)

Click the span.device-name element in the Devices table. Opens a compact detail panel with limited tabs.

// Correct selector for device names in the table
const spans = doc.querySelectorAll('span.device-name');
for (const s of spans) {
  if (s.textContent.trim() === 'Router') { s.click(); break; }
}

Pitfall: span.text-link does NOT match device names in the table. The correct CSS class is span.device-name (class: device-name u-text-word-break-all ellipsis). The span.text-link selector works for site names in the Site List, not device names.

2. Rich View: Click "Manage Device" button

After opening the simple view, click the "Manage Device" button (a.manage-device-button). This opens a wider drawer with full tabs:

Router (DR3650v-4G) tabs in Manage Device view:

  • Overview — Upload/Download rate, Temperature, CPU%, Memory%, Channel Utilization, Link graph, Current Clients table (shows connected clients with MAC, IP, IPv6)
  • Network View — Network topology visualization
  • Ports — Port-level statistics (packets, dropped, errors, bytes per port)
  • Logs — Device-specific log entries
  • Tools — Network Check, Terminal
  • Config — Device configuration with left-side menu:
    • General: Name, Description, LED, Device Labels, Remember Device
    • Wireless: Radio settings
    • SIM Config: PIN Management, Statistics, SMS Message, SMS Settings
    • Transmission: Routing, NAT, Bandwidth Control, Gateway QoS
    • Network Security: ACL
    • Advanced: General, DNS
    • No SNMP section exists (verified 2026-07-05 — see SNMP Monitoring section)

Switch (SG3428MP) tabs in Manage Device view:

  • Same 6 tabs (Overview, Network View, Ports, Logs, Tools, Config)
  • Config menu differs: General, VLAN Interface, Services (Loopback Control, Spanning Tree), Static Route
  • No SNMP section exists

Pitfall: The Config tab's left-side menu uses .ant-menu-item class. Some items show as [skeleton-item fake-menu-item] placeholders that never load (20 skeleton items remained permanently on the router config). Scrolling the menu container does not trigger lazy loading. This appears to be a bug in the Omada SPA when certain firmware versions don't expose all expected config sections.

Known Issue: DR3650 ISP Statistics Empty

Symptom: ISP statistics page for the DR3650v-4G router is always empty in Omada.

Root Cause: The DR3650v-4G with Hardware v1.0 / Firmware 1.1.1 does not push ISP-level telemetry (WAN traffic, cellular data volume, signal strength, connection statistics) to the Omada controller. The controller can only read basic device telemetry (temperature, CPU, memory, port status). This is a hardware/firmware limitation, not a configuration issue.

Observations (2026-06-29):

  • Router detail page has only "Overview" and "Ports" tabs — no ISP/Cellular/WAN section
  • Active WAN ports: DSL + Port 5 (green/active) — DSL is primary WAN, not 4G/SIM
  • Router reports: 75°C, CPU 24%, Memory 57%, uptime 6+ days
  • Port statistics ARE available (packets, bytes, errors per port) but aggregated WAN/ISP stats are NOT

Workaround: Enable local management on the router to access its built-in web UI directly:

  1. In Omada: Configuration → Device Config → Gateway → Local Management → Enable
  2. Access router UI at http://10.0.30.1/webpages/login.html
  3. ISP/cellular statistics are available in the router's own web UI under WAN/Cellular sections

Pitfall: Router Local Login Blocked When Managed by Controller When the DR3650 is adopted by an Omada controller, the local web UI at http://10.0.30.1/webpages/login.html displays: "Note: This Gateway is being managed by Controller [IP]". Login attempts with admin credentials or the Omada cloud password will fail. Local management must be explicitly enabled through the Omada controller's Device Config → Gateway → Local Management settings before local login works.

Logs & Alerts

Viewing Alerts

Navigate to site → Logs (left nav, under Monitoring). The Logs badge shows the count of unresolved alerts. Three tabs: Alerts, Events, Audit Logs.

Filter options:

  • Unresolved / Resolved / All — toggle between alert states
  • System / Device — filter by alert source
  • Filter link — advanced filtering

Alert Types Observed

Type Level Cause Action
Device informed monitor link down Warning AP lost TCP connection to Controller on port 29817 Usually transient — see pitfall below

Resolving Alerts (Batch Resolve)

To mark multiple alerts as resolved at once:

  1. Navigate to site → Logs → Alerts tab (must be in site view, NOT Global View — Global View only has "Events" and "Audit Logs" tabs, no "Alerts")
  2. Click the "Select all" checkbox in the table header (first ant-checkbox-input in the table)
  3. Click "Batch Resolved" link (class s-button s-button-link) in the toolbar
  4. No confirmation dialog appears — alerts are resolved immediately
  5. Verify: the "Unresolved" count drops to 0
// Async flow: select all + batch resolve
(async function(){
  const sleep = ms => new Promise(r => setTimeout(r, ms));
  const fr = document.querySelector('iframe');
  if (!fr || !fr.contentDocument) return 'no iframe';
  const doc = fr.contentDocument;
  // Select all checkboxes
  const cbs = doc.querySelectorAll('.ant-checkbox-input');
  if (cbs.length > 0) cbs[0].click(); // first visible CB = select all
  await sleep(1000);
  // Click "Batch Resolved"
  for (const l of doc.querySelectorAll('a, button, span')) {
    if (l.textContent.trim() === 'Batch Resolved' && l.offsetParent !== null) {
      l.click();
      return 'batch resolved';
    }
  }
  return 'Batch Resolved not found';
})()

Checking Firmware Versions & Available Updates

Navigate to site → Devices (left nav). The device table shows all 6 devices with columns: NAME, IP, STATUS, MODEL, ACTION.

  • Firmware update indicator: A green upward-arrow icon in the ACTION column signals an available firmware update for that device.
  • "Start Rolling Upgrade" button (top right) initiates staged firmware updates across multiple devices.
  • Devices without the arrow icon are on the latest firmware.

Observed firmware status (2026-06-29):

Device Model HW Update?
Router DR3650v-4G v1.0 ✅ Current
Core (Switch) SG3428MP v6.20 ⬆️ Update available
AP Erdgeschoss EAP683 UR(EU) v1.0 ✅ Current
AP Obergeschoss EAP683 UR(EU) v1.0 ✅ Current
AP Garage EAP615-Wall(EU) v1.0 ✅ Current
AP Garten EAP225-Outdoor(EU) v3.0 ✅ Current

Pitfall: Optimization Causes "Monitor Link Down" Alerts

Running WLAN Optimization (especially Global mode) disrupts AP connectivity for several minutes. Each affected AP generates a "Device informed monitor link down" Warning alert (TCP connection to Controller on port 29817 failed). These are expected and harmless — the APs reconnect after optimization completes. Don't treat them as real network problems. Use "Batch Resolved" (see above) to clear them.

Pitfall: Global View vs Site View — Different Tab Sets

The Global View Logs page only has "Events" and "Audit Logs" tabs. The "Alerts" tab exists ONLY in the site-level Logs page. If you see only "Events" and "Audit Logs", you're in Global View — navigate back to the site first. Similarly, the site-level sidebar has "Management", "Monitoring", "Configuration", "Hotspot", "Maintenance" sections, while Global View has "Dashboard", "Devices", "Logs", "SD-WAN", "Accounts", "Settings". Use the sidebar structure to verify which view you're in.

SNMP Monitoring

CRITICAL FINDING: SNMP Cannot Be Enabled via Omada Cloud Controller

As of 2026-07-05, the Omada Cloud Controller does NOT expose SNMP configuration for ANY device type. This was verified exhaustively:

  • Router (DR3650v-4G, FW 1.1.1): Config tab has sections: General, Wireless, SIM Config (PIN Management, Statistics, SMS Message, SMS Settings), Transmission (Routing, NAT, Bandwidth Control, Gateway QoS), Network Security (ACL), Advanced (General, DNS). None contain SNMP. Some sections show [skeleton-item fake-menu-item] placeholders that never load (20 skeleton items remain permanently).
  • Switch (SG3428MP, FW 6.20.26): Config tab has sections: General, VLAN Interface, Services (Loopback Control, Spanning Tree), Static Route. No SNMP.
  • APs: Config tab not tested for SNMP, but given the pattern above, unlikely to have SNMP settings either.

Conclusion: SNMP configuration is only available through the devices' local web UIs, NOT through the Omada cloud controller. The cloud controller simply does not provide this capability.

Prerequisites for SNMP via Local Device UIs

To enable SNMP on the devices, you need access to each device's local web UI:

  1. Router (172.16.1.1): Local login is BLOCKED — shows "Note: This Gateway is being managed by Controller 99.80.193.119". Must enable Local Management via Omada controller first (Configuration → Device Config → Gateway → Local Management — if this setting exists in your controller version).
  2. Switch (172.16.1.2): Local web UI is accessible (no "managed by controller" message), but requires device-specific admin credentials. Neither admin/admin nor the Omada cloud password work. The local credentials are NOT stored in 1Password.
  3. APs: Each AP may have a local web UI at its 172.16.1.x address. Credentials unknown.

Omada API Exporters — Do NOT Work with Cloud Controller

Two community Prometheus exporters exist for TP-Link Omada:

  • charlie-haley/omada_exporter (140 stars) — Docker image chhaley/omada_exporter
  • RCooLeR/omada_exporter (56 stars) — Docker image ghcr.io/rcooler/omada_exporter

Both require a LOCAL Omada controller URL (OMADA_HOST=https://192.168.x.x). They use the Omada controller's REST API (/api/v2/...), which is only served by on-premise controllers. The cloud controller at omada.tplinkcloud.com returns HTML (SPA) for all API paths — it does NOT expose a REST API backend.

To use these exporters, you would need to run a local Omada Software Controller (Docker container) and migrate devices from the cloud controller to the local one.

Local Omada Software Controller Migration (In Progress)

Decision (2026-07-05): Migrate from cloud controller to a local Omada Software Controller to enable SNMP and API-based monitoring.

Rationale: The cloud controller cannot enable SNMP or serve API exporters. A local controller unlocks both paths. Devices retain cached config during controller downtime, so the circular dependency (controller needs network ↔ network managed by controller) is not real — devices boot with last-known config and continue operating.

Deployment target: CT 142 (omada-controller, 10.0.30.142/24, VLAN 30, proxmox7, vm_disks storage, 2 cores / 4 GB RAM / 32 GB disk). Created via pct create with Debian 12 template.

Migration steps (planned):

  1. Install Docker on CT 142
  2. Deploy Omada Software Controller container (TP-Link official image)
  3. Run setup wizard (admin user, site "Rohr")
  4. Remove devices from cloud controller
  5. Adopt devices on local controller (devices at 172.16.1.x)
  6. Deploy omada_exporter (charlie-haley or RCooLeR) pointing at http://10.0.30.142:8088
  7. Add Prometheus scrape config for omada_exporter
  8. Extend Grafana dashboard with Omada panels

Circular Dependency Analysis (user-raised concern):

  • Cold-start sequence: Gateway boots (cached config) → Switch boots (cached config) → PVE nodes boot → HA manager starts CT 142 → Controller reconnects to devices
  • Risk: only if gateway config is corrupt AND controller is down simultaneously — very unlikely
  • Mitigation: CT 142 is in HA-manager (auto-restart on any node)

Alternatives for Omada Metrics Collection

Since neither SNMP nor API exporters work with the cloud controller:

  1. Run a local Omada Software Controller — IN PROGRESS (CT 142). Devices will be re-adopted from the local controller. Then both SNMP (via local device UIs) and API exporters will work.
  2. Browser automation scraping — Periodically read device metrics (CPU, memory, temperature, port stats, client counts) from the Omada cloud controller via browser automation and push to Prometheus via pushgateway. Hacky but functional.
  3. Accept the limitation — The existing Grafana dashboard (network-infra, uid: network-infra) already tracks PVE nodes, guests, HA state, and blackbox probes. Omada device metrics (CPU, memory, temp) are visible in the Omada UI but not in Prometheus.

Device Inventory (Verified 2026-07-05)

All devices are on VLAN 1 (CatchAll/Default, 172.16.1.0/24):

Device Model HW/FW IP Notes
Router DR3650v-4G HW v1.0 / FW 1.1.1 172.16.1.1 Primary gateway, VLAN routing. Also at 10.0.30.1 (VLAN 30 interface)
Core (Switch) SG3428MP HW v6.20 / FW 6.20.26 172.16.1.2 PoE switch, 28 ports, firmware update available (6.20.27)
AP Erdgeschoss EAP683 UR(EU) HW v1.0 / FW 1.4.0 172.16.1.3 Connected to switch port 16
AP Obergeschoss EAP683 UR(EU) HW v1.0 / FW 1.4.0 172.16.1.4 Connected to switch port 14
AP Garage EAP615-Wall(EU) HW v1.0 / FW 1.5.4 172.16.1.5 Connected to switch port 21
AP Garten EAP225-Outdoor(EU) HW v3.0 / FW 5.2.2 172.16.1.6 Outdoor AP

Note

: The 10.0.30.1, 10.0.20.1, etc. addresses are the gateway's VLAN interfaces, not separate devices. All Omada-managed devices use 172.16.1.x (VLAN 1 / CatchAll) as their management IP. The Omada controller communicates with devices via the organization connection IP (84.39.78.100) through the cloud.

snmp_exporter Deployment Status

snmp_exporter IS deployed on CT 141 as a binary + systemd service (v0.27.0, port 9116, using the official snmp.yml with all standard MIBs). Docker-based deployment on CT 141 does not work — see the deployment section below for details. The exporter is running and ready; it just needs SNMP to be enabled on the Omada devices to start collecting.

The monitoring stack on CT 141 runs via Docker: prometheus, grafana, alertmanager, blackbox-exporter, pve-exporter, telegram-bridge. snmp_exporter is the exception — it runs as a systemd service, not Docker.

Deploying snmp_exporter in Monitoring Stack

Critical: Docker-based deployment of snmp_exporter on CT 141 FAILS. Containers get stuck in "Created" state, docker start/docker logs/ docker inspect all hang indefinitely. This affects both docker run and docker compose up. The root cause is unclear (other containers like prometheus/grafana work fine), but the pattern is 100% reproducible. Use the binary + systemd approach instead (below).

Approach A (RECOMMENDED): Binary + systemd service

Works reliably on CT 141. Tested with snmp_exporter v0.27.0.

# On CT 141 (via SSH to proxmox7, pct exec 141):
curl -sL -o /tmp/snmp_exporter.tar.gz \
  https://github.com/prometheus/snmp_exporter/releases/download/v0.27.0/snmp_exporter-0.27.0.linux-amd64.tar.gz
tar xzf /tmp/snmp_exporter.tar.gz -C /tmp/

# Install binary
cp /tmp/snmp_exporter-0.27.0.linux-amd64/snmp_exporter /usr/local/bin/snmp_exporter
chmod +x /usr/local/bin/snmp_exporter

# Use the official snmp.yml bundled with the release (1.4MB, 63574 lines)
# Contains all standard MIBs including if_mib, host_resources, etc.
cp /tmp/snmp_exporter-0.27.0.linux-amd64/snmp.yml /etc/snmp_exporter.yml

# Create systemd service
cat > /etc/systemd/system/snmp-exporter.service << 'EOF'
[Unit]
Description=SNMP Exporter for Prometheus
After=network.target

[Service]
ExecStart=/usr/local/bin/snmp_exporter --config.file=/etc/snmp_exporter.yml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now snmp-exporter
# Verify: systemctl status snmp-exporter
# Test:   curl -s "http://localhost:9116/snmp?target=172.16.1.1&module=if_mib&auth=public_v2"
# Metrics: curl -s http://localhost:9116/metrics | head -5

Pitfall: v0.27.0 does NOT have the /-/healthy endpoint (returns 404). Use curl -s http://localhost:9116/metrics to verify the exporter is alive.

Approach B (NOT RECOMMENDED): Docker container

Adding snmp_exporter as a Docker container on CT 141 does not work. docker create succeeds but docker start hangs for 30+ seconds, then the container enters a crash-restart loop. docker logs, docker inspect, and docker rm all hang. The only way to recover is docker container prune -f or waiting for operations to eventually complete after 30-60s timeouts. Both the full 2MB snmp.yml and a minimal custom snmp.yml produce the same result. This is specific to CT 141 — not a general snmp_exporter Docker issue.

Prometheus Scrape Configuration

Add to /opt/monitoring/prometheus/prometheus.yml on CT 141:

  - job_name: snmp_omada
    scrape_interval: 30s
    static_configs:
      - targets:
          - 172.16.1.1  # Gateway (DR3650v-4G)
          - 172.16.1.2  # Switch (SG3428MP)
          - 172.16.1.3  # AP Erdgeschoss (EAP683 UR)
          - 172.16.1.4  # AP Obergeschoss (EAP683 UR)
          - 172.16.1.5  # AP Garage (EAP615-Wall)
          - 172.16.1.6  # AP Garten (EAP225-Outdoor)
    metrics_path: /snmp
    params:
      module: [if_mib]
      auth: [public_v2]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: localhost:9116  # snmp_exporter runs as systemd, not Docker

Then reload: curl -s -X POST http://localhost:9090/-/reload Verify: curl -s http://localhost:9090/api/v1/targets | python3 -m json.tool | grep snmp

TP-Link Enterprise OIDs

TP-Link uses enterprise OID 11863 (per IANA assignment). Key MIB subtrees:

  • 1.3.6.1.4.1.11863.1 — tp-linkDevice
  • 1.3.6.1.4.1.11863.2 — tp-linkCommon
  • 1.3.6.1.4.1.11863.3 — tp-linkPort
  • 1.3.6.1.4.1.11863.6 — tp-linkSwitch

Standard IF-MIB (1.3.6.1.2.1.2) works for interface stats on all devices. Host Resources MIB (1.3.6.1.2.1.25) works for CPU/memory on devices that expose it.

Best Practices

  • Always wait 5-8s after navigation before snapshotting — the SPA is slow
  • Use browser_console for iframe-internal interactions when browser_click refs fail
  • Prefer async IIFE console chains over individual tool calls for multi-step flows — fewer session-expiry failures
  • Dismiss all popup dialogs before attempting navigation
  • Channel optimization disrupts connectivity — confirm with user before triggering
  • Check "Optimization History" to verify optimization completed successfully
  • After triggering optimization, expect session to drop — re-login to check results
Reference in New Issue View Git Blame Copy Permalink