Installation Guide

Updated Nov 18, 2026 Markdown

System Requirements

Processor Architecture

A 64-bit x86 server (x86_64 / amd64). ARM64 (aarch64) servers are not supported in the 1.0 line: the agent's compiled modules are built for x86_64 only. The installer checks the architecture when it starts and stops on any other, before it installs anything — see Supported OS.

Supported Operating Systems

WHost supports a narrow, deliberately modern OS matrix. Any other release is refused by the installer when it starts, before it installs anything — see Supported OS for the full rationale.

OS Version Status
Ubuntu 24.04 LTS (Noble) Fully Supported
Ubuntu 22.04 LTS (Jammy) Fully Supported — Python 3.12 from the deadsnakes PPA; the nginx ModSecurity connector is compiled from verified source
Debian 12 (Bookworm) Not installable in the 1.0 line — no Python 3.12 package; the installer refuses it. Returns with the multi-ABI build
AlmaLinux 9 Fully Supported
Rocky Linux 9 Fully Supported
CentOS Stream 9 Fully Supported
Validation

The installer has been run end to end on clean servers with Ubuntu 24.04, Ubuntu 22.04 and AlmaLinux 9.8. The fixes those runs led to (agent/requirements.txt, Python 3.12 provisioning, the fail2ban log file, pinned digests and bundled signing keys for the downloads that are compiled into the web server, services restarted with the configuration the installer writes) are part of the installer the published repository carries. Rocky Linux 9 and CentOS Stream 9 take the same installer path as AlmaLinux 9; on all three the installer switches SELinux from Enforcing to Permissive — see SELinux on the RHEL family. Debian 12 is not installable in this release — see Agent Python runtime in the supported-OS page.

Not supported

every other release — among them Debian 11 and 13, the version 8 and 10 releases of AlmaLinux, Rocky Linux and CentOS Stream, Red Hat Enterprise Linux itself, and every Ubuntu release other than 22.04 and 24.04. The installer stops with an error that names the supported releases.

Minimum Hardware

During the beta every supported system was installed and tested on servers of this size; smaller servers have not been tested.

  • CPU: 2 vCPU
  • RAM: 4 GB
  • Disk: 40 GB (the operating system plus WHost took 8.4–11 GB right after installation)
  • Network: Static IP address

For production, plan for more: 4+ vCPU, 8+ GB RAM and SSD storage sized to the accounts you host.

Prerequisites

  • Fresh OS installation (no existing web server, database, or mail server)
  • Root access (sudo or root user)
  • Internet connectivity for package downloads
  • git, to fetch the installation repository (the installer installs the rest of its tools itself)
  • A fully qualified host name for the server (for example srv1.example.com), either already set on the system or passed with --hostname. Cloud images usually boot with a single-label name such as ubuntu-4gb-hel1-3; the installer stops on such a name before it installs anything (see Host name)

Quick Installation

1. Install git. Fresh AlmaLinux, Rocky Linux and CentOS Stream images ship without it (git --version prints a version where it is already there). Run the one command for your system.

AlmaLinux, Rocky Linux, CentOS Stream:

shell
dnf install -y git

Ubuntu:

shell
apt-get install -y git

2. Download and run the installer.

shell
cd /tmp
git clone https://wisecp.com/files/whost/whost.git
cd whost/installer
bash install.sh --hostname=srv1.example.com

--hostname can be left out when hostname -f already prints a fully qualified name.

The installer will automatically:

  • Detect your operating system and processor architecture
  • Set the server's host name (see Host name)
  • Install and configure all required services
  • Generate API credentials and admin password
  • Download the web panel for this release and verify its signature
  • Start the WHost Agent

Verified Downloads

Everything the installer compiles into the web server or loads as a rule set is fetched over TLS and checked against a detached signature before use, with the upstream keys shipped in installer/lib/ (nginx-release-keys.pub, owasp-modsecurity-signing-key.pub, owasp-crs-signing-key.pub). The ModSecurity-nginx connector and the OWASP Core Rule Set also carry a pinned SHA-256. The nginx source archive — needed only where the distribution ships no ModSecurity module package, such as Ubuntu 22.04 — carries a pinned SHA-256 for the nginx releases the installer lists (1.18.0, 1.22.1, 1.24.0) and is checked by its signature alone for any other release. A connector or nginx source that fails a check is not built: the module is left out and the installer says so in its output. A rule set that fails its check stops the installation.

