Traffic Settings

Traffic Settings

Traffic Settings let you control how HAProxy handles traffic for each domain. Every setting is optional — Lumos applies sensible defaults out of the box, so you only need to configure what your application requires.

All traffic settings are configured per-domain from the domain details page: Dashboard -> Domains -> click a domain -> Traffic Settings. Changes are pushed to all assigned shield servers in real time through the config push pipeline.

Tip: If you are just getting started, you do not need to configure any traffic settings. The defaults work well for most websites and APIs. Come back to this page when you need fine-grained control over load balancing, timeouts, or routing.

Load Balancing

When a domain has multiple origin servers, HAProxy distributes incoming requests across them using a load balancing algorithm. You can choose between three algorithms depending on your workload.

Round Robin (default)

Requests are distributed evenly across all origin servers in rotation. Each origin receives roughly the same number of requests over time.

Round robin is the default because it works well for the vast majority of workloads. If your origin servers have similar capacity and your application is stateless, this is the right choice.

Least Connections

Each new request is sent to the origin server with the fewest active connections. This naturally adapts to servers with different processing speeds.

Use least connections when your requests have variable processing times (some fast, some slow) or when your origin servers have different hardware specs. It prevents slow requests from piling up on one server while others sit idle.

Source IP Hash

The client's IP address is hashed to determine which origin server handles the request. The same client IP always reaches the same origin, as long as the server set does not change.

Source IP hashing provides a lightweight form of session persistence without requiring cookies. It is useful when your application stores session state on the origin server and you cannot use sticky sessions (for example, non-HTTP protocols or clients that do not support cookies).

Note: If clients share an IP address (corporate NAT, mobile carrier), they will all land on the same origin. For true per-user affinity, use sticky sessions instead.

Origin Weights

Each origin server can be assigned a weight from 1 to 256 (default: 100). The weight controls how much traffic that origin receives relative to other origins in the pool.

Example scenario: You have three origins with different capacities:

Weights work with all three load balancing algorithms. With round robin, a weight of 200 means that origin receives approximately twice as many requests as an origin with weight 100. With least connections, the weight biases the algorithm toward higher-capacity servers.

When to use weights:

• Your origin servers have different CPU, memory, or bandwidth capacities
• You want to gradually shift traffic to a new origin (start with a low weight, increase over time)
• You are running a canary deployment and want to send only a small percentage of traffic to the new version

To set a weight, edit the origin from the domain details page and adjust the Weight field.

Backup Servers

Any origin server can be marked as a backup. Backup origins only receive traffic when all non-backup (primary) origins in the pool are down.

Typical use case: You have a primary origin running your application and a backup origin running a static "maintenance mode" page or a read-only replica:

origin-1 (primary, weight 100) -- main application server
origin-2 (primary, weight 100) -- secondary application server
origin-3 (backup)              -- maintenance/fallback page server

In this setup, origin-3 only receives traffic if both origin-1 and origin-2 are down. Once any primary origin recovers, traffic automatically shifts back.

To mark an origin as a backup, enable the Backup toggle in the origin editor.

Note: Backup servers work independently from DNS failover. DNS failover switches traffic between shield servers. Backup origins switch traffic between origins behind the same shield server. You can use both together for maximum resilience.

Health Checks

Health checks allow HAProxy to automatically detect when an origin server is down and stop sending traffic to it. When the origin recovers, traffic is automatically restored.

How Health Checks Work

1. HAProxy sends a TCP connection or HTTP request to each origin at the configured interval
2. If the origin responds within the timeout, the check is marked successful
3. After rise consecutive successes, the origin is marked UP
4. After fall consecutive failures, the origin is marked DOWN and removed from the active pool
5. Traffic is redistributed to the remaining healthy origins
6. When the origin comes back and passes rise checks, it is added back to the pool

Customizing Health Checks

For most setups, the defaults are sufficient. Adjust these settings if:

• Your origin has slow startup times -- increase the interval and fall count to avoid premature removal
• You need faster detection of failures -- decrease the interval and fall count (be careful not to set these too aggressively, as brief network blips could remove healthy origins)
• Your origin's health endpoint is slow -- increase the timeout

Tip: If your application has a dedicated health endpoint (like /healthz or /status), the default TCP health check will still work correctly since it only verifies that the port is accepting connections. HTTP-level health checks are planned for a future release.

Sticky Sessions

Sticky sessions (session affinity) ensure that a user's requests are always sent to the same origin server for the duration of their session. This is essential for applications that store session state on the origin server rather than in a shared database or cache.

How Sticky Sessions Work

1. A user's first request arrives and is routed to an origin based on the load balancing algorithm
2. HAProxy inserts a cookie (LUMOSSRV by default) into the response identifying the assigned origin
3. On subsequent requests, the browser sends the cookie back and HAProxy routes the request to the same origin
4. If the assigned origin is down, HAProxy routes to a different healthy origin and updates the cookie

When to use sticky sessions:

• Your application stores sessions in memory on the origin server (PHP sessions, Express.js sessions without Redis, etc.)
• Your application uses WebSocket connections that must persist on the same origin
• You have an upload or multi-step form workflow that needs to reach the same server

