Files
gandalf/kuma.py
jaredandClaude Opus 5.5 c2ff072eb2
Lint / Python (flake8) (push) Failing after 15s
Lint / JS (eslint) (push) Successful in 1m43s
Lint / Deploy (push) Skipped
Test / Python Tests (pytest) (push) Failing after 21s
Security / Python Security (bandit) (push) Successful in 2m3s
Lint / Python (flake8) (pull_request) Failing after 15s
Lint / JS (eslint) (pull_request) Failing after 15s
Lint / Notify on failure (pull_request) Skipped
Lint / Deploy (pull_request) Skipped
Security / Python Security (bandit) (pull_request) Successful in 2m17s
Lint / Notify on failure (push) Successful in 3s
Test / Python Tests (pytest) (pull_request) Successful in 2m58s
Restart modem button: silence Gandalf and Uptime Kuma, restart, end both
Admins get a Restart modem button on the WAN / Fiber panel (needs
modem.access_code). After a confirmation it:

1. switches an Uptime Kuma maintenance window on (new kuma.py: logs in
   over Kuma 2's Socket.IO API and resumes/pauses one pre-made manual
   window, uptime_kuma.maintenance_id); if Kuma fails it stops and asks
   whether to go on without it,
2. starts Gandalf maintenance (global suppression, 20 minutes at most),
3. posts the gateway's Restart Device form (ModemAdmin.restart), undoing
   1 and 2 if that fails.

The monitor waits for the modem to answer with its WAN up and an uptime
showing it restarted, then switches Kuma off, ends the suppression and
records how long it took; after 30 minutes it ends both regardless. The
panel shows the restart in progress and the result for an hour.

New dependency: python-socketio[client].

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 19:27:25 -05:00

57 lines
2.4 KiB
Python

"""Switch one Uptime Kuma maintenance window on and off (Kuma 2.x, over its Socket.IO API).
Kuma has no REST API for maintenance, so this logs in over the same socket its web UI
uses. It only ever resumes or pauses the one window named in config, which is created
once in Kuma ("manual" strategy, covering the monitors that a modem restart takes down):
"uptime_kuma": {"url": "http://10.10.10.25:3001", "username": "...", "password": "...",
"maintenance_id": 7}
Nothing else in Kuma is read or changed.
"""
import logging
from typing import Callable, Optional
import socketio
logger = logging.getLogger('gandalf.kuma')
class KumaError(Exception):
"""Kuma couldn't be reached, refused the login, or refused the change."""
def configured(cfg: Optional[dict]) -> bool:
cfg = cfg or {}
return all(cfg.get(k) for k in ('url', 'username', 'password', 'maintenance_id'))
def set_maintenance(cfg: dict, active: bool, client_factory: Optional[Callable] = None) -> None:
"""Resume (active=True) or pause the configured maintenance window. Raises KumaError."""
timeout = cfg.get('timeout', 10)
factory = client_factory or (lambda: socketio.Client(
reconnection=False, ssl_verify=cfg.get('verify_ssl', True)))
sio = factory()
try:
sio.connect(cfg['url'], transports=['websocket'], wait_timeout=timeout)
res = sio.call('login', {'username': cfg['username'], 'password': cfg['password'], 'token': ''},
timeout=timeout) or {}
if not res.get('ok'):
if res.get('tokenRequired'):
raise KumaError('the Kuma account has two-factor login, which Gandalf cannot answer')
raise KumaError(f'login refused: {res.get("msg") or "no reason given"}')
event = 'resumeMaintenance' if active else 'pauseMaintenance'
res = sio.call(event, int(cfg['maintenance_id']), timeout=timeout) or {}
if not res.get('ok'):
raise KumaError(f'{event} refused: {res.get("msg") or "no reason given"}')
logger.info(f'Uptime Kuma maintenance {cfg["maintenance_id"]} {"on" if active else "off"}')
except KumaError:
raise
except Exception as e: # socketio raises its own errors and plain timeouts
raise KumaError(f'{type(e).__name__}: {e}') from e
finally:
try:
sio.disconnect()
except Exception: # nosec B110 - nothing left to clean up
pass