Configuration: reverse proxying

This page documents directives for forwarding incoming HTTP requests to one or more upstream backend servers. It supports load balancing, connection pooling with keep-alive reuse, health checking, circuit breaking, and TLS upstream connections.

Directives

Reverse proxy and load balancing

• proxy (http-proxy)
  • This directive configures the reverse proxy with one or more upstream backends. Supports block form with nested directives or shorthand form with upstreams as arguments. Default: none
• upstream <url: string> (http-proxy)
  • This directive specifies a backend upstream server URL. Accepts http:// or https:// URLs. Can be nested inside a proxy block with optional limit, idle_timeout, and unix properties. Default: none
• srv <name: string> (http-proxy; requires srv-lookup feature)
  • This directive specifies a dynamic upstream resolved via DNS SRV records. Supports dns_servers, limit, and idle_timeout nested directives. Default: none
• algorithm <algorithm: string> (http-proxy)
  • This directive specifies the load balancing strategy. Supported values: random, round_robin, least_conn, two_random, p2c_ewma. Default: algorithm two_random
• passive_check [bool: boolean] (http-proxy)
  • This directive enables passive health checking for backends. Supports nested max_fails and window directives. Default: passive_check false
• circuit_breaker [bool: boolean] (http-proxy)
  • This directive enables request-time circuit breaking for backends. Transport failures and upstream 5xx responses count toward tripping the circuit. Supports nested max_fails, window, open_duration, and consecutive_passes directives. Default: circuit_breaker false
• retry_connection [bool: boolean] (http-proxy)
  • This directive specifies whether to retry on connection failure if alternative backends are available. Default: retry_connection true

Configuration example:

example.com {
    proxy {
        upstream http://localhost:8080
        upstream http://localhost:8081 {
            limit 100
            idle_timeout "30s"
        }

        algorithm two_random
        passive_check {
            max_fails 3
            window "5s"
        }
    }
}

Weighted round-robin example:

example.com {
    proxy {
        upstream http://localhost:8080 {
            weight 5
        }
        upstream http://localhost:8081 {
            weight 2
        }
        upstream http://localhost:8082 {
            weight 1
        }

        algorithm round_robin
    }
}

In this example, the first backend receives approximately 62.5% of requests (5/8), the second receives 25% (2/8), and the third receives 12.5% (1/8). The smooth weighted round-robin algorithm distributes requests evenly over time rather than sending all requests to one backend before moving to the next.

Passive health check nested directives

Circuit breaker nested directives

SSRF risk with interpolated upstream URLs

The upstream URL supports interpolation syntax for dynamic values. Never use user-controlled request headers (e.g., request.header.host, request.header.x_forwarded_host, request.header.x_forwarded_proto) in upstream URLs, as an attacker can craft requests to redirect the proxy to internal services.

Unsafe — user-controlled header in upstream URL:

example.com {
    # DANGEROUS: attacker can set X-Forwarded-Host to 169.254.169.254 or any internal host
    proxy "http://{{request.header.x_forwarded_host}}:8080"
}

Safe — static upstream URL:

example.com {
    proxy http://localhost:8080
}

Safe — upstream URL derived from trusted, server-controlled variables:

example.com {
    # Safe: request.host is resolved by Ferron's TLS/SNI matcher, not user-controlled
    proxy "http://{{request.host}}:8080"
}

If you need to forward the original host to a backend, use the Host header manipulation instead:

example.com {
    proxy http://localhost:8080 {
        request_header Host "{{request.host}}"
    }
}

Connection behavior

• keepalive [bool: boolean] (http-proxy)
  • This directive specifies whether HTTP keep-alive connection pooling is enabled. Default: keepalive true
• http2 [bool: boolean] (http-proxy)
  • This directive specifies whether HTTP/2 is enabled for upstream connections. Default: http2 false
• http2_only [bool: boolean] (http-proxy)
  • This directive specifies whether only HTTP/2 is used for upstream connections. Default: http2_only false
• intercept_errors [bool: boolean] (http-proxy)
  • This directive specifies whether upstream error responses (4xx/5xx) are passed through to the client unchanged. When false (default), Ferron replaces upstream error responses with built-in error pages. When true, the full upstream response body and headers are passed through. Default: intercept_errors false

