Sankofa/infrastructure/omada/README.md

# TP-Link Omada Management

Comprehensive management tools and integrations for TP-Link Omada SDN (Software-Defined Networking) infrastructure.

## Overview

TP-Link Omada provides centralized management of network infrastructure including access points, switches, and gateways. This directory contains management components for integrating Omada into the Sankofa Phoenix infrastructure.

## Components

### API Client (`api/`)

Omada Controller API client library for:
- Controller authentication and session management
- Site and device management
- Access point configuration
- Network policy management
- Client device tracking
- Analytics and monitoring

### Terraform (`terraform/`)

Terraform provider/modules for:
- Omada Controller configuration
- Site provisioning
- Access point deployment
- Network policy as code
- SSID management

### Ansible (`ansible/`)

Ansible roles and playbooks for:
- Omada Controller deployment
- Access point provisioning
- Network policy configuration
- Firmware management
- Configuration backup

### Scripts (`scripts/`)

Management scripts for:
- Controller health checks
- Device discovery
- Configuration backup/restore
- Firmware updates
- Network analytics

## Omada Controller Integration

### Architecture

```
Omada Controller (Centralized)
├── Sites (Physical Locations)
│   ├── Access Points
│   ├── Switches
│   ├── Gateways
│   └── Network Policies
└── Global Settings
    ├── SSID Templates
    ├── Network Policies
    └── User Groups
```

### Controller Setup

```bash
# Setup Omada Controller
./scripts/setup-controller.sh \
  --controller omada.sankofa.nexus \
  --admin admin \
  --password secure-password
```

### Site Configuration

```bash
# Add a new site
./scripts/add-site.sh \
  --site us-east-1 \
  --name "US East Datacenter" \
  --timezone "America/New_York"
```

## Usage

### Access Point Management

```bash
# Discover access points
./scripts/discover-aps.sh --site us-east-1

# Provision access point
./scripts/provision-ap.sh \
  --site us-east-1 \
  --ap "AP-01" \
  --mac "aa:bb:cc:dd:ee:ff" \
  --name "AP-Lobby-01"

# Configure access point
./scripts/configure-ap.sh \
  --ap "AP-Lobby-01" \
  --radio 2.4GHz \
  --channel auto \
  --power high
```

### SSID Management

```bash
# Create SSID
./scripts/create-ssid.sh \
  --site us-east-1 \
  --name "Sankofa-Employee" \
  --security wpa3 \
  --vlan 100

# Assign SSID to access point
./scripts/assign-ssid.sh \
  --ap "AP-Lobby-01" \
  --ssid "Sankofa-Employee" \
  --radio 2.4GHz,5GHz
```

### Network Policies

```bash
# Create network policy
./scripts/create-policy.sh \
  --site us-east-1 \
  --name "Guest-Policy" \
  --bandwidth-limit 10Mbps \
  --vlan 200

# Apply policy to SSID
./scripts/apply-policy.sh \
  --ssid "Sankofa-Guest" \
  --policy "Guest-Policy"
```

### Ansible Deployment

```bash
# Deploy Omada configuration
cd ansible
ansible-playbook -i inventory.yml omada-deployment.yml \
  -e controller=omada.sankofa.nexus \
  -e site=us-east-1
```

### Terraform

```bash
# Provision Omada infrastructure
cd terraform
terraform init
terraform plan -var="controller=omada.sankofa.nexus"
terraform apply
```

## API Client Usage

### Python Example

```python
from omada_api import OmadaController

# Connect to controller
controller = OmadaController(
    host="omada.sankofa.nexus",
    username="admin",
    password="secure-password"
)

# Get sites
sites = controller.get_sites()

# Get access points for a site
aps = controller.get_access_points(site_id="us-east-1")

# Configure access point
controller.configure_ap(
    ap_id="ap-123",
    name="AP-Lobby-01",
    radio_config={
        "2.4GHz": {"channel": "auto", "power": "high"},
        "5GHz": {"channel": "auto", "power": "high"}
    }
)
```

### Go Example

```go
package main

import (
    "github.com/sankofa/omada-api"
)

func main() {
    client := omada.NewClient("omada.sankofa.nexus", "admin", "secure-password")
    
    sites, err := client.GetSites()
    if err != nil {
        log.Fatal(err)
    }
    
    aps, err := client.GetAccessPoints("us-east-1")
    if err != nil {
        log.Fatal(err)
    }
}
```

## Configuration

### Controller Configuration

```yaml
controller:
  host: omada.sankofa.nexus
  port: 8043
  username: admin
  password: ${OMADA_PASSWORD}
  verify_ssl: true

sites:
  - id: us-east-1
    name: US East Datacenter
    timezone: America/New_York
    aps:
      - name: AP-Lobby-01
        mac: aa:bb:cc:dd:ee:ff
        location: Lobby
      - name: AP-Office-01
        mac: aa:bb:cc:dd:ee:ff
        location: Office
```

### Network Policies

```yaml
policies:
  - name: Employee-Policy
    bandwidth_limit: unlimited
    vlan: 100
    firewall_rules:
      - allow: [80, 443, 22]
      - block: [all]
  
  - name: Guest-Policy
    bandwidth_limit: 10Mbps
    vlan: 200
    firewall_rules:
      - allow: [80, 443]
      - block: [all]
```

## Monitoring

Omada monitoring integrates with Prometheus:

- **omada_exporter**: Prometheus metrics exporter
- **Grafana Dashboards**: Pre-built dashboards for Omada
- **Alerts**: Alert rules for network health

See [Monitoring](../monitoring/README.md) for details.

## Security

- Controller authentication via username/password or API key
- TLS/SSL for all API communications
- Network isolation via VLANs
- Client device authentication
- Regular firmware updates

## Backup and Recovery

### Configuration Backup

```bash
# Backup Omada configuration
./scripts/backup-config.sh \
  --controller omada.sankofa.nexus \
  --output backup-$(date +%Y%m%d).json
```

### Configuration Restore

```bash
# Restore Omada configuration
./scripts/restore-config.sh \
  --controller omada.sankofa.nexus \
  --backup backup-20240101.json
```

## Firmware Management

```bash
# Check firmware versions
./scripts/check-firmware.sh --site us-east-1

# Update firmware
./scripts/update-firmware.sh \
  --site us-east-1 \
  --ap "AP-Lobby-01" \
  --firmware firmware-v1.2.3.bin
```

## Troubleshooting

### Common Issues

**Controller connectivity:**
```bash
./scripts/test-controller.sh --controller omada.sankofa.nexus
```

**Access point offline:**
```bash
./scripts/diagnose-ap.sh --ap "AP-Lobby-01"
```

**Network performance:**
```bash
./scripts/analyze-network.sh --site us-east-1
```

## Related Documentation

- [Network Management](../network/README.md)
- [System Architecture](../../docs/system_architecture.md)
- [Infrastructure Management](../README.md)