shadowdaoandClaude Opus 4.7
6ee2cf13b0
Build and deploy / deploy (push) Successful in 23s
The WHP panel sends Strict-Transport-Security max-age=31536000 includeSubDomains on every response (correct for prod). When a server is rebuilt, the regenerated self-signed cert no longer matches what the admin's browser cached as HSTS-valid, and there is no clickable 'proceed unsafely' escape — the admin is locked out of their own panel by hostname. Add a Caution Aside under Network & SSL describing the symptom, the two-browser HSTS confirmation pattern, and the three recovery paths (IP-direct + LE issuance, browser HSTS clear, real cert preserved across rebuilds). Frames LE issuance as a first-day operation, not an incident response. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
139 lines
9.2 KiB
Plaintext
139 lines
9.2 KiB
Plaintext
---
|
||
title: Server settings & services
|
||
description: Restart services, configure mail server, manage DNS / nameservers, HAProxy + system SSL certificates, and integration API keys.
|
||
sidebar:
|
||
order: 2
|
||
---
|
||
|
||
import { Aside } from '@astrojs/starlight/components';
|
||
import SuperAdmin from '~/content/partials/super-admin-callout.mdx';
|
||
import AdminSignIn from '~/content/partials/admin-signin.mdx';
|
||
import Support from '~/content/partials/support-link.mdx';
|
||
|
||
<SuperAdmin />
|
||
|
||
The **Server Settings** page lives in the admin sidebar and has six tabs along the left rail. Each tab is a different surface area of the server you can inspect or change.
|
||
|
||
|
||
|
||
## Sign in as super admin
|
||
|
||
<AdminSignIn />
|
||
|
||
## The six tabs
|
||
|
||
### System
|
||
|
||
Read-only system summary plus two simple change controls:
|
||
|
||
- **System Information** — Hostname, Operating System, Kernel, Timezone, Uptime, Load Average, Disk Usage, Memory Usage.
|
||
- **Hostname Settings** — change the server's FQDN. Restart the relevant services after a hostname change.
|
||
- **Timezone Settings** — change the system timezone (affects cron timing, backup schedules, log timestamps).
|
||
|
||
<Aside type="caution">
|
||
Changing the hostname affects the certificates and DNS records that reference it. Plan for the related re-issuance and DNS propagation before changing it on a live server.
|
||
</Aside>
|
||
|
||
### Services
|
||
|
||
Service status and restart controls.
|
||
|
||
- **Service Status** — health pills for the host-side services:
|
||
- **Apache** and **PHP-FPM** on the host serve the **WHP control panel itself**, not customer sites. Customer sites run inside their own per-site containers, separate from these host services.
|
||
- **Docker** — the host's Docker daemon. If this is down, no customer container will start.
|
||
- **ProFTPD** — host FTP service (used by FTP-enabled customer accounts).
|
||
- **Backup Upload** — the host-side uploader that streams backups to your configured backup targets.
|
||
- **Restart Services** — checkboxes per service plus **Restart Selected Services**.
|
||
- **Docker Container Management** — status of the core platform containers (Mysql, Haproxy manager, Memcache, Postgresql) and a per-container **Execute Operation** picker (e.g. restart a single container).
|
||
|
||
<Aside type="caution">
|
||
Restarting host Apache or PHP-FPM kicks the **control panel** offline briefly — customers can't sign in to WHP for a few seconds. It does **not** affect customer sites (those are in their own containers). For MySQL, in-flight transactions in the MySQL container roll back. Pick a quiet window when you can.
|
||
</Aside>
|
||
|
||
### Mail
|
||
|
||
Two panels:
|
||
|
||
- **Mail Server** — set the **Mail Server Hostname** (used for MX records on new domains and as the IMAP host for archival). Configure the Mail Server API (URL, Username, Password) that WHP uses to provision mailboxes. Toggle **Enable Mailserver API Debug Logging** when troubleshooting; it writes mailserver API requests/responses to the PHP error log.
|
||
- **Outbound Email (SMTP)** — configure SMTP for outbound system alerts and customer AI Monitor notifications. Toggle **Enable Outbound Email** and provide the relay's credentials.
|
||
|
||
### DNS
|
||
|
||
Two panels:
|
||
|
||
- **WHP Nameserver Configuration** — set the primary and secondary nameserver hostnames and IPs. These are baked into every customer's DNS zone, so changing them affects every domain you host.
|
||
- **Network DNS Settings** — set the upstream resolvers the server uses (defaults to Cloudflare `1.1.1.1` and Google `8.8.8.8`).
|
||
- **DNS Configuration Settings** — default TTL for new DNS records (60–86400 seconds).
|
||
|
||
<Aside type="caution">
|
||
Changing nameserver hostnames or IPs invalidates the zone delegation for every customer domain pointed at the old values. Migrate slowly; expect lag in the order of TTL × propagation window.
|
||
</Aside>
|
||
|
||
### Network & SSL
|
||
|
||
Operational controls for HAProxy and system-service certs:
|
||
|
||
- **HAProxy Configuration Management** — **Regenerate** (rebuild config for every active site), **Reload** (apply config without restart), **Health Check** (probe HAProxy).
|
||
- **HAProxy API Key** — Bearer token used to authenticate against the HAProxy Manager API. After rotating, restart the HAProxy container.
|
||
- **System Service SSL Certificates** — request a Let's Encrypt cert for system-level services like the WHP panel itself and FTP, by picking the service and the domain name.
|
||
|
||
<Aside type="caution" title="Panel SSL + HSTS — VM rebuild and cert change gotcha">
|
||
|
||
The WHP panel always sends `Strict-Transport-Security: max-age=31536000; includeSubDomains` on every HTTPS response. That header is part of the panel's defence-in-depth — once a browser has visited the panel over HTTPS, it will refuse to fall back to HTTP and will refuse to accept an untrusted certificate (no clickable "proceed anyway" escape).
|
||
|
||
**When this bites you:** any time the panel's certificate fingerprint changes for the **same hostname**. Most common cause: rebuilding the VM. A fresh `setup.sh` run regenerates the self-signed `/etc/pki/tls/certs/localhost.crt`. Your browser still has the year-long HSTS rule cached from the previous VM, so it refuses to connect to the new cert. Both Chrome and Firefox enforce HSTS at the browser level.
|
||
|
||
**Recovery options for the admin who's locked out of their own panel:**
|
||
|
||
1. **Use the IP directly instead of the hostname.** HSTS is scoped to host names, not IP addresses. Hit `http://<server-ip>:8080/` or `https://<server-ip>:8443/`, log in, then go straight to **Network & SSL → System Service SSL Certificates** and issue a real Let's Encrypt cert for the panel's hostname. Reload the page and the hostname URL works again.
|
||
2. **Clear the HSTS rule in your browser.**
|
||
- **Chrome / Edge:** `chrome://net-internals/#hsts` → *Delete domain security policies* → enter the panel hostname → *Delete*.
|
||
- **Firefox:** start a private window for the panel hostname, OR close Firefox, open `<profile>/SiteSecurityServiceState.txt`, and remove the line beginning with the panel hostname.
|
||
3. **Issue a real Let's Encrypt cert before the next rebuild.** Once `whp02.example.com` has a real cert that survives rebuilds (e.g., the LE private key is preserved across rebuilds, or the cert is re-issued as part of post-install automation), the HSTS rule has nothing to argue with.
|
||
|
||
Issuing a Let's Encrypt cert for the panel hostname is a first-day operation for every new server, and it's how you avoid having to recover from this scenario on rebuild #2.
|
||
</Aside>
|
||
|
||
### Security
|
||
|
||
API keys for **external integrations** like WHMCS. Not customer-facing.
|
||
|
||
- **Create New API Key** — Key Name, Rate Limit (requests per hour), Permissions (User Management, Resource Management, SSO Access, System Statistics, AI Monitor Management), an optional IP whitelist, and Notes.
|
||
- **Existing API Keys** — list of issued keys with their permissions and rate limit. Revoke by removing the row.
|
||
|
||
## Server-wide configuration files
|
||
|
||
The host runs the WHP control panel and orchestrates customer containers. Most customer-affecting configuration lives **inside** containers, not on the host. A short map:
|
||
|
||
- **Control-panel Apache:** `/etc/httpd/conf.d/` on the host configures the WHP panel's own Apache. Editing here changes how the panel serves; it doesn't change how customer sites serve.
|
||
- **Control-panel PHP-FPM:** `/etc/php-fpm.d/` on the host configures the panel's PHP. Same scope.
|
||
- **MySQL:** the MySQL instance runs as a container. Files under `/etc/my.cnf.d/` on the host are surfaced to customer database connections — they're effectively client-facing settings, not host settings.
|
||
- **HAProxy:** runs as a container with its own volume. Reload via the **Network & SSL** tab; don't hand-edit files in the container.
|
||
|
||
### Customer-side container customisation
|
||
|
||
If a customer needs a non-standard runtime, library, or service inside their site's container — that's done by **building a custom Docker image** and adding it as a container type option in WHP, not by editing host-level config.
|
||
|
||
The pattern is documented in our cloud-container repos. See <a href="https://repo.anhonesthost.net/cloud-hosting-platform/">repo.anhonesthost.net/cloud-hosting-platform/</a> for the cloud-apache-container and cloud-node-container examples — they show the layout, build, and how to publish an image so it appears in the **Container Type** dropdown on the Sites page.
|
||
|
||
<Aside type="tip">
|
||
Cloud container images are a one-time setup per stack you want to support. Once published, every site using that container type benefits automatically — no per-site shell access required.
|
||
</Aside>
|
||
|
||
## Troubleshooting
|
||
|
||
**A service won't restart.** Check `journalctl -u <service>` (for systemd-managed services) or `docker logs <container>` (for containerized ones). The most common cause is a syntax error in a config file you just edited.
|
||
|
||
**Edits to a generated vhost keep disappearing.** That file is generated. Put your customisation in a per-app drop-in under `/etc/httpd/conf.d/`, or open a ticket about adding a stable include hook.
|
||
|
||
**Mailserver API debug log too noisy.** Toggle **Enable Mailserver API Debug Logging** off on the **Mail** tab once you've finished diagnosing.
|
||
|
||
## Related
|
||
|
||
- [Coraza WAF rules](/whp/admin/coraza-waf/)
|
||
- [Users & delegated access](/whp/admin/user-management/)
|
||
|
||
## Still stuck?
|
||
|
||
<Support />
|