Skip to content

Performance tuning

The management server runs the web panel, the node API that every hypervisor polls, the queue workers, Redis and usually the database, often on a small machine. From version 3.3.9 the panel sizes and configures those pieces for the machine it runs on, so a fresh install or an update leaves the server fast without a manual tuning pass.

This page covers what is tuned, the notice you may see on the dashboard, how to run the tuning yourself, and how large the server should be for your fleet.

The tuning runs at the end of an install, a reconfigure and every update. Running it again is safe: it only changes what differs from the wanted state, checks each change before it takes effect, and reloads services gracefully instead of restarting them.

Area What it does
PHP web pool Serves people (the admin and customer panels). Sized from the server’s CPU cores and RAM: roughly two workers per core plus two, never less than 6 on a normal host, and capped so the pool uses at most about 15 percent of RAM at 64 MB per worker. Workers start on demand and are recycled after 500 requests.
PHP nodes pool A second pool with its own socket that serves hypervisor traffic (node polling and the cluster controller). It runs at a lower CPU priority, so a burst of node calls can no longer hold the worker a person is waiting for. Sized at cores plus two (minimum 4), capped at about 10 percent of RAM.
nginx routing The panel’s nginx site sends node traffic to the nodes pool and everything else to the web pool. People and nodes no longer queue behind each other.
OPcache Compiled PHP is kept in memory for both pools, which cut the time each request spends loading code from about 130 ms to about 55 ms in measurements on the shipped build. It is switched on per pool only after a health check on your server proves the installed build runs correctly with it, and it falls back to off on its own if a later check fails. See Turn OPcache off.
Graceful reloads PHP is reloaded with a 60 second grace period for requests in flight, and the new configuration is validated before the reload. Requests that are mid-flight finish normally when the panel updates.
gzip nginx compresses JSON, JavaScript, CSS and text responses larger than 1 KB. Full page loads are typically several hundred KB, so this noticeably cuts transfer time over slow links.
Log rotation The panel’s own logs (nginx access log, PHP access and slow logs, cron log) rotate daily and keep 14 copies, so they stop growing without limit.
MariaDB (local database only) When the database runs on the management server itself, the buffer pool is raised from the 128 MB default to about 20 percent of RAM (between 256 MB and 4 GB), and in-memory temporary tables to 64 MB. The slow query log is switched on for statements over one second, sampled at one in ten, and rotated weekly.

The access logs for both pools include the request path and duration, so a later look at where time goes can rank by page.

  • It does not overwrite a setting you changed by hand. If a value is already set in your own configuration (a pool size, a gzip directive, an innodb_buffer_pool_size, a process_control_timeout), the tuning leaves it alone and says so in its output.
  • It does not touch a remote database. If the database is on another server, the MariaDB step is skipped.
  • It does not restart MariaDB, nginx or PHP. It reloads, and only after the new configuration passed its own check. A change that needs a MariaDB restart (a larger buffer pool the server cannot grow while running) waits for the next restart you do yourself.
  • It does not rewrite a PHP pool someone changed. A distribution pool whose pm settings are still the package defaults is converted; one changed by hand is reported, not converted (see fpm_pool_unmanaged below).
  • It writes small files of its own next to the originals (a drop-in file, a marked block in the panel’s nginx site, a logrotate rule) so removing the tuning is a matter of deleting those.

To stop the panel managing any of this, set VC_HOST_TUNING=off in the panel’s .env file. With that set the tuning changes nothing.

The dashboard notice: “Some performance settings on this server were left unchanged”

Section titled “The dashboard notice: “Some performance settings on this server were left unchanged””

When the tuning meets something it deliberately did not change, it tells you instead of staying silent. Admins then see this notice at the top of the admin dashboard:

Some performance settings on this server were left unchanged. Applying them can make the panel faster.

  • Details lists one entry per finding: what was left alone, the file and value involved, the entry’s code, and a How to fix block with the exact commands for this server (its install directory, its PHP binary, its php-fpm service). Copy puts the commands on the clipboard.
  • Learn more opens this page.
  • Dismiss hides the notice for you only. It comes back when the set of codes changes, for example when a new finding appears.

