config-example.toml

########################################
#                                      #
#       rust-rxpy configuration        #
#                                      #
########################################
###################################
#         Global settings         #
###################################
# Both or either one of http/https ports must be specified
# Port for plaintext http
listen_port = 8080
# Port for https
listen_port_tls = 8443

# Optional. Bind to a specific IPv4 address or addresses. [default: 0.0.0.0]
# Duplicate addresses are silently ignored.
# Single address:
# listen_address_v4 = '0.0.0.0'
# Multiple addresses (bind to specific interfaces, '0.0.0.0' MUST NOT be included in the list if multiple addresses are specified):
# listen_address_v4 = ['192.168.1.1', '10.0.0.1']

# Optional. Bind to a specific IPv6 address or addresses.
# If omitted and listen_ipv6 = true, bind to '[::]'.
# If omitted and listen_ipv6 = false or undefined, IPv6 is disabled.
# Duplicate addresses are silently ignored.
# Single address:
# listen_address_v6 = '[::]'
# Multiple addresses (bind to specific interfaces, '::' MUST NOT be included in the list if multiple addresses are specified):
# listen_address_v6 = ['::1', 'fe80::1']

# Optional. Enable IPv6 listening on '[::]' when listen_address_v6 is not specified.
# [default: false]
listen_ipv6 = false

# Optional. Client-visible HTTPS/H3 port when it differs from `listen_port_tls`
# (for example, when running behind a load balancer, firewall, or container port mapping).
# Used for HTTP->HTTPS redirects and HTTP/3 Alt-Svc. Usually unnecessary if clients use `listen_port_tls`.
# public_https_port = 443

# Optional for h2 and http1.1
tcp_listen_backlog = 1024

# Optional for h2
max_concurrent_streams = 100

# Optional. Shared cap for accepted HTTP/1.1 and HTTP/2 TCP connections, including
# PROXY protocol parsing and TLS handshakes. 0 rejects all HTTP/1.1 and HTTP/2 connections.
# HTTP/3 uses the independent per-endpoint connection cap under [experimental.h3].
max_clients = 512

# Enforce source-IP admission at the network/L4 edge when required; rpxy does not provide a per-IP limit.

# Optional. Trusted proxies whose incoming X-Forwarded-* / Forwarded headers are
# recursively trusted. If omitted or empty, forwarding headers from preceding peers
# are ignored and rebuilt from the immediate peer address.
# Examples:
# trusted_forwarded_proxies = ["10.0.0.0/8", "192.168.0.0/16"]
# trusted_forwarded_proxies = ["cloudflare", "fastly", "cloudfront"]
# trusted_forwarded_proxies = ["cloudfront", "10.0.0.0/8"]
# trusted_forwarded_proxies = "0.0.0.0/0" # trust all IPv4 proxies (not recommended)
# For full dual-stack trust-all, specify both "0.0.0.0/0" and "::/0".
# trusted_forwarded_proxies = []

# Optional. Redact query-string values in the access log so URLs that carry tokens or PII
# (e.g. ?token=..., ?code=..., ?email=...) are not logged verbatim. Default: false (full query
# strings are logged). When enabled, parameter values are replaced with <redacted> while the
# keys and path are kept. Enable this when applications may put secrets or personal data in
# query strings.
# redact_query_in_access_log = true

# Optional. Maximum inbound request body size for h1/h2/h3. Default: 256 MiB.
# Accepts an integer (bytes), or a string with a suffix: "256k", "10m", "1g".
# Requests whose Content-Length exceeds this limit are rejected with 413 before
# any upstream contact; chunked/streamed bodies are detected mid-flight.
# Set to 0 or "unlimited" to disable the limit for all three protocols (ensure
# external controls are in place).
# request_max_body_size = "256m"

# Optional. Required when any reverse_proxy entry uses load_balance = "sticky".
# Value must be a 32-byte secret encoded as unpadded base64url.
# Generate with: openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n'
# sticky_cookie_secret = "<base64url-no-pad-encoded-32-byte-secret>"

# Optional: App that serves all plaintext http request by referring to HOSTS or request header
# except for configured application.
# Note that this is only for http. Https requests with an unknown server_name are rejected
# unconditionally (independent of `sni_consistency`).
# On fallback to `default_app`, rpxy force-overwrites the outgoing `Host` header with the
# default app's configured `server_name` (wins against `keep_original_host` / `set_upstream_host`),
# and exposes the untrusted original client-visible host in `X-Forwarded-Host` (and in
# `Forwarded: host=` when the `forwarded_header` option is set). Backends MUST treat
# `X-Forwarded-Host` / `Forwarded: host=` as untrusted observational data on this path.
default_app = 'another_localhost'

