major-ai-skills
Version:
Installable agentic skills / AI agent skills (SKILL.md) for Claude Code, Cursor, Codex CLI, Gemini CLI & Antigravity - 402+ professional app, token-efficiency, and common-sense skills. SEO/GEO ready.
159 lines (126 loc) • 8.85 kB
Markdown
name: omada-controller
description: "Manage TP-Link Omada controller workflows with the REST OpenAPI, device adoption, and VLAN or VPN configuration."
category: network
risk: safe
source: self
source_type: self
date_added: "2026-08-26"
tags: ["omada-controller", "tp-link-sdn", "rest-openapi", "network-automation", "vlan-routing", "wifi-roaming", "claude"]
tools: ["claude", "cursor", "gemini", "codex"]
# TP-Link Omada SDN Controller AI Skill Guide (Claude)
## Overview & Engine Architecture
TP-Link Omada SDN Controller is a centralized software-defined networking platform managing Omada EAP wireless access points, JetStream managed switches, and SafeStream/Omada multi-WAN VPN gateways. Powered by a **Java OpenJDK daemon** and an embedded **MongoDB database**, Omada exposes an authenticated **HTTPS REST OpenAPI (`/api/v2`)** and maintains southbound device control via dedicated UDP/TCP ports (**UDP 29810 Discovery, TCP 29811 Management, TCP 29812 Adoption, TCP 29813 Heartbeat, TCP 29814 Upgrade**). Claude operates as a Principal Network Systems Architect and SDN Automation Engineer, specializing in **REST OpenAPI automation**, **Layer 3 remote adoption (`set-inform`)**, **802.1Q VLAN trunking**, and **MongoDB database recovery**.
### Omada SDN Controller Architecture & Protocol Stack
```
┌─────────────────────────────────────────────────────────────┐
│ Omada SDN Controller Stack │
│ │
│ Northbound Management & API Ingress │
│ ├── HTTPS Web Management Console (Port 8043) │
│ ├── REST OpenAPI v2/v3 (`/api/v2/login`, Site Operations) │
│ └── Cloud Portal Gateway (Omada Cloud Management Bridge) │
│ │
│ SDN Controller Core & Persistence │
│ ├── Java Application Daemon (`/opt/tplink/EAPController`) │
│ ├── MongoDB Database Backend (Device State, Client Logs) │
│ └── 802.11k/v/r Fast Roaming & AI WLAN Mesh Coordinator │
│ │
│ Southbound Device Communication Layer │
│ ├── UDP 29810 (Device Discovery Broadcasts) │
│ ├── TCP 29811/29813 (Device Management & Heartbeat Keepalive│
│ └── TCP 29812/29814 (Device Adoption, Firmware Upgrade) │
└─────────────────────────────────────────────────────────────┘
```
## Operational Capabilities & Agent Directives
1. **Omada REST OpenAPI Automation**: Author Python scripts to authenticate against Omada Controller, obtain session tokens (`omada_token`), and programmatically retrieve device inventories, client connection stats, and switch port configurations.
2. **Layer 3 Remote Device Adoption**: Remediate cross-subnet adoption failures by guiding administrators to issue the SSH discovery inform command (`set-inform http://<controller_ip>:29812/inform`).
3. **MongoDB Database Recovery & Maintenance**: Repair corrupted database journal locks (`mongod.lock`) and execute database compaction.
4. **VLAN & Multi-WAN Policy Optimization**: Design robust network segmentations with isolated Guest VLANs, 802.1p QoS tagging, and multi-WAN failover rules.
## Production Python Automation: Omada Controller REST API Inventory & Client Telemetry Client
Save this script as `omada_api_client.py` (requires `pip install requests urllib3`):
```python
"""
TP-Link Omada SDN Controller REST API Client
Authenticates with controller, extracts active site ID, device states, and connected clients.
"""
import sys
import requests
import json
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
CONTROLLER_URL = "https://192.168.1.50:8043"
USERNAME = "admin"
PASSWORD = "SecurePassword123"
class OmadaController:
def __init__(self, base_url: str = CONTROLLER_URL):
self.base_url = base_url.rstrip("/")
self.session = requests.Session()
self.session.verify = False
self.token = None
self.omada_id = None
def login(self, username: str = USERNAME, password: str = PASSWORD):
print(f"--- [AUTHENTICATING WITH OMADA CONTROLLER: {self.base_url}] ---")
# 1. Obtain Controller ID / Info
info_res = self.session.get(f"{self.base_url}/api/v2/info")
if info_res.status_code == 200:
self.omada_id = info_res.json().get("result", {}).get("omadacId")
login_url = f"{self.base_url}/api/v2/login"
payload = {"name": username, "password": password}
res = self.session.post(login_url, json=payload)
if res.status_code == 200 and res.json().get("errorCode") == 0:
result = res.json().get("result", {})
self.token = result.get("token")
self.session.headers.update({"Csrf-Token": self.token})
print("✅ Authentication successful!")
else:
print(f"🚨 Login failed: {res.text}")
sys.exit(1)
def get_devices(self, site_id: str = "Default"):
url = f"{self.base_url}/api/v2/sites/{site_id}/devices"
res = self.session.get(url)
if res.status_code == 200:
devices = res.json().get("result", [])
print(f"\n--- [OMADA MANAGED DEVICES: ({len(devices)})] ---")
for d in devices:
name = d.get("name", "Unnamed")
model = d.get("model", "Unknown")
mac = d.get("mac", "")
ip = d.get("ip", "")
status = "CONNECTED" if d.get("status") == 1 else "OFFLINE"
print(f"• [{status:<9}] {name:<20} | Model: {model:<12} | IP: {ip:<15} | MAC: {mac}")
else:
print(f"Failed to fetch devices: {res.text}")
if __name__ == "__main__":
controller = OmadaController()
controller.login()
controller.get_devices()
```
## Technical Troubleshooting Matrix
| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **Device Stuck in `Adopting` or `Pending` State** | Southbound TCP ports 29811-29814 blocked by host firewall or device is on a different L3 subnet without Inform URL. | 1. SSH into AP/Switch (default `admin`/`admin`).<br>2. Run: `set-inform http://<Controller_IP>:29812/inform`.<br>3. In host OS, open ports: `sudo ufw allow 29810:29814/tcp && sudo ufw allow 29810/udp`. |
| **Controller Service Fails to Start: `MongoDB Error`** | Improper shutdown left lock file `mongod.lock` intact or database journal corrupted. | 1. Stop service: `sudo tesseract stop` or `systemctl stop omada`.<br>2. Remove lock: `sudo rm -f /opt/tplink/EAPController/data/db/mongod.lock`.<br>3. Repair: `mongod --dbpath /opt/tplink/EAPController/data/db --repair`.<br>4. Restart service. |
| **Wi-Fi Clients Experience Roaming Drops** | Fast Roaming (802.11k/v/r) disabled or 2.4GHz/5GHz transmit power set too high, preventing handoff. | In Controller Settings $\rightarrow$ Wireless Networks $\rightarrow$ Advanced, enable **802.11r Fast Roaming** and reduce 2.4GHz Tx power to Medium/Low. |
| **SSL / HTTPS Security Warning on Port 8043** | Controller using default self-signed SSL certificate. | In Controller Settings $\rightarrow$ Maintenance $\rightarrow$ **SSL Certificate**, import custom Let's Encrypt / Enterprise PKCS#12 certificate. |
## Command Line Syntax & Omada CLI Recipes
```bash
# 1. Inspect Omada Controller Daemon Logs (Linux)
tail -f /opt/tplink/EAPController/logs/server.log
# 2. SSH into EAP / Switch and Set L3 Adoption Inform URL
ssh admin@192.168.1.105 "set-inform http://192.168.1.50:29812/inform"
# 3. Restart Omada Controller Service on Linux
sudo systemctl restart tpeap.service
```
### Essential File Locations
- **Controller Root Directory**: `/opt/tplink/EAPController/` (Linux) or `C:\Program Files (x86)\TP-LINK\Omada Controller\` (Windows)
- **Application Server Logs**: `/opt/tplink/EAPController/logs/server.log`
- **MongoDB Data Path**: `/opt/tplink/EAPController/data/db/`
## Agent Operational Directive
> **MANDATORY**: For Layer 3 remote site deployments, verify that TCP ports 29811-29814 and UDP port 29810 are forwarded through the edge firewall before troubleshooting adoption timeouts.