The panel keeps working while the notice shows. Only admins see it; customers never do.

The same list, with the result of each tuning step, is on System > Host tuning. Check again there re-reads the server in the background and updates the list without changing anything, so an entry you fixed disappears without waiting for the next update. Two codes, mariadb_restart_pending and fpm_pool_unmanaged, can only be decided by a full run as root, so they clear after you run the tuning again (see Run the tuning by hand) or after the next update.

Run the commands in a How to fix block as root on the management server. The examples below use /opt/virtconsole and /usr/bin/php8.3; the notice shows the path and PHP binary of your own server.

What the notice says. OPcache is switched off for php-fpm by file (opcache.enable=0), so PHP recompiles every file on every request. The pool cannot turn it back on.

How to fix. Set the line to 1 in the file the notice names, reload php-fpm and run the tuning, which runs its health check and switches OPcache on for both pools:

Terminal window
sed -i -E 's/^(\s*opcache\.enable\s*=).*/\1 1/' /etc/php/8.3/fpm/conf.d/99-disable-jit.ini
systemctl reload php8.3-fpm
cd /opt/virtconsole && /usr/bin/php8.3 artisan hypervisor:host-tuning

On AlmaLinux, Rocky Linux and other EL hosts the file is under /etc/php.d/ and the service is php-fpm (systemctl reload php-fpm). Only the opcache.enable line changes; opcache.enable_cli and the JIT settings are left as they are.

If OPcache was switched off on purpose (for example after an encoded build crashed with it on), leave the file as it is and dismiss the notice.

What the notice says. The nginx site file was left unchanged because it is not safe to edit as root (the reason, for example “is writable by group or others” or “is not owned by root”). Without the edit the panel gets no compression and no separate pool for node calls.

How to fix. Make the site a regular file owned by root that only root can write, then run the tuning. The notice prints only the lines your file needs:

Terminal window
chown root:root /etc/nginx/sites-enabled/virtconsole.conf
chmod 0644 /etc/nginx/sites-enabled/virtconsole.conf
cd /opt/virtconsole && /usr/bin/php8.3 artisan hypervisor:host-tuning

If the site is a symbolic link outside the panel directory, has a second hard link, or sits in a directory other users can write to, edit the file it points to as its owner (or replace it with a regular root-owned file) and then run the tuning. If you manage nginx with your own tooling, you can add the equivalent settings yourself instead: a map on the request path that sends /api/v1/slave/ and /api/internal/cluster-controller/ to the nodes socket, plus a gzip on; block.

What the notice says. logrotate is not installed, so the panel and nginx logs are never rotated and grow until the disk is full.

How to fix. Install logrotate and run the tuning, which writes the rotation rule:

Terminal window
# Debian and Ubuntu
apt-get install -y -o Dpkg::Options::=--force-confold logrotate
# AlmaLinux, Rocky Linux and other EL hosts
dnf install -y logrotate
cd /opt/virtconsole && /usr/bin/php8.3 artisan hypervisor:host-tuning

Rotation starts on the next daily run. A log that is already several GB is compressed on that first run, which is disk-heavy; rotate it by hand at a quiet time if you prefer.

What the notice says. MariaDB settings were written to its drop-in but the running server still holds the old values until it restarts, followed by the settings that wait (for example a larger buffer pool while the server has little free memory, or a MariaDB release that cannot grow the pool while running).

How to fix. Restart MariaDB at a quiet time; it drops database connections for a few seconds, so the panel and node reporting pause briefly. Then run the tuning to clear the entry:

Terminal window
systemctl restart mariadb
cd /opt/virtconsole && /usr/bin/php8.3 artisan hypervisor:host-tuning

The tuning never restarts the database itself.

