Skip to content

Commit 1bbb790

Browse files
appleboyappleboy
committed
docs(readme): add Traditional Chinese README and usage examples
- Add a new Traditional Chinese README file with detailed documentation for the easyssh-proxy library. - Include badges for GoDoc, Lint and Testing, codecov, Go Report Card, and Sourcegraph. - Describe the features of easyssh-proxy, including support for user private keys, TCP connection timeout settings, and SSH ProxyCommand. - Provide usage examples for `MakeConfig`, `ssh`, `scp`, `Proxy`, and `stream` commands. - Detail the properties accepted by `MakeConfig` and note the need for explicit configuration for Proxy connections. - Include code examples demonstrating how to use the library for SSH connections, SCP file transfers, and streaming SSH command logs. Signed-off-by: appleboy <appleboy.tw@gmail.com>
1 parent bc41088 commit 1bbb790

1 file changed

Lines changed: 244 additions & 0 deletions

File tree

‎README.zh-tw.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# easyssh-proxy
2+
3+
[![GoDoc](https://godoc.org/github.com/appleboy/easyssh-proxy?status.svg)](https://pkg.go.dev/github.com/appleboy/easyssh-proxy)
4+
[![Lint and Testing](https://github.com/appleboy/easyssh-proxy/actions/workflows/testing.yml/badge.svg)](https://github.com/appleboy/easyssh-proxy/actions/workflows/testing.yml)
5+
[![codecov](https://codecov.io/gh/appleboy/easyssh-proxy/branch/master/graph/badge.svg)](https://codecov.io/gh/appleboy/easyssh-proxy)
6+
[![Go Report Card](https://goreportcard.com/badge/github.com/appleboy/easyssh-proxy)](https://goreportcard.com/report/github.com/appleboy/easyssh-proxy)
7+
[![Sourcegraph](https://sourcegraph.com/github.com/appleboy/easyssh-proxy/-/badge.svg)](https://sourcegraph.com/github.com/appleboy/easyssh-proxy?badge)
8+
9+
easyssh-proxy 提供了一個用 Go 語言實現的一些 SSH 協議功能的簡單實現。
10+
11+
## 功能
12+
13+
這個項目是從 [easyssh](https://github.com/hypersleep/easyssh) 分叉而來，但添加了一些如下所示的功能。
14+
15+
- [x] 支援用戶私鑰的純文字。
16+
- [x] 支援用戶私鑰的路徑。
17+
- [x] 支援 TCP 連接建立的超時設定。
18+
- [x] 支援 SSH ProxyCommand。
19+
20+
```bash
21+
+--------+ +----------+ +-----------+
22+
| Laptop | <--> | Jumphost | <--> | FooServer |
23+
+--------+ +----------+ +-----------+
24+
25+
OR
26+
27+
+--------+ +----------+ +-----------+
28+
| Laptop | <--> | Firewall | <--> | FooServer |
29+
+--------+ +----------+ +-----------+
30+
192.168.1.5 121.1.2.3 10.10.29.68
31+
```
32+
33+
## 使用方法
34+
35+
你可以在 [`examples`](./_examples/) 資料夾中看到 `ssh`、`scp`、`Proxy` 和 `stream` 命令的詳細範例。
36+
37+
### MakeConfig
38+
39+
這個套件提供的所有功能都是通過 MakeConfig 結構體的方法來訪問的。
40+
41+
```go
42+
ssh := &easyssh.MakeConfig{
43+
User: "drone-scp",
44+
Server: "localhost",
45+
KeyPath: "./tests/.ssh/id_rsa",
46+
Port: "22",
47+
Timeout: 60 * time.Second,
48+
}
49+
50+
stdout, stderr, done, err := ssh.Run("ls -al", 60*time.Second)
51+
err = ssh.Scp("/root/source.csv", "/tmp/target.csv")
52+
stdoutChan, stderrChan, doneChan, errChan, err = ssh.Stream("for i in {1..5}; do echo ${i}; sleep 1; done; exit 2;", 60*time.Second)
53+
```
54+
55+
MakeConfig 接受以下屬性：
56+
57+
| 屬性 | 描述 |
58+
| ----------------- | ---------------------------------------------------------------------------- |
59+
| user | 要登入的 SSH 用戶 |
60+
| Server | 伺服器的 IP 或主機名稱 |
61+
| Key | 包含用於建立連接的私鑰的字串 |
62+
| KeyPath | 指向用於建立連接的 SSH 密鑰文件的路徑 |
63+
| Port | 連接到伺服器的 SSH 守護程序時使用的端口 |
64+
| Protocol | 要使用的 TCP 協議："tcp", "tcp4", "tcp6" |
65+
| Passphrase | 用於解鎖提供的 SSH 密鑰的密碼（如果不需要密碼，則留空） |
66+
| Password | 用於登入指定用戶的密碼 |
67+
| Timeout | 請求超時前等待的時間長度 |
68+
| Proxy | 一組額外的配置參數，將通過此頂層塊中配置的伺服器 SSH 到另一個伺服器 |
69+
| Ciphers | 用於 SSH 連接的密碼陣列（例如 aes256-ctr） |
70+
| KeyExchanges | 用於 SSH 連接的密鑰交換陣列（例如 ecdh-sha2-nistp384） |
71+
| Fingerprint | SSH 伺服器返回的預期指紋，如果不匹配則會導致指紋錯誤 |
72+
| UseInsecureCipher | 啟用不安全的密碼和密鑰交換，這些是不安全的，可能會導致妥協，[參見 ssh](#ssh) |
73+
74+
注意：請查看參考文件以獲取 [MakeConfig](https://pkg.go.dev/github.com/appleboy/easyssh-proxy#MakeConfig) 和 [DefaultConfig](https://pkg.go.dev/github.com/appleboy/easyssh-proxy#DefaultConfig) 的最新屬性。
75+
76+
### ssh
77+
78+
See [examples/ssh/ssh.go](./_examples/ssh/ssh.go)
79+
80+
```go
81+
package main
82+
83+
import (
84+
"fmt"
85+
"time"
86+
87+
"github.com/appleboy/easyssh-proxy"
88+
)
89+
90+
func main() {
91+
// Create MakeConfig instance with remote username, server address and path to private key.
92+
ssh := &easyssh.MakeConfig{
93+
User: "appleboy",
94+
Server: "example.com",
95+
// Optional key or Password without either we try to contact your agent SOCKET
96+
// Password: "password",
97+
// Paste your source content of private key
98+
// Key: `-----BEGIN RSA PRIVATE KEY-----
99+
// MIIEpAIBAAKCAQEA4e2D/qPN08pzTac+a8ZmlP1ziJOXk45CynMPtva0rtK/RB26
100+
// 7XC9wlRna4b3Ln8ew3q1ZcBjXwD4ppbTlmwAfQIaZTGJUgQbdsO9YA==
101+
// -----END RSA PRIVATE KEY-----
102+
// `,
103+
KeyPath: "/Users/username/.ssh/id_rsa",
104+
Port: "22",
105+
Timeout: 60 * time.Second,
106+
107+
// Parse PrivateKey With Passphrase
108+
Passphrase: "1234",
109+
110+
// Optional fingerprint SHA256 verification
111+
// Get Fingerprint: ssh.FingerprintSHA256(key)
112+
// Fingerprint: "SHA256:mVPwvezndPv/ARoIadVY98vAC0g+P/5633yTC4d/wXE"
113+
114+
// Enable the use of insecure ciphers and key exchange methods.
115+
// This enables the use of the the following insecure ciphers and key exchange methods:
116+
// - aes128-cbc
117+
// - aes192-cbc
118+
// - aes256-cbc
119+
// - 3des-cbc
120+
// - diffie-hellman-group-exchange-sha256
121+
// - diffie-hellman-group-exchange-sha1
122+
// Those algorithms are insecure and may allow plaintext data to be recovered by an attacker.
123+
// UseInsecureCipher: true,
124+
}
125+
126+
// Call Run method with command you want to run on remote server.
127+
stdout, stderr, done, err := ssh.Run("ls -al", 60*time.Second)
128+
// Handle errors
129+
if err != nil {
130+
panic("Can't run remote command: " + err.Error())
131+
} else {
132+
fmt.Println("don is :", done, "stdout is :", stdout, "; stderr is :", stderr)
133+
}
134+
}
135+
```
136+
137+
### scp
138+
139+
See [examples/scp/scp.go](./_examples/scp/scp.go)
140+
141+
```go
142+
package main
143+
144+
import (
145+
"fmt"
146+
147+
"github.com/appleboy/easyssh-proxy"
148+
)
149+
150+
func main() {
151+
// Create MakeConfig instance with remote username, server address and path to private key.
152+
ssh := &easyssh.MakeConfig{
153+
User: "appleboy",
154+
Server: "example.com",
155+
Password: "123qwe",
156+
Port: "22",
157+
}
158+
159+
// Call Scp method with file you want to upload to remote server.
160+
// Please make sure the `tmp` floder exists.
161+
err := ssh.Scp("/root/source.csv", "/tmp/target.csv")
162+
163+
// Handle errors
164+
if err != nil {
165+
panic("Can't run remote command: " + err.Error())
166+
} else {
167+
fmt.Println("success")
168+
}
169+
}
170+
```
171+
172+
### SSH ProxyCommand
173+
174+
See [examples/proxy/proxy.go](./_examples/proxy/proxy.go)
175+
176+
```go
177+
ssh := &easyssh.MakeConfig{
178+
User: "drone-scp",
179+
Server: "localhost",
180+
Port: "22",
181+
KeyPath: "./tests/.ssh/id_rsa",
182+
Timeout: 60 * time.Second,
183+
Proxy: easyssh.DefaultConfig{
184+
User: "drone-scp",
185+
Server: "localhost",
186+
Port: "22",
187+
KeyPath: "./tests/.ssh/id_rsa",
188+
Timeout: 60 * time.Second,
189+
},
190+
}
191+
```
192+
193+
NOTE: Properties for the Proxy connection are not inherited from the Jumphost. You must explicitly specify them in the DefaultConfig struct.
194+
195+
e.g. A custom `Timeout` length must be specified for both the Jumphost (intermediary server) and the destination server.
196+
197+
### SSH Stream Log
198+
199+
See [examples/stream/stream.go](./_examples/stream/stream.go)
200+
201+
```go
202+
func main() {
203+
// Create MakeConfig instance with remote username, server address and path to private key.
204+
ssh := &easyssh.MakeConfig{
205+
Server: "localhost",
206+
User: "drone-scp",
207+
KeyPath: "./tests/.ssh/id_rsa",
208+
Port: "22",
209+
Timeout: 60 * time.Second,
210+
}
211+
212+
// Call Run method with command you want to run on remote server.
213+
stdoutChan, stderrChan, doneChan, errChan, err := ssh.Stream("for i in {1..5}; do echo ${i}; sleep 1; done; exit 2;", 60*time.Second)
214+
// Handle errors
215+
if err != nil {
216+
panic("Can't run remote command: " + err.Error())
217+
} else {
218+
// read from the output channel until the done signal is passed
219+
isTimeout := true
220+
loop:
221+
for {
222+
select {
223+
case isTimeout = <-doneChan:
224+
break loop
225+
case outline := <-stdoutChan:
226+
fmt.Println("out:", outline)
227+
case errline := <-stderrChan:
228+
fmt.Println("err:", errline)
229+
case err = <-errChan:
230+
}
231+
}
232+
233+
// get exit code or command error.
234+
if err != nil {
235+
fmt.Println("err: " + err.Error())
236+
}
237+
238+
// command time out
239+
if !isTimeout {
240+
fmt.Println("Error: command timeout")
241+
}
242+
}
243+
}
244+
```

0 commit comments

Comments
 (0)