glm-5.1
161049a17d
Security review #005 identified critical vulnerabilities in the Unix domain socket admin API (C1 symlink race, C2 no auth, C3 info leak, W1-W7, S1-S6). ADR-028 (already accepted) replaces the socket with an authenticated HTTP admin API on the health check port. This commit adds the remaining spec work: - ADR-029: Config file TOCTOU mitigation (mtime check on reload) - ADR-030: Store cli_allow_wildcard_bind in ConfigReloadHandle for consistent reload validation - Implementation tasks for the admin HTTP migration (fix/admin-http-api), TOCTOU fix (fix/config-reload-toctou), and wildcard flag fix (fix/wildcard-flag-reload) - Updated review #005 status to resolved with per-finding disposition - Resolved OQ-16: POST for state-changing admin endpoints, GET for read-only - Updated all architecture docs to reference new ADRs, use admin_key_path instead of admin_socket_path, and reflect POST method for /admin/reload
2.7 KiB
2.7 KiB
ADR-014: Unix Domain Socket Config Reload API
Status
Superseded by ADR-028
Context
The proxy supports config reload via SIGHUP (ADR-009). SIGHUP is simple and well-understood, but has limitations:
- No feedback — the sender doesn't know if the reload succeeded or failed
- No structured input — you can only signal "reload", not specify which parts to reload or pass validation context
- Requires process signal permissions — not all deployment tools can send signals
A Unix domain socket API would allow programmatic config reload with success/failure status, enabling integration with CI/CD pipelines, admin tools, and automated configuration management.
Decision
Add a Unix domain socket API for config reload alongside SIGHUP. The socket accepts commands and returns structured responses.
The socket path is configurable via admin_socket_path in StaticConfig
(default: /run/reverse-proxy/admin.sock). Setting it to empty string
disables the admin socket.
Initial commands:
reload— Re-read config file, validate, and swap DynamicConfig. Returns{"status": "ok"}or{"status": "error", "message": "..."}.status— Return basic process info (uptime, config load time, site count). Returns{"status": "ok", "uptime_secs": 1234, "sites": 2}.
Future commands (not in Phase 1, but the protocol supports extension):
metrics— Return Prometheus-compatible metricsshutdown— Graceful shutdown command
Rationale
- Providing reload feedback is operationally valuable — CI/CD pipelines can verify config changes before proceeding
- The implementation cost is low — a Unix domain socket listener is ~50 lines of tokio code, and the command protocol is simple
- SIGHUP is retained as a fallback for environments where socket access is inconvenient
- This pattern will integrate naturally with alknet's admin interface when the projects merge
- Unix domain sockets are filesystem-permission-based, providing access control without additional authentication
- The socket path is configurable, allowing deployment-specific paths
Consequences
Positive:
- Config reload with success/failure feedback
- Programmatic integration with CI/CD and admin tools
- Structured response format enables automation
- SIGHUP still works as fallback
- Natural path to future admin commands
Negative:
- Additional listener and command parsing logic (~100-150 lines)
- Socket file management (cleanup on startup, stale socket detection)
- One more config option (
admin_socket_path)
References
- operations.md
- config.md
- ADR-009 (signal handling — SIGHUP retained as fallback)
- OQ-04 (now resolved)