Home

Awesome

Secure forward proxy for the Caddy web server

This package registers the http.handlers.forward_proxy module, which acts as an HTTPS proxy for accessing remote networks.

:warning: Experimental!

This module is EXPERIMENTAL. We need more users to test this module for bugs and weaknesses before we recommend its use from within surveilled networks or regions with active censorship. Do not rely on this code in situations where personal safety, freedom, or privacy are at risk.

You can help by:

We are also seeking experienced maintainers who have experience with these kinds of technologies and who are interested in continuing its development.

Expect breaking changes.

Features

Introduction

This Caddy module allows you to use your web server as a proxy server, configurable by numerous HTTP clients such as operating systems, web browsers, mobile devices, and apps. However, the feature set of each client varies widely, as does their correctness and security guarantees. You will have to be aware of each clients' individual weaknesses or shortcomings.

Quick start

First, you will have to know how to use Caddy.

Build Caddy with this plugin. You can add it from Caddy's download page or build it yourself with xcaddy:

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

Most people prefer the Caddyfile for configuration. You can stand up a simple, wide-open unauthenticated forward proxy like this:

example.com
route {
	# UNAUTHENTICATED! USE ONLY FOR TESTING
	forward_proxy
}

(Obviously, replace example.com with your domain name which is pointed at your machine.)

Because forward_proxy is not a standard directive, its ordering relative to other handler directives is not defined, so we put it inside a route block. You can alternatively do something like this:

{
	order forward_proxy before file_server
}
example.com
# UNAUTHENTICATED! USE ONLY FOR TESTING
forward_proxy

to define its position globally; then you don't need route blocks. The correct order is up to you and depends on your config.

This plugin enables Caddy to act as a forward proxy, with support for HTTP/3, HTTP/2, and HTTP/1.1 requests. HTTP/3 and HTTP/2 will usually improve performance due to multiplexing.

Forward proxy plugin includes common features like Access Control Lists and authentication, as well as some unique features to assist with security and privacy. Default configuration of forward proxy is compliant with existing HTTP standards, but some features force plugin to exhibit non-standard but non-breaking behavior to preserve privacy.

Probing resistance—one of the signature features of this plugin—attempts to hide the fact that your webserver is also a forward proxy, helping the proxy to stay under the radar. Eventually, forwardproxy plugin implemented a simple reverse proxy (upstream https://user:password@next-hop.com in Caddyfile) just so users may take advantage of probe_resistance when they need a reverse proxy (for example, to build a chain of proxies). Reverse proxy implementation will stay simple, and if you need a powerful reverse proxy, look into Caddy's standard proxy directive.

For a complete list of features and their usage, see Caddyfile syntax:

Caddyfile Syntax (Server Configuration)

The simplest way to enable the forward proxy without authentication just include the forward_proxy directive in your Caddyfile. However, this allows anyone to use your server as a proxy, which might not be desirable.

The forward_proxy directive has no default order and must be used within a route directive to explicitly specify its order of evaluation. In the Caddyfile the addresses must start with :443 for the forward_proxy to work for proxy requests of all origins.

Here's an example of all properties in use (note that the syntax is subject to change):

:443, example.com
route {
	forward_proxy {
		basic_auth user1 0NtCL2JPJBgPPMmlPcJ
		basic_auth user2 密码
		ports     80 443
		hide_ip
		hide_via
		probe_resistance secret-link-kWWL9Q.com # alternatively you can use a real domain, such as caddyserver.com
		serve_pac        /secret-proxy.pac
		dial_timeout     30
		upstream         https://user:password@extra-upstream-hop.com
		acl {
			allow     *.caddyserver.com
			deny      192.168.1.1/32 192.168.0.0/16 *.prohibitedsite.com *.localhost
			allow     ::1/128 8.8.8.8 github.com *.github.io
			allow_file /path/to/whitelist.txt
			deny_file  /path/to/blacklist.txt
			allow     all
			deny      all # unreachable rule, remaining requests are matched by `allow all` above
		}
	}
	file_server
}

(The square brackets [ ] indicate values you should replace; do not actually include the brackets.)

Security

Privacy

Access Control

Timeouts

Other

Get forwardproxy

Download prebuilt binary

Binaries are at https://caddyserver.com/download
Don't forget to add http.forwardproxy plugin.

Build from source

  1. Install latest Golang 1.20 or above and set export GO111MODULE=on
  2. go install github.com/caddyserver/forwardproxy/cmd/caddy@latest
    Built caddy binary will be stored in $GOPATH/bin.

Client Configuration

Please be aware that client support varies widely, and there are edge cases where clients may not use the proxy when it should or could. It's up to you to be aware of these limitations.

The basic configuration is simply to use your site address and port (usually for all protocols - HTTP, HTTPS, etc). You can also specify the .pac file if you enabled that.

Read this blog post about how to configure your specific client.

License

Licensed under the Apache License

Disclaimers

USE AT YOUR OWN RISK. THIS IS DELIVERED AS-IS. By using this software, you agree and assert that authors, maintainers, and contributors of this software are not responsible or liable for any risks, costs, or problems you may encounter. Consider your threat model and be smart. If you find a flaw or bug, please submit a patch and help make things better!

Initial version of this plugin was developed by Google. This is not an official Google product.