Multiple Servers

Multiple Servers

Lumos Gate supports assigning a single domain to multiple shield servers. This provides geographic distribution, redundancy, and the ability to fail over traffic if one server goes down. Each server receives the full configuration for all domains assigned to it, so any server can serve traffic at any time with zero cold-start delay.

Why Use Multiple Servers

• Geographic coverage -- Place shield servers close to your users. A server in Frankfurt serves European users with lower latency, while a server in Ashburn handles North American traffic.
• Redundancy -- If one shield server goes down, others can take over. Combined with DNS Failover, traffic automatically reroutes to a healthy server.
• Load distribution -- Spread traffic across multiple shields to avoid overloading a single VPS, especially useful for high-traffic sites.
• Provider diversity -- Use servers from different providers to avoid being affected by a single provider's outage. See VPS Providers for recommended options.

Plan Limits

The number of servers you can add depends on your plan:

The Free plan supports only one server, so multi-server setups require a Pro or Enterprise plan. See Plans for the full comparison and Credits & Billing for payment details.

Setting Up Multiple Servers

Step 1: Add Servers

Navigate to Dashboard -> Servers -> Add Server for each shield VPS. Give each server a descriptive name that includes the region and provider for easy identification:

Examples:
  "EU Frankfurt"
  "US East"
  "Asia Singapore"

Each server gets a unique connection token. Install the Lumos Agent on each VPS using that token:

curl -fsSL https://get.lumosgate.com/install | LUMOS_TOKEN=YOUR_TOKEN bash

Warning: Each server token is shown only once at creation. Copy it immediately and store it in a secure location. Tokens are hashed (SHA-256) before storage and cannot be retrieved later. If you lose a token, you must decommission the server and create a new one.

The agent installer also runs edge-setup.sh, which tunes the VPS kernel for high-performance reverse proxy workloads (BBR, conntrack, huge pages). Use the LUMOS_NO_TUNE=1 flag to skip this step if you prefer to manage kernel tuning yourself.

Wait until each server shows as Online in Dashboard -> Servers before proceeding.

Step 2: Assign Domains to Multiple Servers

When creating or editing a domain in Dashboard -> Domains, select multiple servers from the server list. The system stores the many-to-many relationship between domains and servers.

Each selected server receives the full domain configuration, including:

• Origin IP addresses and ports
• SSL/TLS settings (certificates are provisioned independently on each server)
• WAF rules (IP blacklist, rate limiting, OWASP patterns)
• Bot protection settings (JS challenge, bad bot UA blocking)

The first server in the assignment list is treated as the primary. All remaining servers are secondaries. This distinction matters for DNS Failover -- during normal operation, DNS points to the primary, and the secondaries are on standby.

Step 3: Configure DNS

You have two options for DNS configuration, depending on whether you want automatic failover.

Option A: Automatic Failover (Recommended)

Configure your DNS provider integration (Cloudflare) so Lumos Gate can update records automatically when a server goes down. Point your domain's A record to the primary server:

Type    Name              Value               TTL
A       example.com       <PRIMARY_SHIELD_IP>  300

See DNS Failover for the complete setup guide.

Option B: Manual DNS Round-Robin

For basic load distribution without automatic failover, add multiple A records pointing to each shield server:

Type    Name              Value               TTL
A       example.com       <SHIELD_1_IP>       300
A       example.com       <SHIELD_2_IP>       300

Warning: DNS round-robin distributes traffic roughly evenly but does not provide health-check-based failover. If one server goes down, DNS resolvers will continue sending traffic to the dead server until the record is manually removed. For production use, DNS Failover is strongly recommended.

How Config Sync Works

When you update a domain's configuration in the dashboard, the change is pushed to all assigned servers simultaneously:

1. The dashboard API route saves the config change to the database
2. A push message is sent for each assigned server
3. The WebSocket server receives the messages and forwards them to the correct agents
4. Each agent generates the updated HAProxy config, writes it (under a mutex lock), validates it, and reloads HAProxy with zero downtime

Dashboard API
     |
     v
Config Push -> WS Server -> Agent 1 -> HAProxy reload
            -> WS Server -> Agent 2 -> HAProxy reload
            -> WS Server -> Agent 3 -> HAProxy reload

All servers receive the update within seconds of the dashboard change. If an agent is temporarily disconnected (e.g., network blip or server reboot), it requests the full configuration upon reconnecting to the WebSocket server. This ensures agents are always eventually consistent, even after outages.

