Configuration: reverse proxying

This page documents directives for forwarding incoming HTTP requests to one or more upstream backend servers. These directives support 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. You can use 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. It accepts http:// or https:// URLs. You can nest it inside a proxy block with optional limit, idle_timeout, unix, logical_dns, and dns_servers properties. When the URL contains a hostname, Ferron resolves A/AAAA records via Hickory DNS by default. This strict DNS mode creates a separate backend per resolved IP. Default: none
• srv <name: string> (http-proxy)
  • This directive specifies a dynamic upstream that Ferron resolves via DNS SRV records. It 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 you enable record_5xx. Slow responses count when you set latency_threshold. It 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 or HTTP request (if request body wasn’t sent yet) 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 share of steady-state traffic. When you enable it alongside retry_connection true, retries consume tokens from a shared pool. Successful requests replenish the pool. If the retry budget runs out, Ferron refuses further retries and the request immediately returns 503 Service Unavailable. This prevents cascading retry storms from overwhelming remaining healthy backends. It supports max_retry_rate, max_tokens, and refill_rate nested directives. Default: retry_budget false
• max_retries_per_upstream <count: integer> (http-proxy)
  • This directive sets how many times Ferron retries the same upstream on a transport or connection failure before it falls back to another backend via retry_connection. Only requests that can be replayed (idempotent methods with a buffered body that has not been sent yet) are retried. Each retry consumes a token from retry_budget when it is enabled. Set to 0 to disable same-upstream retries and fall back immediately. Default: max_retries_per_upstream 1
• metrics_resolved_ip [bool: boolean] (http-proxy)
  • This directive controls whether Ferron includes the ferron.proxy.backend_resolved_ip and ferron.proxy.dns_status attributes in proxy metrics and access logs. When false (default), metrics identify backends by their configured URL and optional Unix socket path only. This keeps metric cardinality low. When true, each resolved IP address becomes a distinct metric label value. A ferron.proxy.dns_status attribute indicates the DNS resolution outcome (resolved, nxdomain, dns_error, logical_dns, static). Enable this only when you need per-IP metric granularity 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. It does not send 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 in upstream URLs. Examples include request.header.host, request.header.x_forwarded_host, and request.header.x_forwarded_proto. 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: Ferron resolves request.host via its 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 you enable HTTP keep-alive connection pooling. Default: keepalive true
• http2 [bool: boolean] (http-proxy)
  • This directive specifies whether you enable HTTP/2 for upstream connections. Default: http2 false
• http2_only [bool: boolean] (http-proxy)
  • This directive specifies whether to use only HTTP/2 for upstream connections. Default: http2_only false
• intercept_errors [bool: boolean] (http-proxy)
  • This directive specifies whether Ferron intercepts upstream error responses (4xx/5xx) and replaces them with built-in error pages. When true, Ferron replaces upstream error responses with its own error pages. When false (default), Ferron passes the full upstream response body and headers through unchanged. Default: intercept_errors false

TLS⁠#

• no_verification [bool: boolean] (http-proxy)
  • This directive specifies whether to disable TLS certificate checks 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"
        }
    }
}

You must provide both cert and key for mTLS to activate. The certificate chain and private key must be PEM-encoded. Ferron scopes mTLS credentials per-upstream. Different backends can require different client certificates. Active health check probes also use the configured mTLS credentials. Ferron caches mTLS credentials in memory until configuration reload or server shutdown.

PROXY protocol⁠#

• proxy_header <version: string> (http-proxy)
  • This directive specifies whether to prepend an 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. It supports three forms:
    • 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 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⁠#

Defines a dynamic upstream that Ferron resolves 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) makes sure the same client’s requests always go 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. It supports four affinity types:

Cookie affinity⁠#

Reads and sets a cookie to track which backend receives each client’s requests. If no cookie is present, Ferron selects a backend and sets a cookie 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⁠#

example.com {
    cache {
        vary_cookies ferron_sticky
    }
}

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

example.com {
    cache {
        vary "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 name you'd use in string interpolations, but with quotes instead of double-curly-braces.
            variable "request.header.x-tenant-id"
        }
    }
}

Affinity behavior⁠#

• Ferron respects affinity only when the target backend is healthy. If the affinity target is unhealthy, Ferron uses the configured load balancing algorithm as a fallback.
• When you enable retry_connection 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.
• Ferron uses the affinity key with a consistent hash ring for deterministic routing.

Priority-based failover⁠#

You can assign numeric priority values to backends to implement tiered failover. Lower values indicate higher priority. When all backends in the highest-priority tier are unavailable, Ferron uses the next tier as a fallback. A backend is unavailable if it is unhealthy, has an open circuit, or was already tried.

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

Ferron routes requests to the primary tier (priority 0) first. If all primary backends are unavailable, Ferron tries the secondary tier (priority 1), 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 Ferron tries. Weight determines how Ferron distributes requests 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 instead of an IP literal, Ferron resolves A and AAAA records using Hickory DNS. Each resolved IP address becomes a separate backend in the load balancer. This enables 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. Ferron preserves the original hostname 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. Ferron passes the upstream URL through as-is, and the system’s DNS resolver handles address selection. This is useful when the upstream uses DNS for logical routing (for example geographic steering). You then get 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, the reverse proxy module injects W3C Trace Context headers into the upstream request. This enables distributed tracing across Ferron and your backend services.

Trace context injection happens after Ferron applies all request_header transformations. 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.
• headers_to_remove cannot remove the injected headers since injection occurs last.

Connection pooling⁠#

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

• Connection reuse - Ferron automatically reuses pooled connections for later requests to the same upstream.
• Idle eviction - Ferron evicts connections idle longer than idle_timeout 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. It tracks request-time failures per backend without background probes. The circuit breaker records transport failures (TCP connect errors, TLS errors) and optionally upstream 5xx responses. It then temporarily ejects unstable backends from the load balancer.

1. Ferron counts transport failures and (optionally) upstream 5xx responses 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 lets you detect backend failures quickly before they affect client requests.

You configure active health checks 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
    }
}

Retry budgets⁠#

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

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, this includes same-upstream retries (max_retries_per_upstream) and cross-backend failovers (retry_connection). If the bucket is empty, Ferron refuses the retry. The request then returns 503 Service Unavailable with a Retry-After header indicating when the client should retry.
4. Ferron lazily refills tokens 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: Ferron logs this when a proxy setup error occurs during parsing. The message includes the error details.
• ERROR: Ferron logs this when a proxy execution error occurs (for example connection failure, transport error). The message includes the error type and details.
• WARN: Ferron logs this when active health checks mark an upstream unhealthy. The message includes the upstream address and failure reason.
• INFO: Ferron logs this when an upstream recovers after consecutive successful health check probes.
• DEBUG: Ferron logs this when it initializes a health check loop 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⁠#

ferron doctor reports the following best-practice checks for directives on this page.

TLS verification⁠#

• proxy { no_verification }: Only disable TLS certificate checks for HTTPS upstreams in testing or tightly controlled internal networks.
• active_check { no_verification }: Only disable TLS checks on health check probes 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 setup or trusted server-controlled variables.