Update README

This commit is contained in:
Toby 2021-03-27 23:31:20 -07:00
parent ed5442de15
commit a67e245a87
2 changed files with 240 additions and 261 deletions

266
README.md
View File

@ -16,62 +16,91 @@
[中文 README](README.zh.md)
Hysteria is a set of relay & proxy utilities that are specifically optimized for harsh network environments (commonly
seen in connecting to overseas servers from China). It's based on a modified version of the QUIC protocol, and can be
considered a sequel to my previous (abandoned) project https://github.com/dragonite-network/dragonite-java
Hysteria is a TCP relay & SOCKS5/HTTP proxy tool optimized for poor network environments (satellite networks,
connections from China to foreign servers, etc.) powered by a custom version of QUIC protocol.
It is essentially a spiritual successor of my previous (now abandoned)
project https://github.com/dragonite-network/dragonite-java
## Quick Start
(See the [advanced usage section](#advanced-usage) for the exact meaning of each argument)
Note: The configs provided in this section are only for people to get started quickly and may not meet your needs.
Please go to [Advanced usage](#advanced-usage) to see all the available options and their meanings.
### Proxy
### Server
Server:
Create a `config.json` under the root directory of the program:
```
./cmd_linux_amd64 proxy server -listen :36712 -cert example.crt -key example.key -obfs BlueberryFaygo
```json
{
"listen": ":36712",
"cert": "/home/ubuntu/my_cert.crt",
"key": "/home/ubuntu/my_key.crt",
"obfs": "AMOGUS",
"up_mbps": 100,
"down_mbps": 100
}
```
A TLS certificate (not necessarily issued by a trusted CA) is required on the server side. If you are using a
self-issued certificate, use `-ca` to specify your own CA file on clients, or `-insecure` to ignore all certificate
errors (not recommended)
A TLS certificate (not necessarily issued by a trusted CA) is required on the server side.
Client:
The (optional) `obfs` option obfuscates the protocol using the provided password, so that it is not apparent that this
is Hysteria/QUIC, which could be useful for bypassing DPI blocking or QoS. If the passwords of the server and client do
not match, no connection can be established. Therefore, this can also serve as a simple password authentication. For
more advanced authentication schemes, see `auth` below.
`up_mbps` and `down_mbps` limit the maximum upload and download speed of the server for each client. These are also
optional and can be removed if not needed.
To launch the server, simply run
```
./cmd_linux_amd64 proxy client -server example.com:36712 -socks5-addr localhost:1080 -up-mbps 10 -down-mbps 50 -obfs BlueberryFaygo
./cmd_linux_amd64 server
```
This will start a SOCKS5 proxy server on the client's localhost TCP 1080 available for use by other programs.
In addition to SOCKS5, it also supports HTTP proxy (`-http-addr` & `-http-timeout`). Both modes can be turned on
simultaneously on different ports.
`-up-mbps 10 -down-mbps 50` tells the server that your bandwidth is 50 Mbps down, 10 Mbps up. Properly setting the
client's upload and download speeds based on your network conditions is essential for it to work at optimal performance!
### Relay
Suppose you have a TCP program on your server at `localhost:8080` that you want to forward.
Server:
If your config file is not named `config.json` or is in a different path, specify it with `-config`:
```
./cmd_linux_amd64 relay server -listen :36712 -remote localhost:8080 -cert example.crt -key example.key
./cmd_linux_amd64 server -config blah.json
```
Client:
### Client
```
./cmd_linux_amd64 relay client -server example.com:36712 -listen localhost:8080 -up-mbps 10 -down-mbps 50
Same as the server side, create a `config.json` under the root directory of the program:
```json
{
"server": "example.com:36712",
"obfs": "AMOGUS",
"up_mbps": 10,
"down_mbps": 50,
"socks5": {
"listen": "127.0.0.1:1080"
},
"http": {
"listen": "127.0.0.1:8080"
},
"relay": {
"listen": "127.0.0.1:2222",
"remote": "123.123.123.123:22"
}
}
```
All connections to client's localhost TCP 8080 will pass through the relay and connect to the server's `localhost:8080`
This config enables a SOCKS5 proxy (with both TCP & UDP support), an HTTP proxy, and a TCP relay to `123.123.123.123:22`
at the same time. Please modify or remove these entries depending on your actual needs.
Some users may attempt to forward other encrypted proxy protocols such as Shadowsocks with relay. While this totally
works, it's not optimal from a performance standpoint - our protocol itself uses TLS, considering that the proxy
protocols being forwarded are also encrypted, and the fact that users mainly use them for HTTPS connections nowadays,
you are essentially doing triple encryption. If you need a proxy, use our proxy mode.
If your server certificate is not issued by a trusted CA, you need to specify the CA used
with `"ca": "/path/to/file.ca"` on the client or use `"insecure": true` to ignore all certificate errors (not
recommended).
`up_mbps` and `down_mbps` are mandatory on the client side. Please try to fill in these values as accurately as possible
according to your network conditions. They are crucial for Hysteria to work in an optimal state.
Some users may attempt to forward other encrypted proxy protocols such as Shadowsocks with relay. While this technically
works, it's not optimal from a performance standpoint - Hysteria itself uses TLS, considering that the proxy protocol
being forwarded is also encrypted, and the fact that almost all sites are now using HTTPS, it essentially becomes triple
encryption. If you need a proxy, just use our proxy modes.
## Comparison
@ -83,119 +112,78 @@ Proxy Server: AWS US West Oregon (us-west-2)
## Advanced usage
The command line program supports loading configurations from both JSON files and arguments. Use `-config` to specify a
JSON file. Config loaded from it can also be overwritten or extended with command line arguments.
### Server
### Proxy server
```json5
{
"listen": ":36712", // Listen address
"cert": "/home/ubuntu/my_cert.crt", // Cert file
"key": "/home/ubuntu/my_key.crt", // Key file
"up_mbps": 100, // Max upload Mbps per client
"down_mbps": 100, // Max download Mbps per client
"disable_udp": false, // Disable UDP support
"acl": "my_list.acl", // See ACL below
"obfs": "AMOGUS", // Obfuscation password
"auth": { // Authentication
"mode": "password", // Mode, only supports "password" and "none" for now
"config": {
"password": "yubiyubi"
}
},
"recv_window_conn": 33554432, // QUIC stream receive window
"recv_window_client": 67108864, // QUIC connection receive window
"max_conn_client": 4096 // Max concurrent connections per client
}
```
| Description | JSON config field | CLI argument |
| --- | --- | --- |
| Server listen address | listen | -listen |
| Disable UDP support | disable_udp | -disable-udp |
| Access control list | acl | -acl |
| TLS certificate file | cert | -cert |
| TLS key file | key | -key |
| Authentication file | auth | -auth |
| Max upload speed per client in Mbps | up_mbps | -up-mbps |
| Max download speed per client in Mbps | down_mbps | -down-mbps |
| Max receive window size per connection | recv_window_conn | -recv-window-conn |
| Max receive window size per client | recv_window_client | -recv-window-client |
| Max simultaneous connections allowed per client | max_conn_client | -max-conn-client |
| Obfuscation key | obfs | -obfs |
### Client
### Proxy client
```json5
{
"server": "example.com:36712", // Server address
"up_mbps": 10, // Max upload Mbps
"down_mbps": 50, // Max download Mbps
"socks5": {
"listen": "127.0.0.1:1080", // SOCKS5 listen address
"timeout": 300, // TCP timeout in seconds
"disable_udp": false, // Disable UDP support
"user": "me", // SOCKS5 authentication username
"password": "lmaolmao" // SOCKS5 authentication password
},
"http": {
"listen": "127.0.0.1:8080", // HTTP listen address
"timeout": 300, // TCP timeout in seconds
"user": "me", // HTTP authentication username
"password": "lmaolmao", // HTTP authentication password
"cert": "/home/ubuntu/my_cert.crt", // Cert file (HTTPS proxy)
"key": "/home/ubuntu/my_key.crt" // Key file (HTTPS proxy)
},
"relay": {
"listen": "127.0.0.1:2222", // Relay listen address
"remote": "123.123.123.123:22", // Relay remote address
"timeout": 300 // TCP timeout in seconds
},
"acl": "my_list.acl", // See ACL below
"obfs": "AMOGUS", // Obfuscation password
"auth": "[BASE64]", // Authentication payload in Base64
"auth_str": "yubiyubi", // Authentication payload in string, mutually exclusive with the option above
"insecure": false, // Ignore all certificate errors
"ca": "my.ca", // Custom CA file
"recv_window_conn": 33554432, // QUIC stream receive window
"recv_window": 67108864 // QUIC connection receive window
}
```
| Description | JSON config field | CLI argument |
| --- | --- | --- |
| SOCKS5 listen address | socks5_addr | -socks5-addr |
| SOCKS5 connection timeout in seconds | socks5_timeout | -socks5-timeout |
| Disable SOCKS5 UDP support | socks5_disable_udp | -socks5-disable-udp |
| SOCKS5 auth username | socks5_user | -socks5-user |
| SOCKS5 auth password | socks5_password | -socks5-password |
| HTTP listen address | http_addr | -http-addr |
| HTTP connection timeout in seconds | http_timeout | -http-timeout |
| HTTP basic auth username | http_user | -http-user |
| HTTP basic auth password | http_password | -http-password |
| HTTPS certificate file | https_cert | -http-cert |
| HTTPS key file | https_key | -http-key |
| Access control list | acl | -acl |
| Server address | server | -server |
| Authentication username | username | -username |
| Authentication password | password | -password |
| Ignore TLS certificate errors | insecure | -insecure |
| Specify a trusted CA file | ca | -ca |
| Upload speed in Mbps | up_mbps | -up-mbps |
| Download speed in Mbps | down_mbps | -down-mbps |
| Max receive window size per connection | recv_window_conn | -recv-window-conn |
| Max receive window size | recv_window | -recv-window |
| Obfuscation key | obfs | -obfs |
#### About SOCKS5
Supports TCP (CONNECT) and UDP (ASSOCIATE) commands. BIND is not supported and is not planned to be supported.
#### About ACL
## ACL
[ACL File Format](ACL.md)
#### About proxy authentication
## Logging
Proxy supports username and password authentication (sent encrypted with TLS). If the server starts with an
authentication file, it will check for the existence of the corresponding username and password in this file when each
user connects. A valid authentication file is a text file with a pair of username and password per line (separated by a
space). Example:
The program outputs `DEBUG` level, text format logs via stdout by default.
```
admin K2MfcwyZNJy3
shady_hacker smokeweed420
This line is invalid and will be ignored
```
Changes to the file take effect immediately while the server is running.
#### About obfuscation
To prevent firewalls from potentially detecting & blocking the protocol, a simple XOR-based packet obfuscation mechanism
has been built in. Note that clients and servers with different obfuscation settings are not be able to communicate at
all.
### Relay server
| Description | JSON config field | CLI argument |
| --- | --- | --- |
| Server listen address | listen | -listen |
| Remote relay address | remote | -remote |
| TLS certificate file | cert | -cert |
| TLS key file | key | -key |
| Max upload speed per client in Mbps | up_mbps | -up-mbps |
| Max download speed per client in Mbps | down_mbps | -down-mbps |
| Max receive window size per connection | recv_window_conn | -recv-window-conn |
| Max receive window size per client | recv_window_client | -recv-window-client |
| Max simultaneous connections allowed per client | max_conn_client | -max-conn-client |
| Obfuscation key | obfs | -obfs |
### Relay client
| Description | JSON config field | CLI argument |
| --- | --- | --- |
| TCP listen address | listen | -listen |
| Server address | server | -server |
| Client name presented to the server | name | -name |
| Ignore TLS certificate errors | insecure | -insecure |
| Specify a trusted CA file | ca | -ca |
| Upload speed in Mbps | up_mbps | -up-mbps |
| Download speed in Mbps | down_mbps | -down-mbps |
| Max receive window size per connection | recv_window_conn | -recv-window-conn |
| Max receive window size | recv_window | -recv-window |
| Obfuscation key | obfs | -obfs |
## Logs
By default, the program outputs DEBUG level, text format logs via stdout.
To change the logging level, set `LOGGING_LEVEL` environment variable, which supports `panic`, `fatal`, `error`, `warn`
, `info`, ` debug`, `trace`
To change the logging level, use `LOGGING_LEVEL` environment variable. The available levels are `panic`, `fatal`
, `error`, `warn`, `info`, ` debug`, `trace`
To print JSON instead, set `LOGGING_FORMATTER` to `json`

View File

@ -14,55 +14,81 @@
[6]: https://t.me/hysteria_github
Hysteria 是专门针对恶劣网络环境(常见于在中国访问海外服务器)进行优化的连接转发和代理工具(即所谓的双边加速)。其基于修改版的 QUIC
协议,可以理解为是我此前弃坑的项目 https://github.com/dragonite-network/dragonite-java 的续作。
Hysteria 是专门针对恶劣网络环境(常见于卫星网络、在中国连接国外服务器等)进行优化的 TCP 连接转发和代理工具(即所谓的双边加速),
基于修改版的 QUIC 协议。
可以理解为是我此前弃坑的项目 https://github.com/dragonite-network/dragonite-java 的续作。
## 快速入门
关于每个参数具体的含义请见 [高级用法](#高级用法)
注意:本节提供的配置只是为了快速上手,可能无法满足你的需求。请到 [高级用法](#高级用法) 中查看所有可用选项及其含义。
### 代理
### 服务器
服务端
在目录下建立一个 `config.json`
```
./cmd_linux_amd64 proxy server -listen :36712 -cert example.crt -key example.key -obfs BlueberryFaygo
```json
{
"listen": ":36712",
"cert": "/home/ubuntu/my_cert.crt",
"key": "/home/ubuntu/my_key.crt",
"obfs": "AMOGUS",
"up_mbps": 100,
"down_mbps": 100
}
```
服务端需要一个 TLS 证书(不一定是由可信 CA 签发的有效证书)。如果你使用自签证书,请在客户端使用 `-ca` 指定你自己的 CA 文件,或者用 `-insecure` 忽略所有证书错误(不推荐)
服务端必须要一个 TLS 证书(但并非一定要受信 CA 签发的)。
客户端
`obfs` 选项使用提供的密码对协议进行混淆,这样协议就不容易被检测出是 Hysteria/QUIC可以用来绕过针对性的 DPI 屏蔽或者 QoS。
如果服务端和客户端的密码不匹配就不能建立连接,因此这也可以作为一个简单的密码验证。对于更高级的验证方案请见下文 `auth`
`up_mbps``down_mbps` 限制服务器对每个客户端的最大上传和下载速度。这些也是可选的,如果不需要可以移除。
要启动服务端,只需运行
```
./cmd_linux_amd64 proxy client -server example.com:36712 -socks5-addr localhost:1080 -up-mbps 10 -down-mbps 50 -obfs BlueberryFaygo
./cmd_linux_amd64 server
```
在客户端的本地 TCP 1080 上启动一个 SOCKS5 代理服务器供其他程序使用。
除了 SOCKS5 还支持 HTTP 代理 (`-http-addr` & `-http-timeout`)。两个模式可以同时开在不同端口。
`-up-mbps 10 -down-mbps 50` 是告诉服务端你的下行速度为 50 Mbps, 上行 10 Mbps。根据实际网络条件正确设置客户端的上传和下载速度十分重要
### 转发
假设你想转发服务端上 `localhost:8080` 的一个 TCP 协议程序。
服务端
如果你的配置文件没有命名为 `config.json` 或在别的路径,请用 `-config` 指定路径:
```
./cmd_linux_amd64 relay server -listen :36712 -remote localhost:8080 -cert example.crt -key example.key
./cmd_linux_amd64 server -config blah.json
```
客户端
### 客户端
```
./cmd_linux_amd64 relay client -server example.com:36712 -listen localhost:8080 -up-mbps 10 -down-mbps 50
和服务器端一样,在程序根目录下建立一个`config.json`
```json
{
"server": "example.com:36712",
"obfs": "AMOGUS",
"up_mbps": 10,
"down_mbps": 50,
"socks5": {
"listen": "127.0.0.1:1080"
},
"http": {
"listen": "127.0.0.1:8080"
},
"relay": {
"listen": "127.0.0.1:2222",
"remote": "123.123.123.123:22"
}
}
```
所有到客户端本地 TCP 8080 的 TCP 连接都将通过转发,到服务器连接那里的 `localhost:8080`
这个配置同时开了 SOCK5 (支持 TCP & UDP) 代理HTTP 代理和到 `123.123.123.123:22` 的 TCP 转发。请根据自己实际需要修改和删减。
有些用户可能会尝试用这个功能转发其他加密代理协议比如Shadowsocks。虽然这完全可行但从性能的角度并不是最佳选择 - 我们的协议本身就有 TLS转发的代理协议也是加密的再加上用户用来访问 HTTPS
网站,等于做了三重加密。如果需要代理就用我们的代理模式。
如果你的服务端证书不是由受信任的 CA 签发的,需要用 `"ca": "/path/to/file.ca"` 指定使用的 CA 或者用 `"insecure": true` 忽略所有
证书错误(不推荐)。
`up_mbps``down_mbps` 在客户端是必填选项,请根据实际网络情况尽量准确地填写,否则将影响 Hysteria 的使用体验。
有些用户可能会尝试用这个功能转发其他加密代理协议,比如 Shadowsocks。这样虽然可行但从性能的角度不推荐 - Hysteria 本身就用 TLS
转发的代理协议也是加密的,再加上如今几乎所有网站都是 HTTPS 了,等于做了三重加密。如果需要代理就用我们的代理模式。
## 对比
@ -74,107 +100,72 @@ Hysteria 是专门针对恶劣网络环境(常见于在中国访问海外服
## 高级用法
命令行程序支持从 JSON 文件和参数加载配置。使用 `-config` 指定一个JSON文件。从文件加载的配置也可以被命令行参数覆盖或进一步扩展。
### Server
### 代理 服务端
```json5
{
"listen": ":36712", // 监听地址
"cert": "/home/ubuntu/my_cert.crt", // 证书
"key": "/home/ubuntu/my_key.crt", // 证书密钥
"up_mbps": 100, // 单客户端最大上传速度
"down_mbps": 100, // 单客户端最大下载速度
"disable_udp": false, // 禁用 UDP 支持
"acl": "my_list.acl", // 见下文 ACL
"obfs": "AMOGUS", // 混淆密码
"auth": { // 验证
"mode": "password", // 验证模式,暂时只支持 "password" 与 "none"
"config": {
"password": "yubiyubi"
}
},
"recv_window_conn": 33554432, // QUIC stream receive window
"recv_window_client": 67108864, // QUIC connection receive window
"max_conn_client": 4096 // 单客户端最大活跃连接数
}
```
| 描述 | JSON 字段 | 命令行参数 |
| --- | --- | --- |
| 服务端监听地址 | listen | -listen |
| 禁用 UDP 支持 | disable_udp | -disable-udp |
| ACL 规则文件 | acl | -acl |
| TLS 证书文件 | cert | -cert |
| TLS 密钥文件 | key | -key |
| 用户名密码验证文件 | auth | -auth |
| 单客户端最大上传速度 Mbps | up_mbps | -up-mbps |
| 单客户端最大下载速度 Mbps | down_mbps | -down-mbps |
| 单连接最大接收窗口大小 | recv_window_conn | -recv-window-conn |
| 单客户端最大接收窗口大小 | recv_window_client | -recv-window-client |
| 单客户端最大连接数 | max_conn_client | -max-conn-client |
| 混淆密钥 | obfs | -obfs |
### Client
### 代理 客户端
```json5
{
"server": "example.com:36712", // 服务器地址
"up_mbps": 10, // 最大上传速度
"down_mbps": 50, // 最大下载速度
"socks5": {
"listen": "127.0.0.1:1080", // SOCKS5 监听地址
"timeout": 300, // TCP 超时秒数
"disable_udp": false, // 禁用 UDP 支持
"user": "me", // SOCKS5 验证用户名
"password": "lmaolmao" // SOCKS5 验证密码
},
"http": {
"listen": "127.0.0.1:8080", // HTTP 监听地址
"timeout": 300, // TCP 超时秒数
"user": "me", // HTTP 验证用户名
"password": "lmaolmao", // HTTP 验证密码
"cert": "/home/ubuntu/my_cert.crt", // 证书 (变为 HTTPS 代理)
"key": "/home/ubuntu/my_key.crt" // 证书密钥 (变为 HTTPS 代理)
},
"relay": {
"listen": "127.0.0.1:2222", // 转发监听地址
"remote": "123.123.123.123:22", // 转发目标地址
"timeout": 300 // TCP 超时秒数
},
"acl": "my_list.acl", // 见下文 ACL
"obfs": "AMOGUS", // 混淆密码
"auth": "[BASE64]", // Base64 验证密钥
"auth_str": "yubiyubi", // 字符串验证密钥,和上面的选项二选一
"insecure": false, // 忽略一切证书错误
"ca": "my.ca", // 自定义 CA
"recv_window_conn": 33554432, // QUIC stream receive window
"recv_window": 67108864 // QUIC connection receive window
}
```
| 描述 | JSON 字段 | 命令行参数 |
| --- | --- | --- |
| SOCKS5 监听地址 | socks5_addr | -socks5-addr |
| SOCKS5 超时时间(秒) | socks5_timeout | -socks5-timeout |
| 禁用 SOCKS5 UDP 支持 | socks5_disable_udp | -socks5-disable-udp |
| SOCKS5 验证用户名 | socks5_user | -socks5-user |
| SOCKS5 验证密码 | socks5_password | -socks5-password |
| HTTP 监听地址 | http_addr | -http-addr |
| HTTP 超时时间(秒) | http_timeout | -http-timeout |
| HTTP 验证用户名 | http_user | -http-user |
| HTTP 验证密码 | http_password | -http-password |
| HTTPS 证书文件 | https_cert | -http-cert |
| HTTPS 密钥文件 | https_key | -http-key |
| ACL 规则文件 | acl | -acl |
| 服务端地址 | server | -server |
| 验证用户名 | username | -username |
| 验证密码 | password | -password |
| 忽略证书错误 | insecure | -insecure |
| 指定可信 CA 文件 | ca | -ca |
| 上传速度 Mbps | up_mbps | -up-mbps |
| 下载速度 Mbps | down_mbps | -down-mbps |
| 单连接最大接收窗口大小 | recv_window_conn | -recv-window-conn |
| 总最大接收窗口大小 | recv_window | -recv-window |
| 混淆密钥 | obfs | -obfs |
#### 关于 SOCKS5
支持 TCP (CONNECT) 和 UDP (ASSOCIATE),不支持 BIND 也无计划支持。
#### 关于 ACL
## 关于 ACL
[ACL 文件格式](ACL.zh.md)
#### 关于用户名密码验证
代理支持用户名和密码认证(经过 TLS 加密发送)。如果服务器启动时指定了一个验证文件,当每个用户连接时,服务器会检查该文件中是否存在相应的用户名和密码。验证文件是一个文本文件,每行有一对用户名和密码(用空格分割)。比如:
```
admin K2MfcwyZNJy3
shady_hacker smokeweed420
这行无效会被忽略
```
对文件的更改立即生效,即使服务端正在运行。
#### 关于混淆
为了防止各类防火墙今后可能检测并阻止协议,程序内置了简单的基于 XOR 的数据包混淆机制。注意客户端和服务器的混淆设置如果不同则完全无法通信。
### 转发 服务端
| 描述 | JSON 字段 | 命令行参数 |
| --- | --- | --- |
| 服务端监听地址 | listen | -listen |
| 转发目标地址 | remote | -remote |
| TLS 证书文件 | cert | -cert |
| TLS 密钥文件 | key | -key |
| 单客户端最大上传速度 Mbps | up_mbps | -up-mbps |
| 单客户端最大下载速度 Mbps | down_mbps | -down-mbps |
| 单连接最大接收窗口大小 | recv_window_conn | -recv-window-conn |
| 单客户端最大接收窗口大小 | recv_window_client | -recv-window-client |
| 单客户端最大连接数 | max_conn_client | -max-conn-client |
| 混淆密钥 | obfs | -obfs |
### 转发 客户端
| 描述 | JSON 字段 | 命令行参数 |
| --- | --- | --- |
| TCP 监听地址 | listen | -listen |
| 服务端地址 | server | -server |
| 客户端名称 | name | -name |
| 忽略证书错误 | insecure | -insecure |
| 指定可信 CA 文件 | ca | -ca |
| 上传速度 Mbps | up_mbps | -up-mbps |
| 下载速度 Mbps | down_mbps | -down-mbps |
| 单连接最大接收窗口大小 | recv_window_conn | -recv-window-conn |
| 总最大接收窗口大小 | recv_window | -recv-window |
| 混淆密钥 | obfs | -obfs |
## 日志
程序默认在 stdout 输出 DEBUG 级别,文字格式的日志。