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, unix, logical_dns, and dns_servers properties. When the URL contains a hostname, A/AAAA records are resolved via Hickory DNS by default (strict DNS), creating a separate backend per resolved IP. 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
• circuit_breaker [bool: boolean] (http-proxy)
  • This directive enables request-time circuit breaking for backends. Transport failures always count toward tripping the circuit. Upstream 5xx responses count only when record_5xx is enabled. Slow responses count when latency_threshold is set. Supports nested max_fails, window, open_duration, consecutive_passes, record_5xx, latency_threshold, flapping_transitions, flapping_window, and slow_start directives. Default: circuit_breaker true
• retry_connection [bool: boolean] (http-proxy)
  • This directive specifies whether to retry on connection failure if alternative backends are available. Default: retry_connection true
• retry_budget [bool: boolean] (http-proxy)
  • This directive enables a token-bucket retry budget that limits retries to a fraction of steady-state traffic. When enabled alongside retry_connection true, retries consume tokens from a shared pool. Successful requests replenish the pool. If the retry budget is exhausted, further retries are refused and the request immediately returns 503 Service Unavailable, preventing cascading retry storms from overwhelming remaining healthy backends. Supports max_retry_rate, max_tokens, and refill_rate nested directives. Default: retry_budget false
• metrics_resolved_ip [bool: boolean] (http-proxy)
  • This directive controls whether the ferron.proxy.backend_resolved_ip and ferron.proxy.dns_status attributes are included in proxy metrics and access logs. When false (default), metrics identify backends by their configured URL and optional Unix socket path only, keeping metric cardinality low. When true, each resolved IP address becomes a distinct metric label value, and a ferron.proxy.dns_status attribute indicates the DNS resolution outcome (resolved, nxdomain, dns_error, logical_dns, static). Enable only when per-IP metric granularity is required and the IP set is stable. Default: metrics_resolved_ip false

Configuration example:

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

        algorithm two_random
    }
}

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.

Circuit breaker nested directives

Retry budget nested directives

Configuration example:

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

        algorithm round_robin
        retry_connection true
        retry_budget {
            max_retry_rate 0.1
            max_tokens 10
            refill_rate 2.0
        }
    }
}

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 intercepted and replaced with built-in error pages. When true, Ferron replaces upstream error responses with its own error pages. When false (default), the full upstream response body and headers are passed through unchanged. 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.

Priority-based failover

Backends can be assigned numeric priority values to implement tiered failover. Lower values indicate higher priority. When all backends in the highest-priority tier are unavailable (unhealthy, circuit-open, or already-tried), the next tier is used as a fallback.

example.com {
    proxy {
        upstream http://primary:8080 {
            priority 0
        }
        upstream http://secondary:8080 {
            priority 1
        }
        upstream http://standby:8080 {
            priority 2
        }
    }
}

Requests are routed to the primary tier (priority 0) first. If all primary backends are unavailable, the secondary tier (priority 1) is tried, and so on. Within each tier, the configured load balancing algorithm selects which backend handles the request. Priority and weight work together: priority determines which tier is tried, and weight determines how requests are distributed within a tier.

For SRV upstreams, the priority subdirective is an additive offset applied to DNS SRV priorities. A backend’s effective priority is dns_priority + offset. For example, if DNS returns priorities 10 and 20, setting priority 5 on the SRV block shifts them to 15 and 25.

example.com {
    proxy {
        srv _http._tcp.example.com {
            priority 5
        }
    }
}

Strict DNS (A/AAAA) resolution

When an upstream URL contains a hostname (not an IP literal), Ferron resolves A and AAAA records using Hickory DNS by default. Each resolved IP address becomes a separate backend in the load balancer, enabling per-IP load balancing, circuit breaking, and health checking.

For example, if http://myapp.example.com:8080 resolves to three IPs (10.0.0.1, 10.0.0.2, 10.0.0.3), Ferron creates three distinct backends — one per IP. The original hostname is preserved for TLS SNI and the HTTP Host header.

example.com {
    proxy {
        upstream http://myapp.example.com:8080 {
            dns_servers "8.8.8.8,8.8.4.4"
        }
    }
}

Opting out with logical_dns

Set logical_dns true to disable strict A/AAAA resolution. The upstream URL is passed through as-is, and the system’s DNS resolver handles address selection. This is useful when the upstream uses DNS for logical routing (e.g., geographic steering) and you want a single logical backend rather than per-IP backends.

example.com {
    proxy {
        upstream http://myapp.example.com:8080 {
            logical_dns
        }
    }
}

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

Circuit breaking

Circuit breaking provides passive health checking — tracking request-time failures per backend without background probes. The circuit breaker records transport failures (TCP connect errors, TLS errors) and optionally upstream 5xx responses, then temporarily ejects unstable backends from the load balancer.

1. Transport failures and (optionally) 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.

By default, only transport failures count toward the circuit. Set record_5xx true to also count upstream 5xx responses. Set latency_threshold to also count slow responses.

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
            record_5xx true
            latency_threshold "0.5s"
        }
    }
}

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
    }
}

DNS result caching

When strict DNS or SRV resolution is enabled, Ferron caches resolved DNS results in memory with TTL-based expiry. The cache key includes the hostname (strict DNS) or SRV name, port, and DNS server list, ensuring that different resolver configurations are not served stale results.

The cached TTL is derived from the minimum TTL across all DNS response records, with a 30-second fallback when no TTL is available. This prevents stale backends from remaining in the pool while avoiding unnecessary DNS resolution for high-traffic hostnames.

Cache entries are evicted lazily — expired entries are treated as cache misses and re-resolved on demand. A periodic background task removes expired entries every 60 seconds to prevent unbounded memory growth for hostnames no longer queried.

Configuration example:

example.com {
    proxy {
        upstream http://myapp.example.com:8080 {
            dns_servers "8.8.8.8,8.8.4.4"
        }
    }
}

In this example, the strict DNS resolution for myapp.example.com is cached. Subsequent requests use the cached result until the DNS TTL expires, reducing DNS resolution overhead.

Retry budgets

The retry budget uses a token-bucket algorithm shared across all requests for a given proxy configuration:

1. The bucket starts full with max_tokens tokens.
2. Each successful request deposits one token (up to capacity), replenishing retry capacity proportional to steady-state traffic.
3. Each retry consumes one token. If the bucket is empty, the retry is refused and the request returns 503 Service Unavailable with a Retry-After header indicating when the client should retry.
4. Tokens are lazily refilled based on elapsed time and refill_rate.

This prevents retry storms: when multiple backends fail simultaneously, the retry budget caps the total retry amplification factor. For example, with max_retry_rate 0.1 and three backends where two fail, at most ~10% of total traffic will be retries — the remaining healthy backend is not overwhelmed.

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.
• DEBUG: logged when a health check loop is initialized for a given upstream.

Structured logs

Access log fields

The reverse proxy module contributes the following fields to the HTTP access log line:

Trace spans

The reverse proxy stage sets the following attributes on its ferron.stage.reverse_proxy span:

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.