Mirror of the pinned files. Every upstream file whose SHA-256 the installer pins — the Core Rule Set and the ModSecurity-nginx connector with their signatures, the nginx sources of the listed releases with theirs, Roundcube and phpMyAdmin — is also kept on the WHost download site, under the upstream address's host and path (https://github.com/<path> is https://wisecp.com/files/whost/upstream/github.com/<path>). The installer asks there first and keeps the copy only when it passes the same check (pinned SHA-256, and the signature from the same place where one is checked); a file the mirror does not have, or a copy that fails the check, is downloaded from its upstream host as before, so an outage of GitHub or another upstream host does not stop the installation and the mirror cannot change what is installed. Each host is tried up to five times on a time-out, a refused connection or a 408 / 429 / 5xx answer. The output names the mirror when a file came from it (… taken from the WHost mirror) and warns when it moved on to the upstream host. An nginx source of a release the installer does not list is always downloaded from nginx.org. The agent asks the same mirror first when it brings an installed Roundcube to the release a newer WHost pins (update-flow.md). WHOST_UPSTREAM_MIRROR points the installer at another mirror with the same layout; an empty value turns the mirror off:

shell
WHOST_UPSTREAM_MIRROR= bash install.sh

The ionCube Loader, which every PHP process loads, is taken as one named release (15.5.1) from ionCube's download server and unpacked only when its archive matches the SHA-256 the installer pins for that release (one digest per processor architecture; WHost itself installs on x86_64 only, see Processor Architecture); an archive that fails the check, or a download that fails, stops the installation.

Panel Archive

The web panel is published as a separate signed archive, whost-panel-<version>.tar.gz, beside the repository. During the frontend step the installer downloads it together with its .asc signature and .sha256 file, checks the release signature against the public key shipped in installer/lib/whost-release.pub and the SHA-256 when the .sha256 file is present, and refuses to unpack an archive that has no signature or fails a check.

Two variables change where the archive comes from:

WHOST_PANEL_URLDownload from another location, such as a mirror. The .asc file must be published beside the archive there as well; a .sha256 file is checked when it is there.
WHOST_PANEL_ARCHIVEUse a local copy instead of downloading, for servers without outbound access. Keep the .asc file (and optionally the .sha256) next to it; the same checks apply. When both variables are set, the local copy is used.
shell
WHOST_PANEL_ARCHIVE=/root/whost-panel-VERSION.tar.gz bash install.sh

Replace VERSION with the release you are installing; bash install.sh --help prints it on its first line.

If the archive cannot be fetched or does not verify, the installer leaves the panel out and says so in its output (Panel archive could not be fetched or verified - the panel is NOT installed, followed by the file name it expects). The closing check then reports the missing panel page, and the run ends with an error instead of the completion screen. Provide the archive and run bash install.sh again; the download is skipped once the panel is in place.


Custom Installation

Command-Line Options

shell
bash install.sh [OPTIONS]
Option Description Default
--webserver=TYPE Web server: nginx_apache or nginx (see below) nginx_apache
--php-versions=LIST Comma-separated PHP versions 8.2,8.3,8.4
--php-default=VER Default PHP version 8.4
--hostname=FQDN Server hostname, fully qualified; set as the system host name, and also the subject of the self-signed certificate and the base of the defaults below. See Host name the system's name (hostname -f); required when that is not fully qualified
--nameservers=NS1,NS2 Nameservers written into new DNS zones ns1.<hostname>,ns2.<hostname>
--mail-hostname=HOST Mail server hostname mail.<hostname>
--ssl-email=EMAIL Email address for Let's Encrypt notifications not set
--timezone=TZ Server timezone, e.g. Europe/Istanbul auto-detected, UTC if unknown
--no-dns Skip PowerDNS installation DNS enabled
--no-mail Skip Postfix/Dovecot installation (Roundcube and Rspamd are skipped with it) Mail enabled
--no-ftp Skip Pure-FTPd installation FTP enabled
--no-firewall Skip firewall configuration Firewall enabled
--no-fail2ban Skip Fail2Ban installation Fail2Ban enabled
--no-modsecurity Skip ModSecurity (OWASP WAF) installation ModSecurity installed in detection_only (logs, never blocks)
--no-reboot Do not restart the server after the install; when the OS update or disk quota on an XFS root needs a restart, the result says so and you restart it yourself. See OS update and restart the server restarts 2 minutes after the install when the OS update or disk quota needs it
--help Show help message -

Web server and the panel. With nginx_apache (the default) or nginx, nginx serves the panel at https://<hostname>/admin/. The installer refuses apache, openlitespeed and litespeed before it changes anything and names the two supported modes. To host sites on OpenLiteSpeed or LiteSpeed Enterprise, install with the default and switch under Plugins in the admin panel; the LiteSpeed Enterprise server itself is downloaded when it is activated there.

Examples

shell
# Nginx only, with PHP 8.3 and 8.4
bash install.sh --webserver=nginx --php-versions=8.3,8.4 --php-default=8.4

