From 95efd457d50b3401ccfe9134d0acdd4ce4e2549c Mon Sep 17 00:00:00 2001 From: Yujia Qiao Date: Tue, 25 Jan 2022 16:08:04 +0800 Subject: [PATCH] chore: rename docs --- README-zh.md | 33 +++++++++++++++--------- README.md | 30 ++++++++++++++------- docs/{security.md => transport.md} | 0 tests/config_test/valid_config/full.toml | 2 +- 4 files changed, 42 insertions(+), 23 deletions(-) rename docs/{security.md => transport.md} (100%) diff --git a/README-zh.md b/README-zh.md index b9ddada..dd9e3e9 100644 --- a/README-zh.md +++ b/README-zh.md @@ -1,4 +1,5 @@ # rathole + ![rathole-logo](./docs/img/rathole-logo.png) [![GitHub stars](https://img.shields.io/github/stars/rapiz1/rathole)](https://github.com/rapiz1/rathole/stargazers) @@ -44,6 +45,7 @@ rathole，类似于 [frp](https://github.com/fatedier/frp) 和 [ngrok](https://g 1. 在有一个公网 IP 的服务器上 创建 `server.toml`，内容如下，并根据你的需要调整。 + ```toml # server.toml [server] @@ -55,6 +57,7 @@ bind_addr = "0.0.0.0:5202" # `5202` 配置了将 `my_nas_ssh` 暴露给互联网 ``` 然后运行: + ```bash ./rathole server.toml ``` @@ -73,26 +76,29 @@ local_addr = "127.0.0.1:22" # 需要被转发的服务的地址 ``` 然后运行： + ```bash ./rathole client.toml ``` 3. 现在 `rathole` 客户端会连接运行在 `myserver.com:2333`的 `rathole` 服务器，任何到 `myserver.com:5202` 的流量将被转发到客户端所在主机的 `22` 端口。 -所以你可以 `ssh myserver.com:5202` 来 ssh 到你的NAS。 +所以你可以 `ssh myserver.com:5202` 来 ssh 到你的 NAS。 [Systemd examples](./examples/systemd) 中提供了一些让 `rathole` 在 Linux 上作为后台服务运行的配置示例。 ## Configuration + 如果只有一个 `[server]` 和 `[client]` 块存在的话，`rathole` 可以根据配置文件的内容自动决定在服务器模式或客户端模式下运行，就像 [Quickstart](#Quickstart) 中的例子。 但 `[client]` 和 `[server]` 块也可以放在一个文件中。然后在服务器端，运行 `rathole --server config.toml`。在客户端，运行 `rathole --client config.toml` 来明确告诉 `rathole` 运行模式。 **推荐首先查看 [examples](./examples) 中的配置示例来快速理解配置格式**，如果有不清楚的地方再查阅完整配置格式。 -关于如何配置 Noise Protocol 和 TLS 来进行加密传输，参见 [Security](./docs/security.md)。 +关于如何配置 Noise Protocol 和 TLS 来进行加密传输，参见 [Security](./docs/transport.md)。 下面是完整的配置格式。 + ```toml [client] remote_addr = "example.com:2333" # Necessary. The address of the server @@ -108,7 +114,7 @@ keepalive_interval = 5 # Optional. Specify `tcp_keepalive_intvl` in `tcp(7)`, if trusted_root = "ca.pem" # Necessary. The certificate of CA that signed the server's certificate hostname = "example.com" # Optional. The hostname that the client uses to validate the certificate. If not set, fallback to `client.remote_addr` -[client.transport.noise] # Noise protocol. See `docs/security.md` for further explanation +[client.transport.noise] # Noise protocol. See `docs/transport.md` for further explanation pattern = "Noise_NK_25519_ChaChaPoly_BLAKE2s" # Optional. Default value as shown local_private_key = "key_encoded_in_base64" # Optional remote_public_key = "key_encoded_in_base64" # Optional @@ -122,11 +128,11 @@ local_addr = "127.0.0.1:1081" # Necessary. The address of the service that needs local_addr = "127.0.0.1:1082" [server] -bind_addr = "0.0.0.0:2333" # Necessary. The address that the server listens for clients. Generally only the port needs to be change. +bind_addr = "0.0.0.0:2333" # Necessary. The address that the server listens for clients. Generally only the port needs to be change. default_token = "default_token_if_not_specify" # Optional [server.transport] # Same as `[client.transport]` -type = "tcp" +type = "tcp" nodelay = false keepalive_secs = 10 keepalive_interval = 5 @@ -137,24 +143,26 @@ pkcs12_password = "password" # Necessary. Password of the pkcs12 file [server.transport.noise] # Same as `[client.transport.noise]` pattern = "Noise_NK_25519_ChaChaPoly_BLAKE2s" -local_private_key = "key_encoded_in_base64" -remote_public_key = "key_encoded_in_base64" +local_private_key = "key_encoded_in_base64" +remote_public_key = "key_encoded_in_base64" [server.services.service1] # The service name must be identical to the client side type = "tcp" # Optional. Same as the client `[client.services.X.type] token = "whatever" # Necessary if `server.default_token` not set -bind_addr = "0.0.0.0:8081" # Necessary. The address of the service is exposed at. Generally only the port needs to be change. +bind_addr = "0.0.0.0:8081" # Necessary. The address of the service is exposed at. Generally only the port needs to be change. -[server.services.service2] +[server.services.service2] bind_addr = "0.0.0.1:8082" ``` ### Logging + `rathole`，像许多其他 Rust 程序一样，使用环境变量来控制日志级别。 支持的 Logging Level 有 `info`, `warn`, `error`, `debug`, `trace` 比如将日志级别设置为 `error`: + ``` RUST_LOG=error ./rathole config.toml ``` @@ -177,9 +185,10 @@ rathole 的延迟与 [frp](https://github.com/fatedier/frp) 相近，在高并 ## Development Status `rathole` 正在积极开发中 -- [x] 支持TLS -- [x] 支持UDP + +- [x] 支持 TLS +- [x] 支持 UDP - [x] 热重载 -- [ ] 用于配置的HTTP APIs +- [ ] 用于配置的 HTTP APIs [Out of Scope](./docs/out-of-scope.md) 列举了没有计划开发的特性并说明了原因。 diff --git a/README.md b/README.md index cf7f023..cca866e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # rathole + ![rathole-logo](./docs/img/rathole-logo.png) [![GitHub stars](https://img.shields.io/github/stars/rapiz1/rathole)](https://github.com/rapiz1/rathole/stargazers) @@ -38,13 +39,14 @@ A full-powered `rathole` can be obtained from the [release](https://github.com/r The usage of `rathole` is very similar to frp. If you have experience with the latter, then the configuration is very easy for you. The only difference is that configuration of a service is split into the client side and the server side, and a token is mandatory. -To use `rathole`, you need a server with a public IP, and a device behind the NAT, where some services that need to be exposed to the Internet. +To use `rathole`, you need a server with a public IP, and a device behind the NAT, where some services that need to be exposed to the Internet. Assuming you have a NAS at home behind the NAT, and want to expose its ssh service to the Internet: 1. On the server which has a public IP Create `server.toml` with the following content and accommodate it to your needs. + ```toml # server.toml [server] @@ -56,6 +58,7 @@ bind_addr = "0.0.0.0:5202" # `5202` specifies the port that exposes `my_nas_ssh` ``` Then run: + ```bash ./rathole server.toml ``` @@ -63,6 +66,7 @@ Then run: 2. On the host which is behind the NAT (your NAS) Create `client.toml` with the following content and accommodate it to your needs. + ```toml # client.toml [client] @@ -74,6 +78,7 @@ local_addr = "127.0.0.1:22" # The address of the service that needs to be forwar ``` Then run: + ```bash ./rathole client.toml ``` @@ -82,18 +87,20 @@ Then run: So you can `ssh myserver.com:5202` to ssh to your NAS. -To run `rathole` run as a background service on Linux, checkout the [systemd examples](./examples/systemd). +To run `rathole` run as a background service on Linux, checkout the [systemd examples](./examples/systemd). ## Configuration + `rathole` can automatically determine to run in the server mode or the client mode, according to the content of the configuration file, if only one of `[server]` and `[client]` block is present, like the example in [Quickstart](#Quickstart). But the `[client]` and `[server]` block can also be put in one file. Then on the server side, run `rathole --server config.toml` and on the client side, run `rathole --client config.toml` to explicitly tell `rathole` the running mode. Before heading to the full configuration specification, it's recommend to skim [the configuration examples](./examples) to get a feeling of the configuration format. -See [Security](./docs/security.md) for more details about encryption and the `transport` block. +See [Security](./docs/transport.md) for more details about encryption and the `transport` block. Here is the full configuration specification: + ```toml [client] remote_addr = "example.com:2333" # Necessary. The address of the server @@ -109,7 +116,7 @@ keepalive_interval = 5 # Optional. Specify `tcp_keepalive_intvl` in `tcp(7)`, if trusted_root = "ca.pem" # Necessary. The certificate of CA that signed the server's certificate hostname = "example.com" # Optional. The hostname that the client uses to validate the certificate. If not set, fallback to `client.remote_addr` -[client.transport.noise] # Noise protocol. See `docs/security.md` for further explanation +[client.transport.noise] # Noise protocol. See `docs/transport.md` for further explanation pattern = "Noise_NK_25519_ChaChaPoly_BLAKE2s" # Optional. Default value as shown local_private_key = "key_encoded_in_base64" # Optional remote_public_key = "key_encoded_in_base64" # Optional @@ -124,11 +131,11 @@ nodelay = false # Optional. Determine whether to enable TCP_NODELAY for data tra local_addr = "127.0.0.1:1082" [server] -bind_addr = "0.0.0.0:2333" # Necessary. The address that the server listens for clients. Generally only the port needs to be change. +bind_addr = "0.0.0.0:2333" # Necessary. The address that the server listens for clients. Generally only the port needs to be change. default_token = "default_token_if_not_specify" # Optional [server.transport] # Same as `[client.transport]` -type = "tcp" +type = "tcp" nodelay = false keepalive_secs = 10 keepalive_interval = 5 @@ -139,25 +146,27 @@ pkcs12_password = "password" # Necessary. Password of the pkcs12 file [server.transport.noise] # Same as `[client.transport.noise]` pattern = "Noise_NK_25519_ChaChaPoly_BLAKE2s" -local_private_key = "key_encoded_in_base64" -remote_public_key = "key_encoded_in_base64" +local_private_key = "key_encoded_in_base64" +remote_public_key = "key_encoded_in_base64" [server.services.service1] # The service name must be identical to the client side type = "tcp" # Optional. Same as the client `[client.services.X.type] token = "whatever" # Necessary if `server.default_token` not set -bind_addr = "0.0.0.0:8081" # Necessary. The address of the service is exposed at. Generally only the port needs to be change. +bind_addr = "0.0.0.0:8081" # Necessary. The address of the service is exposed at. Generally only the port needs to be change. nodelay = false # Optional. Same as the client -[server.services.service2] +[server.services.service2] bind_addr = "0.0.0.1:8082" ``` ### Logging + `rathole`, like many other Rust programs, use environment variables to control the logging level. `info`, `warn`, `error`, `debug`, `trace` are available. ``` RUST_LOG=error ./rathole config.toml ``` + will run `rathole` with only error level logging. If `RUST_LOG` is not present, the default logging level is `info`. @@ -178,6 +187,7 @@ For more details, see the separate page [Benchmark](./docs/benchmark.md). ## Development Status `rathole` is under active development. A load of features is on the way: + - [x] TLS support - [x] UDP support - [x] Hot reloading diff --git a/docs/security.md b/docs/transport.md similarity index 100% rename from docs/security.md rename to docs/transport.md diff --git a/tests/config_test/valid_config/full.toml b/tests/config_test/valid_config/full.toml index 0fb9fc6..88cdf67 100644 --- a/tests/config_test/valid_config/full.toml +++ b/tests/config_test/valid_config/full.toml @@ -9,7 +9,7 @@ type = "tcp" # Optional. Possible values: ["tcp", "tls"]. Default: "tcp" trusted_root = "ca.pem" # Necessary. The certificate of CA that signed the server's certificate hostname = "example.com" # Optional. The hostname that the client uses to validate the certificate. If not set, fallback to `client.remote_addr` -[client.transport.noise] # Noise protocol. See `docs/security.md` for further explanation +[client.transport.noise] # Noise protocol. See `docs/transport.md` for further explanation pattern = "Noise_NK_25519_ChaChaPoly_BLAKE2s" # Optional. Default value as shown local_private_key = "key_encoded_in_base64" # Optional remote_public_key = "key_encoded_in_base64" # Optional