What the notice says. The php-fpm pool file file was not converted to the tuned pools (the reason, for example “it sets pm.max_children” or “the file has pools other than www”), so php-fpm keeps its distribution defaults.

The tuning converts a distribution pool only while its pm settings are still the package defaults. A pool that was changed by hand, holds other pools, or cannot be found is left alone, and the second pool for node traffic is not created.

How to fix. Either set the values yourself in the [www] section of that file (the notice gives the pm.max_children sized for your server):

pm = ondemand
pm.max_children = 6
pm.process_idle_timeout = 10s
pm.max_requests = 500

or restore the distribution’s pool file and let the tuning convert it:

Terminal window
cd /opt/virtconsole && /usr/bin/php8.3 artisan hypervisor:host-tuning

This entry is information only. It is listed on System > Host tuning and never raises the dashboard notice.

What it says. The database runs on another server (host), so its memory settings are not tuned from here. Size innodb_buffer_pool_size on that server.

What to do. On the database server, set innodb_buffer_pool_size to about 60 percent of its free memory. If a managed service hosts the database, use its own tuning controls.

Run these on the management server as root, from the panel’s directory (/opt/virtconsole on a standard install):

Terminal window
php artisan hypervisor:host-tuning --dry-run
php artisan hypervisor:host-tuning
  • --dry-run shows what would change and writes nothing. Use it first on a server you have tuned yourself.
  • The plain command applies the tuning. For each step (php-fpm, nginx, mariadb, and opcache when it ran) it prints a status, the changes it made, notes about things it left alone, and warnings.
  • It exits non-zero only if a step failed. It changes nothing unless it runs as root, and nothing at all when VC_HOST_TUNING=off.
  • It records the result of the last real run, which the dashboard notice and System > Host tuning read, and prints each finding with its code and the commands to fix it.

On a host with more than one PHP version installed, the tuning follows the PHP that the running web server actually uses, not the one on the command line.

OPcache is the one tuning step with its own off switch, because it is the one that changes how the application code itself runs. The panel checks it on your server before turning it on, and turns it back off if a later check fails, but you can also force it off.

  1. Edit storage/app/opcache-switch.json in the panel directory and set "mode": "off". If the file does not exist yet, create it containing {"mode": "off"}.
  2. Run php artisan hypervisor:host-tuning. Both pools are written back to off, PHP is reloaded gracefully, and the state files record off.

A mode of off is kept across updates; the panel never turns OPcache back on while it is set. To re-enable it, set the mode to auto (or remove the line) and run the tuning again, which re-runs the health check.

To disable all tuning, not only OPcache, use VC_HOST_TUNING=off.

The panel’s load is mostly the hypervisors, not people. Every node polls the panel continuously (security group feeds, health, task callbacks), so the number of nodes drives the baseline load, and customers and admins add bursts on top. The queue workers (about 50 supervised processes on a full install, most of them PHP) also share the machine, and each holds memory.

Nodes Recommended management server Notes
Up to 5 2 vCPU, 4 GB RAM Fine with the tuning applied. Local database is fine.
6 to 15 4 vCPU, 8 GB RAM The measured 12-node panel on 2 vCPU and 3.9 GB ran at a load of about 10 on two cores with the stock configuration, so treat 2 vCPU as the floor here only with the tuning applied and low customer traffic.
16 to 40 8 vCPU, 16 GB RAM Consider moving the database to its own server or to a larger local buffer pool.
More than 40 Measure Start from 8 vCPU and 16 GB, put the database on a separate host, and size the pools from the dashboard load.

Other points that apply at any size:

  • Memory comes first. The PHP pools are sized so the web pool takes at most about 15 percent of RAM and the nodes pool about 10 percent. Queue workers, Redis and the database take the rest. A server that swaps is the sign to add RAM before adding cores.
  • Disk. Keep room for logs and the database. With rotation on, the panel’s logs stay bounded.
  • Local or separate database. A local database is simplest. Move it to its own host when the buffer pool you would want is more than a fifth of the machine’s RAM.