summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md71
1 files changed, 56 insertions, 15 deletions
diff --git a/README.md b/README.md
index c06aa29..1ab6924 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,72 @@
## hprox
-hprox is a lightweight HTTP/HTTPS proxy server.
+[![CircleCI](https://circleci.com/gh/bjin/hprox.svg?style=shield)](https://circleci.com/gh/bjin/hprox)
+[![Depends](https://img.shields.io/hackage-deps/v/hprox.svg)](https://packdeps.haskellers.com/feed?needle=hprox)
+[![Release](https://img.shields.io/github/release/bjin/hprox.svg)](https://github.com/bjin/hprox/releases)
+[![Hackage](https://img.shields.io/hackage/v/hprox.svg)](https://hackage.haskell.org/package/hprox)
+[![License](https://img.shields.io/github/license/bjin/hprox.svg)](https://github.com/bjin/hprox/blob/master/LICENSE)
+
+`hprox` is a lightweight HTTP/HTTPS proxy server.
### Features
-* Basic HTTP proxy support, including HTTP GET/HTTP CONNECT support.
+* Basic HTTP proxy functionality.
* Simple password authentication.
-* HTTPS encryption support, requires a valid certificate. Supports TLS 1.3 and
- HTTP 2 out of box. This mode is also known as SPDY Proxy.
-* TLS SNI validation in HTTPS mode. Blocks connections with wrong domain name.
-* Provide PAC file for easy client side configuration. Supports Chrome and Firefox.
-* Can run upon any Haskell Web Application with `wai` interface. Defaults to
- a dumb application which simulate the default empty page from Apache.
-* websocket redirection. Compatible with v2ray-plugin for shadowsocks.
-* Reverse proxy support. Redirect requests to a fallback server.
-
-Use `hprox --help` to list the options for further details.
+* TLS encryption (requires a valid certificate). Supports TLS 1.3 and HTTP 2, also known as SPDY Proxy.
+* TLS SNI validation (blocks all clients with invalid domain name).
+* Provide PAC file for easy client side configuration (supports Chrome and Firefox).
+* Websocket redirection (compatible with [v2ray-plugin for shadowsocks](https://github.com/shadowsocks/v2ray-plugin)).
+* Reverse proxy support (redirect requests to a fallback server).
+* Implemented as a middleware, compatible with any Haskell Web Application with `wai` interface.
+ Defaults to fallback to a dumb application which simulate the default empty page from Apache.
### Installation
-Only Linux and macOS are supported. [stack](https://docs.haskellstack.org/en/stable/README/#how-to-install) is required to build `hprox`.
+`hprox` should build and work on all unix-like OS with `ghc` support, but it's only
+been tested on Linux and macOS.
+
+[stack](https://docs.haskellstack.org/en/stable/README/#how-to-install) is required to build `hprox`.
```sh
+stack setup
stack install
```
+### Usage
+
+Use `hprox --help` to list options with detailed explanation.
+
+* To run `hprox` on port 8080, with simple password authentication:
+
+```sh
+echo "user:pass" > userpass.txt
+chmod 600 userpass.txt
+hprox -p 8080 -a userpass.txt
+```
+
+* To run `hprox` with TLS encryption on port 443, with certificate of `example.com` obtained with [certbot](https://certbot.eff.org/):
+
+```sh
+hprox -p 443 -s example.com:/etc/letsencrypt/live/example.com/fullchain.pem:/etc/letsencrypt/live/example.com/privkey.pem
+```
+
+Browsers can then be configured with PAC file URL `https://example.com/get/hprox.pac`.
+
+* To work with `v2ray-plugin`, with fallback page to ubuntu mirrors:
+
+```sh
+v2ray-plugin -server -localPort 8080 -mode websocket -host example.com -remotePort xxxx
+hprox -p 443 -s example.com:fullchain.pem:privkey.pem --ws 127.0.0.1:8080 --rev archive.ubuntu.com:80
+```
+
+Clients will be able to connect with option `tls;host=example.com`.
+
### Known Issue
-* Only HTTP server are supported for websocket and reverse proxy redirection.
-* Passwords are stored in plain text for now, please avoid using existing password.
+* Only HTTP servers are supported as websocket and reverse proxy redirection destination.
+* Passwords are currently stored in plain text, please set permission accordingly and
+ avoid using existing password.
+
+### License
+
+`hprox` is licensed under the Apache license. See LICENSE file for details.