SSL / TLS

Overview

Lumos Gate provides fully automatic SSL certificate management through Let's Encrypt. When you enable SSL on a domain, the agent running on your shield server provisions a trusted certificate using the ACME HTTP-01 challenge, configures HAProxy to serve HTTPS, and handles renewals automatically. No manual certificate management, no configuration files to edit, no expiry surprises.

SSL is free for all plans and there is no limit on the number of certificates you can provision.

How It Works

The SSL provisioning flow:

1. You enable the SSL toggle for a domain in the dashboard (or set ssl_enabled: true via the API).
2. The config change is pushed to the agent via the real-time pipeline (Dashboard -> WebSocket Server -> Agent).
3. The agent sets the domain's SSL status to Provisioning and reports this to the dashboard.
4. The agent initiates an ACME HTTP-01 challenge with Let's Encrypt.
5. Let's Encrypt sends an HTTP request to http://yourdomain.com/.well-known/acme-challenge/<token> to verify ownership.
6. The agent responds to the challenge on port 80, receives the certificate, and stores it on disk.
7. HAProxy is reloaded with the new certificate active.
8. All HTTP traffic for that domain is automatically redirected to HTTPS via a 301 redirect.

The entire process typically completes in 10-30 seconds.

Dashboard (SSL toggle ON)
    |
    v
WebSocket Server -> Agent
    |
    v
Agent sets status = "provisioning"
    |
    v
ACME HTTP-01 challenge initiated
    |
    v
Let's Encrypt verifies http://domain/.well-known/acme-challenge/
    |
    v
Certificate issued and stored at /etc/letsencrypt/live/<domain>/
    |
    v
HAProxy reloaded with certificate
    |
    v
HTTPS active, HTTP -> HTTPS 301 redirect enabled

Prerequisites

Before enabling SSL on a domain, make sure all of the following conditions are met:

1. DNS Must Point to the Shield VPS

The ACME HTTP-01 challenge requires Let's Encrypt to reach your shield server by making an HTTP request to your domain on port 80. If DNS is not pointing to the shield VPS IP, the challenge will fail because the request will go to the wrong server.

See the DNS Setup guide for step-by-step instructions on configuring your DNS records.

How to verify:

dig +short yourdomain.com
# Expected output: your shield VPS IP address
# Example: 203.0.113.10

If the output shows your origin IP or a different address, update your DNS before enabling SSL.

2. Port 80 Must Be Open

The HTTP-01 challenge uses port 80 to verify domain ownership. HAProxy listens on port 80 by default after the agent is installed, so this should already be the case. However, if you have a host-level firewall (iptables, ufw, or cloud provider security group), make sure port 80 is allowed for inbound TCP traffic.

How to verify from another machine:

curl -v http://yourdomain.com
# Should connect (even if it returns a 503 or redirect, the connection itself must succeed)

3. Domain Must Be Added to Lumos

The domain needs to exist in your Lumos dashboard with at least one origin server configured. SSL cannot be enabled on a domain that has not been created yet.

4. Cloudflare Proxy Must Be Disabled

If you use Cloudflare for DNS, the Cloudflare proxy (orange cloud) must be turned off for the domain. Cloudflare's proxy intercepts the ACME challenge request and prevents it from reaching your shield VPS. Set the record to DNS only (grey cloud). See the Cloudflare section of the DNS Setup guide for details.

Warning: If you are migrating from another provider, update your DNS records first and wait for propagation (verify with dig) before enabling SSL. Attempting to provision a certificate before DNS has propagated will result in a failed challenge.

Enabling SSL

1. Navigate to Dashboard -> Domains.
2. Select the domain you want to secure.
3. Toggle the SSL switch to enabled.
4. The status will show Provisioning while the certificate is being issued (typically 10-30 seconds).
5. Once complete, the status changes to Active with the certificate expiry date displayed.

No other configuration is needed. The agent handles the entire ACME flow, certificate storage, HAProxy configuration, and HTTPS redirect setup automatically.

Disabling SSL

To disable SSL on a domain:

1. Navigate to the domain details page.
2. Toggle the SSL switch to disabled.
3. The config push removes the HTTPS binding from HAProxy.
4. Traffic will be served over HTTP only.

