diff --git a/src/content/docs/whp/admin/data-drive-encryption.mdx b/src/content/docs/whp/admin/data-drive-encryption.mdx new file mode 100644 index 0000000..021f577 --- /dev/null +++ b/src/content/docs/whp/admin/data-drive-encryption.mdx @@ -0,0 +1,202 @@ +--- +title: Data-drive encryption (LUKS) +description: Optional LUKS2 encryption of the /docker data volume on new server installs. Encrypts customer data, databases, and container state at rest; adds a manual unlock step after every reboot. +sidebar: + order: 7 +--- + +import { Aside } from '@astrojs/starlight/components'; +import SuperAdmin from '~/content/partials/super-admin-callout.mdx'; +import Support from '~/content/partials/support-link.mdx'; + + + +WHP can encrypt the **`/docker` data volume** — where customer site files, +databases, container state, and SSL material live — using LUKS2 (the same +disk-encryption layer used by every mainstream Linux distribution). + +When enabled, anyone who walks off with the physical disk (or images it +offline) sees only ciphertext. The encryption key never lives on disk in +plaintext. + + + +## What changes if you enable it + +The trade-off is one extra manual step every time the server reboots. + +**At install time:** +- A strong passphrase (32 hex characters) is generated and **shown to you + once** in the install banner. You're responsible for saving it before + install completes — there is no recovery if it's lost. + +**On every reboot (planned or unplanned):** +- The `/docker` volume comes up **locked**. The regular WHP control panel + at `:8443` is offline until you unlock it. +- The host itself boots normally — SSH, networking, monitoring, etc. + remain reachable. +- You unlock via either: + - **Web:** browse to `https://:8444/`, sign in with the server's + `root` credentials, and paste the LUKS passphrase. The form redirects + you back to the regular panel after the volume mounts and services + come up (around 30 seconds end-to-end). + - **SSH:** run `/root/whp/scripts/whp-unlock-data-drive` and enter the + passphrase at the prompt. Same outcome. + +**While unlocked:** +- The server runs identically to a non-encrypted server. No performance + penalty noticeable for typical hosting workloads. + + + +## The security model in plain English + +LUKS protects you against **data at rest** being read by someone without +the passphrase. Specifically: + +- **Stolen or lost disk:** the device is unreadable without the passphrase. +- **Disk RMA / drive replacement:** you can return drives without secure + erase; the data on them is ciphertext. +- **Offline forensic imaging:** an attacker who can power off the server + and copy the disk gets ciphertext. + +It does **not** protect against: + +- **A live, running server being compromised** — once `/docker` is + unlocked, the data is plaintext in memory and accessible to anyone with + root on the host. (This is the same as any other Linux server.) +- **Lost passphrase** — there is no recovery key, no master override, no + vendor reset. Losing the passphrase means losing the data. + +If your threat model is "compliance / customer expectations around +data-at-rest encryption," LUKS covers it. If it's "attacker has live +shell on the server," LUKS does nothing additional — you need separate +controls (access policy, monitoring, segmentation). + +## The unlock surface in detail + +The unlock daemon (`whp-locked-unlock.service`) is a small standalone +HTTPS server that runs **independently** of the main control panel +(Apache + PHP-FPM). It exists for exactly one purpose: prompt for and +validate the LUKS passphrase, then hand off to the helper that opens the +volume and starts the customer-facing services. + +- **Port:** `8444` (separate from the regular panel on `:8443` / `:8080`) +- **TLS:** if your server has a real Let's Encrypt certificate for its + hostname (the usual case on AnHonestHost-managed installs), the daemon + uses that. If not, it uses the same self-signed cert that the regular + panel falls back to. +- **Authentication:** the server's root credentials via PAM (same login + as the regular control panel), **plus** the LUKS passphrase. Both must + be correct. +- **Rate limit:** five failed attempts per IP per five minutes triggers a + short lockout. You can unlock from another IP, from SSH, or wait for + the window to expire. +- **Auto-stop:** once the unlock succeeds, the daemon exits cleanly. It + comes back automatically on the next reboot. + +After the web unlock, the regular control panel at `:8443` becomes +reachable within ~30 seconds (the time it takes Docker, Apache, and the +boot orchestrator to start the customer containers). + +## Header backup — critical for recovery + +The LUKS2 header is a small region (~16 MB) at the start of the +encrypted device that holds the keyslot data. If that region gets +corrupted (bad sectors, partition table accident, careless `dd`), the +data is unrecoverable **even with the correct passphrase**. + +WHP keeps a header backup automatically: + +- **Initial backup** at `/etc/whp/luks-header.backup`, created during the + install. +- **Daily refresh** via cron — only writes a new file when the header + has actually changed (i.e. on passphrase rotation). +- **Rolling 30-day history** at `/var/lib/whp/luks-headers/`. +- **Off-host upload** if you've configured an rclone remote named + `whp-system-backup`. We strongly recommend setting this up so the + header isn't only on the same disk it's protecting. + +In a header-corruption scenario, restoring is a one-command operation +using the saved backup, then unlocking with your passphrase as normal. + +## Rotating the passphrase + +If you need to change the LUKS passphrase (staff rotation, suspected +compromise of the saved copy, etc.), do it in this order: + +1. **Add the new passphrase** as a second keyslot — the volume now + accepts either one. +2. **Verify the new passphrase works** with a non-destructive test. +3. **Remove the old passphrase** from its keyslot. + +The full command sequence is documented in the operator runbook on the +server itself (`/root/whp/docs/LUKS_RUNBOOK.md`). After any keyslot +change, the daily header backup picks up the new header SHA and uploads +a fresh copy on its next run. + +## Things to know before you commit to it + +- **Lost passphrase = lost data.** This is the single most important + thing to plan around. Treat the passphrase the way you'd treat a + payment-processor master key. +- **Every reboot needs someone awake.** Auto-restart watchdogs, kernel + updates that trigger a reboot, and power events all become events + that require manual intervention. If your team can't respond within + your acceptable downtime window, this isn't the right fit. +- **Server-side backups still matter.** Encryption protects against + data theft. It does not protect against data loss. Your customer + backup configuration and the LUKS header backup are independent + concerns — both need to be in place. +- **Boot drive is unencrypted.** The OS, the control panel itself, and + the LUKS configuration file all live on the unencrypted boot drive. + This is intentional — it lets the unlock UI come up and lets you SSH + in for recovery before `/docker` is available. + +## When LUKS is **not** the right choice + +- Servers where unattended reboots are operationally required (e.g. + automated kernel updates with reboot on a recurring schedule with no + human in the loop). +- Servers where the only "threat" is the existing AnHonestHost + operational controls — if your compliance posture doesn't ask for + data-at-rest encryption specifically, the operational overhead may + not be worth it. +- Existing servers with live customer data on them — wait for the + retrofit workflow rather than attempting a manual migration without + guidance. + +## Setting this up on a new server + +If you're spinning up a fresh server and want data-drive encryption, +mention it in the provisioning ticket and we'll configure it as part of +the install. We'll send you the generated passphrase through a secure +channel and confirm you have it stored before the server is handed over. + +For technically-inclined customers running WHP themselves, the install +flag is documented in the operator runbook that ships on every server at +`/root/whp/docs/LUKS_RUNBOOK.md`. + +## Related + +- [Server settings & services](/whp/admin/server-settings/) — restart + individual services after an unlock, view system info. +- [Backups](/whp/admin/backups/) — independent of LUKS; both should be + configured. +- [Admin overview](/whp/admin/overview/) — other super-admin features. + +## Still stuck? + + diff --git a/src/content/docs/whp/admin/overview.mdx b/src/content/docs/whp/admin/overview.mdx index 8231600..1aebbfe 100644 --- a/src/content/docs/whp/admin/overview.mdx +++ b/src/content/docs/whp/admin/overview.mdx @@ -52,6 +52,7 @@ When you sign in as a super admin, these sections appear in addition to the cust - **[AI Monitor, Issues & Ignore Rules](/whp/admin/site-monitoring/)** — the three pages that drive the Site Monitoring add-on. - **[Users & delegated access](/whp/admin/user-management/)** — create accounts, set account types, delegate access, and handle suspensions. - **[Backups](/whp/admin/backups/)** — configure the default backup target so customer auto-backups start running. Full-server backups are a separate, plan-dependent concern. +- **[Data-drive encryption (LUKS)](/whp/admin/data-drive-encryption/)** — optional at-rest encryption of the `/docker` data volume. Available only on new server installs; adds a manual unlock step after every reboot. ## Things to know before you change server-wide settings diff --git a/src/content/docs/whp/getting-started/what-is-containerized-hosting.mdx b/src/content/docs/whp/getting-started/what-is-containerized-hosting.mdx index ddaee48..4da78aa 100644 --- a/src/content/docs/whp/getting-started/what-is-containerized-hosting.mdx +++ b/src/content/docs/whp/getting-started/what-is-containerized-hosting.mdx @@ -41,7 +41,10 @@ A [Virtual Dedicated Server](https://anhonesthost.com/vds) is our VPS-class prod A VDS suits you when you want full admin control of the server — kernel-level tweaks, custom services, your own systemd units, or you simply prefer to manage the OS yourself. You get a real virtual machine with root access, and WHP still gives you the friendly panel on top. +A VDS also opens up server-wide options that don't apply to shared containers, like opt-in [data-drive encryption](/whp/admin/data-drive-encryption/) for compliance or peace-of-mind scenarios. + ## Related - [Add-ons overview](/whp/add-ons/overview/) - [Service hostnames](/whp/reference/service-hostnames/) +- [Data-drive encryption (LUKS)](/whp/admin/data-drive-encryption/) — optional, new-server-only