Agent Installation

Agent Installation

The Lumos Agent is a lightweight Go binary (~10MB) that runs on your shield VPS. It manages HAProxy configuration, provisions SSL certificates, generates WAF rules, and maintains a persistent WebSocket connection to the Lumos dashboard for real-time config updates.

For day-to-day agent management (service control, logs, health monitoring), see Agent CLI.

Requirements

• OS: Debian 12+ or Ubuntu 24.04+ (x86_64 or arm64). See Supported OS for the full compatibility list.
• Access: Root or sudo privileges
• Network (outbound): HTTPS (port 443) to reach the Lumos WebSocket server
• Network (inbound): Ports 80 and 443 open for incoming HTTP/HTTPS traffic (required for proxying and SSL certificate provisioning via ACME HTTP-01)
• Token: A server connection token from the Lumos dashboard (see Server Management)

Warning: If ports 80 or 443 are blocked by your VPS provider's firewall or security group, SSL certificate provisioning will fail because Let's Encrypt cannot reach the ACME HTTP-01 challenge endpoint. Make sure both ports are open before installing.

Installation

First, create a server in the dashboard (Dashboard -> Servers -> Add Server) and copy the connection token. Then SSH into your VPS and run:

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

What the Installer Does

The installation script performs the following steps in order:

1. System check -- Verifies the operating system (Debian 12+ / Ubuntu 24.04+), architecture (x86_64 or arm64), and root access
2. HAProxy installation -- Installs HAProxy from the official repository if it is not already present
3. HAProxy backup -- Backs up the existing HAProxy configuration to /etc/haproxy/haproxy.cfg.lumos-backup
4. Agent download -- Downloads the Lumos Agent binary to /usr/local/bin/lumos-agent
5. Uninstall script -- Places the lumos-uninstall script at /usr/local/bin/lumos-uninstall
6. Config initialization -- Creates the encrypted config file at /etc/lumos/config.enc using AES-256-GCM encryption
7. Systemd service -- Registers lumos-agent as a systemd service and enables it for auto-start on boot
8. Kernel tuning -- Runs edge-setup.sh to optimize kernel parameters for high-performance proxying (can be skipped with LUMOS_NO_TUNE=1)
9. Agent start -- Starts the agent, which connects to the Lumos WebSocket server

Installer Flags

# Force install with kernel tuning skipped
curl -fsSL https://get.lumosgate.com/install | LUMOS_TOKEN=YOUR_TOKEN LUMOS_FORCE=1 LUMOS_NO_TUNE=1 bash

Existing HAProxy Detection

If HAProxy is already installed and configured before you install the Lumos agent, the installer will detect it and display information about the existing configuration:

Existing HAProxy configuration detected:
  Frontends: 3
  Backends:  5
  Config lines: 127

The existing config will be backed up to:
  /etc/haproxy/haproxy.cfg.lumos-backup

Continue? [y/N]

Use LUMOS_FORCE=1 to skip this prompt and proceed automatically. The original configuration is always backed up regardless of whether you use LUMOS_FORCE=1.

After installation, detected sites from your existing HAProxy configuration can be imported into Lumos through the dashboard. The agent parses your backup config, extracts domain-to-origin mappings (both HTTP and TCP passthrough), and sends them to the dashboard. See Detected Sites for the import workflow.

Tip: You do not lose your existing HAProxy setup. The backup is preserved at /etc/haproxy/haproxy.cfg.lumos-backup, and the uninstaller can restore it. Meanwhile, you can selectively import existing sites into Lumos management to get WAF, SSL, and analytics for them.

Kernel Tuning (edge-setup.sh)

By default, the installer runs edge-setup.sh, which applies kernel optimizations for high-throughput reverse proxying:

• TCP BBR -- Enables BBR congestion control for better throughput and lower latency
• Connection tracking -- Increases conntrack table size for handling many concurrent connections
• Huge pages -- Configures huge pages for HAProxy memory efficiency
• Network buffers -- Tunes TCP buffer sizes for high-bandwidth proxying
• Reboot persistence -- Installs a systemd service that re-applies tuning on every boot

These settings allow even a small VPS to handle 1M+ requests per second under optimal conditions.

When to skip tuning (LUMOS_NO_TUNE=1):

• Container environments (LXC, OpenVZ) where kernel parameters cannot be modified
• Providers that restrict sysctl access (some shared hosting environments)
• Situations where you already have custom kernel tuning applied
• Development/testing environments where performance is not critical