The certificate files remain on disk at /etc/letsencrypt/live/<domain>/ but are no longer referenced by HAProxy. If you re-enable SSL later, a new certificate will be provisioned (the old files are not reused).

Provisioning States

The SSL status for each domain follows this lifecycle:

The status transitions:

Disabled -> Provisioning -> Active (success)
                        \-> Failed (error)

HTTPS Redirect

When SSL is active on a domain, HAProxy automatically redirects all HTTP (port 80) traffic to HTTPS (port 443). This is handled at the proxy level by HAProxy, so your origin server does not need any redirect configuration.

The redirect uses a 301 Moved Permanently status code, which browsers and search engines cache. This ensures:

• All traffic is encrypted without any additional setup on your end
• Search engines index the HTTPS version of your pages
• Users who bookmark or type http:// are automatically sent to https://

Note: The ACME HTTP-01 challenge path (/.well-known/acme-challenge/) is excluded from the redirect during certificate provisioning and renewal. This is handled automatically by the agent.

Auto-Renewal

Let's Encrypt certificates are valid for 90 days. The Lumos agent handles renewal automatically:

• Certificates are renewed 30 days before expiry (at the 60-day mark).
• Renewal uses the same ACME HTTP-01 process -- no downtime, no manual intervention.
• If renewal fails, it retries automatically on subsequent attempts.
• When a certificate is successfully renewed, the agent sends an ssl_renewed status message to the dashboard.
• The WebSocket server's health check (running every 5 minutes) checks SSL expiry dates.
• The dashboard sends an ssl_expiring notification 7 days before expiry if a certificate has not been renewed, giving you time to investigate.

Warning: If your shield VPS is offline or unreachable when renewal is due, the certificate cannot be renewed. Make sure your shield servers stay online and connected to the Lumos WebSocket server. If a server goes offline, you will receive a server_down notification to alert you.

Renewal Timeline

Dashboard Monitoring

The domain detail page shows the current SSL status for each domain:

• Certificate expiry date -- When the current certificate expires (90 days from issuance)
• Provisioning status -- Real-time status updates during initial provisioning
• Expiry warnings -- Visual warning indicator when a certificate is within 7 days of expiry

Notification Alerts

You can configure notification alerts for SSL events in Dashboard -> Settings -> Notifications:

Notifications can be delivered via email and/or webhook. See the Notifications page for configuration details.

Certificate Storage

Certificates are stored on each shield VPS at:

/etc/letsencrypt/live/<domain>/
  fullchain.pem    # Certificate + intermediate chain
  privkey.pem      # Private key

HAProxy is configured to use these certificate files. The agent manages the symlinks and file paths automatically -- you should not need to touch these files manually.

Warning: Do not manually modify or delete certificate files. The agent manages the certificate lifecycle. Manual changes may be overwritten on the next config push or renewal.

Troubleshooting

Certificate provisioning stuck on "Provisioning"

This usually means the ACME challenge is failing silently. Check the following:

1. Verify DNS points to the shield VPS:

   dig +short yourdomain.com
   # Must return your shield VPS IP, e.g., 203.0.113.10

2. Ensure port 80 is open on the shield VPS:

   curl -v http://yourdomain.com
   # Connection must succeed (any HTTP response is fine)

3. Check that the agent is connected: The server should show "Online" status in the dashboard (Dashboard -> Servers). If it shows "Offline", the agent is not connected and cannot receive the SSL config push.

4. Check for Cloudflare proxy: If using Cloudflare, make sure the proxy (orange cloud) is disabled. The record must show a grey cloud (DNS only). See DNS Setup.

Certificate provisioning failed

Common causes:

• Let's Encrypt rate limits: Let's Encrypt allows a maximum of 50 certificates per registered domain per week. If you are testing repeatedly with the same domain, you may hit this limit. Wait a week or use a different subdomain for testing.
• DNS not propagated: The domain must resolve to the shield VPS IP globally, not just from your local DNS. Use dig @8.8.8.8 yourdomain.com +short to check from Google's DNS.
• Cloudflare proxy enabled: Cloudflare intercepts HTTP requests when the proxy (orange cloud) is active, preventing the ACME challenge from reaching the agent.
• Port 80 blocked: A firewall, security group, or the VPS provider may be blocking inbound port 80. Check with your VPS provider.

