Skip to content

Commit d9a569d

Browse files
authored
docs: improved documentation (#96)
* FIX: correct broken path to examples * FEAT: _example -> _examples * FEAT: implemenet MakeConfig documentation * FEAT: capitalisation + small descriptive sentence
1 parent 84a92b1 commit d9a569d

13 files changed

Lines changed: 50 additions & 5 deletions

File tree

README.md

Lines changed: 50 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,50 @@ This project is forked from [easyssh](https://github.com/hypersleep/easyssh) but
3232

3333
## Usage
3434

35-
You can see `ssh`, `scp`, `ProxyCommand` on `examples` folder.
35+
You can see detailed examples of the `ssh`, `scp`, `Proxy`, and `stream` commands inside the [`examples`](./_examples/) folder.
36+
37+
### MakeConfig
38+
39+
All functionality provided by this package is accessed via methods of the MakeConfig struct.
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 takes in the following properties:
56+
57+
| property | description |
58+
| -------------- | --------------- |
59+
| user | The SSH user to be logged in with |
60+
| Server | The IP or hostname pointing of the server |
61+
| Key | A string containing the private key to be used when making the connection |
62+
| KeyPath | The path pointing to the SSH key file to be used when making the connection |
63+
| Port | The port to use when connecting to the SSH daemon of the server |
64+
| Protocol | The tcp protocol to be used: `"tcp", "tcp4" "tcp6"` |
65+
| Passphrase | The Passphrase to unlock the provided SSH key (leave blank if no Passphrase is required) |
66+
| Password | The Password to use to login the specified user |
67+
| Timeout | The length of time to wait before timing out the request |
68+
| Proxy | An additional set of configuration params that will be used to SSH into an additional server via the server configured in this top-level block |
69+
| Ciphers | An array of ciphers (e.g. aes256-ctr) to enable for the SSH connection |
70+
| KeyExchanges | An array of key exchanges (e.g. ecdh-sha2-nistp384) to enable for the SSH connection |
71+
| Fingerprint | The expected fingerprint to be returned by the SSH server, results in a fingerprint error if they do not match |
72+
| UseInsecureCipher | Enables the use of insecure ciphers and key exchanges that are insecure and can lead to compromise, [see ssh](#ssh) |
73+
74+
NOTE: Please view the reference documentation for the most up to date properties of [MakeConfig](https://pkg.go.dev/github.com/appleboy/easyssh-proxy#MakeConfig) and [DefaultConfig](https://pkg.go.dev/github.com/appleboy/easyssh-proxy#DefaultConfig)
3675

3776
### ssh
3877

39-
See [example/ssh/ssh.go](./example/ssh/ssh.go)
78+
See [examples/ssh/ssh.go](./_examples/ssh/ssh.go)
4079

4180
```go
4281
package main
@@ -97,7 +136,7 @@ func main() {
97136

98137
### scp
99138

100-
See [example/scp/scp.go](./example/scp/scp.go)
139+
See [examples/scp/scp.go](./_examples/scp/scp.go)
101140

102141
```go
103142
package main
@@ -132,26 +171,32 @@ func main() {
132171

133172
### SSH ProxyCommand
134173

135-
See [example/proxy/proxy.go](./example/proxy/proxy.go)
174+
See [examples/proxy/proxy.go](./_examples/proxy/proxy.go)
136175

137176
```go
138177
ssh := &easyssh.MakeConfig{
139178
User: "drone-scp",
140179
Server: "localhost",
141180
Port: "22",
142181
KeyPath: "./tests/.ssh/id_rsa",
182+
Timeout: 60 * time.Second,
143183
Proxy: easyssh.DefaultConfig{
144184
User: "drone-scp",
145185
Server: "localhost",
146186
Port: "22",
147187
KeyPath: "./tests/.ssh/id_rsa",
188+
Timeout: 60 * time.Second,
148189
},
149190
}
150191
```
151192

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+
152197
### SSH Stream Log
153198

154-
See [example/stream/stream.go](./example/stream/stream.go)
199+
See [examples/stream/stream.go](./_examples/stream/stream.go)
155200

156201
```go
157202
func main() {

0 commit comments

Comments
 (0)