Purpose
The repair-setup command lets a system administrator fix specific, known-bad setup configuration on a Visulox Portal host without hand-editing the database or reinstalling the server.
Use it when a wrong value captured during installation — most commonly the hostname — leaves the Portal partially or fully unreachable, so the Dashboard cannot be used to correct the configuration.
The command connects to PostgreSQL directly (like the config CLI) and works even when the Portal HTTP service is down.
Related article: For post-repair validation, see Health Check for Visulox Portal.
When to use
-
Installation or first start failed because the hostname or related setup values are wrong.
-
The Portal UI or Dashboard is unavailable, but the host and database are still reachable.
-
Emulator or session launch fails with NGINX host-resolution errors after a hostname change that was not applied everywhere.
-
You need a supported, guided recovery path instead of manual database or config edits.
Permissions
Run the command with effective user ID 0. On an installed Portal host:
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname
The sudo check runs before Portal configuration is loaded or a database connection is opened.
Prerequisite: Real DNS for the new Hostname
Before repairing a hostname, ensure the new hostname has a real DNS record. The command cannot create DNS.
dig +short <new-hostname> @<your-dns-server>
An /etc/hosts entry alone is not sufficient. NGINX resolves emulator session targets through its own resolver and never reads /etc/hosts. If the name exists only in /etc/hosts, the Dashboard may look fine but sessions fail with HTTP 502 and errors such as <hostname> could not be resolved in /var/log/nginx/error.log.
The command warns when a hostname appears to resolve only via /etc/hosts. Do not ignore that warning.
Command hierarchy
-
repair-setup-
update-hostname-
--hostname <new-hostname> -
--old-hostname <previous-hostname> -
--yes
-
-
Additional repair operations may be added as sibling subcommands under repair-setup in future releases.
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname --help
If the default config file is not detected, pass the global config flag:
sudo /opt/visulox-portal/bin/vlx-portald --configFile /opt/visulox-portal/configs/config.json repair-setup update-hostname
What update-hostname updates
The repair identifies stale values that still hold the previous hostname and updates every layer that duplicates hostname identity at setup time, including:
-
OS hostname (
hostnamectl) -
Visulox configuration keys in vlx-core (authoritative) and the Portal mirror
-
portal_server,connector_server, andapp_serverrows where hostname, DNS name, or address matched the old value -
directory_treeentries for portal, connector, and application server objects -
Portal and Connector
config.jsonhostname-related fields -
Connector NGINX includes (refresh and reload)
-
Loki log host labels when configured
-
vlx-core cluster FQDN via
visulox cluster set fqdnwhen vlx-core is installed on the host
Each step after the confirmation prompt reports its own outcome. Non-fatal failures are warnings with guidance; fatal validation failures abort before any change is made.
Flags
|
Flag |
Meaning |
|---|---|
|
|
New hostname. Skips the interactive prompt when provided. |
|
|
Previous hostname to match stale records against. Required to re-run safely after a partial failure (see below). |
|
|
Assume yes for every confirmation prompt. Required for unattended runs: without |
Interactive example
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname
Current hostname: vlx-old.example.com
Enter new hostname: vlx-new.example.com
Checking hostname...
✓ Hostname is valid
✓ DNS resolution successful
The following configuration will be updated:
- System hostname
- Portal configuration
- Related internal configuration
Continue? [y/N]: y
Updating configuration...
✓ Hostname updated
✓ Configuration updated
✓ Required services restarted
Setup repaired successfully.
Non-interactive usage
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname --hostname vlx-new.example.com --yes
Re-running after a partial failure
Stale records are matched using the previous hostname, but the OS hostname is changed early in the run. If a later step fails, the machine may already show the new hostname, so a plain re-run would match nothing.
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname --hostname vlx-new.example.com --old-hostname vlx-old.example.com
Re-running is safe: records are rewritten only when they still hold a recognized old value.
vlx-core
When vlx-core is installed on the host, the repair updates the recorded peer FQDN with:
visulox cluster set fqdn -fqdn <new-hostname>
The vlx-core logical name is never renamed; only the announced address is updated. The repair runs this step before changing the OS hostname, then restarts vlx-core.
If set fqdn fails because the new name does not yet resolve to this machine, the repair continues and prints the manual command to run once DNS is in place:
cd / && sudo visulox cluster set fqdn -fqdn <new-hostname> && sudo visulox stop && sudo visulox start
Failure behavior
-
Everything before the confirmation prompt is read-only. Validation failure or declining confirmation leaves the system untouched.
-
If rewriting a
directory_treeDN would collide with an existing row, the command aborts before writing anything. -
If configuration writes fail after the OS hostname was changed, the OS hostname change is rolled back automatically.
-
Once the OS hostname and Portal DB-backed config succeed, later steps (Connector config, NGINX, service restarts, vlx-core) are best-effort warnings and do not undo the applied fix.
Verification
After a repair:
hostname
hostname -f
/opt/visulox-portal/bin/vlx-portald health-check -c /opt/visulox-portal/configs/config.json
Confirm:
-
hostnameandhostname -fshow the new value. -
The health check reports healthy sections.
-
Any warnings from the repair command (especially vlx-core or service restart) are addressed.
-
A user can launch an application or emulator session from the Dashboard — the end-to-end proof that DNS and configuration are consistent.