Multi-Gateway Setup Guide

Introduction

This guide explains how to configure multiple Main Gateways in a Visulox Cluster to improve availability, load distribution, and fault tolerance.

This document assumes:

• A Visulox Master is already installed and operational.

• At least one Gateway has already been configured.

• UI4 and Dashboard are accessible through the existing Gateway.

For general cluster installation instructions, refer to the Visulox Cluster Installation Guide.

Architecture Overview

In a multi-gateway deployment:

• Each Gateway has its own Connector entry in Portal.

• All Gateways connect to the same Master.

• External traffic can be distributed across Gateways using DNS round-robin, load balancers, or reverse proxies.

Creating Additional Gateway Connectors

Each Gateway requires its own Connector definition in Portal.
To create this record, first generate a Connector secret on the Master server.

Run the following command on the Master server:

sudo /opt/visulox-portal/bin/vlx-portald \
  create-maingateway-connector \
  -c /opt/visulox-portal/configs/config.json \
  --output json \
  --name gateway-a

Example:

{
  "secret":"63301a03-3c1b-4ec5-9590-a84961304ba2"
}

Create one connector per Gateway:

--name gateway-a
--name gateway-b
--name gateway-c

Each command returns a unique secret.

Store each secret securely.

Installing Additional Gateway Nodes

Install the Main Gateway package on every Gateway server:

sudo dnf install vlx-main-gateway-*.rpm -y

The dedicated Main Gateway package is recommended for Gateway-only deployments.

Configuring Gateway Nodes

The Gateway setup command supports three configuration methods:

• Interactive mode

• Command-line mode

• JSON file mode

Interactive Mode

Run:

sudo /opt/visulox-portal-connector/bin/vlx-connectord setup-maingateway

The setup wizard prompts for all required configuration values.

Use:

• The Connector secret created for this Gateway.

• The public hostname of this Gateway.

• The Master Portal hostname and port.

• The desired XPRA route type.

Command-Line Mode

Run:

sudo /opt/visulox-portal-connector/bin/vlx-connectord setup-maingateway \
  --main-server-host master.company.com \
  --main-server-port 8080 \
  --gateway-host gateway-a.company.com \
  --gateway-port 443 \
  --connector-secret <SECRET> \
  --xpra-route-type safe

Parameters:

Example:

sudo /opt/visulox-portal-connector/bin/vlx-connectord setup-maingateway \
  --main-server-host master.company.com \
  --main-server-port 8080 \
  --gateway-host gateway-a.company.com \
  --gateway-port 443 \
  --connector-secret 63301a03-3c1b-4ec5-9590-a84961304ba2 \
  --xpra-route-type safe

JSON File Mode

Generate a template file:

sudo /opt/visulox-portal-connector/bin/vlx-connectord setup-maingateway \
  --get-template /tmp

This creates a template JSON file in the specified folder.

Populate the generated file with the required values.

Example:

{
  "connector_secret": "",
  "gateway_host": "",
  "gateway_port": "8180",
  "main_server_host": "",
  "main_server_port": "8080",
  "dns_resolver": "127.0.0.11",
  "xpra_route_type": "safe"
}

Run the setup using the file:

sudo /opt/visulox-portal-connector/bin/vlx-connectord setup-maingateway \
  -f /path/to/gateway-config.json

Optionally remove the file automatically after successful setup:

sudo /opt/visulox-portal-connector/bin/vlx-connectord setup-maingateway \
  -f /path/to/gateway-config.json \
  -remove-file-after-setup

This mode is recommended for automated deployments and configuration management tools.

Verifying Gateway Registration

On each Gateway:

cat /etc/nginx/includes/visulox-gateway-main-upstream-servers.conf

Verify that the Master server appears in the generated upstream configuration.

Verify NGINX configuration:

sudo nginx -t

Verify service status:

sudo systemctl status nginx
sudo systemctl status visulox-portal-connector

Portal Failure Behavior

If one Gateway becomes unavailable:

• Existing sessions routed through that Gateway may disconnect.

• New sessions can be established through healthy Gateways.

• Master and Worker nodes continue operating normally.

For high availability, at least two Portal Server are recommended.

Validation Checklist

For every Gateway verify:

• Gateway setup completed successfully.

• Connector secret is unique.

• NGINX configuration is valid.

• UI4 login page opens.

• Dashboard opens.

• Native Client sessions start successfully.

• Web Client sessions start successfully.

• Worker-hosted applications launch correctly.

Test access using:

https://<gateway-host>

Repeat the validation for every configured Gateway.

Recommendations

Production deployments should use:

• 2 or more Main Gateways

• 2 or more Portal Servers

Place the Main Gateways behind a load balancer or DNS round-robin configuration to improve availability and distribute incoming traffic.