Server Tools: Fehlerbehebung
Fehlerbehebung für Server Tools: Meldungen im Wortlaut mit Ursache und Lösung für Start, Config, MySQL, VHosts, SSL, SSH-User und Logs sowie die bekannten Einschränkungen mit Workarounds.
Fehlerbehebung
Die Meldungen des Tools sind englisch und erscheinen mit [ERROR] oder [WARN] auf stderr. Details zu ausgeführten Aktionen stehen im Audit-Log (server-tools logs audit). ST_DEBUG=1 gibt zusätzliche [DEBUG]-Zeilen aus.
Start und Voraussetzungen
| Meldung | Ursache | Lösung |
|---|---|---|
/usr/local/bin/server-tools: Permission denied |
Die installierte Binary hat Rechte 700 | Mit sudo aufrufen |
This tool must be run as root. |
Der Befehl läuft ohne root | Mit sudo aufrufen. Nur --version, --help und --config gehen ohne |
Missing required commands: apache2ctl ... |
Eines der Programme apache2ctl (bzw. nginx), openssl, gzip, systemctl, realpath fehlt |
Paket installieren. Läuft Nginx, setze ST_WEBSERVER="nginx". Die Prüfung gilt für alle Befehle außer user, install und uninstall, auch wenn du nur db nutzt |
ERROR: Cannot find server-tools libraries |
Weder ../lib noch /usr/local/lib/server-tools enthalten die Libraries |
Erneut installieren |
install must be run from a source checkout ... |
install wurde aus der installierten Kopie gestartet |
Aus dem Git-Klon starten |
Unknown command: <x>. Use --help for usage. |
Befehl nicht bekannt | server-tools --help |
Unknown <command> action: <x> |
Aktion nicht bekannt | server-tools <command> --help |
Konfiguration
| Meldung | Ursache | Lösung |
|---|---|---|
Config file not owned by root |
Eigentümer ist nicht root | chown root /etc/server-tools/config |
Config file has unsafe permissions (644) |
Für "andere" ist ein Recht gesetzt | chmod 600 /etc/server-tools/config |
Config file is group-writable |
Die Gruppe darf schreiben | chmod 600 /etc/server-tools/config |
ST_WEBSERVER must be 'apache' or 'nginx' ... Resetting und ähnliche Warnungen |
Ungültiger Wert, das Tool nimmt den Standard | Wert in der Config korrigieren, siehe Konfiguration |
| Neue Option wirkt nicht | Die Datei aus der Vorlage wurde bei Updates nicht ersetzt | Option selbst in /etc/server-tools/config eintragen |
Datenbanken
| Meldung | Ursache | Lösung |
|---|---|---|
Database commands require a MySQL/MariaDB client ... |
Client oder Dump-Tool fehlt | apt-get install mariadb-client |
MySQL config not found: /root/.my.cnf |
Options-Datei fehlt | Anlegen, siehe Installation |
Cannot connect to MySQL. Check credentials in ... |
Zugangsdaten falsch oder Server läuft nicht | Mit mysql --defaults-file=/root/.my.cnf -e "SELECT 1" testen |
MySQL config has insecure permissions |
Rechte weder 600 noch 400 | chmod 600 /root/.my.cnf |
Database '<x>' already exists |
Name vergeben | Anderen Namen wählen |
Database '<x>' does not exist. Create it first. |
Restore in eine nicht vorhandene Datenbank | Zuerst anlegen, dann db restore |
Export failed bei db export |
Das Zielverzeichnis existiert nicht | Verzeichnis anlegen, zum Beispiel mkdir -m 700 /root/db-backups, oder db backup einmal ausführen |
Unsupported file format ... |
Endung bei Restore oder Import nicht erlaubt | Erlaubt sind .sql, .sql.gz und .sql.zip |
Unsupported output format: ... (use .sql or .sql.gz) |
Endung bei db export nicht erlaubt |
Erlaubt sind .sql und .sql.gz |
Virtual Hosts
| Meldung | Ursache | Lösung |
|---|---|---|
PHP 8.3 FPM is not installed or not running |
Socket /run/php/php8.3-fpm.sock fehlt |
FPM-Paket installieren und Service starten |
Invalid PHP version: ... |
Version nicht in der festen Liste 7.4 bis 8.4 | Eine dieser Versionen verwenden |
Path not under allowed roots (...) |
--docroot liegt außerhalb von ST_ALLOWED_DOCROOT_PATHS |
Pfad ändern oder die Variable erweitern |
Backend URL is required for proxy vhosts (--backend) |
--type proxy ohne --backend |
--backend http://host:port angeben |
Apache configuration test failed! mit eingerücktem configtest-Text |
Die erzeugte oder eine andere Konfiguration ist fehlerhaft | Ausgabe lesen, apache2ctl configtest ausführen und beheben |
Nginx configuration test failed! |
wie oben für Nginx | nginx -t ausführen und beheben |
Webserver reload failed - rolling back... |
Reload nach vhost create schlug fehl |
Site ist deaktiviert, Dateien bleiben. Fehler beheben und erneut anlegen |
Domain '<d>' has assigned user '<u>'. |
Die Domain hat einen SSH-User | user delete --username <u>, danach vhost delete |
Config already exists: ... |
vhost redirect für eine Domain, die schon eine Konfiguration hat |
Andere Domain wählen oder die Datei entfernen |
SSL
| Meldung | Ursache | Lösung |
|---|---|---|
SSL setup currently only supports Apache ... |
ST_WEBSERVER=nginx |
ssl create, ssl delete und ssl renew werden für Nginx nicht unterstützt. ssl wildcard läuft auch mit Nginx |
Virtual host for '<d>' does not exist. Create it first. |
Kein Apache-VHost <d>.conf |
vhost create zuerst |
Failed to create SSL certificate for '<d>' |
certbot ist fehlgeschlagen (DNS, Port 80, Rate-Limit) | Ausgabe von certbot darüber lesen, /var/log/letsencrypt/ prüfen |
DNS provider not configured. Set ST_DNS_PROVIDER in config. |
Weder --provider noch Config-Wert |
--provider angeben |
DNS credentials file not found: ... |
API-Datei fehlt | Datei anlegen, chmod 600 |
Unsupported DNS provider: ... |
Provider nicht in der Liste | cloudflare, digitalocean, route53, google, linode oder ovh |
SSH-User
| Meldung | Ursache | Lösung |
|---|---|---|
Domain directory does not exist: /var/www/<d> |
VHost nie angelegt oder anderes Verzeichnis | Zuerst vhost create |
ACL tools not installed. Install with: apt install acl |
setfacl/getfacl fehlen |
apt install acl |
Filesystem does not support ACLs. ... |
Dateisystem ohne ACL-Unterstützung | Mit der Option acl mounten oder ext4/xfs verwenden |
Domain '<d>' already has user '<u>'. One user per domain. |
Pro Domain ist ein User erlaubt | Vorhandenen User verwenden |
Reserved system username: ... |
Name gehört einem Account mit UID unter 1000 | Anderen Namen wählen |
ACL setup failed, rolling back... |
html oder logs fehlt oder setfacl schlug fehl |
Verzeichnisse unter /var/www/<d> anlegen, erneut versuchen |
Password must not contain ':' |
Doppelpunkt im Passwort | Anderes Passwort |
Logs und Firewall
| Meldung | Ursache | Lösung |
|---|---|---|
Log file not found: <pfad> |
Datei existiert nicht | ST_APACHE_LOG_DIR, ST_NGINX_LOG_DIR oder ST_MYSQL_LOG_FILE prüfen |
No error log found for domain: <d> |
Weder /var/www/<d>/logs/error.log noch <Log-Verzeichnis>/<d>-error.log |
Domain und ST_WEBSERVER prüfen |
UFW is not installed |
ufw fehlt |
apt install ufw |
Fail2Ban is not installed |
fail2ban-client fehlt |
apt install fail2ban |
Bekannte Einschränkungen
| Verhalten | Workaround |
|---|---|
db backup-all als CLI-Befehl sichert nur die erste Datenbank und endet mit Exit-Code 1 |
Menü "Backup all databases" verwenden oder db backup --name <db> je Datenbank |
cron list als CLI-Befehl zeigt nur die erste Datei und endet mit Exit-Code 1 |
Menü "List cron jobs" oder cat /etc/cron.d/* und crontab -l |
vhost create überschreibt mit --yes einen bestehenden VHost und dessen index.php |
Vorher mit vhost list oder vhost info prüfen |
vhost delete --yes löscht bei VHosts mit DocumentRoot das Verzeichnis /var/www/<domain>. Proxy-VHosts haben kein DocumentRoot, dort wird nichts gelöscht |
Ohne --yes arbeiten und die zweite Rückfrage mit "n" beantworten |
vhost php ändert nur <domain>.conf, nicht die -le-ssl.conf |
Die -le-ssl.conf von Hand anpassen und Apache neu laden |
--preserve-host off schaltet ProxyPreserveHost nicht ab |
--preserve-host false verwenden |
--quiet hat keine Wirkung |
Ausgabe per 2>/dev/null verwerfen |
ST_BACKUP_RETENTION_DAYS löscht keine alten Backups |
Alte Dateien in ST_BACKUP_DIR selbst entfernen |
user set-password ohne --password zeigt das erzeugte Passwort nur auf einem Terminal |
Auf einem Terminal ausführen oder --password übergeben |
db create mit einem vorhandenen User ändert dessen Passwort nicht |
db create-for-user verwenden |
user create prüft die Apache-Konfiguration auch bei ST_WEBSERVER=nginx |
Die Rückfrage mit "y" bestätigen |
user info zeigt bei einem User ohne Schlüssel 0 doppelt |
Reine Anzeige, keine Auswirkung |