###################################
#         Backend settings        #
###################################
[apps]

######################################################################
## Registering a backend app served by a domain name "localhost"
[apps.localhost]
server_name = 'localhost' # Domain name

# Optional: TLS setting. if https_port is specified and tls is true above, this must be given.
# https_redirection can be specified only when both http_port and https_port are specified. If not explicitly specified, it is true by default.
# if only https_port is given, https_redirection must not be specified.
# Plaintext requests are never forwarded to an app with client_ca_cert_path: they receive a 301 redirect when enabled, or 421 when https_redirection is false.
tls = { https_redirection = true, tls_cert_path = '/certs/server.crt', tls_cert_key_path = '/certs/server.key' } # for docker volume mounted certs
#tls = { https_redirection = true, tls_cert_path = './server.crt', tls_cert_key_path = './server.key' }          # for local
#tls = { https_redirection = true, tls_cert_path = './server.crt', tls_cert_key_path = './server.key', client_ca_cert_path = './client_cert.ca.crt' }          # for local with client_cert

## TODO
# allowhosts = ['127.0.0.1', '::1', '192.168.10.0/24'] # TODO
# denyhosts = ['*'] # TODO

# default destination if "path" is not specified
[[apps.localhost.reverse_proxy]]
# List of destinations to send data to. At this point, round-robin is used for load-balancing if multiple URLs are specified.
upstream = [
  { location = 'www.yahoo.com', tls = true },
  { location = 'www.yahoo.co.jp', tls = true },
]
load_balance = "round_robin" # or "random" or "sticky" (sticky session) or "primary_backup" or "none" (default)
                             # "none": fix to the first upstream. When health_check is enabled, picks the first healthy one.
                             # "primary_backup": always routes to the first healthy upstream; requires health_check to be enabled.
upstream_options = [
  "keep_original_host",   # [default] do not overwrite HOST value with upstream hostname (like 192.168.xx.x seen from rpxy), which is prior to "set_upstream_host" if both are specified.
  # By default, TLS upstreams mirror the client HTTP version; plaintext upstreams use HTTP/1.1.
  "force_http2_upstream", # mutually exclusive with "force_http11_upstream"
]

# Optional: Active health check. Periodically probes upstream servers and removes unhealthy ones from the load balancing pool.
# Simplest form — TCP connect check with default settings (interval=10s, timeout=5s, unhealthy_threshold=3, healthy_threshold=2):
# health_check = true
# Full configuration:
# [apps.localhost.reverse_proxy.health_check]
# type = "tcp"              # "tcp" (default) or "http"
# interval = 10             # seconds between checks [default: 10]
# timeout = 5               # seconds per check attempt [default: 5] (must be < interval)
# unhealthy_threshold = 3   # consecutive failures to mark unhealthy [default: 3]
# healthy_threshold = 2     # consecutive successes to mark healthy again [default: 2]
# # HTTP-specific options (only when type = "http"):
# path = "/healthz"         # required for type = "http"; must start with "/"
# expected_status = 200     # expected HTTP status code [default: 200]

# Non-default destination in "localhost" app, which is routed by "path"
[[apps.localhost.reverse_proxy]]
path = '/maps'
# For request path starting with "/maps",
# this configuration results that any path like "/maps/org/any.ext" is mapped to "/replacing/path1/org/any.ext"
# by replacing "/maps" with "/replacing/path1" for routing to the locations given in upstream array
# Note that unless "replace_path" is specified, the "path" is always preserved.
# "replace_path" must be start from "/" (root path)
replace_path = "/replacing/path1"
upstream = [
  { location = 'www.bing.com', tls = true },
  { location = 'www.bing.co.jp', tls = true },
]
load_balance = "random" # or "round_robin" or "sticky" (sticky session) or "none" (fix to the first one, default)
upstream_options = [
  "upgrade_insecure_requests",
  # By default, TLS upstreams mirror the client HTTP version; plaintext upstreams use HTTP/1.1.
  "force_http11_upstream",
  "set_upstream_host",        # overwrite HOST value with upstream hostname (like www.yahoo.com). rpxy always overwrites X-Forwarded-Host with the original client-visible host and never forwards a client-supplied X-Forwarded-Host as-is.
  "forwarded_header"          # add Forwarded header (disabled by default. However, update one if already present.) Incoming Forwarded/X-Forwarded-* values are normalized according to trusted_forwarded_proxies before generation.
]
######################################################################

######################################################################
# Another application backend servied by different domain name
[apps.another_localhost]
server_name = 'localhost.localdomain'
reverse_proxy = [{ upstream = [{ location = 'www.google.com', tls = true }] }]
######################################################################

