Configuration Reference

Configuration File

Location: /etc/whost/agent.conf (YAML format)

File permissions: 600, owner root (readable only by root). The agent resets the mode to 600 at every start.

The installer writes a working configuration with sane defaults — most operators never need to edit it directly: most keys below are changed from the panel, which writes this file and applies the change to the service concerned. The sections below describe what each block controls so you know where to look when something does need adjustment.

How the file is written. The installer writes the first version with the blocks it needs. From then on the agent rewrites the whole file from the settings it holds in memory: at its first start, which adds every block below with its default values, and on every change saved from the panel. Comments, key order and formatting added by hand are not kept, and a key the agent does not know (a misspelled one included) is ignored without a warning and dropped at the next write. Broken YAML, or a value of the wrong type (text where a number or true/false is expected), stops the agent from starting; the reason is appended to /var/log/whost/agent.log.

Secrets. Passwords and secrets are stored in this file in plain text (the administrator password as a bcrypt hash). The agent moves them into an in-memory vault while it runs; on disk the file's 600 root mode is their only protection, so keep every copy and backup of the file equally restricted.

Settings kept elsewhere. Update preferences (/etc/whost/update_settings.json, see the last section), the notification channels and relay of Settings › Notifications (/etc/whost/notification_prefs.json), remote backup destinations (/etc/whost/remote_backup.json), API keys (/var/lib/whost/api_keys.json), plugin state (/etc/whost/plugins.json) and the server time zone (a system setting) are not in this file.

Reading the tables. Default is the value the agent uses when the key is missing; where the installer writes a different value, it is named. Changed from names the panel page. file — only by editing this file (see Applying Changes at the end). agent — written by the installer or the agent: do not edit it, a hand-written value breaks the service that uses it. — — the key has no effect in this release.

Section Details

server

Identity of the server, and the agent's own listener.

Panel certificate. The pair /etc/whost/ssl/cert.pem and /etc/whost/ssl/key.pem is created self-signed for the host name at install. The same pair serves the panel's nginx vhost on port 443, Postfix and Dovecot TLS, the OpenLiteSpeed listener when LiteSpeed serves the sites, and the agent's loopback listener. To serve a trusted certificate, replace the two files (the certificate with its chain in cert.pem), check with nginx -t, then reload nginx, Postfix and Dovecot.

auth

HMAC-SHA256 authentication of API requests (machine-to-machine; the panels use session cookies).

webserver

Which web server stack serves the sites, and its global connection tuning. type takes one of:

• nginx: Nginx handles all HTTP traffic directly
• apache: Apache handles all HTTP traffic directly
• nginx_apache: Nginx as reverse proxy (port 80/443) + Apache backend (apache_port, 8080)
• openlitespeed, litespeed: OpenLiteSpeed or LiteSpeed Enterprise, set when the matching plugin is activated on the Plugins page; PHP then runs through LSAPI

The installer writes nginx_apache or nginx; it refuses the other values (see Installation).

php

Multiple PHP versions can be installed simultaneously, and each hosting account can use a different one.

The seven default_* values are the ini values an account's pool is rendered with until the account saves its own; an account's saved values live in its metadata and survive a version, worker or plan change. Changing a default does not rewrite existing pools: an account without values of its own gets the new default the next time its pool is rendered.

python

Python application hosting (the Python Hosting plugin). The plugin's on/off state is client_features.python_apps, not a key of this block.

node

Node.js application hosting (the Node.js Hosting plugin). The plugin's on/off state is client_features.node_apps, not a key of this block.

mysql

The agent's MariaDB connection and the MariaDB tuning it applies for you.

A save from Settings › General that changes a database value rewrites the drop-in /etc/mysql/mariadb.conf.d/99-whost-tuning.cnf (/etc/my.cnf.d/ on RHEL) from the agent's template with all eight values and applies each one live with SET GLOBAL, so no restart follows. The drop-in also carries local_infile = 0 and secure_file_priv = /var/lib/mysql-files, which MariaDB reads at its next restart. The installer writes its own version of this file, sized to the server's RAM (InnoDB buffer pool 37.5% of RAM, at least 256 MB; max_connections = 300; InnoDB log and flush settings); the first database save from the panel replaces it with the eight values the page shows. Editing these keys in this file does not change MariaDB.

dns

PowerDNS integration via its HTTP API.

mail

Postfix (SMTP) + Dovecot (IMAP/POP3) + OpenDKIM. The mail system uses a MariaDB database for virtual mailbox management.

ssl

Let's Encrypt integration via certbot. Orders validate over HTTP from the domain's own document root, are named after the domain and install a renewal hook that refreshes the files the vhost points at and reloads the web server; renewals run on certbot's own schedule (its systemd timer, or the daily cron line the installer adds where there is no timer). Deleting a certificate removes the lineage.

