Domains

Domain Management

Domains are the central resource in Lumos Gate. Each domain represents a website or service that you want to protect by routing its traffic through your shield servers. When you add a domain, Lumos configures HAProxy on the assigned shield servers to proxy traffic from the internet to your origin server, keeping your origin IP hidden from the public.

The typical traffic flow for a managed domain:

User -> DNS -> Shield VPS (HAProxy + WAF + SSL) -> Origin Server

Adding a Domain

Navigate to Dashboard -> Domains -> Add Domain and fill in the required fields:

Click Create Domain to save. The configuration is pushed to the assigned shield server's agent within seconds via the real-time config pipeline.

Important: After adding a domain, you must update your DNS records to point the domain to your shield VPS IP address. See DNS Setup for detailed instructions. Without correct DNS, traffic will not reach the shield server.

Domain Validation Rules

The following validations are enforced when creating a domain:

What Happens After Creation

When you create a domain, the system performs these steps atomically:

1. The domain record is inserted into the database
2. The domain-server assignments are created, linking the domain to the selected server(s)
3. The plan limit is verified inside the same transaction (preventing race conditions)
4. A config push is triggered to all assigned servers
5. Each server's agent receives the update, regenerates the HAProxy configuration, and reloads HAProxy

The entire process from clicking "Create Domain" to live HAProxy configuration typically completes in under 2 seconds.

Editing a Domain

From the domain details page (Dashboard -> Domains -> click a domain), you can modify:

• Origin servers -- Add, remove, or edit origin IP:port pairs using the inline Origin Editor
• Server assignments -- Add or remove shield servers (multi-server requires Pro plan)
• SSL -- Toggle automatic SSL/TLS on or off
• WAF settings -- Enable/disable the WAF per-domain and set the WAF level (low, medium, or high)

Changes are pushed to all assigned agents immediately via the real-time config pipeline:

Dashboard API -> WebSocket Server -> Agent -> HAProxy reload

Tip: Domain editing is available even on frozen accounts. This is by design -- if your account is frozen due to insufficient balance, you can still make emergency origin changes (for example, pointing to a different origin IP if your origin server moves). You cannot, however, create new domains or delete existing ones while frozen.

Origin Editor

The Origin Editor provides inline editing for origin servers on the domain details page:

Multiple origins can be configured for a single domain (up to 20). HAProxy will load-balance traffic across them using round-robin by default.

Traffic Settings

The Traffic Settings panel gives you fine-grained control over how HAProxy handles traffic for each domain. You can configure load balancing algorithms (round robin, least connections, or source IP hash), origin weights, backup servers, health checks, sticky sessions, and connection limits -- all from the domain details page.

For applications with specific requirements, you can also set custom timeouts (connect, server, and client), add custom HTTP headers to requests forwarded to your origins, define path-based routing to send different URL paths to different origin servers, and create redirect rules that are processed at the HAProxy level with zero latency.

All traffic settings are optional. Lumos applies smart defaults that work well for typical web applications, so you do not need to configure anything unless your workload requires it. Changes are pushed to all assigned shield servers in real time through the config push pipeline.

For a complete reference of all available settings, defaults, and detailed examples for each feature, see the dedicated Traffic Settings page.

WAF Settings

You can configure per-domain WAF settings through the domain edit endpoint:

• waf_enabled -- Boolean toggle to enable or disable the WAF for this specific domain
• waf_level -- One of low, medium, or high, controlling the aggressiveness of request filtering

For more granular WAF configuration (IP blacklists, rate limits, bot protection rules), use the dedicated WAF dashboard.

Multi-Server Assignment

A single domain can be assigned to multiple shield servers. This provides:

• Redundancy -- If one shield server goes down, others continue serving traffic
• Geographic distribution -- Place shields close to users in different regions for lower latency
• Failover -- Combined with DNS failover, traffic automatically switches to healthy servers when a primary goes down

