jp.louvel/ncstatuscheckZentralisiertes Monitoring für mehrere Nextcloud-Instanzen
Zentralisierte Überwachung mehrerer Nextcloud-Instanzen
NcStatusCheck ist ein Überwachungstool, mit dem Sie den Gesundheitszustand mehrerer Nextcloud-Server über eine einzige Weboberfläche verfolgen können. Es analysiert Nextcloud- und PHP-Versionen und gibt Update-Empfehlungen.
< 15d / < 7d)occ app:list gegen den Nextcloud-App-Store, um zu überprüfende Apps zu kennzeichnen – blockierend (Upgrade-blockierend, inkompatibel, Test-Apps in Produktion) sowie informative Reife-/Turbulenzsignale (kürzlich veröffentlicht, vor 1.0, Alpha/Beta/RC-Build, viele Releases, frisch veröffentlichte Version)📦) und ein paralleler Block „Container zum Überwachen" (🐳) fassen jede gekennzeichnete App / jedes Docker-Image über alle Instanzen hinweg zu einem Eintrag zusammen, mit pro Gruppe Typfiltern und einem Popup, das die betroffenen Instanzen und ihre Versionen auflistet.ALERT_WEBHOOK_URL) und/oder eine zusammenfassende E-Mail pro Batch (ALERT_EMAIL_TO), gesendet durch direkte SMTP-Übermittlung an Ihren E-Mail-Server (eingebundener PHPMailer; fällt auf den lokalen MTA zurück, wenn kein SMTP-Relay konfiguriert ist). Deckt auch träge Signale (ALERT_CHECKS) ab: SSL-Zertifikatsablauf (abgestuft), anfällige/veraltete Nextcloud-Version, veraltete Push-Abfrage, kritischer Prüfbericht, blockierender App-Fund – eine Warnung pro neuem Zustand, keine Erinnerungsspam.nc_update_grace_days), um nicht hinter einem am selben Tag fehlerhaften Release herzujagen.⚠️ Warnungen, 📦 Apps, 🔄 Docker, 🔒 SSL, 🔴 offline, 🚧 Wartung) wenn es etwas zu berichten gibt.nc-audit.sh-Bericht sendet.localStorage gespeichertchmod 700) für die entfernte Nextcloud-Instanz, aktualisiert sich automatisch bei Optionsänderungenncstatuscheck/ ├── Frontend │ ├── index.php # Main entry point │ ├── template.html # HTML template (dashboard) │ ├── admin.html # Administration interface │ ├── detail.php # Server detail page │ ├── audit.php # Server-audit script distribution page (nc-audit.sh) │ ├── troubleshooting.php # Probe troubleshooting guide │ ├── app.js / admin.js / detail.js / audit.js / troubleshooting.js │ └── style*.css # One stylesheet per page family ├── APIs (HTTP) │ ├── api.php # Main monitoring API │ ├── detail-api.php # Detail page API (serverinfo + warnings + acks + availability) │ ├── push-api.php # Push reception + trigger + audit-report reception │ ├── ack-api.php # Warning acknowledge / unmute │ ├── admin-api.php # Version configuration routing │ ├── servers-admin-api.php # Server list management │ ├── nextcloud-versions-api.php # Official version scraping │ ├── nextcloud-apps-api.php # App store catalog (slim cache) for the apps audit │ ├── php-versions-api.php # PHP branch support data │ └── apps-warnings-api.php # Manual app warnings (known-bug list) CRUD ├── Shared modules (lib/) │ ├── auth.php # Auth + CSRF + URL redaction (defense in depth) │ ├── csrf-client.js # Auto-inject X-CSRF-Token in fetch() │ ├── nextcloud-client.php # Centralized HTTP client → remote Nextclouds │ ├── servers-store.php # Single source of truth for servers.json │ ├── uptime-state.php # Up/down state machine + transition journal + availability │ ├── alerts.php # Proactive alert dispatch: webhook + email digest │ ├── alerts-checks.php # Slow-signal alerts (SSL/version/push/audit/apps) + dedup state │ ├── smtp-mailer.php # SMTP transport adapter over vendored PHPMailer │ ├── phpmailer/ # Vendored PHPMailer (3 files + LICENSE, pinned in VERSION) │ ├── apps-warnings-manager.php # Manual app warnings storage │ ├── ui-common.js # NcUI: notify / confirm / prompt + shared app-audit messages │ ├── url-guard.php # Anti-SSRF (loopback, RFC1918, link-local…) │ ├── json-cache.php # Locked JSON read/write helpers │ └── version-config-manager.php # Version rules CRUD ├── Business logic │ ├── version-rules.php # NC / PHP status analysis engine │ ├── warnings-rules.php # Configuration warning engine │ ├── apps-rules.php # Installed-apps audit engine (store catalog cross-check) │ ├── cron-update.php # Full collection script, CLI only (twice a day) │ └── cron-ping.php # Lightweight up/down probe, CLI only (every 5 min) ├── Tools (never web-served — blocked by nginx/.htaccess) │ ├── tools/nc-audit.sh # Standalone server audit script (root, read-only) │ └── tools/ncstatuscheck-push-core.sh # Generic Push probe core (fleet-shared) ├── Tests │ └── tests/run.php # Plain-PHP test suite (no framework): php tests/run.php ├── Configuration │ ├── config.php # Central configuration (git-ignored) │ └── servers.json # Server list with tokens (git-ignored) └── Cache ├── servers_data.json # All server data ├── serverinfo_.json # Raw per-server cache (Extended) ├── push_.json # Last push payload per server ├── ack_.json # Acknowledged warnings per server ├── audit_.json # Last nc-audit.sh report per server ├── version-config.json # Version configuration ├── uptime_state.json # Up/down state per server (mini uptime) ├── uptime_history.json # Bounded up/down transition journal (availability % + incidents) ├── alerts_state.json # "Already alerted" memory of the check alerts ├── nextcloud_versions.json # Official NC versions ├── nextcloud_apps.json # App store slim catalog (apps audit) ├── apps-warnings.json # Manual app warnings (admin-curated) ├── .csrf_secret # CSRF HMAC secret (binary, 0600) └── *.log # Activity logs
deploy/ansible/ # Fleet deployment of the Push core (Ansible / scp) deploy/docker/ # Container packaging of the monitor itself
## 🔌 Sammelmodi
Die Modi schließen sich nicht gegenseitig aus – ein Server kann gleichzeitig „Extended“ und „Push“ sein.
| Modus | Badge | Quelle | Gesammelte Daten |
|-------|-------|--------|------------------|
| **Basic** | *(keiner)* | `/status.php` + HTTP‑Header | Nextcloud-Version (PHP/Webserver, falls offengelegt) |
| **Extended** | `⚡ Extended` (lila → orange bei Fehler/veraltet) | `/ocs/v2.php/apps/serverinfo/api/v1/info` mit `NC-Token` | NC-Version, PHP, Webserver, OPcache, Redis, DB, aktive Benutzer … |
| **Push** | `📡 Push` (blau → orange bei Fehler/veraltet) | POST an `push-api.php` | Vom entfernten NC-Instanz via Cron-Skript übermittelte Daten |
Das **serverinfo-NC-Token** ist verfügbar unter **Nextcloud-Einstellungen → Administration → System**.
Das **Push-Token** wird über die Administrationsoberfläche generiert; der Administrator stellt ein einsatzbereites Bash-Cron-Skript (`chmod 700`) zur Bereitstellung auf der überwachten Instanz zur Verfügung.
Die Daten des erweiterten Modus werden von der [nextcloud/serverinfo](https://github.com/nextcloud/serverinfo)-App bereitgestellt, die auf der überwachten Instanz installiert und aktiviert sein muss.
**Fallback-Verhalten**: Wenn die Extended-API nicht erreichbar ist (Verbindungsfehler, ungültiges Token, App nicht installiert), greift NcStatusCheck automatisch auf `/status.php` zurück, um zumindest die Nextcloud-Version abzurufen.
**Push-Staleness-Schwellwert**: Ein Push-Server gilt als veraltet, wenn innerhalb von `auto_push_interval + 30 Minuten` keine Daten empfangen wurden. Standardmäßig beträgt das Push-Intervall 12 Stunden.
### Dashboard-Tabellenspalten
Das Haupt-Dashboard zeigt 5 Spalten: **Server** | **NC-Version** | **PHP** | **Probes** | **Gesundheit**
Die Spalte **Probes** zeigt die aktiven Sammelmodi für jeden Server an:
- `⚡ Extended`-Badge (lila, wird bei Verbindungsfehler oder veralteten Daten orange)
- `📡 Push`-Badge (blau, wird orange, wenn innerhalb des Schwellwerts keine Daten empfangen wurden)
- Beide Badges können gleichzeitig erscheinen, wenn beide Modi aktiv sind
- Kein Badge = nur Basic-Modus
### Gesundheitsspalte
Die Gesundheitsspalte zeigt nur dann etwas an, wenn Handlungsbedarf besteht:
| Indikator | Badge | Bedeutung |
|-----------|-------|-----------|
| Offline | `🔴 Offline` | Instanz nicht erreichbar (HTTP-Probe fehlgeschlagen), mit „offline seit X“ |
| Aktive Warnungen | `⚠️ N` | N Konfigurationsprobleme |
| Apps-Prüfung | `📦 N` | N installierte Apps zur Überprüfung (upgrade-blockierend/inkompatibel) |
| SSL-Ablauf | `🔒 N d` | Zertifikat läuft bald ab – orange `< 15d`, rot `< 7d` oder abgelaufen |
| Docker-Updates | `🔄 M` | M Container-Updates verfügbar |
| Alles OK | *(leer)* | Nichts zu melden |
| Keine Daten | `?` | Basic-Modus ohne Push-Daten |
#### Hoch/Runter & SSL-Ablauf
NcStatusCheck speichert einen **minimalen** Hoch/Runter-Status pro Server (nur aktueller Zustand + Datum der letzten Änderung – keine Zeitreihen, keine Verlaufsseite). „Hoch“ bedeutet, dass die ausgehende HTTPS-Probe die Instanz erreicht hat; ein roter **Offline**-Badge erscheint nur bei „Runter“. Während derselben HTTPS-Probe wird das **SSL-Zertifikatsablaufdatum** ohne Zusatzaufwand ausgelesen (`CURLOPT_CERTINFO`) und gemeldet, wenn es naht. Beide sind auf der Detailseite vollständig einsehbar. *Hinweis: Diese ausgehenden Prüfungen gelten nicht für reine Push-Instanzen, die der Monitor nie kontaktiert.*
#### Apps-Prüfung (`📦`)
Wenn ein Push-Server seine installierten Apps meldet (`occ app:list`, Push-Skript v3+), gleicht NcStatusCheck sie mit dem Nextcloud-App-Store-Katalog ab und markiert überprüfenswerte Apps. **Nur Signalisierung** – das Tool deaktiviert nie etwas; es zeigt Kandidaten an (es kann nicht wissen, ob eine App tatsächlich genutzt wird). Es werden nur **sachliche, binäre** Signale verwendet. Der `📦 N`-Badge zählt blockierende Funde (keine kompatible Version für die aktuelle NC-Version, keine Version für NC N+1 → blockiert das Upgrade, oder eine Test-/Entwicklungs-App, die in der Produktion aktiviert gelassen wurde). Informationsfunde (App auf der Instanz veraltet, upstream aufgegeben, PHP-inkompatibel) werden nur auf der Detailseite angezeigt. Funde können über denselben Bestätigungsmechanismus wie Warnungen stummgeschaltet werden.
### `servers.json`-Format```json
[
{"url": "https://cloud.example.com"},
{"url": "https://cloud2.example.com", "serverinfo_token": "abc123def456"},
{"url": "https://cloud3.example.com", "serverinfo_token": "...", "push_token": "xyz789"}
]
server { server_name monitoring.your-domain.com; root /var/www/ncstatuscheck; index index.php;
# HTTP Basic Authentication
auth_basic "Monitoring Access";
auth_basic_user_file /etc/nginx/.htpasswd;
# Protect sensitive files/dirs (tests/run.php has no CLI-only guard — it must
# never be reachable over HTTP; same blocklist as deploy/docker/nginx.conf)
location ~ ^/(cache/|\.git|deploy/|tools/|tests/) {
deny all;
return 404;
}
# .txt covers servers.txt (legacy server list — real monitored URLs)
location ~* \.(log|json|txt)$ {
deny all;
return 404;
}
# Security headers for static HTML pages (admin.html, template.html).
# PHP pages (index.php, detail.php) send the same headers themselves
# via send_security_headers() in lib/auth.php.
location ~* \.html$ {
add_header X-Content-Type-Options nosniff always;
add_header X-Frame-Options DENY always;
add_header Referrer-Policy no-referrer always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'" always;
try_files $uri =404;
}
# Standard PHP configuration (adjust the socket to your PHP version —
# use a security-supported one: 8.2 has been EOL since December 2025)
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
location / {
try_files $uri $uri/ =404;
}
}
> **Apache**: Das Repository enthält `.htaccess`-Dateien, die die obigen `deny`-Regeln
> widerspiegeln (Root: blockiert `*.log`/`*.json`/`*.txt` und `.git`; `cache/`, `tools/`,
> `deploy/`, `tests/`: `Require all denied`). Sie funktionieren nur, wenn der vhost
> `AllowOverride FileInfo AuthConfig` (oder `All`) setzt – der Debian-Standard für
> `/var/www` ist `AllowOverride None`, in diesem Fall die Regeln direkt im
> vhost replizieren. HTTP Basic Auth muss dennoch im vhost konfiguriert werden.
### Bereitstellung
1. **Repository klonen**```bash
git clone https://gitlab.com/jp.louvel/ncstatuscheck.git
cd ncstatuscheck
Bearbeiten Sie `config.php` und passen Sie die Pfade und URL an Ihre Umgebung an:```php
define('MONITOR_PATH', '/var/www/ncstatuscheck');
define('MONITOR_URL', 'https://monitoring.your-domain.com'); // your public URL
define('CACHE_DIR', MONITOR_PATH . '/cache');
Server werden direkt über die Administrationsoberfläche (⚙️ Admin-Button) verwaltet.
Sie können auch servers.json manuell erstellen:```json
[
{"url": "https://cloud.example.com"},
{"url": "https://nextcloud.mycompany.org", "serverinfo_token": "your_token_here"}
]
> **Migration von `servers.txt`**: Wenn eine Datei `servers.txt` existiert, wird sie beim ersten Zugriff automatisch in `servers.json` konvertiert. Sie können dann `servers.txt` löschen.
4. **Berechtigungen setzen**
nginx/PHP-FPM laufen als eigener Benutzer (`www-data` auf Debian/Ubuntu, `nginx`/`apache`
auf RHEL-Familie — unten anpassen) — wenn Sie als Ihr eigener Login-Benutzer geklont haben, ist dieser Benutzer
mit ziemlicher Sicherheit nicht `www-data` oder in dessen Gruppe, sodass `chmod` allein den
Webserver **überhaupt keinen Zugriff** gewährt, nicht einmal Lesen (jede Anfrage 403/404):```bash
chown -R www-data:www-data /var/www/ncstatuscheck # adjust the user:group to your distro
chmod 750 /var/www/ncstatuscheck
chmod 750 cache img
chmod 640 *.php *.html *.js *.css *.md
chmod 600 config.php servers.json servers.txt # secrets / serverinfo & push tokens
chmod 660 cache/*.json cache/*.log
Wenn
servers.jsonnoch nicht existiert (Sie lassen die Admin-Oberfläche die Datei erstellen, anstatt den manuellen Schritt oben durchzuführen), hat daschmod 600oben einfach nichts, worauf es wirken kann – das ist in Ordnung:ServersStore::save()setzt bei jedem Schreibvorgang selbst die Berechtigung der Datei auf0600, sodass eineservers.json, die über die Admin-Oberfläche (neu)erstellt wird, niemals mit Serverinformationen/Push-Tokens für Gruppe/Welt lesbar bleibt.
6. **Geplante Aufgaben (optional)**
Zwei ergänzende Cron-Jobs — installieren Sie beide **im selben `crontab -`-Aufruf**:
`crontab -` installiert eine völlig neue Crontab von stdin, es hängt nicht an, so führt das zweimalige Ausführen (einmal pro Zeile) dazu, dass nur der *zweite* Job übrig bleibt — der erste verschwindet lautlos, kein Fehler. Dadurch bleibt auch alles erhalten, was bereits in Ihrer Crontab ist (`crontab -l` zuerst eingeleitet), anstatt es zu löschen:```bash
(crontab -l 2>/dev/null; cat <<'EOF'
# Full collection (NC/PHP versions, serverinfo, app-store catalog) — twice a day
0 6,18 * * * cd /var/www/ncstatuscheck && php cron-update.php
# Lightweight reachability probe (status.php only -> up/down state) — every 5 min
*/5 * * * * cd /var/www/ncstatuscheck && php cron-ping.php
EOF
) | crontab -
Re-running this appends duplicates if these lines are already present — check
with crontab -l first if unsure.
cron-ping.php ist bewusst minimal gehalten: es prüft nur den status.php jedes Instanz und aktualisiert den Zustand (up/down) in cache/uptime_state.json, sodass es ohne Last häufig laufen kann. Eine Instanz wird erst dann als down markiert, nach UPTIME_FAIL_THRESHOLD aufeinanderfolgenden fehlgeschlagenen Tests (Standard 2 → ~10 Min bei einem 5-Min-Takt); die Wiederherstellung auf up erfolgt sofort. Der vollständige cron-update.php bleibt für alles andere unverändert.
Anstelle der Schritte 1–6 oben kann NcStatusCheck auch als kleiner docker compose-Stack (PHP-FPM + nginx + ein Cron-Container) ausgeführt werden – das Repository wird wie es ist als Bind-Mount eingebunden, kein Build-Schritt oder Composer nötig, sodass es genau das Bare-Metal-Setup spiegelt, nur containerisiert. Es bedient nur einfaches HTTP (standardmäßig Port 8080) – stellen Sie Ihren eigenen TLS-terminierenden Reverse Proxy davor.
Die vollständige Einrichtung – Konfiguration, die Berechtigungsfallen (uid 82, vorherige Erstellung von servers.json), HTTP Basic Auth, Cron, Updates und Backups – befindet sich in deploy/docker/README.md. Fangen Sie dort an; dieser Abschnitt ist bewusst nur ein Verweis, um zu vermeiden, zwei Kopien derselben Schritte synchron zu halten.
https://monitoring.ihre-domain.deErreichbar durch Klicken auf jeden Servernamen oder dessen Health-Indikator.
Für Basic-Server (kein Extended- oder Push-Sonde) wird eine vereinfachte Seite mit den verfügbaren Daten (NC-Version, Webserver, HTTP-Protokoll) angezeigt, mit einem Hinweis und einem Vorschlag, eine Sonde zu aktivieren.
Für Extended / Push-Server zeigt die vollständige Detailseite separate Abschnitte an:
NcStatusCheck stellt mehrere REST-Endpunkte bereit:
Haupt-API (api.php)
GET ?action=get_data — Daten abrufen (Cache oder aktualisiert)POST ?action=refresh_data — Aktualisierung aller Server erzwingenPush-API (push-api.php)
POST mit push_token-Header — Pushen von Daten von einer entfernten NC-Instanz empfangenPOST ?action=request_push_all — Sofortiges Pushen von allen konfigurierten Push-Servern anfordern (setzt ein Trigger-Flag, das vom entfernten Cron-Skript verbraucht wird)Das vom Admin-UI generierte Cron-Skript ist in zwei Teile aufgeteilt: einen generischen Kern
/usr/local/bin/ncstatuscheck-push.sh– auf jedem Server identisch (die gesamte Logik) – gesteuert von einer kleinen pro-Instanz-Konfiguration/etc/ncstatuscheck/<slug>.conf(SERVER_URL,SLUG,OCC_CMD,DOCKER_ENABLED,SKOPEO_ENABLED). Es wird alsncstatuscheck-push.sh /etc/ncstatuscheck/<slug>.conf [--test]aufgerufen. Der Kern weigert sich, eine gruppen-/weltbeschreibbare Konfiguration zu laden (Anti-Code-Injection).Es ist Multi-Target (Fan-Out): Daten werden einmal gesammelt und an jeden Monitor gepusht, der in
/etc/ncstatuscheck/targets-<slug>.confaufgeführt ist (eineurl|push_token[|http_user|http_pass]Zeile pro Monitor). Jeder Monitor-Admin gibt einen idempotenten Befehl aus, um sich selbst zu registrieren.Mehrere Nextcloud-Instanzen auf einem Host: Pro-Instanz-Pfade werden durch ein ergänzt, das von der überwachten URL abgeleitet wird (z.B. → ): , , , , Zustand . Nur der Kern wird geteilt, sodass sich gemeinsam genutzte Instanzen niemals überschneiden.
Detail-API (detail-api.php)
GET ?server=<url> — Vollständige Serverinfo-Daten + berechnete Warnungen für einen Extended/Push-ServerAdministrations-APIs
admin-api.php — Versionskonfigurationservers-admin-api.php — Serververwaltung (get_servers, add_server, remove_server, update_server_token, generate_push_token, remove_push_token)nextcloud-versions-api.php — Offizielle Versionennc-audit.sh)Ein separates Subsystem zur Überwachung: ein eigenständiges, schreibgeschütztes Bash-Skript
(tools/nc-audit.sh), das als root auf einem Nextcloud-Server für ein einmaliges / monatliches
Audit der Web- + PHP- + Datenbank-Abstimmung ausgeführt wird, abgeglichen mit der physischen
Kapazität des Rechners (RAM, CPU, Festplattentyp). Ausgerichtet auf ein verwaltetes Aufsichts-Angebot:
Der Kunde installiert es, der Monitor empfängt nur Berichte – kein Maschinen-/Netzwerkzugriff
erforderlich. Das Skript liest nur die Konfiguration (keine Änderungen), gibt einen
farbigen Bericht aus und schreibt eine Kopie nach /tmp.
Was es prüft: Serverkapazität (RAM/CPU/SSD-HDD, Swappiness, Shared-Server-Erkennung) · Nextcloud
(Versionen, Cron, Cache, Redis-Laufzeit, DB-Typ, Logs) · PHP/PHP-FPM (echte serving SAPI,
OPcache-Laufzeit, Multi-Pool-Speicher) · Apache (MPM-bewusster Worker-Speicher) · Nginx ·
PostgreSQL · MariaDB · Sicherheitshygiene (fail2ban oder CrowdSec + Bouncer + Community-Blocklist;
ausstehende Updates / Neustart / Dienste auf veralteten Bibliotheken) · RAM-Budget-Abgleich
(InnoDB + FPM + Apache vs. realer RAM) · Tiefenanalyse mit optionalen Tools, falls bereits vorhanden
(mysqltuner, pt-variable-advisor, apache2buddy, sar/iostat).```bash
curl -fsSL https://gitlab.com/jp.louvel/ncstatuscheck/-/raw/master/tools/nc-audit.sh -o /usr/local/bin/nc-audit.sh chmod 700 /usr/local/bin/nc-audit.sh
sudo nc-audit.sh # auto-detect, dedicated server sudo nc-audit.sh /var/www/nextcloud # explicit path (or NC_PATH=…) sudo NC_RAM_BUDGET_PCT=50 nc-audit.sh # shared host: size to 50% of RAM
**Multi-Instanz-Hosts** (mehrere Nextclouds + eine gemeinsame Datenbank). `NC_RAM_BUDGET_PCT` ist dann das **gesamte** Stack-Budget; `NC_PHP_SHARE_PCT`% davon (Standard 60, der Rest deckt DB + Web + OS — auf DB-lastigen Servern verringern) ist der PHP-Anteil, der auf FPM-Pools nach **Gewicht** (eine relative Bedeutung — kein Prozentsatz, keine MB) aufgeteilt wird, um einen Zielwert für `pm.max_children` pro Pool zu erhalten:```
target = PHP_share × (weight / Σ weights) / ~50 MB per process
Das Ziel ist eine Obergrenze, die das Budget erlaubt, kein Wert, den Sie festlegen müssen (erhöhen Sie nur einen Pool, der tatsächlich gesättigt wird). Gewichte sind Ihre Entscheidung – das Tool errät sie nie.```bash
sudo NC_RAM_BUDGET_PCT=70 NC_INSTANCES="poolA:4,poolB:2,poolC:1" nc-audit.sh
sudo NC_RAM_BUDGET_PCT=70 nc-audit.sh --tune-fpm
**Report-Push-Back** (optional, verwendet die Push-Infrastruktur): `nc-audit.sh --push /etc/ncstatuscheck/<slug>.conf` führt den Audit durch und sendet den Bericht per POST an die Monitor(en), die ihn speichern und auf der Detailseite des Servers anzeigen (Abschnitt „🩺 Server-Audit“). In der Regel ein monatlicher Cron-Job. Die Webseite (Admin, Beta) unter `audit.php` verteilt das Skript (Download + Inline + GitLab-Einzeiler) und zeigt seine Version an.
> **Deep-Analyse-Werkzeuge werden niemals vom Skript installiert** — sie werden nur ausgeführt, wenn sie bereits vorhanden sind (kein `curl | bash`, keine Auto-Installation), jedes durch `timeout` begrenzt.
## 🔧 Erweiterte Konfiguration
### Anpassung der Versionsregeln
Bewertungsregeln sind über die Administrationsoberfläche konfigurierbar:
**Nextcloud-Status:**
- `dev` — Entwicklungsversion
- `stable` — Aktuelle stabile Version
- `oldstable` — Vorherige unterstützte stabile Version
- `deprecated` — Veraltete Version
**PHP-Status:**
- `recommended` — Empfohlene Version
- `supported` — Unterstützte Version
- `deprecated` — Veraltete Version
### Konfigurationsvariablen
Bearbeiten Sie `config.php`, um die Konfiguration anzupassen:```php
// Environment: 'dev' or 'prod'
define('ENV', 'prod');
// Paths and URLs
define('MONITOR_PATH', '/var/www/ncstatuscheck');
define('MONITOR_URL', 'https://monitoring.your-domain.com');
// Main server cache duration
define('CACHE_MAX_AGE', 86400); // 24 hours
// Official Nextcloud versions cache duration
define('VERSIONS_CACHE_AGE', 86400);
// Consecutive failed probes before a server is marked "down" (min 1)
define('UPTIME_FAIL_THRESHOLD', 2);
// Proactive alerts — webhook on a confirmed up/down state change.
// Empty URL = disabled. Format: 'slack' (default, also Mattermost/Google Chat),
// 'discord', or 'raw' (structured JSON). The URL usually carries a secret, so it
// is never logged in full — see config-example.php for details.
define('ALERT_WEBHOOK_URL', '');
define('ALERT_WEBHOOK_FORMAT', 'slack');
// Check alerts on top of up/down (cron-update cadence, 2×/day): SSL expiry
// tiers, vulnerable (below min_secure) or deprecated Nextcloud version, stale
// Push data, critical audit report, blocking apps-audit finding. Edge-triggered with a persisted state
// (cache/alerts_state.json): one alert per NEW condition, no reminders, re-arms
// when resolved (renewed cert, fixed/acked app…). First run arms silently.
define('ALERT_CHECKS', 'ssl,version,push_stale,audit,apps'); // '' = up/down only
define('ALERT_SSL_DAYS', '30,14,7'); // days-left tiers
// Email channel, independent of the webhook (either one arms the alerting).
// One digest mail per batch. Recommended transport: direct SMTP submission to
// your mail server (vendored PHPMailer, lib/phpmailer/ — nothing to set up on
// the host). Without ALERT_SMTP_HOST it falls back to PHP mail() (local MTA).
define('ALERT_EMAIL_TO', ''); // comma list of recipients, '' = off
define('ALERT_EMAIL_FROM', ''); // default: ncstatuscheck@<hostname>
define('ALERT_SMTP_HOST', ''); // e.g. 'mail.example.org', '' = mail() fallback
define('ALERT_SMTP_PORT', 587);
define('ALERT_SMTP_SECURITY', 'starttls'); // 'starttls' | 'tls' | 'none'
define('ALERT_SMTP_USER', '');
define('ALERT_SMTP_PASS', '');
Siehe
config-example.phpfür die vollständige, kommentierte Liste der Optionen (einschließlichDEMO_MODEundPUSH_SCRIPT_VERSION).
lib/csrf-client.js + csrf_require()).htaccess-Dateien für Apache gespiegelt; servers.json wird automatisch auf 0600 gesetzt (Tokens enthalten)X-Frame-Options, nosniff, Referrer-Policy) auf jeder über PHP ausgelieferten Seiteconfig.php ist gitignored und wird pro Server manuell bearbeitet, daher driftet es ab – stillschweigend, da fast jede Konstante einen Fallback im Code hat. Ein Banner oben auf der Admin-Seite meldet, was tatsächlich falsch ist, und nur wenn etwas falsch ist: eine von einem Update zurückgelassene PUSH_SCRIPT_VERSION, überhaupt kein Alarmtransport konfiguriert, ein abschließendes schließendes Tag, das vor jedem header() ein Byte ausgibt, ein nicht beschreibbares Cache-Verzeichnis, Konstanten, die fehlen und stillschweigend auf Standardwerte zurückfallen.
Schreibgeschützt von Natur aus und ohne Speicheraktion, aus dem gleichen Grund wie der Reiter Benachrichtigungen: config.php gehört root und enthält Geheimnisse. Der Dateiinhalt wird nie übertragen – nur Fakten darüber – und es wird kein Geheimnis gelesen.
Alles oben Genannte ist auf Anwendungsebene: Jeder im Internet kann den Monitor immer noch erreichen und abtasten, und nur das Passwort stoppt ihn. Der Reiter IP-Filterung generiert die Regeln, die eine Whitelist vor die App setzen, sodass unbekannte Hosts überhaupt nicht mit ihr kommunizieren können. Es handelt sich um eine Verteidigung in der Tiefe, nicht um einen Ersatz für die Basisauthentifizierung oder die Push-Tokens – und es erzeugt nur Text zur Überprüfung und zum Einfügen, es schreibt niemals eine Webserver- oder Firewall-Konfiguration.
Zwei Klassen von Quellen, bewusst ungleich, sodass ein kompromittierter überwachter Server nicht auf den Admin zugreifen kann:
| Klasse | Wer | Darf erreichen |
|---|---|---|
push | überwachte Instanzen nur im Push-Modus | /push-api.php, sonst nichts |
admin | Bastion / VPN / feste Büro-IP | alles |
Instanzen, die im Basis-/Erweiterten Modus abgefragt werden, öffnen keine eingehende Verbindung und erhalten überhaupt keinen Whitelist-Eintrag.
Adressen stammen aus zwei Quellen, und der Unterschied ist wichtig: Der DNS-Eintrag einer überwachten Domäne ist ihre Eingangs-Adresse, während ihr Push von ihrer Ausgangs-Adresse ausgeht. Wo sie sich unterscheiden, funktioniert nur die zweite. push-api.php zeichnet daher die tatsächliche Quelladresse jedes Pushes auf (source_ip im Push-Cache), und der Reiter setzt diese auf die Whitelist und meldet die Abweichung. Bis ein Server einmal gepusht hat, wird auf DNS A+AAAA zurückgegriffen, und das wird mitgeteilt.
Drei Ausgaben:
conf.d-Datei (geo + map) plus eine einzelne if ($ncsc_forbidden) { return 403; }-Zeile im vhost. Keine Notwendigkeit, den fastcgi-Block zu duplizieren, statische Dateien sind ebenfalls abgedeckt (admin.html ist eine), und /.well-known/acme-challenge/ bleibt offen, sodass die Zertifikatserneuerung nicht stillschweigend scheitern kann.<LocationMatch> mit einem negativen Lookahead plus ein <Location> für den Push-Endpunkt, sodass sich die beiden Abschnitte nicht überschneiden können und nichts von der Zusammenführungsreihenfolge von Apache abhängt. Alle Adressen einer Regel werden auf eine Require ip-Zeile gesetzt: Mehrere Zeilen innerhalb von <RequireAll> werden UND-verknüpft, was niemand erfüllen kann.Der Generator weigert sich, etwas auszugeben, wenn keine Administrationsadresse angegeben ist, warnt, wenn die eigene Adresse des Betreibers nicht abgedeckt ist, und warnt, wenn die Anfrage über einen Proxy kam (sowohl geo als auch Require ip lesen den Transport-Peer, sodass hinter einem Proxy jeder Client gleich aussieht). Der generierte ufw-Ausschnitt setzt die SSH-Regel an die erste Stelle, hält Port 80 für die HTTP-01-Herausforderung offen und beschreibt die IPv6-Falle: Im Gegensatz zu nginx, das eine nicht aufgeführte v6-Adresse ablehnt, filtert ufw v6 überhaupt nicht, es sei denn, IPV6=yes ist gesetzt – ein Dual-Stack-Host wäre sonst über IPv6 weit offen.
Bekannte Einschränkung, auf der Seite selbst angezeigt: Sobald die Regeln angewendet sind, entdeckt dieser Reiter nichts Neues. Ein abgelehnter Push wird vom Webserver bevor er PHP erreicht abgewiesen, sodass die aufgezeichnete Adresse die letzte ist, die durchgekommen ist – und immer noch als verifiziert gilt. Zwei Konsequenzen: Das Hinzufügen eines Push-Servers bedeutet, die Regeln neu zu generieren und erneut anzuwenden, oder sein erster Push wird abgelehnt; und wenn sich die Adresse einer Instanz ändert, ist die neue nur im Webserver-Access-Log lesbar (grep 'push-api.php' access.log | grep ' 403 '). Der Reiter zeigt daher das Datum der letzten Sichtung jeder beobachteten Adresse an und markiert sie, sobald sie älter als ein vollständig verpasster Push-Zyklus ist – die gleiche Schwelle wie der push_stale-Alarm, der denselben toten Winkel von der anderen Seite abdeckt.
Unterscheidung eines Filterproblems von einem anderen: Ein bloßer GET auf dem Push-Endpunkt trennt die Ebenen sauber, ohne Nebenwirkungen und ohne Token — führen Sie ihn von der betreffenden Maschine aus, da beurteilt wird, was die ausgehende Adresse dieser Maschine ist:```bash
curl -sS -o /dev/null -w '%{http_code}\n' https://your-monitor/push-api.php
| Antwort | Bedeutung |
|---|---|
| `403` | von der IP-Filterung blockiert |
| `401` | Filterung bestanden, Basic Auth antwortet — das Problem liegt woanders |
| `405` | Die Anfrage erreichte die Anwendung (GET ist dort keine akzeptierte Methode) |
| nichts / Timeout | Nicht die Filterung: Ein Filter antwortet, er verstummt nicht |
Wiederholen Sie den Vorgang mit `-u user:password`, um einen Zweifel bei einem `403` zu beseitigen: Wenn sich der Code nicht ändert, liegt es wirklich an der Filterung. Verifiziert sowohl auf nginx als auch auf Apache (auch mit aktiviertem `Require valid-user`), antwortet der Filter *vor* der Authentifizierung — und ein `403` von der Anwendung selbst enthält immer JSON im Body.
Die Snippet-Logik befindet sich in `lib/hardening-rules.php`, das rein ist und von `tests/run.php` abgedeckt wird: Die Snippets sind hier das Produkt, und ein falsches sperrt entweder den Betreiber aus oder hinterlässt ein Loch. Sowohl die nginx- als auch die Apache-Ausgabe wurden verhaltensmäßig verifiziert (echte Server, echte Quelladressen, einschließlich Path-Traversal-Versuchen aus der `push`-Klasse).
### Automatisierte Analyse (CI `security`-Stufe)
Abhängigkeitsscans (`npm/pnpm audit`, Snyk Open Source, Dependabot) sind hier ein No-Op: Es gibt keine `package.json` und keine `composer.json` — es gibt nichts zu scannen. Das Risiko liegt im benutzerdefinierten Code (~15k Zeilen PHP, ~6k JS) und in den Shell-Skripten, die **als root** auf überwachten Instanzen ausgeführt werden (`tools/*.sh`). Die Pipeline ist darauf ausgerichtet:
| Job | Tool | Blocking | Umfang |
|---|---|---|---|
| `secrets_scan` | gitleaks | yes | committierte Geheimnisse (Arbeitsverzeichnis) |
| `sast_semgrep` | semgrep (`p/php`, `p/javascript`, `p/owasp-top-ten`) | yes | SSRF, fehlende AuthZ/CSRF, XSS |
| `shellcheck` | shellcheck (`--severity=warning`) | yes | `tools/*.sh` — root auf Client-Hosts |
| `dockerfile_misconfig` | trivy misconfig | yes | `deploy/docker/` |
| `container_cve` | trivy image | no (`allow_failure`) | das Image, das `deploy/docker` baut, plus `nginx:alpine` |
| `ui_tests` | node (no deps) | yes | Escape-Invarianten von `lib/ui-common.js` (beide vergangenen XSS-Regressionen) |
| `phpmailer_freshness` | GitHub API | no (`allow_failure`) | vendored Pin vs. Upstream-Release |
| `deploy_selfcheck` | nc-selfcheck.sh | yes | das ausgelieferte nginx-Regelwerk (Deny-Regeln + Sicherheitsheader), aufgesetzt in einem Wegwerf-Container |
Alle blockierenden Jobs haben eine **Null-Findungs-Baseline**, sodass jede neue Warnung ein echtes Signal ist. Zwei bewusste Entscheidungen, dokumentiert inline in `.gitlab-ci.yml`:
- **`php.lang.security.injection.echoed-request` ist von semgrep ausgeschlossen**: es markiert jedes `echo json_encode()` als XSS, was hier jeder API-Endpunkt legitimerweise tut (JSON-Antworten, nicht HTML). Es war für 10 von 10 Funden beim ersten Durchlauf verantwortlich, alle falsch. Es zu behalten würde alle dazu bringen, den Job zu ignorieren.
- **Die beiden `allow_failure`-Jobs melden Upstream-Fakten** (eine CVE in `nginx:alpine` oder eine, deren Fix noch nicht den Alpine-Branch erreicht hat, eine neue PHPMailer-Version), die ein Merge Request nicht beheben kann. Rot-aber-toleriert ist das genaue Signal — „Zeit zum Neubauen/Auffrischen des Vendorings“ —, kein Grund, unabhängige Arbeit zu blockieren. `phpmailer_freshness` meldet eine unerreichbare oder ratenlimitierte GitHub-API als *Skip*, niemals als „veraltet“.
- **`container_cve` scannt das Image, das es baut, nicht den `FROM`-Tag.** Das Dockerfile härtet die Basis mit `apk --no-cache upgrade` (das offizielle PHP-Image hinkt den Alpine-Repos hinterher — es enthielt c-ares 1.34.6-r0, während 1.34.8-r0, das CVE-2026-33630 behebt, bereits veröffentlicht war). Das Scannen des Basis-Tags würde daher CVEs melden, die das ausgelieferte Image nicht mehr hat: ein permanent oranger Job, den niemand liest.
Allowlists sind bewusst eng gehalten: `.gitleaks.toml` entschuldigt **literale** Platzhalter-Strings, niemals ganze Dokumentationsdateien (das Allowlisten von `README.md` würde den Scan blenden, sobald ein echtes Geheimnis hineinkopiert wird) — daher muss ein neues Beispiel-Token in der Dokumentation dort hinzugefügt werden. `.trivyignore` enthält einen einzigen Eintrag, `DS-0002`, begründet in der Datei: Der php-fpm-Master muss als root starten, um seine Worker auf `www-data` (UID 82) herabzustufen.
### Überprüfung nach der Bereitstellung (`nc-selfcheck.sh`)
CI kann die *ausgelieferte* Konfiguration sperren (der `deploy_selfcheck`-Job oben stellt das nginx-Regelwerk in einem Container auf und testet es), kann aber nicht den Server überprüfen, auf den Sie tatsächlich bereitgestellt haben — anderer Host, Basic-Auth-Anmeldedaten, Dateisystemberechtigungen. `tools/nc-selfcheck.sh` schließt diese Lücke. Es ist ein eigenständiges, schreibgeschütztes Bash-Skript (gleiches Modell wie `nc-audit.sh`), das Sie nach jedem Deploy ausführen:```bash
# Black-box, no credentials: confirms Basic auth is enforced (401) and that
# sensitive files are blocked (cache/, servers.*, .git, config.php source).
bash tools/nc-selfcheck.sh https://monitoring.example.com
# + security headers behind Basic auth:
bash tools/nc-selfcheck.sh -u user:pass https://monitoring.example.com
# + filesystem checks (run ON the host): servers.json / config.php / CSRF-secret
# permissions, and a stray closing "?>" in config.php.
bash tools/nc-selfcheck.sh --webroot /var/www/ncstatuscheck https://monitoring.example.com
Es gibt einen Exit-Code ungleich Null bei jedem kritischen Fund (Quelltext-Leck, ungeschützte Geheimnisdatei, weltweit lesbarer Token-Speicher, fehlende Basic-Authentifizierung), sodass es als Tor für eine Bereitstellung dienen kann – binden Sie es als Nach-Schritt in Ihr Sync-/Bereitstellungsskript ein. WARN/INFO führen nie zu einem Fehlschlag des Durchlaufs.
// In config.php define('ENV', 'dev');
Im Entwicklungsmodus werden zusätzliche Informationen angezeigt (PHP-Version, Webserver).
### Server-Tests
Verwenden Sie die Administrationsoberfläche, um einen Server per URL hinzuzufügen. Der Server wird beim nächsten Datenabruf abgefragt.
### Debug-Protokolle
Überprüfen Sie die Protokolldateien in `cache/`:
- `monitor.log` — Allgemeine Anwendungsprotokolle
- `cron.log` — Vollständige Sammlungsskript-Protokolle (`cron-update.php`)
- `ping.log` — Leichte Auf/Ab-Probenprotokolle (`cron-ping.php`)
- `alerts.log` — Proaktive Alarmverteilung (Webhook/E-Mail), protokolliert niemals Webhook-Geheimnisse oder SMTP-Anmeldedaten
### Testsuite```bash
php tests/run.php # plain-PHP assertions, no framework — exit 0 = all green
Behandelt die reine Geschäftslogik (Version/App-Regeln, Warnungen, Uptime-Zustandsmaschine und Verfügbarkeit, Alert-Dedup/Re-Arm-Zustandsmaschine, E-Mail-Builder).
Eröffnen Sie ein neues Issue mit:
Dieses Projekt ist lizenziert unter GNU AGPL v3.
NcStatusCheck wird entwickelt von ézéo, einer digitalen Genossenschaft, die auf Open-Source-Lösungen spezialisiert ist.
Hilfe benötigt? Sehen Sie in den Issues nach oder kontaktieren Sie das ézéo Team.
| Abschnitt | Felder |
|---|
| Nextcloud-System | Version, Debug-Modus, lokaler/verteilter Memcache, File Locking, Speicherplatz |
| PHP | Version, memory_limit, upload_max_filesize, max_execution_time, FPM, OPcache |
| Webserver | Name + Version, HTTP-Protokoll |
| Datenbank | Typ, Version, Größe |
| Cache | Redis, APCu-Trefferquote |
| Aktive Benutzer | Letzte 5 Min, 1 Std, 24 Std, 7 Tage |
<slug>latest.ezeo.cooplatest_ezeo_coop<slug>.conf/etc/cron.d/ncstatuscheck-<slug>targets-<slug>.confncstatuscheck-push-<slug>.log…-<slug>.<md5>.lastNextcloud in Docker (offizielles Image, Compose, AIO): Vollständig unterstützt – das
Skript wird auf dem Host installiert (Root-Cron + Docker-Daemon-Zugriff), niemals im
Container, und occ läuft über docker exec:
OCC_CMD=docker exec -u www-data <container> php occ (AIO-Container: nextcloud-aio-nextcloud).
Der Admin-Skript-Generator hat eine Installationstyp-Voreinstellung, die dies vorausfüllt. Fügen Sie niemals
-t hinzu (kein TTY unter Cron); behalten Sie -u www-data bei (das offizielle Image verweigert occ als root).
Flottenbereitstellung / Updates: Da der Kern eine einzige identische Datei ist,
bedeutet das Aktualisieren der Logik auf vielen Servern = Ersetzen dieser einen Datei (das ↑-Flag markiert Server,
die eine ältere Version ausführen). Siehe deploy/ansible/ für ein einsatzbereites
Playbook (oder eine einfache scp-Schleife). Der Monitor bleibt passiv – er sendet niemals Code
an die Flotte; der Vertrauensanker ist Ihr eigener SSH-Zugriff, nicht der Monitor.
Migration von einer Pre-v4-Installation (monolithisches Pro-Instanz-Skript): Entfernen Sie das alte
/usr/local/bin/ncstatuscheck-push-<slug>.sh und /etc/cron.d/ncstatuscheck-<slug>,
bevor Sie den Kern + Konfiguration installieren (die targets-<slug>.conf wird unverändert
wiederverwendet), da Sie sonst doppelt pushen.
hash_equals()request_pushrequest_push_alltargets.conf würde sonst jeden Push stillschweigend an einen Dritten kopieren<>"'& befreit, zusätzlich zur Maskierung zum Renderntry/catch abfangen kann, der den Sammlungsdurchlauf mitten in der Schleife beenden und damit alle Warnungen für die gesamte Flotte zerstören würde