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.
| Key | Default | Changed from | What it does |
|---|---|---|---|
hostname |
installer: the host name (--hostname) |
Settings › General › Hostname | The panel's host name (FQDN). A save from the panel also runs hostnamectl, rewrites /etc/hosts, sets mail.hostname, reloads Postfix and Dovecot and rewrites the panel's nginx vhost. Notification e-mails link to https://<hostname>, and it is the fallback origin of the password-reset link (see frontend.public_url). |
server_ip |
installer: the server's primary IPv4 address | Settings › General › Server IP Address | The primary public IPv4 address: an account gets it unless another address is assigned, the account's DNS zone points at it, and the panel vhost answers on it. A save from the panel rewrites the DNS A records that carried the old address. |
force_ssl |
true |
Settings › General › Force HTTPS Redirection | Redirects the panel's HTTP requests to HTTPS; a request that a proxy or CDN forwards with X-Forwarded-Proto: https is served without the redirect. The save rewrites the panel vhost and reloads nginx. Keep it on unless an edge in front of the panel forces HTTPS itself: with it off, a panel reached directly over plain HTTP answers the page without a redirect (the agent still listens on TLS only). The API never answers over plain HTTP, whatever this setting: an /api/ request that reaches the panel over HTTP — on port 80, or through a proxy that reports X-Forwarded-Proto: http — gets 403 HTTPS_REQUIRED from nginx (so the panel cannot be signed into over plain HTTP), and with the setting on, /api/ paths get that answer instead of the redirect. A proxy that ends TLS in front of the panel must send X-Forwarded-Proto: https. Existing installations receive the refusal with the agent update (the panel's locations snippet is rewritten at start-up); the /api/ exception to the redirect is written with the next save of the hostname, the server IP or this setting. |
host, port |
0.0.0.0, 2000 (installer: 127.0.0.1, 2000) |
file | They do not move the listener: the agent listens on 127.0.0.1:2000 as its service unit sets it (--host, --port; the unit also reserves ports below 2001 to root — net.ipv4.ip_unprivileged_port_start = 2001, kept in /etc/sysctl.d/60-whost-agent-port.conf — so no process of an account can listen on the agent's port, not even while the agent restarts; processes that do not run as root cannot listen on ports 1024–2000), and the panel's nginx proxy and the update pipeline use that address. port is still read by the firewall rule that keeps tenant processes away from the agent and by the port list Under-Attack mode never drops — keep it 2000. |
ssl_cert, ssl_key |
/etc/whost/ssl/cert.pem, /etc/whost/ssl/key.pem |
— | Not read; see the certificate note below. |
workers |
1 |
— | Always 1: any other value is logged and replaced with 1. |
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 HTTPS of a site without its own certificate while OpenLiteSpeed / LiteSpeed Enterprise serves the sites (nginx serves a site that has one with its own certificate; LiteSpeed has no listener on 443), 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).
| Key | Default | Changed from | What it does |
|---|---|---|---|
api_key, api_secret |
generated by the installer | agent | The API key pair the installer generated (also saved in /etc/whost/api_key and /etc/whost/api_secret). At its first start the agent copies it into the API key list as Default API Key (Settings › API Access), where it is managed like any other key; revoke or delete it there to retire it. A deleted installer key stays retired: it does not answer through this copy and is not copied back at the next start. A pair a later installer run writes answers until it is managed the same way. |
allowed_ips |
[] |
file | Copied onto that key's IP allowlist when the agent adds the key to the list; afterwards the allowlist is edited in Settings › API Access, and this list no longer applies to the key. |
api_key_encryption_secret |
generated at first start | agent | Encrypts the stored API key secrets and the credentials of remote backup destinations. Never change or remove it: the stored secrets could no longer be decrypted. |
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).
| Key | Default | Changed from | What it does |
|---|---|---|---|
type |
nginx_apache (installer: --webserver) |
Settings › General › Default Web Server (nginx, nginx_apache; apache is offered and accepted only on a server installed with Apache alone) |
The stack the agent writes every site configuration, certificate renewal hook and WAF setup for. The General save changes only this value — it does not install, start or reconfigure a web server — so change it only after the server's stack has been changed to match. With OpenLiteSpeed or LiteSpeed the field is read-only (the plugin owns it). Five minutes after it starts, the agent logs WEBSERVER_BINDING_DRIFT when the process listening on port 443 does not match, and a warning when nothing listens on 443 (a clean install starts the agent before it writes the panel's 443 site, so the check waits). With nginx_apache nginx writes each site's access log (one line per visit, with the visitor's address) and the Apache backend site writes none; the agent writes whost-remoteip.conf at start and switches mod_remoteip on, so Apache — PHP's REMOTE_ADDR, .htaccess rules such as Require ip / Require local, the error logs — sees the visitor's address from the X-Real-IP nginx sets (a header the visitor sends is replaced by nginx), believed only on connections from 127.0.0.1; a loopback-only rule (Apache's own /server-status, a site's Require ip 127.0.0.1 or Require local) admits only requests made on the server itself. The vhosts behind nginx take HTTPS from X-Forwarded-Proto only on a connection from loopback (CONN_REMOTE_ADDR); the file waits until every vhost has been rendered with that line, and stays only when apachectl configtest passes. With apache the agent writes whost-remoteip.conf at start (/etc/apache2/conf-available + a2enconf, RHEL /etc/httpd/conf.d) and switches mod_remoteip on: behind Cloudflare Apache takes the visitor's address from CF-Connecting-IP, believed only on connections from the networks nginx trusts (set_real_ip_from) or, without them, Cloudflare's published list — access checks, the account's IP blocks and the access logs then see the visitor; a header from any other address is ignored. The file is kept only when apachectl configtest passes. |
max_clients, keepalive_timeout |
256, 65 |
Settings › General › Max Clients (1–10000), Keep-Alive Timeout (0–300 s) | Written to the web server when saved from the panel: Nginx worker_connections and keepalive_timeout in nginx.conf (only where those lines exist; nginx -t, then reload), Apache KeepAliveTimeout only (apachectl configtest, then reload), OpenLiteSpeed/LiteSpeed maxConnections and keepAliveTimeout (the server restarts). A failed test restores the previous file. The page shows the configured values, not the running server's. |
apache_port |
8080 |
file | The Apache port nginx proxies to in nginx_apache site configurations. Apache's own Listen line is set by the installer and does not follow this key: a new installation binds it to loopback (Listen 127.0.0.1:8080), so the backend is reachable only through nginx on the host itself. An installation made before this still carries Listen 8080 (every interface, closed by the firewall); to bring it to the same state change that line in /etc/apache2/ports.conf (Debian) or /etc/httpd/conf/httpd.conf (RHEL) to Listen 127.0.0.1:8080 and reload Apache — site configurations (<VirtualHost *:8080>) need no change. |
php_handler |
fpm |
agent | fpm (PHP-FPM pools) or lsapi; set to lsapi whenever type is OpenLiteSpeed or LiteSpeed. |
ols_admin_port, ols_admin_user, ols_admin_password |
7080, admin, empty |
agent | The OpenLiteSpeed/LiteSpeed WebAdmin console. The LiteSpeed Enterprise plugin generates the password when it installs the server (a value already here is reused on a reinstall); read it here when you need the console. |
lscache_enabled |
true |
file | Adds LSCache to OpenLiteSpeed/LiteSpeed site configurations. |
litespeed_serial |
— | agent | The LiteSpeed Enterprise serial the plugin was activated with. |
nginx_port |
80 |
— | Not read. |
php
Multiple PHP versions can be installed simultaneously, and each hosting account can use a different one.
| Key | Default | Changed from | What it does |
|---|---|---|---|
default_version |
8.4 (installer: --php-default) |
Settings › General › Default PHP Version; PHP › Default PHP Settings | PHP version of new accounts; must be one of installed_versions. |
installed_versions |
7.4, 8.0–8.5 (installer: the versions it installed, --php-versions; default 8.2, 8.3, 8.4) |
PHP › Default PHP Settings: version switches, Install / Remove | Versions offered to accounts. A version can be switched on only when its PHP-FPM package is installed; installing a version from the panel adds it, removing one takes it out; the default version and a version a domain still uses cannot be switched off or removed. |
default_upload_max_filesize, default_post_max_size |
64M |
PHP › Default PHP Settings | A size with an optional K/M/G; -1 is refused. |
default_memory_limit |
256M |
PHP › Default PHP Settings | A size, or -1 for unlimited. |
default_max_execution_time |
300 |
PHP › Default PHP Settings | Seconds, 0–86400. |
default_max_input_time |
300 |
PHP › Default PHP Settings | Seconds, -1–86400. |
default_max_input_vars |
1000 |
PHP › Default PHP Settings | 1–1000000. |
default_display_errors |
false |
PHP › Default PHP Settings | true or false. |
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.
Session defaults. Every installed PHP version carries a 99-whost-session.ini drop-in in its PHP-FPM scan directory (/etc/php/<version>/fpm/conf.d/ on Ubuntu and Debian, /etc/opt/remi/php<version>/php.d/ on the RHEL family, where it also reaches that version's command line) with session.upload_progress.enabled = 0 and session.use_strict_mode = 1. The installer writes it for every version it installs, a version installed from the panel gets it from the install job, and an installation made before this file existed gets it from the agent's start-up host hardening (security.host_hardening_reconcile below; rollback there removes it again). Both settings are directory-level: a site that needs PHP's upload progress feature puts session.upload_progress.enabled = 1 in a .user.ini of its document root (the panel's per-domain PHP Configuration rewrites that file with the panel's own values when it is saved, so the line has to be added again after such a save). The panel's own phpMyAdmin and webmail run with the same defaults; phpMyAdmin's import progress bar is the only visible difference. Every pool the panel renders (account pools and, on the RHEL family, the shared www pool) also locks session.serialize_handler = php with php_admin_value, so a script cannot leave the pool writing session data in one format and reading it in another; the setting is not changed, only locked. On an OpenLiteSpeed host the same three values are in each vhost's phpIniOverride block (the two session defaults overridable, the handler locked). The web server configuration refuses a request for a sess_<id> file name inside a document root, and an addon or subdomain's document_root may not be the account home itself or one of its private folders (logs, tmp, ssl, backups, mail).
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.
| Key | Default | Changed from | What it does |
|---|---|---|---|
installed_versions |
3.10, 3.11, 3.12, 3.13 |
file | Python versions offered to apps; only those whose interpreter is installed on the server are listed. |
default_timeout, default_max_requests |
120, 1000 |
file | Gunicorn timeout and max_requests of an app that has not set its own. |
allowed_manage_commands |
migrate, collectstatic, createsuperuser, showmigrations, check, shell |
file | The Django manage.py commands the panel may run for an app; any other command is refused. |
socket_dir, venv_base_dir |
/run/whost, venvs |
agent | Where app sockets and (under the account's home) virtual environments are created. |
enabled, default_version, default_app_server, default_workers, default_worker_class, max_workers_per_app |
— | — | Not read. |
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.
| Key | Default | Changed from | What it does |
|---|---|---|---|
installed_versions |
18, 20, 22 |
file | Node.js versions offered to apps; only those whose runtime is installed on the server are listed. |
allowed_npm_scripts |
start, build, test, lint, migrate, seed |
file | The npm run scripts the panel may run for an app; any other script is refused. |
socket_dir, wrappers_dir |
/run/whost, /etc/whost/wrappers |
agent | Where app sockets and the per-app start wrappers are created. |
enabled, default_version, default_app_type, default_package_manager, default_instances, max_instances_per_app, default_max_memory_mb, runtime_base_dir |
— | — | Not read. |
mysql
The agent's MariaDB connection and the MariaDB tuning it applies for you.
| Key | Default | Changed from | What it does |
|---|---|---|---|
host, port |
localhost, 3306 |
agent | The agent's MariaDB connection. |
root_password |
set by the installer | agent | MariaDB root password (also in /etc/whost/mysql_root_password). |
max_connections |
151 |
Settings › General (1–10000) | max_connections. |
buffer_pool_size |
256 (MB) |
Settings › General (16–65536) | innodb_buffer_pool_size. |
connect_timeout, wait_timeout, interactive_timeout |
300 (seconds) |
Settings › General (1–86400) | The MariaDB variables of the same name. |
sort_buffer_size, read_buffer_size, max_allowed_packet |
4M, 4M, 64M |
Settings › General | A non-zero K/M/G size (4M, 256K, 1G). |
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.
| Key | Default | Changed from | What it does |
|---|---|---|---|
enabled |
true (installer: false with --no-dns) |
file | Whether PowerDNS is installed. While false, accounts are created without a DNS zone, and an account's address change or a nameserver change is not pushed to zones. |
nameservers |
ns1.example.com, ns2.example.com (installer: --nameservers, default ns1.<hostname>, ns2.<hostname>) |
Settings › General › Nameservers (up to four, filled in order) | NS records of every zone the agent creates; the first entry is the SOA primary. A save from the panel also rewrites the NS records and SOA primary of every existing zone; a hand edit reaches only zones created after the restart. Set them to your real nameserver host names, as the delegation at the registrar names them. |
api_url, api_key |
http://127.0.0.1:8081, set by the installer |
agent | The PowerDNS HTTP API and its key (also in /etc/whost/pdns_api_key). |
default_ttl |
3600 |
file | TTL of the records the agent creates. |
soa_content |
ns1.example.com hostmaster.example.com 0 10800 3600 604800 3600 |
file | Only its last four numbers — refresh, retry, expire and negative-cache TTL — are used; the SOA primary is the first nameserver and the contact is hostmaster.<zone>. |
type |
powerdns |
— | Not read; PowerDNS is the only DNS server. |
Postfix (SMTP) + Dovecot (IMAP/POP3) + OpenDKIM. The mail system uses a MariaDB database for virtual mailbox management.
| Key | Default | Changed from | What it does |
|---|---|---|---|
enabled |
true (installer: false with --no-mail) |
file | Whether the mail stack is installed. While false the agent does not install or refresh the WHost Mail Policy service (whost-policyd) that applies the hourly sending limits. |
hostname |
mail.example.com (installer: --mail-hostname, default mail.<hostname>) |
file | The mail host name recorded at install; a host-name change in Settings › General replaces it with the new server host name. |
default_hourly_limit |
500 |
Settings › General › Default Hourly Email Limit (0–100000) | Messages an account may send per hour when its plan sets no limit of its own; 0 = unlimited. A save from the panel re-renders and restarts whost-policyd; a hand edit reaches it at the next agent start. |
max_email_size |
50 (MB) |
Settings › General › Maximum Email Size (1–100 MB) | Written to Postfix message_size_limit when saved from the panel (Postfix reloads); a hand edit does not change Postfix. Webmail takes an attachment up to Postfix's size: the agent writes it into the webmail location (nginx body limit and PHP upload limits) on every start and on every save of this field. |
dkim_selector, dkim_key_dir |
default, /etc/opendkim/keys |
agent | Selector and key directory of the DKIM keys the agent creates (<selector>._domainkey.<domain> records). |
maildir_base, vmail_uid, vmail_gid |
/var/vmail, 5000, 5000 |
agent | Mailbox storage and its owner, as installed. |
mysql_host, mysql_port, mysql_user, mysql_password, mysql_database |
localhost, 3306, vmail, set by the installer, vmail |
agent | The virtual-mailbox database (password also in /etc/whost/mail_db_password). |
dovecot_master_user, dovecot_master_password |
whost_master, set with webmail |
agent | The Dovecot master login used for webmail single sign-on. |
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.
| Key | Default | Changed from | What it does |
|---|---|---|---|
email |
empty (installer: --ssl-email) |
Settings › General › Let's Encrypt Email | Account e-mail of the orders, required: an order is refused with 400 SSL_EMAIL_REQUIRED while it is empty. |
staging |
false |
file | true sends orders to the Let's Encrypt staging environment, whose certificates browsers do not trust — for testing without hitting rate limits. Restart the agent after changing it. |
auto_renew |
true |
Settings › General › Auto-SSL for New Domains | Stored only in this release: the account and addon-domain forms carry their own Auto-SSL choice. |
provider, webroot_path, renew_days_before |
certbot, /var/www/letsencrypt, 30 |
— | Not read. |
ftp
Pure-FTPd with MariaDB authentication. Each hosting account can have multiple FTP sub-accounts.
| Key | Default | Changed from | What it does |
|---|---|---|---|
enabled |
true (installer: false with --no-ftp) |
file | Whether Pure-FTPd is installed. |
passive_ports |
30000:30100 |
Settings › General › Passive Port Range | START:END, 1024–65535, START lower than END. Written to Pure-FTPd's PassivePortRange when saved from the panel. The installer opens 30000:30100 in the firewall; open a new range on the Firewall page as a START:END port rule. |
max_clients |
50 |
Settings › General › Max Clients (1–1000) | MaxClientsNumber. |
max_per_ip |
10 |
Settings › General › Max Connections per IP (1–100) | MaxClientsPerIP. |
passive_mode, bandwidth_limit |
true, 0 (KB/s) |
API only (the form does not show them) | Stored only: the save keeps and echoes them, but no Pure-FTPd directive is written for them. |
mysql_host, mysql_port, mysql_user, mysql_password, mysql_database |
localhost, 3306, pureftpd, set by the installer, pureftpd |
agent | The Pure-FTPd authentication database (password also in /etc/whost/ftp_db_password). |
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.
| Key | Default | Changed from | What it does |
|---|---|---|---|
enabled |
true |
Backups › Settings › Backup System | While false, creating, restoring and scheduling backups is refused (403 BACKUP_DISABLED) and scheduled runs are skipped. |
local_path |
/var/whost/backups |
file | Where local archives are kept, one directory per account. |
retention_days |
7 (installer: 30) |
Backups › Settings › Retention Days (1–365) | Once a day, on the scheduler's first run at or after 04:00 UTC, every account backup older than this is deleted; 0 in this file turns pruning off. |
schedule.enabled |
true |
Backups › Settings › Schedule System | Starts the built-in scheduler, which runs the backup schedules and the retention pruning. |
schedule.max_per_account |
3 |
Backups › Settings › Max Schedules per Account (1–20) | A schedule beyond this is refused (403 BACKUP_SCHEDULE_LIMIT). |
schedule.check_interval |
300 (seconds) |
file | Time between scheduler runs. |
new_account_schedule.enabled |
false (installer: true) |
Backups › Settings › Back up new accounts every night; the setup guide's backup step | While true, every account created from then on gets a daily schedule (files, databases and email, no remote destination). An account that already has a schedule gets none. Saving with "Also add it to existing accounts without a schedule" adds it once to every account that has no schedule. |
new_account_schedule.time |
02:00 |
the same places | The schedule's start time, HH:MM in the server's time zone. |
new_account_schedule.retention_count |
7 |
the same places | How many of its newest archives the schedule keeps (1–100). |
remote |
enabled: false, type: s3 |
— | Parsed but not used; see below. |
encrypt_archives |
false |
Backups › Settings › Encrypt backup archives | While true, every new archive is sealed right after it is made (AES-256-GCM under a key derived from auth.api_key_encryption_secret — the secret the agent generates at its first start and keeps in its vault; no second key to manage) and is kept, copied and downloaded as *.tar.gz.enc; a restore opens it on this server. Without that secret, creating and restoring sealed archives is refused (409 BACKUP_ENCRYPTION_KEY_MISSING); an archive sealed under another server's secret, or altered, is refused (409 BACKUP_DECRYPT_FAILED). Archives made while false stay plain and still restore. |
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
| Key | Default | Changed from | What it does |
|---|---|---|---|
level |
info |
file | debug, info, warning, error or critical (an unknown name means info). In production, info is recommended; use debug only for troubleshooting. |
file |
/var/log/whost/agent.log |
file | Keep the default: the service unit appends the process output to this path, the fail2ban whost-agent jail watches it and the post-update check writes to it. The file is kept at mode 640. |
max_size, keep |
100M, 10 |
file | The agent rotates the file itself when it reaches max_size (a number with an optional K, M or G; any other suffix stops the agent from starting) and keeps keep old copies. No logrotate rule covers it. |
license
license.servers lists the licence service endpoints the agent dials (HTTPS,
validated against the system CA store). On an installed agent the list is
pinned to the licence domain of the build: an address outside that domain, or
one that is not https://, is ignored with one warning in the agent log
(license.servers: N configured address(es) outside the built-in licence domain ignored (…)), and a list that is left empty by that rule falls back to the
built-in servers. Editing the key therefore cannot point an installed agent at
another peer; it exists so a development tree (plain sources, no compiled
build) can be pointed at a test service.
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.check_interval (seconds between periodic verifications, default
86400) and license.grace_period (offline tolerance measured from the last
valid verification, default 86400) accept values from 60 to 2592000
(30 days). A value outside that range fails configuration validation and the
agent does not start; correct the value and restart.
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.
defaultApplied by the limiter middleware to the few routes that carry no class of their own (deploy event streams, the update status stream, the SSO endpoints, the frontend debug beacon). /health, the panel's root files (/config.json, favicon, logo), / and the page fallback are exemptreadLimit for GET (read) endpoints, including the public GET /api/v1/auth/ip-check allowlist probe used by the login pagewriteLimit for POST, PUT, PATCH (write) endpointsdeleteLimit for DELETE endpointsheavyLimit for resource-intensive operations: backups and restores, file upload, compress and extract, Let's Encrypt orders, plugin installs, license activation, password and second-factor changes, password-reset requestsauthLimit for authentication endpoints (admin and client login, 2FA)fail2ban
| Key | Default | Changed from | What it does |
|---|---|---|---|
enabled |
true |
— | Not read: the panel manages fail2ban whenever fail2ban-client answers. |
bantime, findtime, maxretry |
3600, 600, 5 |
— | Not read: the installer writes jail.local with its own values, and per-jail changes on the Fail2Ban page go to /etc/fail2ban/jail.d/<jail>.local. |
ignoreip |
127.0.0.1/8, ::1 |
file | Shown as the whitelist only when no jail answers; the live whitelist is the jails' ignoreip set, edited on the Fail2Ban page and persisted in jail.local. |
modsecurity
WHost enforces ModSecurity on nginx (nginx and nginx_apache) and on OpenLiteSpeed (openlitespeed, through its ols-modsecurity module and the agent's copy of the rule set under /etc/modsecurity/litespeed/); on LiteSpeed Enterprise only while litespeed_enterprise below is true; 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.
| Key | Default | Changed from | What it does |
|---|---|---|---|
enabled, default_account_waf |
true, true |
file | An account that has not chosen its own WAF state gets modsecurity on in its site configuration only while both are true (picked up when the configuration is next rendered). enabled: false also makes the WAF page report the WAF as inactive. |
engine_mode |
detection_only |
WAF page | on (block), detection_only (log only) or off; rendered as SecRuleEngine. A new installation starts in detection_only; an existing one keeps the mode it has. |
crs_paranoia_level |
1 |
WAF page | OWASP CRS paranoia level, 1–4: written to the CRS setup as tx.paranoia_level (the name CRS 3.3 reads); the WAF loads the CRS rules up to it. |
audit_log |
true |
WAF page | SecAuditEngine RelevantOnly (5xx and 4xx responses except 404) or Off. |
audit_log_path |
/var/log/modsecurity/audit.log |
file | The serial audit log the WAF page reads; the installer's logrotate rule (daily, 30 kept, copytruncate) names the default path. |
owasp_crs |
true |
file | Loads the OWASP Core Rule Set from <rules_path>/crs. |
rules_path, custom_rules_path |
/etc/modsecurity, /etc/modsecurity/custom |
file | The rule set's base directory, and the custom rules directory (included only while it holds a .conf). |
per_account_overrides |
true |
file | Per-account WAF state and rule exclusions under /etc/modsecurity/accounts/; while false the account-scope WAF writes answer 409 FEATURE_DISABLED. |
litespeed_enterprise |
false |
file | Applies the rule set on LiteSpeed Enterprise, whose own WAF engine reads it from the XML configuration: a server-level rule set named WHost with the engine off there, and each site whose account WAF is on switches it on with the account's file. It stays false until the connector has been measured on a licensed server; while false LiteSpeed's files are not changed and the WAF page reports the server as not enforcing. Setting it back to false removes the WHost rule set and the sites' switch at the agent's next start or sync round (within five minutes). |
alert_command |
[] |
file | A local command the agent runs for every match of its own detection rules (the php2shell file, ids 9900100–9900119), as an argument list without a shell: <command...> <SEVERITY> <subject> <body> — WARN with the subject WAF: php2shell request refused on <host> when the engine refused the request, CRIT with … detected on <host> when it only detected it. The first element must be an absolute path. The agent follows the audit log every 15 seconds from its start and reports the same address and rule once per 30 minutes; every match also becomes a panel notification (category firewall, mail per the notification settings) and the webhook event security.waf_detection. Example for an operations tool whose alert entry point takes SEVERITY subject body: alert_command: ["/usr/bin/php8.4", "/opt/tool/alert.php"]. |
security
| Key | Default | Changed from | What it does |
|---|---|---|---|
admin_allowed_ips |
empty | Settings › Security › Admin Panel IP Whitelist | IP/CIDR entries, one per line (a YAML block string); empty allows every address. nginx answers 404 for the /admin pages from any other address, and the agent refuses admin sign-in and admin sessions from it (403 IP_NOT_ALLOWED). A save from the panel rewrites /etc/nginx/conf.d/whost-admin-geo.conf and /etc/nginx/snippets/whost-admin-ip-whitelist.conf (after nginx -t), and a changed non-empty list signs out every admin and client session; a list that leaves out your own address is refused unless you confirm it. A hand edit changes only the agent's check. |
two_factor_enforcement, two_factor_enforcement_method |
false, both |
Settings › Security › Two-Factor Authentication Enforcement | The switch and the method it demands (totp, email, or both = either). While it is on, the login and session endpoints answer requires_2fa_setup: true (with required_2fa_method) for an identity that has no second factor yet, and the panels keep that identity on its enrolment page (admin Settings › Profile, client Settings › Security) until it enrols. |
ssh_port, ssh_root_login, ssh_password_auth, ssh_key_auth, ssh_allowed_ips |
22, true, true, true, empty |
Settings › Security › SSH Access Restrictions | Written to /etc/ssh/sshd_config.d/00-whost.conf when saved from the panel (after sshd -t; a port change restarts sshd and updates the firewall and fail2ban, other changes reload it). At least one of password and key authentication stays on, and a port another service holds is refused (PORT_IN_USE). ssh_allowed_ips (one IP/CIDR per line) denies SSH logins from every other address. ssh_port is also the SSH port the firewall and Under-Attack mode protect. A hand edit does not change sshd. |
auto_configure_dkim, auto_configure_spf, auto_configure_dmarc, dmarc_policy |
true, true, true, none |
Settings › Security › DKIM / SPF / DMARC | Which mail records the agent adds when it creates an account's mail DNS: the DKIM key record, SPF (v=spf1 a mx ip4:<server_ip> ~all) and DMARC (v=DMARC1; p=<policy>; rua=mailto:postmaster@<domain>, policy none, quarantine or reject). Existing zones are not rewritten. |
host_hardening_reconcile |
true |
file | At every start the agent brings the installer's host hardening onto an installation that predates it — the 60-whost-hardening.conf sshd drop-in (forwarding withdrawn from the hosting accounts only), the Postfix per-client limits (100 messages / 30 connections per 60 s), the postfix-sasl jail, on an nginx_apache host Apache's Listen 127.0.0.1:8080, wherever Apache is installed no CGI module and no mod_fcgid (cgi, cgid, fcgid disabled with a2dismod on Ubuntu and Debian; on the RHEL family their LoadModule lines in conf.modules.d/ and mod_fcgid's conf.d/fcgid.conf commented out as # WHost - not loaded: …, the copies kept in /var/lib/whost/host_hardening-backups/; apachectl configtest first), the /etc/logrotate.d/whost rule for the frontend debug beacon logs (frontend-*.log, daily, seven kept; a rule elsewhere that already names /var/log/whost or a hand-written whost file without frontend-*.log is left alone and reported as skipped), PowerDNS's version-string=anonymous in pdns.conf (the text the server gives for a CHAOS TXT version.bind query; the service is restarted once, and a version-string set by hand is left alone), and the per-user inotify limits fail2ban needs (fs.inotify.max_user_instances 1024, fs.inotify.max_user_watches 65536 through /etc/sysctl.d/60-whost-inotify.conf, applied by systemd-sysctl; only a lower value is raised, and a key another sysctl file sets is left to that file), an open file limit of 65536 for nginx and every PHP-FPM unit (LimitNOFILE=65536:524288 through /etc/systemd/system/<unit>.d/60-whost-nofile.conf, only where the effective soft limit is lower; one daemon-reload, and the running main process is raised in place with prlimit, so nothing restarts — nginx's master opens every vhost's logs and stopped taking new configuration at a few hundred accounts under the default 1024), and on an nginx / nginx_apache host nginx's server name hash (/etc/nginx/conf.d/whost-server-names.conf: server_names_hash_max_size 8192, server_names_hash_bucket_size 128, so a host with many account domains does not fall back to a suboptimal hash; written only when nginx.conf and conf.d set neither size, kept only when nginx -t accepts it; a hand-edited copy of the file is left alone), and the PHP session defaults (99-whost-session.ini in every installed version's PHP-FPM scan directory, see the php section: written where the file is missing or still an older copy of the panel's, checked with that version's command-line PHP, then the version's PHP-FPM is reloaded; a hand-written file of that name is left alone and reported as skipped). Every step is idempotent (a host already there is left alone, no service is reloaded), each change keeps a stamped backup (the logrotate rule's under /var/lib/whost/host_hardening-backups/) and is recorded in /var/lib/whost/host_hardening.json, and a change the service's own configuration test refuses (logrotate -d for the rule) is undone on the spot. false leaves the steps to the command line: /opt/whost/venv/bin/python3 -m whost_agent.services.host_hardening_service status|apply|rollback [--dry-run] (rollback puts the recorded previous state of every step back). |
trusted_origins |
empty | file | Extra origins allowed to send cookie-authenticated writes (POST, PUT, PATCH, DELETE) whose Origin differs from the host they are sent to, whitespace separated as host[:port]. The panel calling its own API under whatever name it was opened always passes, and HMAC-signed calls are not checked; any other cross-origin write that carries a panel session cookie is refused with 403 CROSS_ORIGIN_DENIED. A literal null Origin (what a browser sends for a sandboxed frame or another opaque origin) names no host and is always refused; it cannot be listed here. |
spam_reject_threshold, spam_add_header_threshold, spam_greylist_threshold |
15, 6, 4 |
— | Not read: the spam scores are set on the Spam Filter page. |
admin
The built-in administrator, the sign-in protection of both panels and the session lifetimes.
| Key | Default | Changed from | What it does |
|---|---|---|---|
enabled |
true |
file | While false, cookie sign-in is off for both panels: the admin sign-in answers 404, admin and client session cookies are no longer accepted, and only HMAC-signed API calls are served. |
username |
admin |
file | The administrator signs in with this name or with email. |
email |
empty | Settings › Profile | Recovery address and second sign-in name of the administrator; admin notification e-mails and e-mail sign-in codes are sent to it. |
password |
set by the installer | Settings › Profile (password change) | A bcrypt hash; a plain-text value is never accepted at sign-in. A change signs out every other admin and client session. |
language |
auto |
Settings › Profile | The administrator's panel language (auto keeps the language chosen at sign-in). |
session_timeout |
3600 (seconds; installer: 3600) |
Settings › Security › Session Timeout (5–1440 minutes) | Lifetime of an admin or client session; a session in use is renewed once half of it has passed. |
remember_me_timeout |
2592000 (30 days) |
file | Lifetime of a "remember me" session, in both panels, counted from sign-in (its hard limit when longer than session_max_lifetime). |
session_max_lifetime |
604800 (7 days) |
file | Hard limit counted from sign-in, whatever the activity, in both panels; a "remember me" session lasts remember_me_timeout instead when that is longer. |
allow_concurrent_sessions |
false |
file | Off: a sign-in ends the earlier sessions of the same identity (the administrator, or that client account) and a sign-out ends them all. On: earlier sessions keep working until they time out, a sign-out ends only the session it is made in (the cookie it presented is refused from then on, in both modes), and session_max_lifetime counts from the identity's latest sign-in or sign-out; a password change still signs everyone out. |
session_secret |
set by the installer | agent | Signs admin and client session cookies. The agent replaces it when the admin password changes and when the admin IP whitelist is changed to a non-empty list; any change signs everyone out. Each replacement writes a secret_rotated audit row (Logs › Audit; the row names the secret and the reason, never a value), so the date of the last rotation is read from the audit log rather than inferred from a password or settings change. api_key_encryption_secret and the licence app_secret are never rotated by the product. |
two_factor.enabled, two_factor.method |
false, totp |
Settings › Profile | The administrator's own second factor (totp or email). |
two_factor.email |
empty | Settings › Profile | Where the administrator's e-mail sign-in codes go; it follows email unless set to another address here. |
two_factor.trusted_ip_days |
0 |
file | How long an address that passed the administrator's second factor skips it: 0 = with no expiry while sign-ins come from that address, -1 = the code is always asked, N = N days. |
two_factor.smtp_host, two_factor.smtp_port, two_factor.smtp_user, two_factor.smtp_password, two_factor.smtp_tls |
localhost, 587, empty, empty, true |
file | The relay of the sign-in code e-mails of both panels and of the client password-reset e-mail — not the relay of Settings › Notifications. With the defaults the local Postfix is used on port 25. In this release these messages are sent without SMTP authentication even when smtp_user and smtp_password are set, so smtp_host must name a relay that accepts this server without a login. |
recaptcha.enabled, recaptcha.provider, recaptcha.min_score |
false, recaptcha, 0.5 |
Settings › Security › CAPTCHA Protection | Sign-in captcha of both panels; provider recaptcha, hcaptcha or turnstile; min_score (0.0–1.0) is the reCAPTCHA v3 threshold. Switching it on requires the selected provider's site key and secret key. The public GET /api/v1/auth/captcha-config publishes only the enabled flag, the provider and its site key. |
recaptcha.<provider>_site_key, recaptcha.<provider>_secret_key |
empty | Settings › Security › CAPTCHA Protection | The key pair of each provider; the page shows secret keys masked. |
notification_smtp_password |
empty | Settings › Notifications | Password of the notification relay. The rest of that SMTP block (host, port, user name, encryption and sender) is stored in /etc/whost/notification_prefs.json; only the password is kept here. Notification e-mails use that block, then fall back to the two_factor.smtp_* keys, then to the local relay. |
two_factor.totp_secret, backup_codes, pending_*, totp_last_step, avatar_url, last_login |
— | agent | Maintained by the Profile page and the sign-in flow (the TOTP secret, hashed backup codes, an enrolment in progress, the avatar). The TOTP secret is stored sealed (enc:v1:…, AES-256-GCM under auth.api_key_encryption_secret, bound to the account name); a record written in the clear by an earlier version keeps working and is sealed the next time a sign-in or an enrolment saves it. Restoring such a record on a host with a different api_key_encryption_secret leaves the authenticator unusable: the account signs in with a backup code and sets 2FA up again. |
frontend
Static panel bundle served by nginx.
| Key | Default | Changed from | What it does |
|---|---|---|---|
public_url |
empty | file | The address the panel is reached at from outside (https://panel.example.com): the origin of the password-reset link the panel mails. When it is empty the link uses https://<server.hostname>, and only without a host name the bare https://<server_ip> — a name matches the certificate the panel serves, an address does not. Notification e-mails link to https://<server.hostname> whatever this key says. |
default_language |
auto |
Settings › General › Language Settings | auto or one of the panel's locale codes: the language of a browser that has not chosen one. Written to the panel's config.json when saved and at every agent start. |
debug_log |
false |
file | Opens the browser debug beacon route (POST /api/v1/debug-log); its file /var/log/whost/frontend-debug.log is rotated daily by /etc/logrotate.d/whost (seven copies kept), written by the installer and, where an existing installation lacks it, by the agent's start-up host hardening (security.host_hardening_reconcile). |
enabled, path |
true, /opt/whost/frontend/out |
agent | The agent's copy of the panel files; nginx serves /var/www/whost/panel, which the installer copies from it. |
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.
files
| Key | Default | Edited from | Notes |
|---|---|---|---|
max_upload_mb |
256 (MB) |
Settings › General › File Manager › Maximum Upload Size (1–10240 MB) | The largest file one File Manager upload may carry, in the admin and the client panel. The file service refuses a larger file (413 FILE_TOO_LARGE); the agent's body limit and the panel's nginx client_max_body_size on the two File Manager upload routes are this value plus 1 MB (413 PAYLOAD_TOO_LARGE above it). A save from the panel rewrites /etc/nginx/snippets/whost-panel-locations.conf and reloads nginx; a hand edit reaches the snippet at the next agent start. A value outside 1–10240 is clamped when the file is read (nginx reads 0 as no limit). The other upload routes keep 300 MB. |
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.
traffic
suspend_on_limit (default false) — what happens when an account uses up its plan's monthly traffic (bandwidth_mb; 0 is unlimited). The agent counts each account's traffic for the calendar month (UTC) from the services' logs — the body bytes of its sites' access logs, the mail it sends and receives plus IMAP sessions and POP3 retrievals, its FTP transfers — every 15 minutes, into /var/lib/whost/traffic/<YYYY-MM>.json (root, 0600); counting starts when an agent with the counter first runs, so the first month is partial. A log that appears later — a new account's or domain's access log, a transfer log written for the first time — is counted from the lines written since the previous 15-minute cycle began (by the time each line carries), so a new site's first visits are included; a log restored with older lines (a backup restore or a migration) adds only lines written after that cycle. At 80 % and at 100 % the operator and the customer get a Bandwidth Limit Warning (once per threshold per month; channels on Settings → Notifications). With suspend_on_limit: true the account is also suspended when the 100 % notice goes out; an operator who unsuspends it during the month is not overridden. FTP traffic is counted from Pure-FTPd's transfer log (AltLog clf:…), which the Debian / Ubuntu and the RHEL-family (EPEL) packages both write by default; a configuration that turns it off counts no FTP bytes. A rotated log's last lines are read from its rotated copy (<log>.1, or <log>-YYYYMMDD where logrotate uses dateext, the RHEL-family default). A changed value takes effect after an agent restart.
product_feedback
receiver_url (default https://wisecp.com) — where the admin panel's Report a bug window sends its reports and asks whether they are accepted. Only an https://host[:port] origin without a path is used; any other value keeps the window hidden. The agent asks GET <receiver>/api/v1/store/releases/whost once a day (beside its update check) with the licence key and server.server_ip, reads feedback.products.whost and keeps the answer in /var/lib/whost/product_feedback.json (root, 0600) for at most 48 hours; the record names the receiver it came from, so a changed address discards it. Reports go to POST <receiver>/api/v1/feedback. There is no local switch: the window shows only while the receiver accepts reports, the licence is active or in grace and the whitelabel brand is off. A changed value takes effect after an agent restart.
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, os_packages_auto_security, os_packages_auto_mode, os_auto_reboot, os_auto_reboot_time. os_packages_auto_security switches the operating system updates that WHost's guarded run installs every night, checked and rolled back when they break something (true | false; absent or null = never saved: the agent writes no OS file and the operating system's default stays — see OS Security Updates in the administrator guide and OS Package Channel in update-flow.md); os_packages_auto_mode is what that run installs: security (default) or all — in both, the database takes only security fixes of its own series and the kernel only security fixes. os_auto_reboot switches the night restart (true | false; absent or null = never saved: no unit is written and the server is never restarted on its own) and os_auto_reboot_time is its window in server time (HH:MM, default 04:30; the API refuses another form, a value in the file that is not HH:MM reads as the default) — see Night Restart in the administrator guide. 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 os_packages_auto_security: true, os_auto_reboot: true, 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):
- Keep a copy, for example
cp -p /etc/whost/agent.conf /root/agent.conf.bak— it holds the same secrets, so keep it at mode600. - 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.
- Check that the agent came back:
curl -sk https://127.0.0.1:2000/healthanswers{"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]
Our support team is here around the clock for anything you can't find above.