To assign a domain to multiple servers, edit the domain and select additional servers from the server list. The configuration is pushed to all selected servers simultaneously.

Note: Multi-server assignment requires the Pro plan or higher. On the Free plan, each domain can only be assigned to a single server.

Real-Time Config Push

When you create, update, or delete a domain, the changes flow through the system in real time:

Dashboard API
     |
     v
WebSocket Server
     |
     v
Agent (via WebSocket connection)
     |
     v
HAProxy config regenerated + reloaded (zero-downtime)

This entire process typically completes in under 2 seconds. There is no polling or scheduled sync -- the agent receives the update and applies it immediately. HAProxy performs a graceful reload, so existing connections are not dropped.

For domain deletion, a separate notification is sent to all relevant agents to remove the domain from their HAProxy configuration. The server IDs are included in the message so only the affected agents act on it.

Config Safety

The agent applies several safety measures when updating HAProxy configuration:

• Backup before write -- The current working config is backed up before any change
• Validation -- The new config is validated with haproxy -c -f before being applied
• Rollback on failure -- If the reload fails, the previous config is restored automatically
• Mutex serialization -- All config writes and reloads are serialized under a single mutex to prevent race conditions
• Empty config protection -- If the new config would have 0 domains and a backup exists, the write is skipped

See the Architecture page for more details on the config sync pipeline.

SSL

When SSL/TLS is enabled on a domain, the agent automatically:

1. Sets the domain's SSL status to "provisioning" in the dashboard
2. Starts an ACME HTTP-01 challenge listener on port 80
3. Requests a certificate from Let's Encrypt for the domain
4. Stores the certificate at /etc/letsencrypt/live/<domain>/
5. Configures HAProxy to use the certificate for HTTPS traffic
6. Enables automatic HTTP-to-HTTPS redirect (301)
7. Reloads HAProxy to activate the certificate

Certificate renewal is handled automatically 30 days before expiration. The dashboard sends notifications (ssl_expiring) if a certificate is within 7 days of expiry and has not been renewed.

Warning: SSL provisioning requires that port 80 is accessible from the internet and that the domain's DNS already points to the shield VPS. If DNS is not configured, the ACME HTTP-01 challenge will fail. Always set up DNS before enabling SSL.

See the SSL/TLS page for the full provisioning lifecycle, troubleshooting, and multi-server certificate details.

Private IP Support

Lumos Gate allows private and internal IP addresses as origins, making it compatible with VPN and container networking setups:

Common private IP scenarios:

• WireGuard tunnels -- Shield VPS connects to origin over an encrypted WireGuard tunnel, origin uses a 10.x address. This is the most secure setup because origin traffic never traverses the public internet.
• Docker networks -- Origin runs in a Docker container on the same VPS or a linked host using 172.x addresses.
• Localhost -- Origin runs on the same VPS as the shield (useful for testing or single-server setups).

Tip: For production setups, consider using a WireGuard tunnel between the shield VPS and origin. This encrypts the proxy-to-origin traffic and allows you to lock down the origin firewall to only accept WireGuard connections. See Origin Firewall for details.

Deleting a Domain

To delete a domain:

1. Navigate to the domain details page (Dashboard -> Domains -> click the domain)
2. Click Delete Domain
3. Confirm the deletion in the confirmation dialog

Deleting a domain triggers the following actions:

1. The domain record is deleted from the database (cascading to server assignment entries)
2. A deletion notification is sent to all relevant agents with the server IDs
3. Each affected agent removes the domain from its HAProxy configuration
4. HAProxy reloads on each server to apply the removal
5. SSL certificates for the domain are left on disk at /etc/letsencrypt/live/<domain>/ but are no longer used

Warning: Domain deletion is immediate and cannot be undone. If you need the domain again later, you will need to add it from scratch and re-provision the SSL certificate. Consider exporting your configuration before deleting domains if you want a backup.

Note: Deleting a domain requires an active account. Frozen accounts cannot delete domains -- only edit existing ones.

