-
Notifications
You must be signed in to change notification settings - Fork 228
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
145 additions
and
148 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,7 +18,7 @@ We are also seeking experienced maintainers who have experience with these kinds | |
|
|
||
| ## Features | ||
|
|
||
| - HTTP/1.1 and HTTP/2 support | ||
| - HTTP/1.1, HTTP/2, and HTTP/3 support | ||
| - Authentication | ||
| - Access control lists | ||
| - Optional probe resistance | ||
|
|
@@ -37,14 +37,13 @@ First, you will have to know [how to use Caddy](https://caddyserver.com/docs/get | |
| Build Caddy with this plugin. You can add it from [Caddy's download page](https://caddyserver.com/download) or build it yourself with [xcaddy](https://github.com/caddyserver/xcaddy): | ||
|
|
||
| ``` | ||
| $ xcaddy build --with github.com/caddyserver/forwardproxy@caddy2 | ||
| $ xcaddy build --with github.com/caddyserver/forwardproxy | ||
| ``` | ||
|
|
||
| Most people prefer the [Caddyfile](https://caddyserver.com/docs/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 | ||
|
|
@@ -59,26 +58,14 @@ Because `forward_proxy` is not a standard directive, its ordering relative to ot | |
| { | ||
| 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](https://caddyserver.com) to act as a forward proxy, with support for HTTP/2.0 and HTTP/1.1 requests. HTTP/2.0 will usually improve performance due to multiplexing. | ||
| This plugin enables [Caddy](https://caddyserver.com) 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. | ||
|
|
||
|
|
@@ -123,109 +110,125 @@ route { | |
|
|
||
| (The square brackets `[ ]` indicate values you should replace; do not actually include the brackets.) | ||
|
|
||
| ##### Security | ||
|
|
||
| - **basic_auth [user] [password]** | ||
| Sets basic HTTP auth credentials. This property may be repeated multiple times. Note that this is different from Caddy's built-in `basic_auth` directive. BE SURE TO CHECK THE NAME OF THE SITE THAT IS REQUESTING CREDENTIALS BEFORE YOU ENTER THEM. | ||
| _Default: no authentication required._ | ||
|
|
||
| - **probe_resistance [secretlink.tld]** | ||
| Attempts to hide the fact that the site is a forward proxy. | ||
| Proxy will no longer respond with "407 Proxy Authentication Required" if credentials are incorrect or absent, | ||
| and will attempt to mimic a generic Caddy web server as if the forward proxy is not enabled. | ||
| Probing resistance works (and makes sense) only if `basic_auth` is set up. | ||
| To use your proxy with probe resistance, supply your `basic_auth` credentials to your client configuration. | ||
| If your proxy client(browser, operating system, browser extension, etc) | ||
| allows you to preconfigure credentials, and sends credentials preemptively, you do not need secret link. | ||
| If your proxy client does not preemptively send credentials, you will have to visit your secret link in your browser to trigger the authentication. | ||
| Make sure that specified domain name is visitable, does not contain uppercase characters, does not start with dot, etc. | ||
| Only this address will trigger a 407 response, prompting browsers to request credentials from user and cache them for the rest of the session. | ||
| _Default: no probing resistance._ | ||
|
|
||
| ##### Privacy | ||
|
|
||
| - **hide_ip** | ||
| If set, forwardproxy will not add user's IP to "Forwarded:" header. | ||
| WARNING: there are other side-channels in your browser, that you might want to eliminate, such as WebRTC, see [here](https://www.ivpn.net/knowledgebase/158/My-IP-is-being-leaked-by-WebRTC-How-do-I-disable-it.html) how to disable it. | ||
| _Default: no hiding; `Forwarded: for="useraddress"` will be sent out._ | ||
|
|
||
| - **hide_via** | ||
| If set, forwardproxy will not add Via header, and prevents simple way to detect proxy usage. | ||
| WARNING: there are other side-channels to determine this. | ||
| _Default: no hiding; Header in form of `Via: 2.0 caddy` will be sent out._ | ||
|
|
||
| ##### Access Control | ||
|
|
||
| - **ports [integer] [integer]...** | ||
| Specifies ports forwardproxy will whitelist for all requests. Other ports will be forbidden. | ||
| _Default: no restrictions._ | ||
|
|
||
| - **acl { | ||
| acl_directive | ||
| ... | ||
| acl_directive | ||
| }** | ||
| Specifies **order** and rules for allowed destination IP networks, IP addresses and hostnames. | ||
| The hostname in each forwardproxy request will be resolved to an IP address, | ||
| and caddy will check the IP address and hostname against the directives in order until a directive matches the request. | ||
| acl_directive may be: | ||
| - **allow [ip or subnet or hostname] [ip or subnet or hostname]...** | ||
| - **allow_file /path/to/whitelist.txt** | ||
| - **deny [ip or subnet or hostname] [ip or subnet or hostname]...** | ||
| - **deny_file /path/to/blacklist.txt** | ||
|
|
||
| If you don't want unmatched requests to be subject to the default policy, you could finish | ||
| your acl rules with one of the following to specify action on unmatched requests: | ||
| - **allow all** | ||
| - **deny all** | ||
|
|
||
| For hostname, you can specify `*.` as a prefix to match domain and subdomains. For example, | ||
| `*.caddyserver.com` will match `caddyserver.com`, `subdomain.caddyserver.com`, but not `fakecaddyserver.com`. | ||
| Note that hostname rules, matched early in the chain, will override later IP rules, | ||
| so it is advised to put IP rules first, unless domains are highly trusted and should override the | ||
| IP rules. Also note that domain-based blacklists are easily circumventable by directly specifying the IP. | ||
| For `allow_file`/`deny_file` directives, syntax is the same, and each entry must be separated by newline. | ||
| This policy applies to all requests except requests to the proxy's own domain and port. | ||
| Whitelisting/blacklisting of ports on per-host/IP basis is not supported. | ||
| _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 | ||
| } | ||
| _Default deny rules intend to prohibit access to localhost and local networks and may be expanded in future._ | ||
|
|
||
| ##### Timeouts | ||
|
|
||
| - **dial_timeout [integer]** | ||
| Sets timeout (in seconds) for establishing TCP connection to target website. Affects all requests. | ||
| _Default: 20 seconds._ | ||
|
|
||
| ##### Other | ||
|
|
||
| - **serve_pac [/path.pac]** | ||
| Generate (in-memory) and serve a [Proxy Auto-Config](https://en.wikipedia.org/wiki/Proxy_auto-config) file on given path. If no path is provided, the PAC file will be served at `/proxy.pac`. NOTE: If you enable probe_resistance, your PAC file should also be served at a secret location; serving it at a predictable path can easily defeat probe resistance. | ||
| _Default: no PAC file will be generated or served by Caddy (you still can manually create and serve proxy.pac like a regular file)._ | ||
|
|
||
| - **upstream [`https://username:[email protected]:443`]** | ||
| Sets upstream proxy to route all forwardproxy requests through it. | ||
| This setting does not affect non-forwardproxy requests nor requests with wrong credentials. | ||
| Upstream is incompatible with `acl` and `ports` subdirectives. | ||
| Supported schemes to remote host: https. | ||
| Supported schemes to localhost: socks5, http, https (certificate check is ignored). | ||
| _Default: no upstream proxy._ | ||
| ### Security | ||
|
|
||
| - `basic_auth [user] [password]` | ||
| Sets basic HTTP auth credentials. This property may be repeated multiple times. Note that this is different from Caddy's built-in `basic_auth` directive. BE SURE TO CHECK THE NAME OF THE SITE THAT IS REQUESTING CREDENTIALS BEFORE YOU ENTER THEM. | ||
|
|
||
| Default: no authentication required. | ||
| - `probe_resistance [secretlink.tld]` | ||
| Attempts to hide the fact that the site is a forward proxy. | ||
| Proxy will no longer respond with "407 Proxy Authentication Required" if credentials are incorrect or absent, | ||
| and will attempt to mimic a generic Caddy web server as if the forward proxy is not enabled. | ||
|
|
||
| Probing resistance works (and makes sense) only if `basic_auth` is set up. | ||
| To use your proxy with probe resistance, supply your `basic_auth` credentials to your client configuration. | ||
| If your proxy client(browser, operating system, browser extension, etc) | ||
| allows you to preconfigure credentials, and sends credentials preemptively, you do not need secret link. | ||
|
|
||
| If your proxy client does not preemptively send credentials, you will have to visit your secret link in your browser to trigger the authentication. | ||
| Make sure that specified domain name is visitable, does not contain uppercase characters, does not start with dot, etc. | ||
| Only this address will trigger a 407 response, prompting browsers to request credentials from user and cache them for the rest of the session. | ||
|
|
||
| Default: no probing resistance. | ||
|
|
||
| ### Privacy | ||
|
|
||
| - `hide_ip` | ||
| If set, forwardproxy will not add user's IP to "Forwarded:" header. | ||
|
|
||
| WARNING: there are other side-channels in your browser, that you might want to eliminate, such as WebRTC, see [here](https://www.ivpn.net/knowledgebase/158/My-IP-is-being-leaked-by-WebRTC-How-do-I-disable-it.html) how to disable it. | ||
|
|
||
| Default: no hiding; `Forwarded: for="useraddress"` will be sent out. | ||
| - `hide_via` | ||
| If set, forwardproxy will not add Via header, and prevents simple way to detect proxy usage. | ||
|
|
||
| WARNING: there are other side-channels to determine this. | ||
|
|
||
| Default: no hiding; Header in form of `Via: 2.0 caddy` will be sent out. | ||
|
|
||
| ### Access Control | ||
|
|
||
| - `ports [integer] [integer]...` | ||
| Specifies ports forwardproxy will whitelist for all requests. Other ports will be forbidden. | ||
|
|
||
| Default: no restrictions. | ||
| - acl { | ||
| acl_directive | ||
| ... | ||
| acl_directive | ||
| } | ||
| Specifies **order** and rules for allowed destination IP networks, IP addresses and hostnames. | ||
| The hostname in each forwardproxy request will be resolved to an IP address, | ||
| and caddy will check the IP address and hostname against the directives in order until a directive matches the request. | ||
|
|
||
| `acl_directive` may be: | ||
| - `allow [ip or subnet or hostname] [ip or subnet or hostname]...` | ||
| - `allow_file /path/to/whitelist.txt` | ||
| - `deny [ip or subnet or hostname] [ip or subnet or hostname]...` | ||
| - `deny_file /path/to/blacklist.txt` | ||
|
|
||
| If you don't want unmatched requests to be subject to the default policy, you could finish | ||
| your acl rules with one of the following to specify action on unmatched requests: | ||
| - `allow all` | ||
| - `deny all` | ||
|
|
||
| For `hostname`, you can specify `*.` as a prefix to match domain and subdomains. For example, | ||
| `*.caddyserver.com` will match `caddyserver.com`, `subdomain.caddyserver.com`, but not `fakecaddyserver.com`. | ||
| Note that hostname rules, matched early in the chain, will override later IP rules, | ||
| so it is advised to put IP rules first, unless domains are highly trusted and should override the | ||
| IP rules. Also note that domain-based blacklists are easily circumventable by directly specifying the IP. | ||
|
|
||
| For `allow_file`/`deny_file` directives, syntax is the same, and each entry must be separated by newline. | ||
|
|
||
| This policy applies to all requests except requests to the proxy's own domain and port. | ||
| Whitelisting/blacklisting of ports on per-host/IP basis is not supported. | ||
|
|
||
| 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 | ||
| } | ||
| ``` | ||
|
|
||
| Default deny rules intend to prohibit access to localhost and local networks and may be expanded in future. | ||
|
|
||
| ### Timeouts | ||
|
|
||
| - `dial_timeout [integer]` | ||
| Sets timeout (in seconds) for establishing TCP connection to target website. Affects all requests. | ||
|
|
||
| Default: 20 seconds. | ||
|
|
||
| ### Other | ||
|
|
||
| - `serve_pac [/path.pac]` | ||
| Generate (in-memory) and serve a [Proxy Auto-Config](https://en.wikipedia.org/wiki/Proxy_auto-config) file on given path. If no path is provided, the PAC file will be served at `/proxy.pac`. NOTE: If you enable probe_resistance, your PAC file should also be served at a secret location; serving it at a predictable path can easily defeat probe resistance. | ||
|
|
||
| Default: no PAC file will be generated or served by Caddy (you still can manually create and serve proxy.pac like a regular file). | ||
| - `upstream [https://username:[email protected]:443]` | ||
| Sets upstream proxy to route all forwardproxy requests through it. | ||
| This setting does not affect non-forwardproxy requests nor requests with wrong credentials. | ||
| Upstream is incompatible with `acl` and `ports` subdirectives. | ||
|
|
||
| Supported schemes to remote host: https. | ||
|
|
||
| Supported schemes to localhost: socks5, http, https (certificate check is ignored). | ||
|
|
||
| Default: no upstream proxy. | ||
|
|
||
| ## Get forwardproxy | ||
| #### Download prebuilt binary | ||
| ### Download prebuilt binary | ||
| Binaries are at https://caddyserver.com/download | ||
| Don't forget to add `http.forwardproxy` plugin. | ||
|
|
||
| #### Build from source | ||
| ### Build from source | ||
|
|
||
| 0. Install latest Golang 1.20 or above and set export GO111MODULE=on | ||
| 1. ```bash | ||
| go install github.com/caddyserver/forwardproxy/cmd/caddy@latest | ||
| ``` | ||
| Built `caddy` binary will be stored in $GOPATH/bin. | ||
| 0. Install latest Golang 1.20 or above and set `export GO111MODULE=on` | ||
| 1. `go install github.com/caddyserver/forwardproxy/cmd/caddy@latest` | ||
| Built `caddy` binary will be stored in $GOPATH/bin. | ||
|
|
||
| ## Client Configuration | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.