caddyserver/forwardproxy

To use the forward proxy, you must configure your client (browser, OS, or application) to route traffic through the Caddy server's address and port.

Note that client support for proxy settings varies significantly. Some clients may bypass the proxy in certain edge cases. If you have enabled PAC (Proxy Auto-Configuration) files on the server, you must also specify the .pac file location in your client configuration.

For specific guidance on configuring individual clients, refer to external resources such as this blog post.

To use the forward_proxy module, you must build a custom version of Caddy that includes the plugin. You can do this using xcaddy or by downloading a prebuilt binary from the Caddy website that includes the http.forwardproxy plugin.

Build with xcaddy

$ xcaddy build --with github.com/caddyserver/forwardproxy

Build from source

1. Install Golang 1.20 or above and set export GO111MODULE=on.
2. Run:

go install github.com/caddyserver/forwardproxy/cmd/caddy@latest

Note: The resulting binary will be in your $GOPATH/bin.

You can build a custom Docker image containing both the Caddy web server and the forwardproxy plugin using the provided Dockerfile. This image is designed to simplify the setup of a private web server with proxying capabilities.

docker build -t caddy-forwardproxy .

To set up a simple, wide-open forward proxy, add the forward_proxy directive to your Caddyfile.

Important: The site address must start with :443 for the proxy to work for requests of all origins.

Warning: This configuration is unauthenticated and allows anyone to use your server as a proxy. Use it only for testing.

Because forward_proxy has a default directive order of "after file_server", you may need to use the order global option or a route block to ensure it executes correctly.

{ 
	order forward_proxy first
}

:443, example.com {
	# UNAUTHENTICATED! USE ONLY FOR TESTING
	forward_proxy
}

The forward_proxy handler uses an Access Control List (ACL) to permit or deny connections based on hostnames or IP addresses.

By default, the handler includes a deny rule for several private/local IP ranges (e.g., 10.0.0.0/8, 127.0.0.0/8, 192.168.0.0/16, etc.) to prevent SSRF-style attacks.

When a connection is attempted (e.g., via CONNECT), the handler checks:

1. If the port is in the allowed_ports list (if provided).
2. If the host/IP matches any deny rules in the ACL.
3. If the host/IP matches any allow rules in the ACL.

Upstream Proxies

Use the upstream directive to route all forward_proxy requests through another proxy.

• Supported schemes for remote hosts: https.
• Supported schemes for localhost: socks5, http, https (certificate check is ignored).
• Note: upstream is incompatible with acl and ports subdirectives.

Proxy Auto-Config (PAC)

Use serve_pac [/path.pac] to generate and serve an in-memory PAC file.

• If no path is provided, it is served at /proxy.pac.
• Security Tip: If using probe_resistance, serve the PAC file at a secret location to avoid defeating the protection.

forward_proxy {
	upstream https://user:password@extra-upstream-hop.com
	serve_pac /secret-proxy.pac
}

To prevent leaking user information to destination servers, use the following privacy options:

• hide_ip: Prevents the proxy from adding the user's IP to the Forwarded: header.
• hide_via: Prevents the proxy from adding the Via: header, making it harder to detect proxy usage.

forward_proxy {
	hide_ip
	hide_via
}

The acl block allows you to define rules for allowed destination IP networks, IP addresses, and hostnames. Rules are evaluated in order.

Default Policy:

acl {
	deny 10.0.0.0/8 127.0.0.0/8 172.16.0.0/12 192.168.0.0/16 ::1/128 fe80::/10
	allow all
}

Available Directives:

• allow [ip|subnet|hostname]...
• deny [ip|subnet|hostname]...
• allow_file /path/to/whitelist.txt (one entry per line)
• deny_file /path/to/blacklist.txt (one entry per line)

Notes:

• Use *.domain.com to match a domain and all its subdomains.
• Hostname rules are resolved to IPs before checking.
• It is recommended to put IP rules before hostname rules.
• To define a strict policy, end your ACL with deny all.

forward_proxy {
	acl {
		allow *.caddyserver.com
		deny 192.168.1.1/32
		allow all
	}
}

When defining subjects in an ACLRule, you can use the following formats:

1. All Traffic: Use the literal string all to match any request.
2. IP Addresses: A single IPv4 or IPv6 address (e.g., 192.168.1.1 or 2001:db8::1). The system automatically treats these as single-host networks (/32 for IPv4 or /128 for IPv6).
3. IP Networks (CIDR): Standard CIDR notation for IP ranges (e.g., 10.0.0.0/8).
4. Domains: A specific domain name (e.g., example.com).
5. Wildcard Domains: Use a *. prefix to allow subdomains (e.g., *.example.com matches example.com and sub.example.com).

Note on Domain Validation: Domains must follow a 'lite' validation rule: they can only contain alphanumeric characters, underscores, hyphens, and dots. Sections between dots cannot be empty and cannot exceed 63 characters.

The handler can serve a Proxy Auto-Configuration (PAC) file. This is triggered when a request is made to the path specified in PACPath.

The served PAC file uses a template that directs traffic for localhost, 127.0.0.1, and ::1 to DIRECT, and all other traffic to the proxy using the HTTPS scheme and the host requested.

{
  "pac_path": "/proxy.pac"
}