When you do NOT need sticky sessions:

• Your application stores sessions in a shared database or Redis
• Your application is stateless (API with JWT authentication)
• You are serving only static content

Note: Sticky sessions require the roundrobin or leastconn algorithm. They do not work with source since source IP hashing already provides IP-based affinity.

Max Connections

The max connections setting limits the number of simultaneous connections HAProxy will send to each origin server. This protects your origins from being overwhelmed during traffic spikes.

Example: If your origin server can handle 500 concurrent connections and you set max connections to 500, HAProxy will queue additional requests instead of forwarding them, preventing your origin from being overwhelmed.

When to set a limit:

• Your origin has a known connection limit (database connection pools, application server thread limits)
• You want to prevent a traffic spike from crashing your origin
• You are running multiple domains on the same origin and want to ensure fair resource allocation

When the limit is reached, new connections are queued by HAProxy and forwarded as existing connections complete. If all origins in the pool are at their connection limit, HAProxy holds the request until a slot opens or the client timeout expires.

Custom Timeouts

Timeouts control how long HAProxy waits at each stage of the connection lifecycle. The defaults are tuned for typical web applications, but you may need to adjust them for specific workloads.

When to Adjust Timeouts

Increase server timeout for:

• Long-running API requests (report generation, file processing, AI inference)
• Server-Sent Events (SSE) or long-polling endpoints
• Large file uploads or downloads

Increase client timeout for:

• Slow clients on mobile networks
• Large file uploads where the client may take time to send data
• WebSocket connections that may be idle for extended periods

Decrease connect timeout for:

• Fast-fail scenarios where you want to quickly move to a backup origin if the primary is unreachable
• Internal network origins where connections should establish in milliseconds

Example for an AI inference API:

Warning: Setting timeouts too low will cause requests to fail prematurely. Setting them too high wastes resources on connections that are likely dead. Start with the defaults and only adjust based on observed behavior.

Custom Headers

Custom headers let you add, set, or remove HTTP headers on requests forwarded to your origin servers. This is useful for passing metadata, authentication tokens, or identifying traffic that comes through Lumos.

Common Use Cases

Identifying Lumos traffic at the origin:

Passing authentication to the origin:

Removing headers before forwarding:

You can add up to 20 custom headers per domain. Headers are applied in order and processed by HAProxy before the request reaches the origin.

Tip: Lumos automatically forwards standard proxy headers like X-Forwarded-For, X-Forwarded-Proto, and X-Real-IP. You do not need to add these manually. The client's real IP is always available via the CF-Connecting-IP header if you use Cloudflare in front of your shield, or X-Forwarded-For otherwise.

Path Routing

Path routing lets you send different URL paths to different origin servers. This is useful for microservice architectures where different services handle different parts of your application under a single domain.

Example: Microservice Routing

You have example.com with three backend services:

In this setup:

• example.com/api/users is forwarded to api-server:3000/users (prefix stripped)
• example.com/docs/getting-started is forwarded to docs-server:8080/docs/getting-started (prefix preserved)
• example.com/about is forwarded to frontend:3000/about (default route)

Path Routing Rules

• Paths are matched by longest prefix first -- more specific paths take priority
• The default route (path /) catches everything that does not match a more specific rule
• If strip prefix is enabled, the matched prefix is removed from the path before forwarding
• Path routing works with all other traffic settings (load balancing, health checks, headers, etc.)
• Each path route can have its own set of origins with independent weights and health check settings

Note: Path routing is available on the Pro plan and higher. Free plan domains use a single origin pool for all paths.

Redirect Rules

Redirect rules let you define URL redirects at the HAProxy level, before requests reach your origin server. This is useful for URL migrations, domain consolidation, or enforcing canonical URLs without modifying your application.

Common Redirect Scenarios

Redirecting old URLs after a migration:

Enforcing www or non-www:

Temporary maintenance redirects:

Redirect Rules Behavior

• Redirects are processed before path routing -- a matching redirect takes priority
• Up to 50 redirect rules per domain
• Redirect rules support exact path matching and prefix matching
• The redirect is sent directly by HAProxy as an HTTP response -- the request never reaches the origin server, which means zero-latency redirects

Tip: Use 301 (permanent) redirects for URL changes that are meant to be permanent. Search engines will update their indexes. Use 302 (temporary) for redirects you plan to remove later. Using the wrong status code can cause search engine indexing issues.

Defaults Reference

All traffic settings are optional. If you do not configure a setting, these defaults are applied:

These defaults are designed to work well for typical web applications, APIs, and static sites. You only need to adjust them when your workload has specific requirements.

Next Steps

• Domains -- Add and configure domains with origin servers and SSL
• WAF -- Protect your domains with firewall rules and rate limiting
• Multiple Servers -- Assign domains to multiple shields for redundancy
• Failover -- Set up automatic DNS failover for high availability
• Plans -- Compare plan features including path routing availability
• Architecture -- Understand how config changes reach your servers