Agent CLI

Agent CLI

The Lumos Agent runs as a systemd service on your shield VPS. This page covers service management, log access, configuration details, and the agent's self-healing capabilities.

For initial installation and uninstallation, see Agent Installation. For dashboard-side server management, see Server Management.

Service Management

The agent is managed through systemd using standard commands:

# Start the agent
systemctl start lumos-agent

# Stop the agent
systemctl stop lumos-agent

# Restart the agent
systemctl restart lumos-agent

# Check current status
systemctl status lumos-agent

# Enable auto-start on boot (enabled by default after install)
systemctl enable lumos-agent

# Disable auto-start on boot
systemctl disable lumos-agent

When you stop the agent, HAProxy continues running with its current configuration. Traffic will keep flowing through the proxy, but:

• No new config updates from the dashboard will be applied (changes to domains, WAF rules, SSL settings, etc.)
• No metrics will be reported to the dashboard analytics
• The server will appear as Offline in the dashboard
• A server_down notification will be sent if configured
• DNS failover may trigger if a secondary server is configured

Tip: If you need to restart the agent (e.g., after a manual intervention), use systemctl restart lumos-agent. The agent will reconnect to the WebSocket server and perform a full config sync to catch up on any changes made while it was stopped.

Viewing Logs

Agent logs are available through journalctl:

# Follow logs in real-time (press Ctrl+C to stop)
journalctl -u lumos-agent -f

# View the last 50 log entries
journalctl -u lumos-agent --no-pager -n 50

# View logs since a specific time
journalctl -u lumos-agent --since "1 hour ago"

# View logs from today only
journalctl -u lumos-agent --since today

# View logs between two timestamps
journalctl -u lumos-agent --since "2026-02-20 10:00" --until "2026-02-20 12:00"

# Search for a specific term in logs
journalctl -u lumos-agent | grep "error"

Log Messages to Look For

Tip: When troubleshooting an issue, start with journalctl -u lumos-agent -f to watch logs in real-time, then trigger the problematic action from the dashboard (e.g., update a domain, toggle SSL). This lets you see exactly what the agent does in response.

Configuration

The agent stores its configuration in an encrypted file:

/etc/lumos/config.enc

This file is encrypted using AES-256-GCM and contains the connection token, server identity, and current domain/WAF configuration. You should never need to edit this file manually. All configuration is managed through the Lumos dashboard and pushed to the agent in real time.

Warning: Do not delete /etc/lumos/config.enc. Deleting this file will require a fresh agent installation with a new token. The agent cannot start without a valid encrypted config file.

Note: The encrypted config file is updated automatically as the agent receives configuration changes from the dashboard. It serves as the agent's local state, so if the WebSocket connection drops temporarily, the agent continues operating with the last-known configuration.

WebSocket Connection

The agent maintains a persistent WebSocket connection to the Lumos WebSocket server. This connection is used for:

• Receiving config updates -- Domain changes, WAF rule changes, SSL toggle changes
• Sending metrics -- HAProxy stats (requests per second, bytes in/out, response times, active connections) collected from the stats socket
• Reporting status -- HAProxy health, SSL certificate status (provisioning, active, expiring), error notifications
• Receiving commands -- Decommission signals, config sync requests

Auto-Reconnection

If the WebSocket connection drops (network interruption, WebSocket server restart, VPS network blip, etc.), the agent automatically reconnects using exponential backoff:

1. First retry after 1 second
2. Subsequent retries double the interval: 2s, 4s, 8s, 16s, 32s...
3. Maximum interval caps at 60 seconds
4. Retries continue indefinitely until the connection is restored

On successful reconnection, the agent requests a full configuration sync from the server to ensure it has the latest state. This handles any config changes that may have occurred while the agent was disconnected (e.g., new domains added, WAF rules changed, SSL toggled).

Note: During disconnection, HAProxy continues running with its last-known configuration. Existing traffic is not interrupted. Only new configuration changes are delayed until the connection is restored.

HAProxy Health Monitoring

The agent monitors HAProxy health by checking the process every 10 seconds:

• If HAProxy is not running, the agent attempts to restart it automatically
• If the restart fails, the agent reports a haproxy_crash error to the dashboard (triggering a server_error notification if configured)
• If HAProxy has been manually stopped, the agent will restart it on the next health check cycle

