VISULOX 5 Documentation
VISULOX 5 Documentation
Breadcrumbs

Health Check for VISULOX Portal

Purpose

The health-check command helps a system administrator verify that a VISULOX Portal installation is usable after installation, upgrade, or maintenance.

The command checks the local machine, required software, host permissions, important filesystem paths, PostgreSQL, KeyDB, REST and SOAP APIs, registered portal and connector servers, and configured LDAP or Active Directory servers.

Use this command when

  • a new portal server has been installed.

  • a portal server has been upgraded.

  • a node was joined to a cluster.

  • the portal service is running but users report login, API, session, connector, or directory problems.

  • you need a JSON health report for support or automation.

Command

Bash
/opt/visulox-portal/bin/vlx-portald health-check [flags]

If the configuration is stored in a file, pass the global config flag:

Bash
/opt/visulox-portal/bin/vlx-portald --configFile /opt/visulox-portal/configs/config.json health-check

Short form:

Bash
/opt/visulox-portal/bin/vlx-portald -c /opt/visulox-portal/configs/config.json health-check

Permissions

In host mode, run the command as root or as a user with sudo access. The command validates host-level installation paths and service files, so a normal user may not be able to inspect every required item.

Output Modes

CLI Report

The default mode prints a formatted report:

Bash
/opt/visulox-portal/bin/vlx-portald health-check

The report includes the VISULOX logo, version information, detailed tables for every check, and a final Summary section. The summary is printed at the end so it remains visible after the long report finishes in the terminal.

JSON to stdout

Use --json or -j when another tool needs structured output:

Bash
/opt/visulox-portal/bin/vlx-portald health-check --json

Short form:

Bash
/opt/visulox-portal/bin/vlx-portald health-check -j

Save JSON to a File

Use --output to write the structured report to a file:

Bash
/opt/visulox-portal/bin/vlx-portald health-check --output /tmp/visulox-health-check.json

This still prints the normal CLI report unless --no-print is also used.

Save JSON without Printing

Use --no-print with --output for automation:

Bash
/opt/visulox-portal/bin/vlx-portald health-check --output /tmp/visulox-health-check.json --no-print

--no-print is only valid when --output is provided.

What the Command Checks

Machine

The command reports:

  • VISULOX application name

  • Hostname

  • First non-loopback IPv4 address

  • Application environment

  • CPU usage

  • RAM usage

  • Root disk usage

Software

The command checks the required software list:

  • vlx-python, python, or python3

  • vlx-docker or docker in host mode

  • xpra

  • visulox, vlx-portal, or vlx-portald

  • nginx

  • python3-paramiko

  • python3.12-tkinter, python3-tkinter, or python3-tk

  • freerdp, freerdp2, freerdp3, xfreerdp, or wlfreerdp

  • jq

  • unzip

In container mode, the Docker check is skipped because Docker is required on the host, not inside the container.

Host Access

In host mode, the command verifies that the current process is running as root or can run sudo -n true. In container mode, this check is treated as available.

Filesystem

The command checks important VISULOX installation paths. In host mode, this includes paths such as:

  • /opt/visulox-portal

  • /opt/visulox-portal/bin/vlx-portald

  • /opt/visulox-portal/configs

  • /opt/visulox-portal/tls

  • /opt/visulox-portal/packages

  • /var/log/visulox-portal

  • /etc/systemd/system/vlx-portal.service

  • /etc/pam.d/vlx-portal

In container mode, it checks the container-specific portal paths such as /opt/visulox-portal/bin/vlx-portal and /opt/visulox-portal/docker-entrypoint.sh.

For each path, the report shows whether it exists, whether it is a file or directory, and whether it is readable, writable, or executable by the current process.

PostgreSQL

The command checks PostgreSQL by:

  1. Opening a write connection to the master database.

  2. Opening a read connection to the slave database, or the master database if no slave is configured.

  3. Running SELECT 1.

  4. Creating a temporary table inside a transaction.

  5. Inserting and reading a probe row.

The write probe uses a transaction and is rolled back.

KeyDB

The command checks KeyDB by:

  1. Creating a KeyDB client from configuration.

  2. Writing a temporary health-check key.

  3. Reading the key back.

  4. Deleting the key.

If KeyDB is disabled in configuration, the KeyDB section is reported as failed with a configuration message.

REST API

The command sends a local HTTP request to:

/api/v1/version

The target port and TLS setting come from the Echo Gateway configuration.

SOAP API

The command sends a local SOAP keep-alive request to:

/soap/services/document/utility

The target port and TLS setting come from the SOAP gateway configuration.

Portal and Connector Servers

The command reads registered servers from PostgreSQL:

  • portal_server

  • connector_server

For each server it prints the database status, last ping time, ping age, and interpreted live status.

Live status is interpreted as:

Condition

Result

Database status is not active

offline

Last ping is empty

offline

Last ping is less than 1 minute old

healthy

Last ping is up to 4 minutes old

warning

Last ping is older than 4 minutes

dangerous

LDAP and Active Directory

The command loads LDAP and Active Directory configuration from dynamic configuration when PostgreSQL is available. If dynamic configuration cannot be loaded, it falls back to static authorization configuration.

For each enabled LDAP or Active Directory server, the command opens an LDAP or LDAPS connection, optionally binds with the configured admin user, and optionally runs a base DN probe.

Reading the Summary

The Summary section is the fastest way to decide what to investigate first.

Status

Meaning

OK

The section passed.

WARNING

The section is usable but has stale or non-critical health signals.

FAILED

The section has a failed required check.

SKIPPED

The section was not applicable or had no configured targets.

When a section is FAILED, inspect the corresponding detailed table above the summary.

Common Problems

Missing Software

If the software summary is FAILED, install the missing package shown in the Software table, then run the command again.

Host Access Failed

Run the command as root or configure sudo for the administrator account:

Bash
sudo -n true

The command expects this to succeed in host mode.

PostgreSQL Failed

Check the database host, port, database name, username, password, and TLS settings in the VISULOX configuration. Also verify that the server can reach PostgreSQL over the network.

KeyDB Failed

Check whether KeyDB is enabled and reachable from the portal server. Verify the KeyDB host, port, password, TLS, and timeout configuration.

API Checks Failed

Check whether the REST and SOAP services are running locally and listening on the configured ports. If TLS is enabled, the command uses <https://127.0.0.1:<port>>.

Server Status is Offline or Dangerous

Check the related portal or connector service. A missing or stale last_ping_time usually means the server is not running, cannot reach PostgreSQL, or cannot update its heartbeat.

LDAP or Active Directory Failed

Check host, port, TLS mode, certificate behavior, bind user, bind password, and base DN. If the server is disabled in configuration, the command reports it as disabled and does not attempt a connection.