Init

2026-04-26 16:56:13 +00:00
commit 76adff71d7
10 changed files with 2016 additions and 0 deletions
@@ -0,0 +1,159 @@
+# xonotic_exporter
+
+Prometheus exporter for [Xonotic](https://xonotic.org/) game servers.
+Scrapes metrics via RCON (`sv_public` + `status 1`) and exposes them
+in Prometheus exposition format.
+
+## Features
+
+- **Python 3.11+** (fully compatible with 3.13 — no deprecated asyncio `loop=` args)
+- **TOML configuration** — one file, all servers, one systemd unit
+- **All three RCON modes** — nonsecure, secure-time, secure-challenge (MD4)
+- **Blackbox-style multi-target** — one exporter, many game servers
+- **CLI test interface** — human-readable or raw Prometheus output
+- **Zero-downtime config reload** — `kill -HUP $PID` or `POST /-/reload`
+
+## Installation
+
+```bash
+python3 -m venv /opt/xonotic_exporter/venv
+/opt/xonotic_exporter/venv/bin/pip install .
+```
+
+## Configuration
+
+Copy `examples/xonotic_exporter.toml` to `/etc/xonotic_exporter/xonotic_exporter.toml`
+and fill in your `rcon_password` values.
+
+```toml
+[exporter]
+host = "0.0.0.0"
+port = 9260
+
+[[servers]]
+name          = "vehicles"
+host          = "localhost"
+port          = 26010
+rcon_password = "secret"
+rcon_mode     = 2           # 2 = secure-challenge (MD4) — recommended
+
+[[servers]]
+name          = "resurrection"
+host          = "localhost"
+port          = 26015
+rcon_password = "secret"
+rcon_mode     = 2
+
+[[servers]]
+name          = "insurrection"
+host          = "localhost"
+port          = 26016
+rcon_password = "secret"
+rcon_mode     = 2
+```
+
+**rcon_mode values** match your server's `server.cfg`:
+
+| Value | Name              | server.cfg setting |
+|-------|-------------------|--------------------|
+| `0`   | nonsecure         | `rcon_restricted 0` |
+| `1`   | secure-time       | `rcon_secure 1`    |
+| `2`   | secure-challenge  | `rcon_secure 2`    |
+
+## Running
+
+### As a systemd service
+
+```bash
+sudo cp examples/xonotic_exporter.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now xonotic_exporter
+```
+
+Reload config without restarting:
+
+```bash
+sudo systemctl reload xonotic_exporter
+# or
+curl -XPOST http://localhost:9260/-/reload
+```
+
+### Manually
+
+```bash
+xonotic-exporter serve /etc/xonotic_exporter/xonotic_exporter.toml
+```
+
+## CLI Testing
+
+```bash
+# Human-readable output (default)
+xonotic-exporter query vehicles --config xonotic_exporter.toml
+
+# Raw Prometheus exposition
+xonotic-exporter query vehicles --config xonotic_exporter.toml --prometheus
+
+# Ad-hoc (no config file needed)
+xonotic-exporter query --host localhost --port 26010 --password secret --mode 2
+
+# Ad-hoc with verbose logging
+xonotic-exporter -v query --host localhost --port 26010 --password secret
+
+# Validate config
+xonotic-exporter validate /etc/xonotic_exporter/xonotic_exporter.toml
+```
+
+Human-readable output example:
+
+```
+  RCON mode : secure-challenge (MD4)
+────────────────────────────────────────────────────
+  Server   : vehicles
+  Hostname : My Xonotic Server
+  Map      : warfare
+  Public   : yes (sv_public=1)
+────────────────────────────────────────────────────
+  Ping     : 2.3 ms
+  CPU      : 1.4 %
+  Lost     : 0.0 %
+  Offset   : avg=0.02ms  max=1.20ms  sdev=0.10ms
+────────────────────────────────────────────────────
+  Players  : 4/16
+    Active      : 3
+    Spectators  : 1
+    Bots        : 0
+────────────────────────────────────────────────────
+```
+
+## Prometheus Configuration
+
+See `examples/prometheus.yml` for a ready-to-use scrape config.
+
+## Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `xonotic_up` | 1 if server reachable |
+| `xonotic_sv_public` | Value of sv_public cvar |
+| `xonotic_ping_seconds` | Round-trip time to server |
+| `xonotic_timing_cpu_percent` | Server CPU usage % |
+| `xonotic_timing_lost_percent` | Packet loss % |
+| `xonotic_timing_offset_avg_ms` | Average timing offset ms |
+| `xonotic_timing_offset_max_ms` | Max timing offset ms |
+| `xonotic_timing_offset_sdev_ms` | Timing offset std dev ms |
+| `xonotic_players_active` | Active (scoring) players |
+| `xonotic_players_spectators` | Spectators |
+| `xonotic_players_bots` | Bots |
+| `xonotic_players_total` | Total connected |
+| `xonotic_players_max` | Max player slots |
+
+All metrics carry an `instance` label set to the server name from TOML.
+
+## Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | HTML index with all configured servers |
+| `/metrics?target=<name>` | GET | Prometheus metrics for one server |
+| `/-/reload` | POST | Reload config from disk |
+| `/-/healthy` | GET | Liveness probe |