Skip to content

Feature Guide Proxy Hosts

Jump to bottom
fuomag9 edited this page Sep 26, 2026 · 10 revisions

Feature Guide: Proxy Hosts

Create and manage reverse proxies handled by Caddy.

Table of Contents

  1. What Proxy Hosts Do
  2. Create a Proxy Host
  3. Domains and Upstreams
  4. List View Search and Pagination
  5. Advanced Features
  6. Examples
  7. Troubleshooting

What Proxy Hosts Do

A proxy host maps public domain(s) to one or more upstream services.

Common uses:

  • Expose internal apps at public domains
  • Terminate HTTPS automatically with Caddy-managed ACME certs
  • Add HTTP basic auth via access lists
  • Enforce geo-based allow/block rules
  • Load balance across multiple upstreams

Create a Proxy Host

  1. Open Proxy Hosts in the sidebar.
  2. Click Create Host.
  3. Configure at minimum:
    • Name
    • Domains (one per line or comma-separated)
    • Upstreams (one per line)
  4. Optional: choose a custom imported certificate or an access list.
  5. Click Create.

By default, a new host is created with Caddy-managed certificate handling.

Domains and Upstreams

Domains

You can define one or multiple domains per host.

Examples:

app.example.com
api.example.com

Wildcard example (requires DNS-01):

*.example.com

Upstreams

You can define one or multiple upstream targets.

Examples:

http://app:8080
http://app2:8080
https://backend.internal:8443

When multiple upstreams are defined, enable Load Balancer to control selection and health behavior.

List View Search and Pagination

The Proxy Hosts page uses server-side filtering and pagination.

  • Search is available at the top of the page
  • Search matches host name, domains, and upstream values
  • Results are paged on the server
  • Default page size: 25
  • URL params are used (?search=...&page=N) so links are shareable

Actions available from the list:

  • Enable/disable host
  • Duplicate host
  • Edit host
  • Delete host

Advanced Features

Load Balancer

Enable Load Balancer in the host dialog to configure:

  • Policy: random, round_robin, least_conn, ip_hash, first, header, cookie, uri_hash
  • Retry behavior: try duration, try interval, max retries
  • Active health checks: URI, port, interval, timeout, expected status/body
  • Passive health checks: fail duration, max fails, unhealthy status codes, unhealthy latency

DNS Controls

Two DNS-related options are available per host:

  • DNS Resolver: set explicit resolver(s), optional fallback resolver(s), and timeout
  • Upstream DNS Resolution: override pinning behavior (ipv4, ipv6, both) when upstream hostnames are resolved on apply

Forward Auth Portal

Enable the built-in forward auth to protect a host with CPM's login portal. Choose which users and/or groups may access the host. No external IdP required.

See Feature Guide Forward Auth for full setup.

Authentik Integration

Per-host Authentik forward-auth settings can be enabled for protected routes, including copied identity headers and trusted proxies.

Generic Forward Auth (Authelia etc.)

Protect a host through any forward-auth server with an Authelia preset, including the split browser vs API pattern: browser requests are redirected to the auth portal, API clients and WebSocket handshakes can get a plain 401, and requests carrying a bypass header (e.g. X-Api-Key) skip forward auth so the upstream can enforce its own API keys.

See Feature Guide Forward Auth for full setup.

Location Rules

Add path-based routing rules to send different URL paths to different upstreams. For example, /api/* to one backend and /ws/* to another. Each rule specifies a path prefix and one or more upstream targets.

Error Pages, Path Blocks and Redirects

The host dialog can also serve responses you write yourself:

  • Error Pages: a custom body and content type for error status codes (e.g. 502/503 when the upstream is down); the original status code is kept
  • Path Blocks: a status code and an optional body for blocked paths
  • Redirects: from a path (From Path) to To URL / Path, with a status code

Global fallback error pages are configured under Settings → Error Pages, and the response for unknown hosts and direct IP access under Settings → Default Response.

Placeholders (since v1.13.1): in error page bodies and content types (per host and global), path block bodies, and the default response body, headers and redirect URL, Caddy request placeholders such as {http.request.uri} and {http.request.host} are still expanded, while host placeholders ({env.*}, {system.*} and {file.*}) are sent literally, exactly as written. For example, a default response redirect URL of https://{env.PRIMARY_DOMAIN}{http.request.uri} now sends {env.PRIMARY_DOMAIN} as text; write the host name out instead: https://www.example.com{http.request.uri}.

Per-host Redirects take no placeholders at all: CPM removes every {…} from From Path and To URL / Path when the host is saved, as older releases did. A target of https://www.example.com{http.request.uri} is stored as https://www.example.com.

mTLS RBAC

When mTLS is enabled, you can add path-based access rules that restrict which client certificates (by role or individually) can reach specific URL paths.

See Feature Guide mTLS RBAC for full setup.

WAF (Web Application Firewall)

Enable the WAF per host in the host dialog. Three options:

  • Disabled — WAF off for this host, regardless of global setting
  • Global — use the global WAF settings (default)
  • Custom — override with host-specific WAF settings (enable/disable, OWASP CRS, custom directives)

Custom mode also supports per-host rule suppression. Events from this host appear in WAF → Events filtered by host.

Custom directives are checked when you save the host: a newly added line that CPM would not send to Caddy (for example SecRuleRemoveByTag or ctl:ruleEngine=Off) is rejected with the reason (see Feature Guide WAF#accepted-and-dropped-directives).

See Feature Guide WAF for full WAF setup.

Geo Blocking

Configure allow/block rules by:

  • Country
  • Continent
  • ASN
  • CIDR
  • IP

See Feature Guide Geo Blocking for full setup and rule strategy.

Custom JSON Overrides

Advanced users can supply:

  • Custom Pre-Handlers (JSON)
  • Custom Reverse Proxy (JSON)

These are merged into generated Caddy configuration for edge cases.

Host State and TLS Flags

Per-host options include:

  • Enable/pause host
  • Include HSTS subdomains
  • Skip upstream HTTPS hostname validation (for specific self-signed/private PKI cases)

Examples

Example 1: Single upstream app

Domains:
  app.example.com
Upstreams:
  http://app:3000

Example 2: Multi-upstream with round robin

Domains:
  api.example.com
Upstreams:
  http://api-1:8080
  http://api-2:8080
Load balancer:
  enabled=true
  policy=round_robin

Example 3: Wildcard host

Domains:
  *.example.com
Upstreams:
  http://tenant-router:3000

Requires DNS-01 challenge support. See Cloudflare DNS Configuration.

Troubleshooting

502 Bad Gateway

Checks:

  1. Validate upstream is reachable from Caddy network
  2. Confirm container/service name and port
  3. Review Caddy logs: 
    docker compose logs caddy | grep -i upstream

Certificate not issued

Checks:

  1. Domain resolves to your server
  2. Ports 80/443 are reachable (unless using DNS-01)
  3. ACME email configured in Settings
  4. Inspect ACME logs: 
    docker compose logs caddy | grep -i acme

{env.…} or {file.…} shows up literally in a response

Since v1.13.1, host placeholders in error pages, path block bodies and the default response (body, headers and redirect URL) are not expanded (see Error Pages, Path Blocks and Redirects). Replace them with the literal value. Request placeholders such as {http.request.uri} still work there. Per-host redirect targets drop every {…} placeholder when the host is saved.

Search results look stale

The list is server-rendered from URL params. If needed, clear search input and confirm search is removed from the URL.

Related Documentation

Need help? Open an issue with your host configuration and relevant logs.

Clone this wiki locally