Tip: If a HAProxy reload fails on one server (e.g., due to a config syntax issue), the agent automatically rolls back to the previous working configuration and reports a server_error notification of type haproxy_reload_failed. The other servers are not affected.

Multi-Server with Failover

The most common multi-server pattern is primary/secondary failover:

Primary server:    EU Frankfurt (handles all traffic normally)
Secondary server:  US East (standby, receives config but no traffic)

Normal:   DNS -> Frankfurt shield -> Origin
Failover: DNS -> US East shield   -> Origin
Recovery: DNS -> Frankfurt shield -> Origin

Both servers have the full configuration and are ready to serve traffic at any time. The secondary server is not idle -- it has HAProxy running with the correct config, SSL certificates provisioned, and WAF rules active. When failover triggers, traffic switches instantly without any cold-start delay.

How Failover Decides Which Server to Use

1. The health check cycle (every 5 minutes) evaluates the primary server
2. If the primary has been unseen for more than 120 seconds or has a status of offline/error, it is considered down
3. The first healthy secondary is selected as the failover target
4. The DNS A record is updated from the primary IP to the secondary IP via the Cloudflare API
5. When the primary recovers, DNS is switched back automatically

See DNS Failover for the full lifecycle, timing details, and configuration steps.

Managing Multiple Servers

Server Status

Each server's status is visible in Dashboard -> Servers:

Per-Server Metrics

Analytics are collected per-server, so you can see traffic, request rates, error rates, and bandwidth for each shield VPS independently in Dashboard -> Analytics. Metrics flow from the HAProxy stats socket through the agent to the WebSocket server, which stores them for dashboard display. See Architecture for the full data flow.

Detected Sites

When you install the agent on a server that already has HAProxy running, the agent parses the existing HAProxy configuration and sends the detected sites to the dashboard. You can then import these sites as Lumos-managed domains without reconfiguring them from scratch. See Detected Sites for details.

Decommissioning a Server

To remove a server from your setup:

1. Navigate to Dashboard -> Servers -> [Server] -> Decommission
2. The server is soft-deleted (status set to decommissioned)
3. A decommission message is sent to the WebSocket server
4. The WebSocket server cleans up the agent connection after a 1-hour grace period
5. Domains assigned only to this server need to be reassigned or will lose proxy coverage

Warning: Before decommissioning, ensure any domains assigned to this server are also assigned to at least one other active server. Otherwise, traffic to those domains will be interrupted. If the server was the failover primary, DNS will remain pointing to its IP until you manually update it or assign a new primary.

On the VPS itself, you can run the uninstall script to cleanly remove the agent and restore the original HAProxy configuration:

lumos-uninstall

Private Networks and WireGuard

If your shield servers and origin servers are connected via a private network (e.g., WireGuard tunnel), you can use private IP addresses as origin targets. Lumos Gate allows the following private ranges as origin IPs:

• 10.x.x.x (WireGuard, VPN)
• 172.16-31.x.x (Docker networks)
• 192.168.x.x (private LAN)
• 127.x.x.x (localhost -- useful for same-server proxying)

Only non-routable addresses (0.0.0.0, 169.254.x.x, fe80:) are blocked.

See WireGuard and Origin Firewall for setting up private connectivity between shield servers and origins.

Best Practices

• Use different providers -- Do not put all your shields on the same VPS provider. If one provider has an outage, servers on other providers can still serve traffic.
• Match regions to users -- Place shields near your largest user base. If most of your users are in Europe, your primary should be in Europe.
• Keep configs in sync -- Lumos Gate handles this automatically, but verify that all servers show the correct domain count in the dashboard after making changes.
• Set up notifications -- Enable notifications for server_down, server_error, and failover_triggered on all servers so you are aware of any issues immediately.
• Test failover regularly -- Periodically stop the agent on your primary server (systemctl stop lumos-agent) to verify that failover works correctly and your secondary picks up traffic.
• Monitor server_error alerts -- Repeated haproxy_reload_failed errors on one server may indicate a server-specific issue (disk full, permissions, etc.) that does not affect other servers.
• Plan for capacity -- Each shield server should be capable of handling your full traffic load alone, since during a failover event, one server will serve all traffic.

Next Steps

• DNS Failover -- Configure automatic failover between servers
• Agent Installation -- Install the agent on new shield VPS servers
• VPS Providers -- Recommended DDoS-protected VPS providers
• Detected Sites -- Import existing HAProxy sites from new servers
• Notifications -- Get alerts when servers go offline or errors occur
• WireGuard -- Set up private tunnels between shields and origins
• Plans -- Compare plan features and server limits