ftp

Pure-FTPd with MariaDB authentication. Each hosting account can have multiple FTP sub-accounts.

A save that changes passive_ports, max_clients or max_per_ip writes the three directives (/etc/pure-ftpd/conf/ on Debian/Ubuntu, /etc/pure-ftpd/pure-ftpd.conf on RHEL) and restarts Pure-FTPd; a hand edit does not change Pure-FTPd.

backup

Local backup storage and its retention.

The scheduler starts with the agent only while both enabled and schedule.enabled are true, and schedule.check_interval is read at that moment: a change of schedule.enabled — also when saved from the panel — takes effect at the next agent start, and so does switching enabled back on when it was off at start. While the scheduler is not running, neither scheduled backups nor retention pruning run.

Remote destinations are not configured in this file: they are managed from the panel (Backups › Remote Storage) and stored encrypted in /etc/whost/remote_backup.json (per-account ones under /etc/whost/accounts/<user>/remote_backup.json).

logging

license

license.state_file selects the persistent license state file; its default is /etc/whost/license.state. The companion HMAC file appends .hmac to that path. State loading, saving, and independent endpoint, service, startup and runtime checks use the selected file. An old state file at the default location does not substitute for a missing file at the configured location.

Keep both files owned by root with mode 0600. Startup normalizes their modes to 0600. Restart the agent after changing the setting; avoid repeated restarts, which consume license verification limits. The installation's boot token stays at /etc/whost/.boot_token; prior activation evidence in either the selected or default state file prevents silent regeneration of a missing or malformed token.

License grace and cached-token validity use the license server's verified UTC time advanced by elapsed kernel boot time. Moving the system clock backward does not add grace time. The state HMAC also protects the clock anchor, allowing an agent restart within the same operating-system boot to preserve elapsed time. After an operating-system reboot, or when upgrading a cache without this anchor, the agent requires online license verification before cached grace can be used. Keep NTP enabled: TLS certificate validation and other system services still depend on the system clock.

Cached activation and grace require the original RSA-signed license assertion and its expiry. A valid local HMAC alone does not authorize cached access. Missing signature fields, a missing signed expiry, modified assertions, and expired tokens discard the cache and require online verification. Activation and periodic verification both persist the signed assertion. Do not edit or remove token fields when restoring a state file.

The other keys of this block are maintained by the agent — do not edit them. key and the license secrets are written when the license is activated on the License page; a hand-edited key that differs from the activated one is replaced with the activated key at the next start.

rate_limit

API rate limiting per client address (the visitor's address as the agent resolves it behind the panel's nginx), using slowapi. A request over its limit is answered 429 RATE_LIMIT with a Retry-After header. Values follow the format {count}/{period} (e.g., 120/minute, 5/minute).

rate_limit:
  default: "60/minute"
  read: "120/minute"
  write: "30/minute"
  delete: "20/minute"
  heavy: "5/minute"
  auth: "5/minute"

All six values are read from this file at agent start and applied.

fail2ban

modsecurity

WHost enforces ModSecurity at the nginx tier (nginx and nginx_apache); with another web server the settings are saved but not applied to traffic. /etc/modsecurity/modsecurity.conf is rendered from this block when the WAF page changes a setting or a rule — after a web-server configuration test — so a hand edit reaches it only at the next such change.

security

admin

The built-in administrator, the sign-in protection of both panels and the session lifetimes.

frontend

Static panel bundle served by nginx.

client_features

