louispaulb 56ad97bc71 feat: GenieACS config export + TR-069 to TR-369 migration plan

- Add /acs/export endpoint: dumps all provisions, presets, virtual
  params, files metadata in one call (insurance policy for migration)
- Add /acs/provisions, /acs/presets, /acs/virtual-parameters, /acs/files
- Shell script export_genieacs.sh for offline full backup
- TR069-TO-TR369-MIGRATION.md: phased migration plan from GenieACS
  to Oktopus with parallel run, provision mapping, CPE batching

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-02 21:03:41 -04:00

5.3 KiB

Raw Blame History

TR-069 (GenieACS) → TR-369 (Oktopus) Migration Plan

Why Migrate

GenieACS maintenance risk — single maintainer, slow release cadence, Node.js/MongoDB stack aging
TR-069 is polling-based — CPE connects every X minutes, no real-time push. Reboot command waits for next inform.
TR-369 (USP) is the ITU/BBF successor — MQTT/WebSocket transport, bidirectional, real-time, certificate-based auth
Oktopus is actively developed — Go-based, NATS messaging, supports both TR-069 and TR-369

Current GenieACS Architecture

CPE fleet (TR-069)
    │ HTTP/SOAP (CWMP)
    ▼
96.125.192.25 — GenieACS Core (CWMP, NBI, FS)
    │
    ▼
10.5.2.125 — MongoDB (devices, tasks, faults, provisions)
    │
    ▼
10.5.2.124 — GenieACS GUI (admin portal)
    │
    ▼
targo-hub /devices/* — Ops UI integration

Target Oktopus Architecture

CPE fleet (TR-369 USP + legacy TR-069)
    │
    ├── MQTT/WebSocket (USP) ──▶ Oktopus Controller
    │                               │
    ├── HTTP/SOAP (CWMP) ──────▶ Oktopus TR-069 Adapter
    │                               │
    │                               ▼
    │                           NATS (internal messaging)
    │                               │
    │                               ▼
    │                           PostgreSQL / TimescaleDB
    │
    ▼
targo-hub /devices/* — Ops UI integration (same endpoints, new backend)

Migration Phases

Phase 0: Export & Document (NOW)

Run scripts/migration/export_genieacs.sh on GenieACS server
Catalog all provisions, presets, virtual parameters
Document each provision's purpose and parameter paths
Download all firmware files from GridFS

Phase 1: Deploy Oktopus with TR-069 Adapter (Parallel Run)

Deploy Oktopus CE alongside GenieACS (different port/IP)
Enable Oktopus TR-069 adapter to accept CWMP connections
Point a small test group of CPEs (5-10 units) to Oktopus
Verify: inform, reboot, parameter read/write, firmware upgrade
Keep GenieACS running for the rest of the fleet

Phase 2: Reproduce Provisions in Oktopus

Map each GenieACS provision to Oktopus equivalent:

GenieACS Concept	Oktopus Equivalent
Provision script (JS)	USP Set/Get/Operate messages + webhooks
`declare(path, ...)`	USP Get/Set on TR-181 path (same paths!)
`ext('script', ...)`	Oktopus webhook to targo-hub
Preset (trigger rule)	Device group + event subscription
Preset tag filter	Oktopus device group membership
Preset event (inform/boot)	MQTT topic subscription
Virtual parameter	Oktopus computed metric or targo-hub enrichment
File (firmware)	Oktopus firmware repository

Phase 3: Gradual CPE Migration

Update CPE ACS URL via GenieACS setParameterValues:

Device.ManagementServer.URL = "https://acs-new.gigafibre.ca"

Migrate in batches: 50 → 500 → all
Monitor for faults, missed informs, failed tasks
Keep GenieACS read-only as fallback for 30 days

Phase 4: TR-369 Firmware Upgrade

For CPEs that support USP (newer models):
- Push firmware with TR-369 agent enabled
- Configure USP controller URL and MQTT broker
- Migrate from TR-069 adapter to native TR-369
For legacy CPEs (TR-069 only):
- Keep on Oktopus TR-069 adapter permanently
- Replace hardware on failure with TR-369 capable units

Phase 5: Decommission GenieACS

Verify 100% of fleet reports to Oktopus
Archive MongoDB data (export to JSON/PostgreSQL)
Shut down GenieACS servers
Update targo-hub to point to Oktopus API instead of GenieACS NBI

targo-hub Integration Changes

The /devices/* endpoints in targo-hub currently proxy GenieACS NBI. For Oktopus:

# Current (GenieACS NBI)
GENIEACS_NBI_URL=http://10.5.2.115:7557

# Future (Oktopus API)
OKTOPUS_API_URL=https://oss.gigafibre.ca/api

The summarizeDevice() function already handles both TR-098 and TR-181 parameter paths, so the Ops UI won't need changes — only the backend proxy target.

CPE Compatibility Check

Before migration, verify each CPE model's protocol support:

Model	TR-069	TR-369	Notes
ZTE F670L	✅	❌	Legacy, keep on TR-069 adapter
ZTE F680	✅	✅	Firmware update enables USP
Huawei HG8245H	✅	❌	Legacy
Nokia G-010G-Q	✅	✅	USP via firmware 3.x+

(Fill in with actual fleet models after running device summary export)

Risk Mitigation

GenieACS stays running during entire migration — no big bang cutover
Same TR-181 data model — parameter paths don't change
targo-hub abstraction layer — Ops UI doesn't care which ACS backend serves /devices/*
Export script preserves all business logic — can recreate GenieACS from scratch if needed
Oktopus TR-069 adapter means even legacy CPEs work without firmware changes

Timeline Estimate

Phase	Duration	Prerequisite
Phase 0: Export	1 day	SSH access to GenieACS
Phase 1: Parallel deploy	1 week	Oktopus server provisioned
Phase 2: Reproduce provisions	1-2 weeks	Understanding of all scripts
Phase 3: CPE migration	2-4 weeks	Phase 2 validated
Phase 4: TR-369 firmware	Ongoing	CPE vendor firmware availability
Phase 5: Decommission	1 day	30 days after Phase 3

5.3 KiB Raw Blame History