Server Limits

All plans include unlimited domains. The main limit is the number of shield servers you can connect, which depends on your plan:

If you need more servers, upgrade your plan for a higher server limit.

Importing Existing Sites

If your shield VPS had HAProxy running before you installed the Lumos Agent, you can import those existing sites automatically instead of adding them one by one. The agent detects the pre-existing configuration during installation.

See the Detected Sites guide for full details on how detection works, how to review detected sites, and how to import them.

Best Practices

• Point to the origin's direct port. If your origin runs a web server on port 8080 behind its own reverse proxy (like nginx on port 80), point Lumos to port 8080 directly. Avoid double-proxying when possible, as it adds unnecessary latency and complicates header forwarding.

• Always enable SSL. SSL/TLS certificates are free and automatic via Let's Encrypt. There is no reason to leave SSL disabled for production domains. Certificate provisioning completes in seconds.

• Assign multiple servers for important domains. For any production domain, assign at least two shield servers across different regions. This provides redundancy and enables DNS failover if one shield goes down. Multi-server requires the Pro plan.

• Lock down your origin firewall. After confirming traffic flows correctly through the shield, configure your origin server's firewall to only accept connections from your shield VPS IP addresses. This prevents attackers from bypassing the shield by connecting directly to the origin. See Origin Firewall for step-by-step instructions.

• Use private networks when possible. If your origin and shield VPS are with the same provider or connected via VPN, use a private network (WireGuard or provider VLAN) for the origin connection. This avoids exposing origin traffic on the public internet and provides an additional layer of security.

• Set up notifications. Configure notification alerts for server downtime, SSL expiry warnings, and failover events so you are alerted immediately when something needs attention.

• Export your config regularly. Use the config export feature to back up your domain configurations, WAF rules, and server assignments. This gives you a recovery path if you ever need to rebuild.

IPv6 Support

Lumos Gate supports IPv6 addresses as origin servers. You can use IPv6 origins alongside or instead of IPv4 origins.

When adding an IPv6 origin, use bracket notation in the origin IP field (e.g., [2001:db8::1]). The agent and HAProxy handle IPv6 origins natively.

Note: DNS failover currently manages A records (IPv4) only. AAAA records are not automatically updated during failover events. If your shield VPS has both IPv4 and IPv6, ensure the A record is configured for failover purposes.

TCP Passthrough (Layer 4)

Lumos Gate primarily operates in HTTP mode (Layer 7), where HAProxy terminates SSL and inspects HTTP traffic for WAF rules, header manipulation, and path routing. However, the agent also supports TCP passthrough mode for pre-existing HAProxy configurations.

In TCP passthrough mode, HAProxy routes traffic based on the TLS SNI (Server Name Indication) header without terminating SSL. The encrypted connection passes directly through to the origin server:

User -> Shield VPS (HAProxy SNI routing) -> Origin Server (SSL termination)

TCP passthrough sites are detected automatically when you install the agent on a VPS that already has HAProxy running. See Detected Sites for how to review and import these configurations.

Note: New domains created through the dashboard always use HTTP mode (Layer 7) with automatic SSL. TCP passthrough is only available for imported pre-existing configurations. If you need TCP passthrough for a new domain, configure it manually in HAProxy and the agent will detect it on the next restart.

Next Steps

• DNS Setup -- Configure DNS records to route traffic through your shield server
• SSL/TLS -- Enable automatic HTTPS with Let's Encrypt
• WAF -- Protect your domains with firewall rules
• Bot Protection -- Block bad bots with JS challenges and UA filtering
• Multiple Servers -- Assign domains to multiple shields for redundancy
• Failover -- Set up automatic DNS failover
• Origin Firewall -- Lock down your origin to only accept shield traffic
• Detected Sites -- Import existing HAProxy sites automatically
• Traffic Settings -- Configure load balancing, timeouts, headers, path routing, and redirects
• Plans -- Compare plan features and server limits