# All services, PHP 7.4 to 8.5
bash install.sh --php-versions=7.4,8.0,8.1,8.2,8.3,8.4,8.5

# Minimal install (no DNS, no mail, no FTP)
bash install.sh --no-dns --no-mail --no-ftp

# Own nameservers, hostname and Let's Encrypt contact
bash install.sh --hostname=srv1.example.com --nameservers=ns1.example.com,ns2.example.com [email protected]

OS update and restart

Before it installs anything, the installer applies every pending operating-system update: apt-get full-upgrade on Ubuntu and Debian, dnf upgrade on the RHEL family. It runs unattended; a configuration file the image changed keeps its current version (--force-confold; on the RHEL family the package's new copy is left beside it as .rpmnew), and on a first boot it waits for unattended-upgrades to release the package lock instead of failing. Expect a few minutes more on an image that is weeks behind.

At the end the installer checks whether the server has to start again: the update's own marker (/var/run/reboot-required on Ubuntu and Debian), core libraries replaced under running processes (dnf needs-restarting -r on the RHEL family), a kernel newer than the running one, or the boot flag that turns on disk quota on an XFS root (see Disk quota). The result block names each reason under Restart. When a restart is needed, the server restarts by itself 2 minutes after the installer finishes, enough time to copy the credentials from the screen; cancel it with shutdown -c. With --no-reboot nothing is scheduled and the result says to run reboot when convenient. When nothing needs a restart, the result says Restart: not needed.

Package repositories that answer with a temporary error

Third-party package repositories (on Ubuntu the PHP and Python PPAs) sometimes answer with a temporary error such as 503 Service Unavailable for minutes at a time. Before its first apt call the installer writes /etc/apt/apt.conf.d/99whost-retries: apt then tries a failed download ten more times, waiting 1, 2, 4 … up to 30 seconds between tries (about three minutes in all), instead of stopping the step. The file stays in place, so the panel's own package work and the OS updates retry the same way. A longer outage still stops a step that needs the package: run the installer again once the repository answers (see Rollback). On the RHEL family dnf moves on to the next mirror of the repository's mirror list. Adding a PPA on Ubuntu asks Launchpad's API first, which apt's setting does not cover: the installer gives that step three tries of up to 150 seconds each and, when none succeeds, stops with the reason (see Could not add ppa:<name> from Launchpad on Ubuntu).

The Python runtimes for Python hosting (3.10, 3.11 and 3.13 by default) do not stop the install. A version that could not be installed is named with the reason: could not be downloaded (temporary repository error) together with the command that installs it later, or not available on this OS/repo for a version the distribution does not package (3.10 on the RHEL family). The post-install check counts each requested version that is missing as a warning, and the closing screen names a version that only needs the command:

text
  Python 3.11:     not installed - the download failed (temporary repository error)
                   install it: apt-get install python3.11 python3.11-venv python3.11-dev

Run the command when the repository answers again; the panel offers the version as soon as it is installed, without a restart.

Host name

The name the panel is installed under becomes the subject of the self-signed certificate, the base of the default nameservers (ns1.<hostname>) and mail host (mail.<hostname>), the DKIM domain, and the domain of the address the panel mails from (whost@<hostname> while no SMTP relay is configured). It therefore has to be fully qualified: at least two labels of letters, digits and hyphens, the last one not purely numeric. A single-label name (ubuntu-4gb-hel1-3, localhost) or an IP address is refused, and the installer stops before it installs anything:

text
[ERROR] 2026-09-26 09:14:03 Server hostname "ubuntu-4gb-hel1-3" is not a fully qualified domain name.
[ERROR] 2026-09-26 09:14:03 Run the installer with --hostname=<fqdn>, for example: --hostname=srv1.example.com

The installer also makes the system answer to that name: it runs hostnamectl set-hostname <fqdn> and points the 127.0.1.1 line of /etc/hosts at it (exactly one such line is kept; it is added when the file has none). hostname -f then prints the panel's name, which is what the mail server and the agent read. On cloud images whose /etc/hosts is managed by cloud-init the change stays in place across reboots. A run on a server that already carries the name changes nothing.

Give the name an A record in public DNS. The installation finishes without one, but the local mail server checks the domain of every sender address: while the name does not resolve, mail the panel sends through it (notifications, password resets, e-mailed sign-in codes) is turned away with 450 4.1.8 Sender address rejected: Domain not found, and the agent log records the notification with email=failed.

SELinux on the RHEL family

WHost does not ship an SELinux policy yet. With SELinux Enforcing — the default of AlmaLinux, Rocky Linux and CentOS Stream installed from their own media — nginx may not connect to the agent (the panel's API answers 502) or hand PHP sites to Apache on port 8080, fail2ban may not read the account logs, and quotaon is refused at boot. The installer therefore switches a host that enforces SELinux to Permissive before it installs anything, in the running system (setenforce 0) and in /etc/selinux/config (SELINUX=permissive), so the mode holds after a reboot. It says so on the screen, in /var/log/whost/install.log and in the closing summary:

text
[WARN] 2026-10-01 10:02:11 SELinux switched from Enforcing to Permissive: the running system and /etc/selinux/config

In Permissive mode SELinux still labels files and logs what it would have refused (the AVC entries in /var/log/audit/audit.log), but refuses nothing. A host that is already Permissive — some cloud images ship that way — or that has SELinux disabled is left as it is. If the installation fails and rolls back, the previous mode is put back. Running WHost with SELinux enforcing is planned after the beta; until then keep the host Permissive (getenforce prints the current mode).

Older PHP versions

the installer sets up the supported releases only (8.2, 8.3 and 8.4; new accounts use 8.4). A version an older site still needs — 5.6, 7.4, 8.0 or 8.1 — is installed later from the panel (PHP Management → Default PHP Settings → Install beside the version), or here by naming it in --php-versions. PHP 5.6 exists on Ubuntu (the ondrej/php PPA) only: on AlmaLinux / Rocky / CentOS Stream 9 the Remi repository no longer ships it, the panel marks it "Not available on this system" and the installer skips it with a warning (PHP 5.6 unavailable on RHEL 9+ (Remi dropped EOL series) — skipping).


Post-Installation

Verify Installation

shell
# Check service status
systemctl status whost-agent

# Verify the agent answers (it listens on 127.0.0.1 only)
curl -k https://127.0.0.1:2000/health

The answer is {"status":"ok","version":"<version>"}.

The agent tree /opt/whost/agent is owned by root with no access for other users (0750 directories, 0640 files); tenant shells cannot read the agent's source or compiled modules. stat -c '%a' /opt/whost/agent should print 750.

Access Admin Panel

The built-in admin panel is accessible at:

text
https://<SERVER_IP>/admin/
https://<SERVER_HOSTNAME>/admin/

Right after installation the host name rarely resolves yet, so the installer's result block leads with the server's public IPv4 address and names the host name address beside it (Admin panel: https://<SERVER_IP>/admin/ (also https://<SERVER_HOSTNAME>/admin/); the client panel line the same way). The address is the first public one on the server's network interfaces; on a cloud server whose interface carries a private address behind the provider's NAT, it is the public address the server is seen from (asked of the public IP echo services the agent also uses — api.ipify.org, checkip.amazonaws.com, ifconfig.me), and the Server line shows both (10.0.0.5 (public 203.0.113.7)). When none of them answers, the private address is shown. The API base keeps the host name: an integration checks the certificate against a name and keeps the address for the server's lifetime. Until a trusted certificate is installed, the browser warns about the self-signed one (see SSL Certificate Issues under Troubleshooting).

Sign in with the user name admin and the admin password printed at the end of the installer. The password is shown on that screen only: no file keeps it (/etc/whost/agent.conf holds its bcrypt hash), so copy it before you close the terminal. API keys are managed from Settings → API Access in the admin panel.

Forgotten admin password. As root on the server, run:

shell
whost-admin reset-password

It prints a new strong password once, ends every admin session and restarts the agent (the panel is unavailable for a few seconds); the reset is recorded in the audit log. It also lifts the admin sign-in lock-out that failed attempts cause (five wrong passwords for the admin's user name or e-mail address lock the sign-in for 15 minutes, and the lock-out survives an agent restart), so the new password signs in at once; the command then says The sign-in lock-out from failed attempts was lifted. To choose the password yourself, pass it on standard input: whost-admin reset-password --stdin (at least 8 characters, at most 72 bytes, no control characters). Two-factor sign-in, if enabled, stays enabled. Installations made before this command existed may still have the file /etc/whost/admin_password from their first install; nothing reads it, its value stops being valid after the first password change, and it can be deleted.

The installer writes no license: block into /etc/whost/agent.conf and takes no license option, so the agent starts without a key, in the NOT_ACTIVATED state. The first screen is the ordinary sign-in form: once the admin password printed by the installer is accepted, the panel opens on the license page, which says that no license is active and holds the key form. That sign-in's session is what submits the key, and until a key is accepted it opens nothing else in the panel. Activation contacts the license service over outbound HTTPS, binds the license to this server's public IP address and hardware, and stores the issued credentials in agent.conf; the license page then shows the active license and the rest of the panel opens. Afterwards the license is managed from Settings → License. See the admin user guide for the first-login steps.

Reinstalling a server under the same key. The license service keeps a key registered to the installation that activated it, together with credentials that lived only in that installation's agent.conf. After a reinstall those credentials are gone, and the activation form answers "This license key is already registered to an installation". Reissue the license with your license provider (for licenses bought from WISECP: the service's management screen on wisecp.com), then enter the key in the form again. A reissue is handed to the first request that reaches the license service afterwards: if the earlier installation is still running, stop its agent (systemctl stop whost-agent) before you reissue, or it picks the new credentials up on its next check and the new server is refused again. An installation that keeps running through a reissue needs nothing — its next check applies the new credentials by itself.

A fresh install accepts admin sign-ins from any address: no CAPTCHA is configured and the admin IP whitelist is empty, so the sign-in form is guarded only by the web server's request limit, the agent's lockout and the whost-agent fail2ban jail. After the first sign-in open Settings → Security and set the Admin Panel IP Whitelist and CAPTCHA Protection; the installer's closing output says the same.


Disk quota

Per-account disk limits are enforced by filesystem quota on /. On an ext4 root filesystem the installer adds usrquota,grpquota to the root filesystem's mount options, creates the aquota.* files and turns quota on, then checks whether it is actually active and says so in its output. On an XFS root (the default of AlmaLinux and Rocky Linux) quota cannot be turned on while the filesystem is mounted: XFS takes it only at mount time, and / is mounted with the kernel's rootflags before /etc/fstab is read. The installer therefore adds rootflags=uquota to the kernel command line — on the RHEL family with grubby on every boot entry and in /etc/kernel/cmdline, which the boot entries of kernels installed later are made from; on Ubuntu and Debian with the drop-in /etc/default/grub.d/99-whost-quota.cfg and update-grub — and names the restart under Restart in the result; quota is on from the next boot. A kernel command line that already sets other rootflags is left as it is and the output says so; add uquota to them yourself. On any other filesystem the installer skips quota with a warning.

Quota needs the quota_v2 kernel module. Ubuntu cloud images boot a kernel whose base module package does not include it. When the module is missing, the installer installs linux-modules-extra-<running kernel> and, on images that use the linux-image-virtual meta package, linux-image-extra-virtual, so that later kernel upgrades keep the module. The second package depends on the generic kernel image, so it also installs the kernel firmware packages (about 0.7 GB on disk) and a newer kernel when one is available; that kernel becomes the running one at the next reboot. Installing only the modules of the running kernel would be smaller, but the next kernel upgrade would then silently turn quota off.

If the installer reports Disk quota is NOT active on /, the panel still records and shows each plan's disk limit, but nothing enforces it, and the agent logs an error every time it tries to apply one. On ext4 the installer then takes the quota mount options out of /etc/fstab again and removes the aquota.* files, so that the server does not come up with a failed quotaon.service on every boot. To enable quota afterwards on ext4:

  1. Install the kernel module package of your distribution that provides fs/quota/quota_v2 (Ubuntu: apt-get install linux-modules-extra-$(uname -r) linux-image-extra-virtual), then run modprobe quota_v2.
  2. Add usrquota,grpquota to the options of the / line in /etc/fstab, then run mount -o remount /, quotacheck -cugm / and quotaon -v /.
  3. Confirm with quotaon -p / — both user and group quota should read on.

To enable quota afterwards on an XFS root:

  1. Add rootflags=uquota to the kernel command line. RHEL family: grubby --update-kernel=ALL --args="rootflags=uquota"; on AlmaLinux and Rocky Linux 9 it also writes /etc/kernel/cmdline and /etc/default/grub — if /etc/kernel/cmdline exists and still does not carry rootflags=uquota, add it to the end. Ubuntu and Debian: put the line GRUB_CMDLINE_LINUX="${GRUB_CMDLINE_LINUX:+$GRUB_CMDLINE_LINUX }rootflags=uquota" in /etc/default/grub.d/99-whost-quota.cfg, then run update-grub.
  2. Restart the server.
  3. Confirm with quotaon -p / — user quota should read on.

The agent applies an account's disk limit when the account is created and when the disk limit of its plan changes, so quota turned on after accounts were created does not reach them by itself. Apply the limit to such an account with setquota -u <account> <limit> <limit> 0 0 /, where the limit is the plan's disk limit in MB times 1024 (1048576 for a 1024 MB plan).

Limits are applied on / only: the agent sets each account's limit on the root filesystem, so a server whose /home is a separate filesystem does not enforce them.

Service Management

shell
# WHost Agent
systemctl start whost-agent
systemctl stop whost-agent
systemctl restart whost-agent
systemctl status whost-agent

# View logs (the agent writes to agent.log; the journal holds only unit start/stop events)
tail -f /var/log/whost/agent.log

A new installation installs the operating system's security updates and the patch releases of its PHP versions on its own, every morning between 06:00 and 07:00 server time: the installer saves the setting on and the agent configures the operating system's own tool at its first start — unattended-upgrades on Ubuntu (its own security updates plus Ondřej Surý's PHP PPA), dnf-automatic on the RHEL family, which the installer installs, plus a WHost timer for Remi's PHP builds. The verification step reports whether the agent wrote that configuration. The server is never restarted on its own, and the setting is changed under Updates › Settings (see OS Security Updates in the administrator guide).

On Ubuntu, after such an update needrestart restarts the services that use an upgraded library, the WHost Agent among them. The panel and the API are away for the length of that restart (about 15–20 seconds on a small server); the agent checks its files and verifies its license again when it comes back. The installer leaves this distribution default in place: a service that keeps running on the old library does not receive the fix.


Firewall

The installer opens the following ports and refuses the rest: on Ubuntu it sets UFW's incoming policy to deny; on the RHEL family it adds the services below to firewalld's default zone, which refuses what it does not list, and removes the cockpit service that zone opens by default. The list is the same whichever --no-dns, --no-mail or --no-ftp options are given; with --no-firewall the firewall is left untouched.

Port Protocol Service
22 TCP SSH
80 TCP HTTP
443 TCP HTTPS
21 TCP FTP
30000–30100 TCP FTP passive data range
25 TCP SMTP
465, 587 TCP SMTP submission (implicit TLS / STARTTLS)
110, 995 TCP POP3 / POP3S
143, 993 TCP IMAP / IMAPS
53 TCP + UDP DNS
2000 TCP, loopback only WHost Agent — bound to 127.0.0.1, not opened in the firewall; the panel and /api/v1/ are served through the web server on 443

Manual Port Management

shell
# Ubuntu (UFW) — example: an extra service port
ufw allow 8443/tcp

# AlmaLinux / Rocky Linux / CentOS Stream (firewalld)
firewall-cmd --permanent --add-port=8443/tcp
firewall-cmd --reload

# Do not open 2000/tcp: the agent only listens on loopback and every
# client, the panel included, reaches it through https://<host>/api/v1/.

Troubleshooting

Agent won't start

shell
# Check that the configuration file loads (PYTHONPATH as in the service unit)
PYTHONPATH=/opt/whost/agent /opt/whost/venv/bin/python -c "from whost_agent.config import load_config; load_config()"

# Check port availability
ss -tlnp | grep 2000

# Unit start/stop events; the agent's own output goes to agent.log
journalctl -u whost-agent --no-pager -n 50
tail -50 /var/log/whost/agent.log

If the agent log shows ModuleNotFoundError: No module named 'paramiko', the venv is missing dependencies — re-run pip install:

shell
/opt/whost/venv/bin/python -m pip install --require-hashes -r /opt/whost/agent/requirements.lock
systemctl restart whost-agent

SSL Certificate Issues

The installer creates a self-signed certificate for the host name at /etc/whost/ssl/cert.pem, with its key at /etc/whost/ssl/key.pem, before any step that needs it. The panel's nginx site, Postfix, Dovecot and the agent's loopback listener all use this pair. The paths are fixed in the panel's nginx configuration and in the agent's service unit, so the server.ssl_cert and server.ssl_key keys of /etc/whost/agent.conf do not change the certificate that is served. To use a trusted certificate, replace the two files in place (keep the key readable by root only), then reload the services that read them:

shell
systemctl reload nginx postfix dovecot
systemctl restart whost-agent

Pure-FTPd uses a self-signed certificate of its own (/etc/ssl/private/pure-ftpd.pem on Ubuntu, /etc/pki/pure-ftpd/pure-ftpd.pem on the RHEL family).

Multi-OS Specific Issues

Could not add ppa:<name> from Launchpad on Ubuntu

On Ubuntu the PHP packages come from the ondrej/php PPA and the Python versions Ubuntu does not ship from the deadsnakes PPA. The installer adds a PPA through Launchpad when the configured sources do not offer what it needs: up to three tries, each cut after 150 seconds, with a wait of 30 and then 60 seconds between them. When no try adds the PPA, the installer stops at that step:

text
[ERROR] <date> <time> Could not add ppa:ondrej/php from Launchpad after 3 tries (last try: <reason>)
[ERROR] <date> <time> Installer stopped: "adding ppa:ondrej/php" exited with 1 (transcript: /var/log/whost/install.log)

The reason is what the last try got: Launchpad did not answer within 150 s, or add-apt-repository exited with <code>: <its last line>; the command's full output is in the transcript above these lines. The server has to reach api.launchpad.net and ppa.launchpadcontent.net over HTTPS:

shell
curl -sI https://api.launchpad.net/1.0/ | head -n 1
curl -sI https://ppa.launchpadcontent.net/ondrej/php/ubuntu/ | head -n 1

Once both answer, run the installer again with the same options (see Rollback). After adding the PPA the installer also checks that apt reads it, and stops with apt could not read ppa:<name> after adding it (the PPA's package lists could not be downloaded from ppa.launchpadcontent.net; apt's own lines are above it) or with ppa:ondrej/php is read by apt but offers no php<version>-fpm for this Ubuntu release (that PHP version is not published for your Ubuntu release).

The panel's API answers 502 on AlmaLinux, Rocky Linux or CentOS Stream

The login page opens but every sign-in fails, and the nginx error log shows connect() to 127.0.0.1:2000 failed (13: Permission denied): SELinux is enforcing (a server switched back after the installation). Switch it to Permissive now and for the next boot (see SELinux on the RHEL family):

shell
setenforce 0
sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config

git: command not found before the installer starts

The quick installation fetches the repository with git; the installer then installs the rest of its base tools (curl, wget, tar, unzip and others) itself. On an image without git, install it first with the one command for your system (Quick Installation, step 1):

AlmaLinux, Rocky Linux, CentOS Stream:

shell
dnf install -y git

Ubuntu:

shell
apt-get install -y git

Nginx returns the Apache 404 page on RHEL family

mod_ssl on RHEL drops /etc/httpd/conf.d/ssl.conf with Listen 443 https, which steals the port from Nginx. The installer disables this listen directive in nginx_apache mode. If you see the wrong page, verify:

shell
grep -i '^Listen 443\|^#Listen 443' /etc/httpd/conf.d/ssl.conf
ss -tlnp | grep ':443 '

The ^Listen 443 line should be commented; :443 should belong to nginx, not httpd. Restart both services if needed:

shell
systemctl restart httpd nginx

nginx: [emerg] Invalid input: IncludeOptional on account create

ModSecurity v3 (the nginx connector) accepts Include only, not IncludeOptional, and an Include pattern must match at least one file. The installer writes Include /etc/modsecurity/custom/*.conf into /etc/modsecurity/modsecurity.conf together with a placeholder file, /etc/modsecurity/custom/00-placeholder.conf, so the pattern always matches. If the error appears after a manual edit, replace IncludeOptional with Include and keep at least one .conf file in /etc/modsecurity/custom/.

Rollback

When a step fails, the installer stops and names the command that stopped it, in its output and in the transcript:

text
[ERROR] <date> <time> Installer stopped: "<command>" exited with <code> (transcript: /var/log/whost/install.log)

A check of the post-install validation that fails does not hide the closing screen: the screen is headed "WHost installed, but some checks failed", still prints the panel address, the admin password and the API values, and points to the [FAIL] lines above it; the run then ends with the stop line naming post-install validation and a non-zero exit code. Everything the check did not name is in place: fix the named service (for Rspamd on the RHEL family see Troubleshooting) or run the installer again as below.

Fix the cause and run bash install.sh with the same options again. The second run goes through the steps again and completes the installation: package installs and configuration files come out the same, phpMyAdmin, Roundcube and a panel that is already in place are left as they are, and the admin password, the API key and secret and the service database passwords are generated anew — the closing screen prints the new values. Do not run the installer again on a server that is already in use: it writes agent.conf anew, which drops the license credentials and the settings saved from the panel, and on Ubuntu it removes the hosting accounts' PHP-FPM pools.

Steps that already ran are not undone by a failure inside one of the installer's own step functions, which is where almost every failure occurs; only a failure of a top-level command in install.sh runs the registered undo steps (stop the services installed so far, drop the databases the installer created, remove /opt/whost, the panel tree and the ModSecurity, phpMyAdmin and Roundcube trees). To remove a partial installation by hand (a run that stopped late can also have written the files listed under Uninstallation below):

shell
systemctl stop whost-agent
rm -rf /opt/whost
rm -rf /etc/whost
rm -f /etc/systemd/system/whost-agent.service
systemctl daemon-reload

Uninstallation

A default run (--webserver=nginx_apache, Ubuntu 24.04) leaves the files below, the ones the agent writes when it first starts included. Remove what WHost owns and keep the service packages (nginx, Apache, MariaDB, PowerDNS, Postfix, Dovecot, Pure-FTPd, Rspamd, PHP) with their data unless you also mean to remove the services.

shell
# Stop and disable the WHost units
systemctl disable --now whost-agent whost-policyd whost-http-ban.path whost-http-ban-apply
rm -f /etc/systemd/system/whost-agent.service /etc/systemd/system/whost-policyd.service \
      /etc/systemd/system/whost-http-ban.path /etc/systemd/system/whost-http-ban-apply.service
rm -f /etc/systemd/system/php*-fpm.service.d/whost-limits.conf
systemctl daemon-reload

# WHost trees: agent + venv + bundled Node.js runtimes, config + accounts, panel, state, backups + metrics, logs
rm -rf /opt/whost /etc/whost /var/www/whost /var/lib/whost /var/whost /var/log/whost

# Web server pieces WHost added (reload nginx and Apache afterwards, or remove the packages)
rm -f /etc/nginx/sites-enabled/whost-panel.conf /etc/nginx/sites-available/whost-panel.conf \
      /etc/nginx/snippets/whost-panel-locations.conf /etc/nginx/snippets/whost-security-headers.conf \
      /etc/nginx/conf.d/whost-panel-ratelimit.conf /etc/nginx/conf.d/whost-banlist.conf \
      /etc/nginx/conf.d/whost-cloudflare-realip.conf /etc/nginx/conf.d/whost-modsecurity.conf
rm -f /etc/apache2/conf-enabled/whost-status.conf /etc/apache2/conf-available/whost-status.conf \
      /etc/apache2/conf-enabled/whost-banlist.conf
rm -rf /etc/modsecurity            # ModSecurity configuration, the OWASP CRS copy, per-account rules

# phpMyAdmin and Roundcube, unpacked from their upstream archives and served through the panel site
rm -rf /usr/share/phpmyadmin /etc/phpmyadmin /var/lib/phpmyadmin /usr/share/roundcube /var/lib/roundcube
rm -f /etc/nginx/snippets/phpmyadmin.conf /etc/nginx/snippets/roundcube.conf

# PHP drop-ins, log rotation, fail2ban, SSH and Dovecot drop-ins
rm -f /etc/php/*/fpm/conf.d/99-whost-opcache.ini
rm -f /etc/logrotate.d/whost /etc/logrotate.d/whost-accounts /etc/logrotate.d/modsecurity
rm -f /etc/fail2ban/filter.d/whost-agent.conf /etc/fail2ban/filter.d/whost-web-scan.conf \
      /etc/fail2ban/filter.d/whost-web-probe.conf /etc/fail2ban/filter.d/whost-waf.conf \
      /etc/fail2ban/action.d/whost-http-deny.conf /etc/fail2ban/action.d/whost-nginx-deny.conf
# the jails the agent writes read files under /var/log/whost; left behind, they keep fail2ban from starting
rm -f /etc/fail2ban/jail.d/whost-webscan.conf /etc/fail2ban/jail.d/whost-waf.conf \
      /etc/fail2ban/jail.d/whost-webscan.local /etc/fail2ban/jail.d/whost-webprobe.local /etc/fail2ban/jail.d/whost-waf.local
rm -f /usr/local/sbin/whost-http-ban /usr/local/sbin/whost-bot-verify
rm -rf /var/lib/fail2ban/whost-http-ban
rm -f /etc/ssh/sshd_config.d/10-whost-accounts.conf /etc/ssh/sshd_config.d/60-whost-hardening.conf
rm -f /etc/dovecot/conf.d/95-whost-quota.conf

# Kernel settings (ptrace restriction, swap tuning); the running values change back at the next reboot
rm -f /etc/sysctl.d/99-whost-ptrace.conf /etc/sysctl.d/99-whost-perf.conf

Kept unless you remove the services too: /etc/fail2ban/jail.local (the installer's jails, [whost-agent] included) and /etc/fail2ban/fail2ban.local, the ionCube loader (/usr/local/ioncube, /etc/php/*/mods-available/00-ioncube.ini and its conf.d links), the MariaDB drop-ins 99-whost.cnf (loopback only) and 99-whost-tuning.cnf (sized to the RAM) in /etc/mysql/mariadb.conf.d/ with /var/lib/mysql-files, the MariaDB root login in /root/.my.cnf, the MariaDB databases powerdns, pureftpd, roundcubemail and vmail with their users (powerdns, pureftpd, roundcube, vmail), the vmail user and group with the whost-noshell and whost-sso groups, the UFW rules (ufw status numbered), the usrquota,grpquota mount options in /etc/fstab with /aquota.user and /aquota.group, on an XFS root rootflags=uquota on the kernel command line (RHEL family: grubby --update-kernel=ALL --remove-args=rootflags, which on AlmaLinux and Rocky Linux 9 also takes it out of /etc/kernel/cmdline and /etc/default/grub; Ubuntu and Debian: delete /etc/default/grub.d/99-whost-quota.cfg and run update-grub), the kernel module packages the quota step installed where the image lacked them (linux-modules-extra-*, linux-image-extra-virtual), the APT sources the installer added (ondrej/php, deadsnakes, rspamd) and its apt retry setting (/etc/apt/apt.conf.d/99whost-retries).


Developed by WISECP LLC. Contact: [email protected]

Still Need Help?

Our support team is here around the clock for anything you can't find above.