This means HAProxy downtime on your shield VPS is typically limited to under 10 seconds, even in the case of an unexpected crash.

# Manually check HAProxy status (independent of the agent)
systemctl status haproxy

# Manually validate the current HAProxy config
haproxy -c -f /etc/haproxy/haproxy.cfg

Tip: You generally should not need to manage HAProxy directly. The agent handles all HAProxy lifecycle operations including starting, reloading, health monitoring, and crash recovery. If you need to inspect HAProxy's behavior, use the logs: journalctl -u haproxy --since "10 minutes ago".

Configuration Rollback

When the agent receives a config update and generates a new HAProxy configuration:

1. The current HAProxy config is backed up in memory
2. The new configuration is written to /etc/haproxy/haproxy.cfg
3. HAProxy config is validated with haproxy -c and then reloaded
4. If the reload succeeds, the backup is discarded
5. If the reload fails, the previous configuration is immediately restored and HAProxy is reloaded with it

This ensures that a bad configuration push never takes down your proxy. The rollback happens automatically with no manual intervention required. The agent reports the failure to the dashboard, which triggers a server_error notification with details about the config_update_failed or haproxy_reload_failed event.

Note: Configuration writes and HAProxy reloads are serialized under a single mutex. This prevents race conditions when multiple config updates arrive in quick succession -- for example, when you rapidly update multiple domains or WAF rules from the dashboard.

Empty Config Protection

The agent includes a safety mechanism to prevent accidentally clearing all HAProxy configuration:

• If a config update would result in zero domains and a backup exists, the agent skips the write
• This protects against edge cases like network glitches sending empty config payloads or deserialization errors
• The agent logs an empty config rejected warning when this protection activates

This means your existing proxy configuration is preserved even if something goes wrong with the config push pipeline. The agent will continue serving traffic with the last valid configuration.

SSL Certificate Management

The agent handles SSL/TLS certificate provisioning and renewal automatically:

• When a domain has SSL enabled, the agent provisions a Let's Encrypt certificate via ACME HTTP-01
• The agent reports a provisioning status while the certificate is being obtained
• Certificates are automatically renewed before expiration
• The WebSocket server checks for expiring certificates (7-day warning) and triggers ssl_expiring notifications
• After successful renewal, an ssl_renewed notification is sent

Certificate files are stored in /etc/letsencrypt/live/ and managed entirely by the agent. See SSL/TLS for more details on the provisioning process.

WAF Script Generation

When WAF rules are pushed from the dashboard, the agent generates Lua scripts in /etc/haproxy/lua/. These scripts implement:

• IP blacklisting
• Rate limiting
• Bot protection (JavaScript challenge + HMAC cookie + bad bot UA blocking)
• OWASP pattern matching

The Lua scripts are loaded by HAProxy at reload time. You should not edit these files manually -- they are regenerated on every WAF config update.

File Reference

Warning: Do not manually edit files in /etc/haproxy/ or /etc/haproxy/lua/. These are managed by the agent and will be overwritten on the next config update from the dashboard. Use the Lumos dashboard for all configuration changes.

Resource Usage

The agent is designed to be lightweight:

• Memory: Typically 10-20 MB RSS
• CPU: Near-zero when idle, brief spikes during config generation and SSL provisioning
• Disk: ~10 MB for the binary, plus SSL certificates and Lua scripts (minimal)
• Network: Minimal -- WebSocket keepalive packets + periodic metrics reports (every few seconds)

The vast majority of resource usage on a shield VPS comes from HAProxy processing traffic, not from the agent itself. Even on a 512 MB VPS, the agent's footprint is negligible.

Common Operations Quick Reference

Next Steps

• Agent Installation -- Installation, reinstallation, and uninstallation procedures
• Server Management -- Dashboard-side server management
• Domains -- Add domains to start proxying traffic through the agent
• SSL/TLS -- Understand certificate provisioning and renewal
• WAF -- Configure web application firewall rules
• Notifications -- Set up alerts for agent and HAProxy events
• Troubleshooting -- Common issues and solutions
• Architecture -- How the agent fits into the overall system