From cc2076970f872abf5508e65d0e428ceb2eb723b9 Mon Sep 17 00:00:00 2001 From: fatedier Date: Thu, 14 Dec 2023 20:54:03 +0800 Subject: [PATCH] update doc (#3844) --- .github/workflows/golangci-lint.yml | 2 +- .golangci.yml | 2 +- README.md | 23 ++++++++++++++---- doc/ssh_tunnel_gateway.md | 36 +++++++++++++---------------- go.mod | 2 +- 5 files changed, 37 insertions(+), 28 deletions(-) diff --git a/.github/workflows/golangci-lint.yml b/.github/workflows/golangci-lint.yml index 98583c7..9517af5 100644 --- a/.github/workflows/golangci-lint.yml +++ b/.github/workflows/golangci-lint.yml @@ -22,7 +22,7 @@ jobs: uses: golangci/golangci-lint-action@v3 with: # Optional: version of golangci-lint to use in form of v1.2 or v1.2.3 or `latest` to use the latest version - version: v1.53 + version: v1.55 # Optional: golangci-lint command line arguments. # args: --issues-exit-code=0 diff --git a/.golangci.yml b/.golangci.yml index 18cbaf0..f166e9d 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -1,5 +1,5 @@ service: - golangci-lint-version: 1.51.x # use the fixed version to not introduce new linters unexpectedly + golangci-lint-version: 1.55.x # use the fixed version to not introduce new linters unexpectedly run: concurrency: 4 diff --git a/README.md b/README.md index d6e1986..4bebb8a 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ frp also offers a P2P connect mode. * [Using Environment Variables](#using-environment-variables) * [Split Configures Into Different Files](#split-configures-into-different-files) * [Server Dashboard](#server-dashboard) - * [Admin UI](#admin-ui) + * [Client Admin UI](#client-admin-ui) * [Monitor](#monitor) * [Prometheus](#prometheus) * [Authenticating the Client](#authenticating-the-client) @@ -75,7 +75,7 @@ frp also offers a P2P connect mode. * [Custom Subdomain Names](#custom-subdomain-names) * [URL Routing](#url-routing) * [TCP Port Multiplexing](#tcp-port-multiplexing) - * [Connecting to frps via HTTP PROXY](#connecting-to-frps-via-http-proxy) + * [Connecting to frps via PROXY](#connecting-to-frps-via-proxy) * [Client Plugins](#client-plugins) * [Server Manage Plugins](#server-manage-plugins) * [SSH Tunnel Gateway](#ssh-tunnel-gateway) @@ -510,6 +510,7 @@ includes = ["./confd/*.toml"] ```toml # ./confd/test.toml + [[proxies]] name = "ssh" type = "tcp" @@ -621,6 +622,7 @@ The features are off by default. You can turn on encryption and/or compression: ```toml # frpc.toml + [[proxies]] name = "ssh" type = "tcp" @@ -776,6 +778,7 @@ We would like to try to allow multiple proxies bind a same remote port with diff ```toml # frpc.toml + [[proxies]] name = "ssh" type = "tcp" @@ -881,6 +884,7 @@ This feature is only available for types `tcp`, `http`, `tcpmux` now. ```toml # frpc.toml + [[proxies]] name = "test1" type = "tcp" @@ -916,6 +920,7 @@ With health check type **tcp**, the service port will be pinged (TCPing): ```toml # frpc.toml + [[proxies]] name = "test1" type = "tcp" @@ -935,6 +940,7 @@ With health check type **http**, an HTTP request will be sent to the service and ```toml # frpc.toml + [[proxies]] name = "web" type = "http" @@ -959,6 +965,7 @@ However, speaking of web servers and HTTP requests, your web server might rely o ```toml # frpc.toml + [[proxies]] name = "web" type = "http" @@ -975,6 +982,7 @@ Similar to `Host`, You can override other HTTP request headers with proxy type ` ```toml # frpc.toml + [[proxies]] name = "web" type = "http" @@ -1002,6 +1010,7 @@ Here is an example for https service: ```toml # frpc.toml + [[proxies]] name = "web" type = "https" @@ -1024,6 +1033,7 @@ It can only be enabled when proxy type is http. ```toml # frpc.toml + [[proxies]] name = "web" type = "http" @@ -1048,6 +1058,7 @@ Resolve `*.frps.com` to the frps server's IP. This is usually called a Wildcard ```toml # frpc.toml + [[proxies]] name = "web" type = "http" @@ -1067,6 +1078,7 @@ frp supports forwarding HTTP requests to different backend web services by url r ```toml # frpc.toml + [[proxies]] name = "web01" type = "http" @@ -1152,6 +1164,7 @@ Using plugin **http_proxy**: ```toml # frpc.toml + [[proxies]] name = "http_proxy" type = "tcp" @@ -1171,6 +1184,7 @@ Read the [document](/doc/server_plugin.md). Find more plugins in [gofrp/plugin](https://github.com/gofrp/plugin). ### SSH Tunnel Gateway + *added in v0.53.0* frp supports listening to an SSH port on the frps side and achieves TCP protocol proxying through the SSH -R protocol, without relying on frpc. @@ -1180,7 +1194,7 @@ frp supports listening to an SSH port on the frps side and achieves TCP protocol sshTunnelGateway.bindPort = 2200 ``` -When running ./frps -c frps.toml, a private key file named .autogen_ssh_key will be automatically created in the current working directory. This generated private key file will be used by the SSH server in frps. +When running `./frps -c frps.toml`, a private key file named `.autogen_ssh_key` will be automatically created in the current working directory. This generated private key file will be used by the SSH server in frps. Executing the command @@ -1197,7 +1211,6 @@ User: ProxyName: test-tcp Type: tcp RemoteAddress: :9090 - ``` This is equivalent to: @@ -1206,7 +1219,7 @@ This is equivalent to: frpc tcp --proxy_name "test-tcp" --local_ip 127.0.0.1 --local_port 8080 --remote_port 9090 ``` -Find more arguments in [document](/doc/ssh_tunnel_gateway.md). +Please refer to this [document](/doc/ssh_tunnel_gateway.md) for more information. ## Contributing diff --git a/doc/ssh_tunnel_gateway.md b/doc/ssh_tunnel_gateway.md index 7f1a3ef..b3dd4c3 100644 --- a/doc/ssh_tunnel_gateway.md +++ b/doc/ssh_tunnel_gateway.md @@ -2,15 +2,14 @@ *Added in v0.53.0* - ### Concept + SSH supports reverse proxy capabilities [rfc](https://www.rfc-editor.org/rfc/rfc4254#page-16). frp supports listening on an SSH port on the frps side to achieve TCP protocol proxying using the SSH -R protocol. This mode does not rely on frpc. SSH reverse tunneling proxying and proxying SSH ports through frp are two different concepts. SSH reverse tunneling proxying is essentially a basic reverse proxying accomplished by connecting to frps via an SSH client when you don't want to use frpc. - ```toml # frps.toml sshTunnelGateway.bindPort = 0 @@ -26,8 +25,8 @@ sshTunnelGateway.authorizedKeysFile = "" | autoGenPrivateKeyPath | string |Default value is ./.autogen_ssh_key. If the file does not exist or its content is empty, frps will automatically generate RSA private key file content and store it in this file.|No| | authorizedKeysFile | string |Default value is empty. If it is empty, ssh client authentication is not authenticated. If it is not empty, it can implement ssh password-free login authentication. It can reuse the local /home/user/.ssh/authorized_keys file or a custom path can be specified.| No | - ### Basic Usage + #### Server-side frps Minimal configuration: @@ -36,26 +35,27 @@ Minimal configuration: sshTunnelGateway.bindPort = 2200 ``` -Place the above configuration in frps.toml and run ./frps -c frps.toml. It will listen on port 2200 and accept SSH reverse proxy requests. +Place the above configuration in frps.toml and run `./frps -c frps.toml`. It will listen on port 2200 and accept SSH reverse proxy requests. Note: -1. When using the minimal configuration, a .autogen_ssh_key private key file will be automatically created in the current working directory. The SSH server of frps will use this private key file for encryption and decryption. Alternatively, you can reuse an existing private key file on your local machine, such as /home/user/.ssh/id_rsa. +1. When using the minimal configuration, a `.autogen_ssh_key` private key file will be automatically created in the current working directory. The SSH server of frps will use this private key file for encryption and decryption. Alternatively, you can reuse an existing private key file on your local machine, such as `/home/user/.ssh/id_rsa`. 2. When running frps in the minimal configuration mode, connecting to frps via SSH does not require authentication. It is strongly recommended to configure a token in frps and specify the token in the SSH command line. #### Client-side SSH + The command format is: ```bash ssh -R :80:{local_ip:port} v0@{frps_address} -p {frps_ssh_listen_port} {tcp|http|https|stcp|tcpmux} --remote_port {real_remote_port} --proxy_name {proxy_name} --token {frp_token} ``` -1. --proxy_name is optional, and if left empty, a random one will be generated. -The username for logging in to frps is always "v0" and currently has no significance, i.e., v0@{frps_address}. -2. The server-side proxy listens on the port determined by --remote_port. -3. {tcp|http|https|stcp|tcpmux} supports the complete command parameters, which can be obtained by using --help. For example: ssh -R :80::8080 v0@127.0.0.1 -p 2200 http --help. -4. The token is optional, but for security reasons, it is strongly recommended to configure the token in frps. +1. `--proxy_name` is optional, and if left empty, a random one will be generated. +2. The username for logging in to frps is always "v0" and currently has no significance, i.e., `v0@{frps_address}`. +3. The server-side proxy listens on the port determined by `--remote_port`. +4. `{tcp|http|https|stcp|tcpmux}` supports the complete command parameters, which can be obtained by using `--help`. For example: `ssh -R :80::8080 v0@127.0.0.1 -p 2200 http --help`. +5. The token is optional, but for security reasons, it is strongly recommended to configure the token in frps. #### TCP Proxy @@ -80,8 +80,7 @@ Equivalent to: frpc tcp --proxy_name "test-tcp" --local_ip 127.0.0.1 --local_port 8080 --remote_port 9090 ``` -More parameters can be obtained by executing --help. - +More parameters can be obtained by executing `--help`. #### HTTP Proxy @@ -100,16 +99,16 @@ curl 'http://test-http.frps.com' More parameters can be obtained by executing --help. - #### HTTPS/STCP/TCPMUX Proxy + To obtain the usage instructions, use the following command: ```bash ssh -R :80:127.0.0.1:8080 v0@{frp address} -p 2200 {https|stcp|tcpmux} --help ``` - ### Advanced Usage + #### Reusing the id_rsa File on the Local Machine ```toml @@ -120,7 +119,6 @@ sshTunnelGateway.privateKeyFile = "/home/user/.ssh/id_rsa" During the SSH protocol handshake, public keys are exchanged for data encryption. Therefore, the SSH server on the frps side needs to specify a private key file, which can be reused from an existing file on the local machine. If the privateKeyFile field is empty, frps will automatically create an RSA private key file. - #### Specifying the Auto-Generated Private Key File Path ```toml @@ -131,8 +129,7 @@ sshTunnelGateway.autoGenPrivateKeyPath = "/var/frp/ssh-private-key-file" frps will automatically create a private key file and store it at the specified path. -Note: Changing the private key file in frps can cause SSH client login failures. If you need to log in successfully, you can delete the old records from the /home/user/.ssh/known_hosts file. - +Note: Changing the private key file in frps can cause SSH client login failures. If you need to log in successfully, you can delete the old records from the `/home/user/.ssh/known_hosts` file. #### Using an Existing authorized_keys File for SSH Public Key Authentication @@ -146,11 +143,10 @@ The authorizedKeysFile is the file used for SSH public key authentication, which If authorizedKeysFile is empty, frps won't perform any authentication for SSH clients. Frps does not support SSH username and password authentication. -You can reuse an existing authorized_keys file on your local machine for client authentication. +You can reuse an existing `authorized_keys` file on your local machine for client authentication. Note: authorizedKeysFile is for user authentication during the SSH login phase, while the token is for frps authentication. These two authentication methods are independent. SSH authentication comes first, followed by frps token authentication. It is strongly recommended to enable at least one of them. If authorizedKeysFile is empty, it is highly recommended to enable token authentication in frps to avoid security risks. - #### Using a Custom authorized_keys File for SSH Public Key Authentication ```toml @@ -159,6 +155,6 @@ sshTunnelGateway.bindPort = 2200 sshTunnelGateway.authorizedKeysFile = "/var/frps/custom_authorized_keys_file" ``` -Specify the path to a custom authorized_keys file. +Specify the path to a custom `authorized_keys` file. Note that changes to the authorizedKeysFile file may result in SSH authentication failures. You may need to re-add the public key information to the authorizedKeysFile. diff --git a/go.mod b/go.mod index d11e1ef..4e178fb 100644 --- a/go.mod +++ b/go.mod @@ -22,6 +22,7 @@ require ( github.com/rodaine/table v1.1.0 github.com/samber/lo v1.38.1 github.com/spf13/cobra v1.8.0 + github.com/spf13/pflag v1.0.5 github.com/stretchr/testify v1.8.4 golang.org/x/crypto v0.15.0 golang.org/x/net v0.17.0 @@ -61,7 +62,6 @@ require ( github.com/prometheus/procfs v0.10.1 // indirect github.com/quic-go/qtls-go1-20 v0.3.1 // indirect github.com/rogpeppe/go-internal v1.11.0 // indirect - github.com/spf13/pflag v1.0.5 // indirect github.com/templexxx/cpufeat v0.0.0-20180724012125-cef66df7f161 // indirect github.com/templexxx/xor v0.0.0-20191217153810-f85b25db303b // indirect github.com/tjfoc/gmsm v1.4.1 // indirect