######################################################################
# ACME enabled example. ACME will be used to get a certificate for the server_name with ACME tls-alpn-01 protocol.
# Note that acme option must be specified in the experimental section.
[apps.localhost_with_acme]
server_name = 'kubernetes.docker.internal'
reverse_proxy = [{ upstream = [{ location = 'example.com', tls = true }] }]
tls = { https_redirection = true, acme = true }

###################################
#      Experimental settings      #
###################################
[experimental]
# Highly recommend not to be true. If true, you ignore RFC. if not specified, it is always false.
# This might be required to be true when a certificate is used by multiple backend hosts, especially in case where a TLS connection is re-used.
# We should note that this strongly depends on the client implementation.
# Note: this relaxation never applies to applications with client authentication (client_ca_cert_path);
# requests reaching such an application over a TLS session established for a different server name are always rejected.
ignore_sni_consistency = false

# Force connection handling timeout regardless of the connection status, i.e., idle or not.
# 0 represents an infinite timeout. [default: 0]
# Note that idle and header read timeouts are always specified independently of this.
# A non-zero value is recommended in production unless long-lived connections (e.g. WebSocket) are required.
connection_handling_timeout = 0 # sec

# If this is specified, h3 is enabled. The H3 connection limit is independent
# from max_clients and applies separately to each H3 endpoint/listener.
[experimental.h3]
alt_svc_max_age = 3600             # sec
# At 0, Quinn silently drops new attempts while s2n closes them explicitly;
# both enforce reject-all.
max_concurrent_connections = 512   # H3 connections per endpoint/listener. Default: 512.
max_concurrent_bidistream = 100    # bidirectional streams per H3 connection
max_concurrent_unistream = 100     # unidirectional streams per H3 connection
max_idle_timeout = 10              # secs. 0 represents an infinite timeout.
# WARNING: If a peer or its network path malfunctions or acts maliciously, an infinite idle timeout can result in permanently hung futures!

# If this specified, file cache feature is enabled
[experimental.cache]
cache_dir = './cache'                # optional. default is "./cache" relative to the current working directory
max_cache_entry = 1000               # optional. default is 1k
max_cache_each_size = 65535          # optional. default is 64k
max_cache_each_size_on_memory = 65535 # optional. default is 64k, same as max_cache_each_size (cacheable objects are served from memory by default; the file tier engages when max_cache_each_size is raised beyond this). if 0, it is always file cache. Worst-case memory use is max_cache_entry x this value.
max_cache_total_size = "1g"          # optional. default is 1 GiB. ceiling on the total bytes retained by the cache across both tiers; accepts an integer (bytes) or a string with a binary suffix ("256m", "1g"). set "unlimited" to disable (0 also works, but note that 0 means "always file cache" for max_cache_each_size_on_memory above, so the string form is recommended here).
# Note: cached responses are keyed on the request URI forwarded upstream. A backend that varies content by the original (client-facing) host, scheme, or URI - e.g. multiple virtual hosts flattened onto one upstream via set_upstream_host or default_app - must emit an appropriate `Vary` header on cacheable responses or mark them non-cacheable.

# ACME settings. Unless specified, ACME is disabled.
[experimental.acme]
dir_url = "https://localhost:14000/dir" # optional. default is "https://acme-v02.api.letsencrypt.org/directory"
email = "test@example.com"
registry_path = "./acme_registry"       # optional. default is "./acme_registry" relative to the current working directory

# HAProxy PROXY Protocol v1/v2 inbound receive (requires `proxy-protocol` feature).
# This is enabled when [experimental.tcp_recv_proxy_protocol] and its required field `trusted_proxies` are specified. Unless specified, this is disabled.
# When enabled, rpxy expects to receive a PROXY header at the beginning of each TCP connection, which is sent by an upstream L4 proxy (e.g. rpxy-l4) to recover the original client's source IP/port.
# Then, rpxy parses the PROXY header sent by an upstream L4 proxy (e.g. rpxy-l4) to recover the original client's source IP/port.
# SECURITY WARNING: When configured, ALL TCP connections must originate from a listed trusted proxy.
# PROXY headers are not authenticated — restrict access with firewall rules.
# [experimental.tcp_recv_proxy_protocol]
# trusted_proxies = ["127.0.0.1/32", "10.0.0.0/8"]  # required, non-empty CIDR list. IPv4 and/or IPv6. Example: ["127.0.0.1/32", "::1/128"]
# timeout = 50  # optional, milliseconds. Default 50ms. 0 = fallback to 5s (not recommended).