Collector Enrolment & Verification
Enrolment is a one-time exchange: a scoped registration token from the Orchestrator portal for a long-lived collector JWT. Once enrolled, the appliance heart-beats every 30s and resumes after reboot without re-registering. The credential model and rotation are detailed in Security & Compliance → Collector authentication.
1. Register the collector
The tenant admin generates a one-time token in the Orchestrator portal (ozone.techforcz.com). The token is single-use, sha256-hashed at rest, and expires 72 hours after it is issued. Run enrolment on the appliance with that token:
# One-time enrolment; token is scoped to the tenant and expires in 72h
python3 /opt/techforcz/bin/register.py --token "${TFZ_REGISTRATION_TOKEN:?paste the one-time token}"
# On success the Orchestrator returns and the appliance persists:
# collector_id, tenant_id, access_token (collector JWT), tier
# written to .env and /data/saas_sync.json
The SAAS_URL the collector dials is the Orchestrator:
# /opt/techforcz/config/.env (relevant identity + egress keys)
SAAS_URL=https://ozone.techforcz.com # Orchestrator endpoint (registration, heartbeat, ingest)
STATE_PATH=/data/saas_sync.json # persisted identity; survives reboot, no re-onboarding
HEARTBEAT_INTERVAL=30 # seconds; OFFLINE in fleet view after > 3 missed (~90s)
COLLECTOR_ID= # filled by register.py
TENANT_ID= # filled by register.py
The registration token is single-use and expires in 72 hours: it is consumed and cleared on first successful registration. After a reboot the collector resumes heart-beating from
/data/saas_sync.json, so it does not need the token again.
Offline auth and break-glass
Beyond the collector JWT, the Orchestrator publishes an edge token signed with RS256 and a public JWKS (at /auth/jwks.json). The WebUI caches the public key, so it can verify a user token offline and let an operator log in even while the SaaS is unreachable. If the outage is total and the edge token cannot be refreshed, an operator can still get in with the break-glass path (POST /api/v1/saas/breakglass-login): a locally signed admin token gated by BREAKGLASS_USER and a BREAKGLASS_PASSWORD_HASH (sha256 hex). Both paths exist so the appliance stays operable during a SaaS outage without weakening the normal SSO flow.
2. Run diagnostics (the 16 checks)
python3 /opt/techforcz/bin/diagnostics.py # human output + /opt/techforcz/logs/diagnostics.json
| # | Check | PASS means | First action on FAIL |
|---|---|---|---|
| 1 | Docker daemon | engine responding | sudo systemctl restart docker |
| 2 | Disk space | mounts < 90% | docker system prune -f; check /data growth |
| 3 | Memory | usage sane | docker stats --no-stream to find the hog |
| 4 | Compose services | stack containers Up | docker compose up -d from the canonical dir |
| 5 | NATS health | bus alive | restart nats; see Troubleshooting |
| 6 | NATS JetStream | streams present | as check 5 |
| 7 | VictoriaMetrics | container healthy | restart container; check disk |
| 8 | Health monitor | :9090/health reports healthy | restart the appliance health-monitor; see Troubleshooting |
| 9 | WebUI | :3000 serving | restart aiops-webui |
| 10–12 | Ports 162/514/2055 | listeners bound | restart the respective collector |
| 13 | Registration | COLLECTOR_ID present + Orchestrator ack | run register.py (needs Orchestrator reachable) |
| 14 | TLS certificate | valid, not near expiry | check clock/NTP |
| 15 | DNS resolution | ozone.techforcz.com resolves | customer DNS/firewall; Firewall |
| 16 | Orchestrator reachable | HTTPS round-trip | Firewall / Proxy |
Baselines:
- Before enrolment: 13/16 pass. Checks 13/15/16 are expected to fail until the appliance is enrolled and the Orchestrator is reachable.
- After enrolment: 16/16. If 13/15/16 still fail post-enrolment, walk the Firewall and Proxy paths in order.
3. Confirm it is online
# Local: heartbeat firing and identity persisted
systemctl status techforcz-heartbeat.timer
sudo cat /data/saas_sync.json | python3 -m json.tool # collector_id, tenant_id, registered: true
docker compose logs --tail 30 saas-sync | grep -i heartbeat
In the Orchestrator fleet view the collector shows online within ~30s of the first heartbeat. If it shows OFFLINE while local collection is healthy, the broken path is the heartbeat, not collection; see SaaS Troubleshooting.
4. Re-enrolment & revocation
| Situation | What to do |
|---|---|
| Token expired before use | generate a fresh token in the portal; tokens are single-use and expire 72h after issue |
Appliance rebuilt / /data lost | re-run register.py with a new token; identity is rebuilt from the Orchestrator |
| Collector decommissioned | delete it in the Orchestrator fleet view; its JWT is blacklisted |
| Revoked but still running | the appliance keeps collecting locally and shows Unregistered (autonomy principle), and it stops forwarding to the Orchestrator |
Deleting a collector does not stop local monitoring, because the appliance is autonomous by design (see Platform Architecture). To fully retire it, power off the VM after deletion.
Section complete
With the appliance installed, networked, optionally proxied, and enrolled, telemetry begins flowing to the Orchestrator within one poll cycle (default 60s). Operate ingestion policy, alerts, and dashboards from SaaS Workflows; resolve faults from Troubleshooting.