Eleven switches (file_manager, dns, backups, cron, ssl, php, email, ftp, databases, python_apps, node_apps), all true by default, edited from Settings › General. A switch that is off is enforced at the API for every client route of that surface (409 FEATURE_DISABLED, keyed on the request path — /client/emails and /client/spam for email, /client/files for file_manager, the per-domain /client/domains/{domain}/php/* routes for php); the client profile carries the switches as features, and the client panel hides the sidebar entry and the dashboard tiles of a surface that is off. A switch that is off does not stop the backup scheduler: backups off refuses the client's backup routes only, and the account's existing schedules keep running.

python_apps and node_apps are also the on/off state of the Python Hosting and Node.js Hosting plugins: activating or deactivating the plugin on the Plugins page sets them (deactivation is refused while apps are deployed), and while one is off every Python or Node.js app route — the administrator's included — answers 503 PLUGIN_DISABLED.

whitelabel

enabled, company_name, four logo addresses (logo_light, logo_dark, favicon, favicon_dark), the sign-in page video and its cover for each panel (login_video_admin, login_poster_admin, login_video_client, login_poster_client; empty = the default video), six HSL colours (primary_color, secondary_color, nav_color and their _dark twins, "H S% L%" with H 0–360 and S, L 0–100) and hide_login_branding (default true). Edited on the Whitelabel page (account menu at the top right); every change writes a settings_updated audit row and rewrites config.json in the panel trees. While the whitelabel license addon is not active, the page's saves, logo and login video uploads and removals and reset are refused with 403 LICENSE_ADDON_REQUIRED; the values already in this block stay, and the public branding read answers active: false until the addon is active. A licence check that grants or withdraws the addon rewrites config.json at once, so the panel follows without a restart. A hand edit is published at the next agent start while the addon is active.

A logo field holds the address of a file the agent stores under /var/lib/whost/branding/ — /branding/<field>.<digest>.<png|jpg|webp|svg>, served by the panel's nginx (location ^~ /branding/ in /etc/nginx/snippets/whost-panel-locations.conf) with a one-year immutable cache and a sandboxing content policy; the name changes with the content, and a replaced or removed logo's file is deleted. Only such an address (or an inline data:image/ URL, see below) is published; any other hand-written value stays private. Uploads (2 MB per file) are shaped before they are stored: a raster logo to fit 512 × 160 px (width × height), a favicon to a square PNG of at most 256 px with transparent padding; an image above 25 megapixels is refused (400 IMAGE_DIMENSIONS_TOO_LARGE), a file that does not decode as its type too (400 INVALID_IMAGE); SVG is sanitised and kept. A sign-in video field holds /branding/login_video_<admin|client>.<digest>.mp4 — an MP4 whose video track is H.264, at most 5 MB, stored as uploaded (the panel compresses a larger video in the browser before it uploads it) — and its cover /branding/login_poster_<admin|client>.<digest>.<jpg|png|webp>, scaled to fit 1920 × 1080 (1080 × 1920 upright); each publishes only a file written for that field. Logos an earlier release stored inline as data: URLs move to files at the first agent start that finds the panel nginx serving /branding/: the original values are copied first to /var/lib/whost/branding-legacy-<timestamp>.yaml (mode 0600), the logos are shaped as uploads are, and the block is saved once; a value that does not decode stays as it was. Include /var/lib/whost/branding/ in host backups.

update preferences (not an agent.conf block)

agent.conf carries no update: block; an update: block left by an older install is not read by any code and is dropped the next time the agent writes the file. The update preferences live in /etc/whost/update_settings.json (root, 0600): channel (stable | beta), auto_update, auto_update_type (all | security | patch | minor), backup_before_update, notify_available, notify_installed, os_packages_check_enabled, os_packages_notify_security, allow_vendor_critical_override. auto_update_type decides what installs on its own: security only releases the vendor flags as critical (and only while allow_vendor_critical_override is on), patch a patch step, minor a minor or patch step, all every release; a vendor-flagged critical release also installs under the other types while allow_vendor_critical_override is on. The installer writes the file once on a new server with the channel of the release it installs (beta for a -beta.N release, stable otherwise) and leaves an existing file alone; afterwards the file is written by the Updates page (Settings tab, PUT /system/update/settings) and read by the install pipeline and the scheduler; an absent file means the defaults (auto-update of vendor-flagged critical releases on), a file that cannot be parsed is logged and treated as auto_update: false until it is repaired. The check cadence is fixed: five minutes after every agent start, then every 24 hours (up to 30 minutes of jitter).

Environment Variables

The agent reads its settings from this YAML file only; no key of this file can be set through an environment variable. The service unit (/etc/systemd/system/whost-agent.service) sets the environment the agent runs with — among it WHOST_CONFIG_PATH=/etc/whost/agent.conf, the path of this file — together with hardening switches. Keep the unit as installed: the installer and the agent's start-up permission check work on /etc/whost/agent.conf.

Applying Changes

Settings saved from the panel take effect at once: the agent writes this file itself and applies the change to the service concerned, as the tables describe. To change a key the panel does not offer (file in the tables):

1. Keep a copy, for example cp -p /etc/whost/agent.conf /root/agent.conf.bak — it holds the same secrets, so keep it at mode 600.
2. Edit the file, then restart the agent before saving anything in the panel; until the restart, the next panel save writes the agent's in-memory settings back over the edit.
3. Check that the agent came back: curl -sk https://127.0.0.1:2000/health answers {"status":"ok",...} once the start has finished (a few seconds). If it does not, read the end of /var/log/whost/agent.log.

systemctl restart whost-agent
curl -sk https://127.0.0.1:2000/health

A hand edit changes what the agent reads; it does not rewrite the service configurations a panel save writes (web server tuning, MariaDB, Pure-FTPd, the Postfix message size, sshd, the nginx admin whitelist, DNS zones, the panel vhost). Change those keys from the panel. Every agent start verifies the license with the license server; avoid repeated restarts.

Developed by WISECP LLC. Contact: [email protected]