Niko/forwardproxy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Start to update README for Caddy 2

Browse source
This commit is contained in:
Matthew Holt 2023-05-09 13:19:19 -06:00
parent a7059fa9b0
commit 0ea925feff
No known key found for this signature in database
GPG key ID: 2A349DD577D586A5
1 changed files with 118 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

162
README.md
View file

@ -1,7 +1,81 @@
# Secure forward proxy plugin for the Caddy web server
# 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:**
- Safely deploying this module
- Trying to break it
- Contributing to the code and tests in this repo to make it better
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
- HTTP/1.1 and HTTP/2 support
- Authentication
- Access control lists
- Optional probe resistance
- PAC file
## 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](https://caddyserver.com/docs/getting-started).
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
```
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
}
```
(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.
[![Build Status](https://travis-ci.org/caddyserver/forwardproxy.svg?branch=master)](https://travis-ci.org/caddyserver/forwardproxy)
[![Join the chat at https://gitter.im/forwardproxy/Lobby](https://badges.gitter.im/forwardproxy/Lobby.svg)](https://gitter.im/forwardproxy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
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.
@ -23,27 +97,27 @@ Here's an example of all properties in use (note that the syntax is subject to c
```
:443, example.com
route {
forward_proxy {
basicauth user1 password1
basicauth user2 password2
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
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
}
```
@ -95,24 +169,24 @@ Specifies **order** and rules for allowed destination IP networks, IP addresses
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**
- **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.
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
@ -149,9 +223,9 @@ Don't forget to add `http.forwardproxy` plugin.
0. Install latest Golang 1.12 or above and set export GO111MODULE=on
1. ```bash
go install github.com/caddyserver/forwardproxy/cmd/caddy
```
Built `caddy` binary will be stored in $GOPATH/bin.
go install github.com/caddyserver/forwardproxy/cmd/caddy
```
Built `caddy` binary will be stored in $GOPATH/bin.
## Client Configuration