Skip to content

Diagnose a host

When a management server or a KVM node stops working as expected, one command checks the usual causes and tells you what to fix. Run it as root on the host you want to check:

Terminal window
curl -fsSL https://packages.virtconsole.com/diagnose.sh | sudo bash

It works on Ubuntu, Debian and AlmaLinux (and other RHEL-compatible systems). You do not need to tell it what the host is: it detects whether it is a management server, a KVM node or both, and finds the install directory and the service user by itself.

  • Operating system: SELinux and AppArmor, disk space and inodes, memory and swap, recent out-of-memory kills, time synchronization.
  • Web stack: nginx and PHP-FPM installed, running and enabled, their ports, the user they run as, and permission errors in their logs.
  • Application: file ownership and permissions of the install directory, the .env file, the queue workers under supervisor, the scheduler cron, and errors logged in the last hour.
  • Management server: the database and Redis, the WebSocket and console proxies, the mail transport, the panel URL and its TLS certificate, failed jobs, and whether every node runs the same version as the panel.
  • KVM node: libvirt and the node services, the agent on port 2443, and the link to the panel (master.json).

Each check prints one line:

Status Meaning
PASS The check is fine.
WARN Something to fix soon; the host still works.
FAIL Something that breaks the panel or the node now.
INFO Context, no action needed.

Every WARN and FAIL comes with a fix: line that says what to do. The run ends with a summary and a short list of the top problems, most important first.

The exit code is 0 when everything passed, 1 when there are only warnings, and 2 when at least one check failed.

Everything shown on screen is also written to a log file, and the last line tells you where:

Send this file to support: /var/log/virtconsole-diagnose/diagnose-<host>-<time>.log

Attach that file to your support ticket. The log file is readable by root only.

The command only reads. It does not restart services, change permissions, or edit or delete files; the log file is the only thing it writes. Secrets are never printed or logged: passwords, tokens, keys and similar values are shown as <redacted>.

Pass options after bash -s --, for example:

Terminal window
curl -fsSL https://packages.virtconsole.com/diagnose.sh | sudo bash -s -- --quiet
Option What it does
--quiet Show only WARN and FAIL lines on screen (the log still has everything).
--no-color Plain output, for copying into a ticket.
--json Machine-readable output.
--role master or --role slave Check as a management server or as a KVM node instead of detecting it.
--app-dir DIR Install directory, if it is not /opt/virtconsole.
--log PATH or --no-log Write the log to a file of your choice, or not at all.
--help Show all options.