RustProxy/docs/VHOSTS.md

Vhosts, domains and backends

A Vhost publishes one or more hostnames on named HTTP/HTTPS listeners. Its source can be an HTTP reverse-proxy backend pool or a reusable local Web Service. Use Vhosts → Add in the panel.

Publish a site

1. Enter an ID and the exact domain (app.example.com) or supported wildcard (*.example.com). Exact names win over wildcards. Configure DNS independently.
2. Choose the enabled HTTP/HTTPS frontend listeners. Select a certificate for HTTPS.
3. Choose Reverse Proxy and add an upstream address such as http://10.0.0.20:3000, or select an existing Web Service.
4. Check backend reachability and TLS policy; configure health checks and load balancing for multiple origins.
5. Decide whether to force HTTPS, redirect www/non-www, enable WebSockets, cache, access rules and custom paths.
6. Save, visit the hostname, inspect the Vhost's health and logs, then test failure and recovery.

A Vhost may bind several frontends. Hostnames and selected listeners must match: the existence of a certificate or an upstream does not create DNS entries or a listening socket. Existing Vhosts retain their bindings when new listeners are created.

Source and backends

• Reverse Proxy: one Vhost has a backend pool. Each member has a configured URL, ID, enabled flag, weight, optional backup/drain state, health settings and capacity limits.
• Web Server: Vhost references a Web Service by ID. Its document root, directory handling, PHP options and static-file headers remain configured under Web Server.
• Custom locations: can override selected URL paths and use the default pool, a pinned backend, a different Web Service, a redirect or a local response. Unmatched paths still use the main source.

Sample documents in examples/vhosts-private.json and examples/vhosts-balanced.json illustrate JSON formats, but their IP addresses, certificates and health endpoints are examples only.

Backend connection and HTTP modes

Setting	Use
http1	Standard HTTP/1.1 upstream.
auto	HTTPS negotiates HTTP/2 or HTTP/1.1; plaintext uses HTTP/1.1.
http2 (legacy)	Compatible HTTPS ALPN or plaintext H2C, kept for existing configurations.
h2	Strict HTTP/2/H2C; requires origin support.

A backend's preserve_host option can retain the frontend authority when appropriate. HTTPS encryption alone does not guarantee verified backend identity: tls_verify is false by default. Enable verification and configure trusted CA/name for sensitive connections. Private, loopback and RustProxy-local listener targets require explicit security exceptions; do not point a public route to the admin listener. Read Security.

Connection reuse is bounded by configured idle-pool/recycle limits. 0.34.0 changes the default H1 upstream idle pool for newly configured Vhosts; previously saved explicit values remain. Configure timeouts to suit expected request and upload behavior; a slow origin may need more than the default response-header timeout.

Load balancing and health

Backend pools support scheduling/weighting, standby members, draining and optional session affinity. Check the Backends status view for member health, recently observed HTTP response code, upstream protocol and resource usage. A reported status from normal traffic is not necessarily the result of a health probe.

• Health monitoring may use TCP or HTTP checks with a path, Host, interval and thresholds. Avoid write endpoints; use a lightweight /health or equivalent.
• Each member can override the pool health check or disable active/passive monitoring with health_check_enabled=false. Disabling checks treats the member as available, not proven healthy.
• New monitored pools can temporarily have no eligible healthy member until rise checks succeed. A failed/incorrect check can produce 503 even if the process is reachable.
• backup members act as fallbacks; drain prevents new normal selection while letting existing work complete within normal lifetimes. Explicitly pinned backends need careful policy review.
• Concurrency and queue limits protect overloaded origins. Retries are restricted; do not assume non-idempotent requests are automatically replayed.

Hostnames, redirects and errors

• force_ssl redirects matching plaintext traffic to HTTPS using 308, preserving path/query; configure both HTTP and HTTPS frontends.
• WWW controls can direct www.example.com to example.com or the opposite as supported by the editor; ensure DNS/certificate coverage for both.
• Use the dedicated Redirects workspace for redirect-only domains. Use 404 hosts to claim a hostname and return a local not-found page without forwarding.
• Custom locations may return status/body or redirect for selected paths. Internal locations can be used as fallbacks for configured 403/404/500/502/503/504 application responses.
• The Pages section can replace supported origin error bodies without contacting a second backend. This keeps the response status and disables caching of the replaced error body.

Safe operating practices

Keep Vhost IDs stable for monitoring/history unless renaming is intentional. Renaming may reset the runtime identity and invalidate incompatible cache objects. Confirm the deployed scheme and Host, HTTPS trust, method/access restrictions, health status and logs after saving. For per-path behavior see Custom locations; for policies see Access; for caching see Cache.