Golang SSH Client.
Fast and easy golang ssh client module.
Goph is a lightweight Go SSH client focusing on simplicity!
Goph is a lightweight Go SSH client focusing on simplicity!
Installation โ Features โ Usage โ Examples โ License
## ๐ Installation and Documentation ```bash go get github.com/melbahja/goph ``` You can find the docs at [go docs](https://pkg.go.dev/github.com/melbahja/goph). ## ๐ค Features - Easy to use and **simple API**. - Supports **known hosts** by default. - Supports connections with **passwords**. - Supports connections with **private keys**. - Supports connections with **protected private keys** with passphrase. - Supports **upload** files from local to remote. - Supports **download** files from remote to local. - Supports connections with **ssh agent** (Unix systems only). - Supports adding new hosts to **known_hosts file**. - Supports **file system operations** like: `Open, Create, Chmod...` - Supports **context.Context** for command cancellation. ## ๐ Usage Run a command via ssh: ```go package main import ( "log" "fmt" "github.com/melbahja/goph" ) func main() { // Start new ssh connection with private key. auth, err := goph.Key("/home/mohamed/.ssh/id_rsa", "") if err != nil { log.Fatal(err) } client, err := goph.New("root", "192.1.1.3", auth) if err != nil { log.Fatal(err) } // Defer closing the network connection. defer client.Close() // Execute your command. out, err := client.Run("ls /tmp/") if err != nil { log.Fatal(err) } // Get your output as []byte. fmt.Println(string(out)) } ``` #### ๐ Start Connection With Protected Private Key: ```go auth, err := goph.Key("/home/mohamed/.ssh/id_rsa", "you_passphrase_here") if err != nil { // handle error } client, err := goph.New("root", "192.1.1.3", auth) ``` #### ๐ Start Connection With Password: ```go client, err := goph.New("root", "192.1.1.3", goph.Password("you_password_here")) ``` #### โ Start Connection With SSH Agent (Unix systems only): ```go auth, err := goph.UseAgent() if err != nil { // handle error } client, err := goph.New("root", "192.1.1.3", auth) ``` #### โคด๏ธ Upload Local File to Remote: ```go err := client.Upload("/path/to/local/file", "/path/to/remote/file") ``` #### โคต๏ธ Download Remote File to Local: ```go err := client.Download("/path/to/remote/file", "/path/to/local/file") ``` #### โ Execute Bash Commands: ```go out, err := client.Run("bash -c 'printenv'") ``` #### โ Execute Bash Command with timeout: ```go context, cancel := context.WithTimeout(ctx, time.Second) defer cancel() // will send SIGINT and return error after 1 second out, err := client.RunContext(ctx, "sleep 5") ``` #### โ Execute Bash Command With Env Variables: ```go out, err := client.Run(`env MYVAR="MY VALUE" bash -c 'echo $MYVAR;'`) ``` #### ๐ฅช Using Goph Cmd: `Goph.Cmd` struct is like the Go standard `os/exec.Cmd`. ```go // Get new `Goph.Cmd` cmd, err := client.Command("ls", "-alh", "/tmp") // or with context: // cmd, err := client.CommandContext(ctx, "ls", "-alh", "/tmp") if err != nil { // handle the error! } // You can set env vars, but the server must be configured to `AcceptEnv line`. cmd.Env = []string{"MY_VAR=MYVALUE"} // Run you command. err = cmd.Run() ``` ๐๏ธ Just like `os/exec.Cmd` you can run `CombinedOutput, Output, Start, Wait`, and [`ssh.Session`](https://pkg.go.dev/golang.org/x/crypto/ssh#Session) methods like `Signal`... #### ๐ File System Operations Via SFTP: You can easily get a [SFTP](https://github.com/pkg/sftp) client from Goph client: ```go sftp, err := client.NewSftp() if err != nil { // handle the error! } file, err := sftp.Create("/tmp/remote_file") file.Write([]byte(`Hello world`)) file.Close() ``` ๐๏ธ For more file operations see [SFTP Docs](https://github.com/pkg/sftp). ## ๐ฅ Examples See [Examples](https://github.com/melbahja/ssh/blob/master/examples). ## ๐ค Missing a Feature? Feel free to open a new issue, or contact me. ## ๐ License Goph is provided under the [MIT License](https://github.com/melbahja/goph/blob/master/LICENSE).