Server Tools: Troubleshooting
Troubleshooting Server Tools: messages verbatim with cause and solution for startup, config, MySQL, VHosts, SSL, SSH users and logs, plus the known limitations with workarounds.
Troubleshooting
The messages of the tool are in English and appear with [ERROR] or [WARN] on stderr. Details of executed actions are in the audit log (server-tools logs audit). ST_DEBUG=1 prints additional [DEBUG] lines.
Startup and prerequisites
| Message | Cause | Solution |
|---|---|---|
/usr/local/bin/server-tools: Permission denied |
The installed binary has mode 700 | Call it with sudo |
This tool must be run as root. |
The command runs without root | Call it with sudo. Only --version, --help and --config work without |
Missing required commands: apache2ctl ... |
One of the programs apache2ctl (or nginx), openssl, gzip, systemctl, realpath is missing |
Install the package. If Nginx is running, set ST_WEBSERVER="nginx". The check applies to all commands except user, install and uninstall, even if you only use db |
ERROR: Cannot find server-tools libraries |
Neither ../lib nor /usr/local/lib/server-tools contain the libraries |
Install again |
install must be run from a source checkout ... |
install was started from the installed copy |
Start it from the Git clone |
Unknown command: <x>. Use --help for usage. |
Command not known | server-tools --help |
Unknown <command> action: <x> |
Action not known | server-tools <command> --help |
Configuration
| Message | Cause | Solution |
|---|---|---|
Config file not owned by root |
Owner is not root | chown root /etc/server-tools/config |
Config file has unsafe permissions (644) |
A permission is set for "others" | chmod 600 /etc/server-tools/config |
Config file is group-writable |
The group may write | chmod 600 /etc/server-tools/config |
ST_WEBSERVER must be 'apache' or 'nginx' ... Resetting and similar warnings |
Invalid value, the tool uses the default | Correct the value in the config, see Configuration |
| New option has no effect | The file from the template was not replaced on updates | Add the option to /etc/server-tools/config yourself |
Databases
| Message | Cause | Solution |
|---|---|---|
Database commands require a MySQL/MariaDB client ... |
Client or dump tool is missing | apt-get install mariadb-client |
MySQL config not found: /root/.my.cnf |
Options file is missing | Create it, see Installation |
Cannot connect to MySQL. Check credentials in ... |
Credentials wrong or server not running | Test with mysql --defaults-file=/root/.my.cnf -e "SELECT 1" |
MySQL config has insecure permissions |
Mode is neither 600 nor 400 | chmod 600 /root/.my.cnf |
Database '<x>' already exists |
Name taken | Choose another name |
Database '<x>' does not exist. Create it first. |
Restore into a database that does not exist | Create it first, then db restore |
Export failed on db export |
The target directory does not exist | Create the directory, for example mkdir -m 700 /root/db-backups, or run db backup once |
Unsupported file format ... |
Extension not allowed for restore or import | Allowed are .sql, .sql.gz and .sql.zip |
Unsupported output format: ... (use .sql or .sql.gz) |
Extension not allowed for db export |
Allowed are .sql and .sql.gz |
Virtual hosts
| Message | Cause | Solution |
|---|---|---|
PHP 8.3 FPM is not installed or not running |
Socket /run/php/php8.3-fpm.sock is missing |
Install the FPM package and start the service |
Invalid PHP version: ... |
Version not in the fixed list 7.4 to 8.4 | Use one of these versions |
Path not under allowed roots (...) |
--docroot is outside ST_ALLOWED_DOCROOT_PATHS |
Change the path or extend the variable |
Backend URL is required for proxy vhosts (--backend) |
--type proxy without --backend |
Specify --backend http://host:port |
Apache configuration test failed! with indented configtest text |
The generated or another configuration is faulty | Read the output, run apache2ctl configtest and fix it |
Nginx configuration test failed! |
as above for Nginx | Run nginx -t and fix it |
Webserver reload failed - rolling back... |
The reload after vhost create failed |
The site is disabled, files remain. Fix the error and create it again |
Domain '<d>' has assigned user '<u>'. |
The domain has an SSH user | user delete --username <u>, then vhost delete |
Config already exists: ... |
vhost redirect for a domain that already has a configuration |
Choose another domain or remove the file |
SSL
| Message | Cause | Solution |
|---|---|---|
SSL setup currently only supports Apache ... |
ST_WEBSERVER=nginx |
ssl create, ssl delete and ssl renew are not supported for Nginx. ssl wildcard also runs with Nginx |
Virtual host for '<d>' does not exist. Create it first. |
No Apache VHost <d>.conf |
vhost create first |
Failed to create SSL certificate for '<d>' |
certbot failed (DNS, port 80, rate limit) | Read the certbot output above it, check /var/log/letsencrypt/ |
DNS provider not configured. Set ST_DNS_PROVIDER in config. |
Neither --provider nor config value |
Specify --provider |
DNS credentials file not found: ... |
API file is missing | Create the file, chmod 600 |
Unsupported DNS provider: ... |
Provider not in the list | cloudflare, digitalocean, route53, google, linode or ovh |
SSH users
| Message | Cause | Solution |
|---|---|---|
Domain directory does not exist: /var/www/<d> |
VHost never created or different directory | vhost create first |
ACL tools not installed. Install with: apt install acl |
setfacl/getfacl are missing |
apt install acl |
Filesystem does not support ACLs. ... |
Filesystem without ACL support | Mount with the option acl or use ext4/xfs |
Domain '<d>' already has user '<u>'. One user per domain. |
One user per domain is allowed | Use the existing user |
Reserved system username: ... |
Name belongs to an account with a UID below 1000 | Choose another name |
ACL setup failed, rolling back... |
html or logs is missing or setfacl failed |
Create the directories under /var/www/<d>, try again |
Password must not contain ':' |
Colon in the password | Use another password |
Logs and firewall
| Message | Cause | Solution |
|---|---|---|
Log file not found: <path> |
File does not exist | Check ST_APACHE_LOG_DIR, ST_NGINX_LOG_DIR or ST_MYSQL_LOG_FILE |
No error log found for domain: <d> |
Neither /var/www/<d>/logs/error.log nor <log directory>/<d>-error.log |
Check the domain and ST_WEBSERVER |
UFW is not installed |
ufw is missing |
apt install ufw |
Fail2Ban is not installed |
fail2ban-client is missing |
apt install fail2ban |
Known limitations
| Behavior | Workaround |
|---|---|
db backup-all as a CLI command backs up only the first database and ends with exit code 1 |
Use the menu "Backup all databases" or db backup --name <db> per database |
cron list as a CLI command shows only the first file and ends with exit code 1 |
Menu "List cron jobs" or cat /etc/cron.d/* and crontab -l |
vhost create with --yes overwrites an existing VHost and its index.php |
Check beforehand with vhost list or vhost info |
vhost delete --yes deletes /var/www/<domain> for VHosts with a DocumentRoot. Proxy VHosts have no DocumentRoot, nothing is deleted for them |
Work without --yes and answer the second prompt with "n" |
vhost php only changes <domain>.conf, not the -le-ssl.conf |
Adjust the -le-ssl.conf by hand and reload Apache |
--preserve-host off does not turn ProxyPreserveHost off |
Use --preserve-host false |
--quiet has no effect |
Discard the output with 2>/dev/null |
ST_BACKUP_RETENTION_DAYS does not delete old backups |
Remove old files in ST_BACKUP_DIR yourself |
user set-password without --password shows the generated password only on a terminal |
Run it on a terminal or pass --password |
db create with an existing user does not change its password |
Use db create-for-user |
user create checks the Apache configuration even with ST_WEBSERVER=nginx |
Confirm the prompt with "y" |
user info shows 0 twice for a user without keys |
Display only, no effect |