Improve README

This commit is contained in:
Andrew Gaul 2017-01-16 16:35:53 -08:00
parent cde47b46f3
commit 84b6dbd153

View file

@ -10,40 +10,46 @@ Features:
- HTTPS proxy (encrypted connection between client and proxy) - HTTPS proxy (encrypted connection between client and proxy)
- man in the middle support (compress HTTPS traffic) - man in the middle support (compress HTTPS traffic)
- HTTP2 support (over tls) - HTTP2 support (over TLS)
- gzip compression - gzip compression
- transcode animated gifs to static images - transcode animated GIFs to static images
- transcode jpeg images to desired quality using libjpeg - transcode JPEG images to desired quality using libjpeg
- transcode PNG and JPEG images to WebP - transcode PNG and JPEG images to WebP
- html/css/js minification - HTML/CSS/JavaScript minification
Installation Installation
------------ ------------
`go get github.com/barnacs/compy` ```
go get github.com/barnacs/compy
```
### HTTPS ### HTTPS
To use the proxy over HTTPS, you will need a certificate for your host. If you don't already have one, you can get one for [free](https://letsencrypt.org/) or you can generate a self-signed cert by running: To use the proxy over HTTPS, you will need a certificate for your host. If you don't already have one, you can get one for [free](https://letsencrypt.org/) or you can generate a self-signed cert by running:
`openssl req -x509 -newkey rsa:2048 -nodes -keyout cert.key -out cert.crt -days 3650 -subj '/CN=<your-domain>'`
then visit the proxy url and confirm that you trust your own certificate
To connect to the proxy over tls, you will need to supply a PAC (proxy auto-config) file to the browser, as most of them do not expose this option to the UI directly. Example:
``` ```
openssl req -x509 -newkey rsa:2048 -nodes -keyout cert.key -out cert.crt -days 3650 -subj '/CN=<your-domain>'
```
then visit the proxy URL and confirm that you trust your own certificate
To connect to the proxy over TLS, you will need to supply a PAC (proxy auto-config) file to the browser, as most of them do not expose this option to the UI directly. Example:
```javascript
function FindProxyForURL(url, host) { function FindProxyForURL(url, host) {
if (url.substring(0, 5) == 'http:' || url.substring(0, 6) == 'https:') { if (url.substring(0, 5) == 'http:' || url.substring(0, 6) == 'https:') {
return "HTTPS <your-domain>:9999"; return "HTTPS <your-domain>:9999";
} }
return "DIRECT"; return "DIRECT";
} }
``` ```
This tells the browser to fetch http/https urls via the https proxy and for all other schemas (eg. websocket) connect directly.
This tells the browser to fetch HTTP and HTTPS URLs via the HTTPS proxy and for all other schemas, e.g., WebSocket, connect directly.
Set the path to this file in the browser UI and you're good to go. Set the path to this file in the browser UI and you're good to go.
### MitM ### MitM
To enable man-in-the-middle support, you will need to generate a root cert to sign all the certs generated by the proxy on the fly: To enable man-in-the-middle support, you will need to generate a root cert to sign all the certs generated by the proxy on the fly:
`openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt -days 3650 -subj '/CN=<your-domain>'` ```
openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt -days 3650 -subj '/CN=<your-domain>'
```
and add it to your client (browser) as a trusted certificate authority and add it to your client (browser) as a trusted certificate authority
@ -51,22 +57,38 @@ Usage
----- -----
To run a simple http forward proxy: To run a simple http forward proxy:
`compy` ```
compy
```
To run it over tls: To run it over TLS:
`compy -cert cert.crt -key cert.key` ```
compy -cert cert.crt -key cert.key
```
With man in the middle support: With man in the middle support:
`compy -ca ca.crt -cakey ca.key` ```
compy -ca ca.crt -cakey ca.key
```
Probably the best option is to run it with both tls and mitm support, combining the two: Probably the best option is to run it with both TLS and MitM support, combining the two:
`compy -cert cert.crt -key cert.key -ca ca.crt -cakey ca.key` ```
compy -cert cert.crt -key cert.key -ca ca.crt -cakey ca.key
```
You can also specify the listen port (defaults to 9999): You can also specify the listen port (defaults to 9999):
`compy -host :9999` ```
compy -host :9999
```
For compression, transcoding and minification options, see `compy --help` For compression, transcoding and minification options, see `compy --help`
References
----------
* [Google Flywheel](https://www.usenix.org/conference/nsdi15/technical-sessions/presentation/agababov) - NSDI 2015 paper discussing techniques used by Chrome data saver
* [Mozilla Janus](https://wiki.mozilla.org/Mobile/Janus) - now-defunct experiment similar to compy
* [Ziproxy](https://en.wikipedia.org/wiki/Ziproxy) - older approach similar to compy
Credits Credits
------- -------