TLS

• no_verification [bool: boolean] (http-proxy)
  • This directive specifies whether TLS certificate verification is disabled for HTTPS upstreams. Default: no_verification false

Client certificate authentication (mTLS)

When connecting to an upstream over HTTPS, Ferron can present a client certificate to authenticate itself. Configure the cert and key subdirectives on the upstream:

example.com {
    proxy {
        upstream https://backend.internal:443 {
            cert "/etc/ferron/client-cert.pem"
            key "/etc/ferron/client-key.pem"
        }
    }
}

Both cert and key must be provided for mTLS to activate. The certificate chain and private key must be PEM-encoded. mTLS credentials are scoped per-upstream, so different backends can require different client certificates. Active health check probes also use the configured mTLS credentials. mTLS credentials are cached in memory until configuration reload or server shutdown.

PROXY protocol

• proxy_header <version: string> (http-proxy)
  • This directive specifies whether to prepend HAProxy PROXY protocol header to upstream connections. Supported versions: v1, v2. Default: disabled

Header manipulation

• request_header (http-proxy)
  • This directive manipulates request headers before forwarding to upstream. Three forms are supported:
    • request_header +Name "value" — add header (appends, allows duplicates)
    • request_header -Name — remove all instances of the header
    • request_header Name "value" — replace header (removes existing, sets new value)
  • Default: none

Configuration example:

example.com {
    proxy http://localhost:8080 {
        request_header +X-Custom-Header "value"
        request_header -X-Sensitive-Header
        request_header Host "new-host.example.com"
    }
}

Global connection limit

• proxy_concurrent_conns <limit: integer> (global scope)
  • This directive specifies the global maximum number of concurrent TCP connections maintained in the keep-alive connection pool across all upstream backends. Unix socket connections are always unbounded. Default: proxy_concurrent_conns 16384

Configuration example:

{
    proxy_concurrent_conns 10000
}

example.com {
    proxy http://localhost:8080 {
        keepalive
    }
}

Upstream nested properties

upstream

Defines a static backend server.

example.com {
    upstream http://localhost:8080 {
        limit 100
        idle_timeout "30s"
        unix /var/run/backend.sock
    }
}

srv (feature-gated)

Defines a dynamic upstream resolved via DNS SRV records.

example.com {
    srv _http._tcp.example.com {
        dns_servers "8.8.8.8,8.8.4.4"
        limit 100
        idle_timeout "30s"
    }
}

Load balancing algorithms

Session affinity

Session affinity (sticky sessions) ensures that requests from the same client are consistently routed to the same backend server. This is useful for stateful applications, WebSocket-heavy workloads, and improving cache locality.

The affinity directive configures session affinity inside a proxy block. Four affinity types are supported:

Cookie affinity

Reads and sets a cookie to track which backend a client should be routed to. If no cookie is present, a backend is selected and a cookie is set on the response.

example.com {
    proxy {
        upstream http://localhost:8080
        upstream http://localhost:8081

        affinity cookie {
            name "ferron_sticky"
            ttl "24h"
            path "/"
            httponly
            samesite lax
        }
    }
}

Cookie nested directives

Header affinity

Routes based on a specific request header value using consistent hashing.

example.com {
    proxy {
        upstream http://localhost:8080
        upstream http://localhost:8081

        affinity header {
            name "X-Backend-Id"
        }
    }
}

IP affinity

Routes based on the client’s IP address using consistent hashing. The same IP always routes to the same backend (while it remains healthy).

example.com {
    proxy {
        upstream http://localhost:8080
        upstream http://localhost:8081

        affinity ip
    }
}

Hash affinity

Routes based on a hashed variable value. Supports any built-in variable or request header.

example.com {
    proxy {
        upstream http://localhost:8080
        upstream http://localhost:8081

        affinity hash {
            variable "request.header.x-tenant-id"
        }
    }
}

Affinity behavior