# Install without kernel tuning
curl -fsSL https://get.lumosgate.com/install | LUMOS_TOKEN=YOUR_TOKEN LUMOS_NO_TUNE=1 bash

For more information on VPS selection and performance considerations, see VPS Providers.

Verifying the Installation

After installation, verify the agent is running:

# Check service status -- should show "active (running)"
systemctl status lumos-agent

# View recent logs -- look for "connected to websocket server"
journalctl -u lumos-agent --no-pager -n 20

# Check if the agent is connected
journalctl -u lumos-agent | grep "connected"

The server should appear as Online in the Lumos dashboard within a few seconds of the agent starting.

You can also verify HAProxy is running:

# HAProxy should be active
systemctl status haproxy

# Test HAProxy config validity
haproxy -c -f /etc/haproxy/haproxy.cfg

For more log inspection commands and understanding log messages, see Agent CLI.

File Locations

Warning: Do not manually edit /etc/haproxy/haproxy.cfg or files in /etc/haproxy/lua/. These are managed by the agent and will be overwritten on the next config update. All configuration should be done through the Lumos dashboard. If you need to make manual HAProxy changes, consider using the config export feature first.

Uninstalling

The installer places an uninstall script on the system. To remove the Lumos Agent:

lumos-uninstall

The uninstall process:

1. Stops the lumos-agent systemd service
2. Disables the service from auto-start
3. Validates the HAProxy backup by running haproxy -c -f /etc/haproxy/haproxy.cfg.lumos-backup to ensure the backup is a valid configuration
4. Restores the original HAProxy configuration from the backup (only if validation passes)
5. Reloads HAProxy with the restored configuration
6. Removes the agent binary, uninstall script, and configuration files

Warning: The uninstaller validates the backup configuration with haproxy -c before restoring it. If the backup is invalid (e.g., it references backends or certificates that no longer exist), the restore step is skipped and you will need to manually configure HAProxy. The current Lumos-managed configuration is not removed until the backup is validated.

Important: Before uninstalling, make sure to decommission the server in the dashboard first. If you uninstall the agent without decommissioning, the dashboard will show the server as Offline and continue to expect it to reconnect. Decommission first, then uninstall.

Reinstalling

To reinstall the agent (e.g., after an update or to reset the configuration):

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

The LUMOS_FORCE=1 flag tells the installer to overwrite the existing installation without prompting. The previous HAProxy backup is preserved.

Note: When reinstalling, use the same token as the original installation. Using a different token would require creating a new server entry in the dashboard. If you want a fresh start, decommission the old server first, create a new one, and install with the new token.

Troubleshooting

Agent is not connecting:

• Verify the token is correct (check the token prefix displayed in the dashboard matches the first characters of your token)
• Ensure outbound HTTPS (port 443) is not blocked by a firewall: curl -I https://lumosgate.com should succeed
• Check the agent logs for specific error messages: journalctl -u lumos-agent -f
• If you see "authentication failed," the token may have been copied incorrectly or the server was decommissioned

HAProxy is not starting:

• Check HAProxy logs: journalctl -u haproxy -f
• Validate the config manually: haproxy -c -f /etc/haproxy/haproxy.cfg
• The agent will automatically attempt to rollback to the previous config if a reload fails
• If ports 80/443 are already in use by another process (e.g., Apache, Nginx), HAProxy cannot bind to them. Stop the conflicting service first.

Installation fails on older OS:

• Lumos requires Debian 12+ or Ubuntu 24.04+. Older versions are not supported. See Supported OS.
• Ensure curl, systemctl, and apt are available on the system

SSL certificates not provisioning:

• Ensure port 80 is open and reachable from the internet (ACME HTTP-01 needs it)
• Check that DNS for the domain points to the shield VPS IP, not the origin
• See SSL/TLS for detailed SSL troubleshooting

Agent connected but domains not working:

• Verify the domain is assigned to this server in the dashboard
• Check that DNS points to the shield VPS IP
• Verify the origin server is reachable from the shield VPS: curl -I http://ORIGIN_IP:ORIGIN_PORT from the VPS

For additional help, see the Troubleshooting guide.

Next Steps

• Agent CLI -- Manage the agent service, view logs, understand health monitoring and rollback
• Detected Sites -- Import existing HAProxy sites after installation
• Server Management -- Manage servers in the dashboard
• Domains -- Add your first domain to start proxying traffic
• SSL/TLS -- Understand automatic certificate provisioning
• WAF -- Enable web application firewall rules for your domains
• Supported OS -- Full list of compatible operating systems
• Troubleshooting -- Common issues and solutions