HTTPS not working after enabling SSL

• Allow time: Give 30 seconds for the certificate to be provisioned and HAProxy to reload.
• Clear browser cache: Browsers aggressively cache redirect and certificate information. Try an incognito/private window.
• Verify with curl:

  curl -vI https://yourdomain.com
  # Look for "SSL certificate verify ok" in the output

• Check certificate details:

  echo | openssl s_client -connect yourdomain.com:443 -servername yourdomain.com 2>/dev/null | openssl x509 -noout -dates
  # Shows notBefore and notAfter dates

Certificate renewal failed

• Ensure the shield VPS is online and the agent is connected (check Dashboard -> Servers for "Online" status).
• Verify port 80 is still open -- some VPS providers reset firewall rules after reboots.
• Check that DNS still points to the shield VPS (DNS records may have been changed accidentally).
• If the agent was offline during the renewal window, it will retry automatically once it reconnects.

"Too many certificates" error

Let's Encrypt enforces rate limits. If you see this error:

• You have issued too many certificates for the same domain in a short period.
• Wait one week for the rate limit to reset.
• For testing, use Let's Encrypt's staging environment (not currently exposed in the Lumos dashboard -- this is a future feature).

Multiple Shield Servers

If a domain is assigned to multiple shield servers, the SSL certificate is provisioned independently on each server. Each agent runs its own ACME challenge and maintains its own certificate copy. This means:

• No shared storage needed -- There is no need for shared certificate storage or a central certificate authority between servers.
• Independent renewal -- Each server can independently renew its certificate on its own schedule.
• Fault isolation -- If one server goes down, others continue serving HTTPS without interruption. The downed server will renew its certificate when it comes back online.
• Identical certificates -- While each server provisions separately, Let's Encrypt will issue functionally identical certificates (same domain, same trust chain) to each server.

Note: When using DNS failover, only the server currently receiving traffic needs a valid certificate. However, it is best practice to keep certificates active on all assigned servers so failover transitions are seamless.

SSL with WAF

SSL and WAF features work together seamlessly:

• HAProxy terminates SSL at the shield VPS, then applies WAF rules (IP blacklist, rate limiting, bot protection) to the decrypted traffic.
• This means WAF rules can inspect HTTP headers, request bodies, and other Layer 7 content even for HTTPS traffic.
• The bot protection JS challenge is served over HTTPS when SSL is active.

SSL with WireGuard

If you use a WireGuard tunnel between the shield VPS and origin, the full traffic path is:

User -> HTTPS -> Shield VPS (SSL termination) -> WireGuard tunnel -> Origin

SSL is terminated at the shield VPS. Traffic between the shield and origin travels over the encrypted WireGuard tunnel, so it does not need to be HTTPS on the origin side. You can point the origin to an HTTP port (e.g., 10.0.0.2:80), keeping your origin configuration simple.

TLS Versions & Ciphers

HAProxy handles TLS termination on the shield VPS. The agent configures HAProxy with a modern TLS setup automatically -- no manual cipher configuration is needed.

Clients using TLS 1.0 or 1.1 (very old browsers, legacy systems) will fail to connect. This is intentional -- TLS 1.0 and 1.1 are deprecated and have known vulnerabilities. All modern browsers and HTTP clients support TLS 1.2 or higher.

The cipher suite and TLS configuration are managed entirely by the agent when it generates the HAProxy config. There is no dashboard setting to change cipher preferences. If you have specific compliance requirements (e.g., TLS 1.3 only), contact support for Enterprise plan options.

Next Steps

• DNS Setup -- Required before enabling SSL; configure DNS records to point to the shield VPS
• Domain Management -- Add and manage domains where SSL is applied
• Notifications -- Configure alerts for SSL expiry warnings and renewal events
• Failover -- Automatic DNS failover keeps HTTPS available even if a shield goes down
• Multiple Servers -- SSL on multi-server domain assignments
• WAF -- Firewall rules that work alongside SSL
• WireGuard -- Encrypt the shield-to-origin connection
• Troubleshooting -- General troubleshooting guide for common issues