• Affinity is respected only when the target backend is healthy. If the affinity target is unhealthy, the configured load balancing algorithm is used as a fallback.
• When retry_connection is enabled and the affinity-targeted backend fails, Ferron retries with another backend.
• Cookie affinity automatically sets the cookie on the first request if no valid cookie is present.
• The affinity key is used with a consistent hash ring for deterministic routing.

Forwarding headers

The reverse proxy module automatically manages standard forwarding headers:

Trace context injection

When a trace context exists for the request, the reverse proxy module automatically injects W3C Trace Context headers into the outgoing upstream request. This enables end-to-end distributed tracing across Ferron and your backend services.

Trace context injection happens after all request_header transformations are applied. This means:

• You can override the injected headers using request_header +traceparent "..." to add a custom value.
• You can remove injected headers using request_header -traceparent to suppress propagation.
• The injected headers cannot be removed by headers_to_remove since injection occurs last.

Connection pooling

Ferron maintains a keep-alive connection pool for upstream backends. Key behaviors:

• Connection reuse - pooled connections are automatically reused for subsequent requests to the same upstream.
• Idle eviction - connections idle longer than idle_timeout are evicted from the pool.
• HTTP/2 multiplexing - HTTP/2 connections share a single TCP connection for multiple concurrent requests.

Health checking

Passive health checking

Passive health checking tracks connection failures per backend:

1. Each failed connection increments a counter for that backend.
2. If the counter exceeds max_fails within the window duration, the backend is temporarily excluded from selection.
3. After the window expires, the counter resets and the backend becomes eligible again.
4. When retry_connection is enabled and the selected backend fails, Ferron tries the next available backend.

Circuit breaking

Circuit breaking tracks request-time backend failures and temporarily ejects unstable backends:

1. Transport failures and upstream 5xx responses are counted per backend in a rolling window.
2. When the backend reaches max_fails failures within window, Ferron opens the circuit and stops selecting that backend.
3. After open_duration, Ferron allows a single half-open trial request to the backend.
4. If the trial request succeeds, Ferron closes the circuit after consecutive_passes successful half-open requests.
5. If the half-open trial request fails, Ferron reopens the circuit immediately.

Circuit breaking does not automatically retry upstream 5xx responses. It only changes which backends are eligible for future requests.

Configuration example:

example.com {
    proxy {
        upstream http://localhost:3000
        upstream http://localhost:3001

        algorithm round_robin
        retry_connection false

        circuit_breaker {
            max_fails 5
            window "30s"
            open_duration "10s"
            consecutive_passes 1
        }
    }
}

Active health checking

Active health checks proactively probe backend health on a schedule, independent of incoming traffic. This allows quick detection of backend failures before they affect client requests.

Active health checks are configured per-upstream inside an active_check block.

active_check nested directives

Configuration example:

example.com {
    proxy {
        upstream http://localhost:3000 {
            active_check {
                uri "/health"
                interval "10s"
                timeout "5s"
                expect_status "200,204"
                consecutive_fails 2
                consecutive_passes 2
            }
        }
        upstream https://localhost:3001 {
            active_check {
                uri "/api/status"
                method HEAD
                response_time_threshold "1s"
                no_verification
            }
        }
        algorithm two_random
    }
}

Observability

Metrics

Logs

• ERROR: logged when a proxy configuration error occurs during parsing. The message includes the error details.
• ERROR: logged when a proxy execution error occurs (e.g., connection failure, transport error). The message includes the error type and details.
• WARN: logged when an upstream is marked unhealthy by active health checks. The message includes the upstream address and failure reason.
• INFO: logged when an upstream recovers after consecutive successful health check probes.

Structured logs

Best practices

The following best-practice checks are reported by ferron doctor for directives on this page.

TLS verification

• proxy { no_verification } — Disabling TLS certificate verification for HTTPS upstreams should only be used for testing or tightly controlled internal networks.
• active_check { no_verification } — Disabling TLS verification for health check probes should only be used for strictly internal endpoints.

Upstream SSRF risk

• Upstream URL with request header interpolation — Upstream URLs containing {{request.header.*}} are vulnerable to SSRF. Derive upstream targets from static configuration or trusted server-controlled variables.