unifi-scheduler.md

UniFi Scheduler Usage

This doc captures how we access the UniFi controller via the local tunnel and query client stats with unifi-scheduler.

Prerequisites

• SSH jump host: homepi
• Controller IP: 192.168.1.39
• Local tunnel (must be running while you use the CLI):

ssh -N -L 8444:192.168.1.39:443 -L 8443:192.168.1.39:8443 homepi

• Endpoint for the CLI: https://127.0.0.1:8444
• Use a non-MFA UniFi user when running CLI automation.

Local build (current workflow)

We currently use a locally built binary in tmp/unifi-scheduler/unifi-scheduler.

cd tmp/unifi-scheduler/unifi-scheduler-master
make build

Notes:

• The local build includes a small allowlist change so raw requests can hit /stat/report/* endpoints.
• If you re-download the tool, reapply the allowlist change in pkg/unifi/validation.go.

Basic usage

List clients:

tmp/unifi-scheduler/unifi-scheduler \
  --endpoint https://127.0.0.1:8444 \
  --tls-insecure \
  --username <user> \
  --password '<pass>' \
  client list

Get current client stats (raw):

tmp/unifi-scheduler/unifi-scheduler \
  --endpoint https://127.0.0.1:8444 \
  --tls-insecure \
  --username <user> \
  --password '<pass>' \
  raw --method GET /stat/sta

Time-series client stats (5-minute, hourly, daily)

These endpoints require POST payloads. All timestamps are Unix milliseconds.

5-minute user stats (good for short windows):

tmp/unifi-scheduler/unifi-scheduler \
  --endpoint https://127.0.0.1:8444 \
  --tls-insecure \
  --username <user> \
  --password '<pass>' \
  raw --method POST /stat/report/5minutes.user '{
    "attrs": ["time", "signal", "tx_retries", "rx_rate", "tx_rate"],
    "start": 1767374033164,
    "end": 1767460433164,
    "mac": "aa:bb:cc:dd:ee:ff"
  }'

Hourly stats (last ~7 days by default):

tmp/unifi-scheduler/unifi-scheduler \
  --endpoint https://127.0.0.1:8444 \
  --tls-insecure \
  --username <user> \
  --password '<pass>' \
  raw --method POST /stat/report/hourly.user '{
    "attrs": ["time", "signal", "tx_retries", "rx_rate", "tx_rate"],
    "start": 1766855823601,
    "end": 1767460623601,
    "mac": "aa:bb:cc:dd:ee:ff"
  }'

Daily stats (last ~30 days by default):

tmp/unifi-scheduler/unifi-scheduler \
  --endpoint https://127.0.0.1:8444 \
  --tls-insecure \
  --username <user> \
  --password '<pass>' \
  raw --method POST /stat/report/daily.user '{
    "attrs": ["time", "signal", "tx_retries", "rx_rate", "tx_rate"],
    "start": 1764868623601,
    "end": 1767460623601,
    "mac": "aa:bb:cc:dd:ee:ff"
  }'

Troubleshooting

• Self-signed TLS: use --tls-insecure or supply a root CA with --tls-root-ca.
• MFA: CLI automation cannot complete WebAuthn challenges; use a non-MFA local UniFi user.
• Stale events: stat/event appears stale on this controller; use stat/report/5minutes.user for recent history.

Useful fields

• signal: RSSI (dBm)
• rx_rate, tx_rate: link rates
• tx_retries: retry count (higher indicates poor link or interference)
• time: sample timestamp (ms)