README
¶
Golang SSH Client.
Fast and easy golang ssh client module.
Goph is a lightweight Go SSH client focusing on simplicity!
Installation ❘ Features ❘ Usage ❘ Examples ❘ License
🚀 Installation and Documentation
go get github.com/melbahja/goph
You can find the docs at go docs.
🤘 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...
📄 Usage
Run a command via ssh:
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:
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:
client, err := goph.New("root", "192.1.1.3", goph.Password("you_password_here"))
☛ Start Connection With SSH Agent (Unix systems only):
auth, err := goph.UseAgent()
if err != nil {
// handle error
}
client, err := goph.New("root", "192.1.1.3", auth)
⤴️ Upload Local File to Remote:
err := client.Upload("/path/to/local/file", "/path/to/remote/file")
⤵️ Download Remote File to Local:
err := client.Download("/path/to/remote/file", "/path/to/local/file")
☛ Execute Bash Commands:
out, err := client.Run("bash -c 'printenv'")
☛ Execute Bash Command With Env Variables:
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.
// Get new `Goph.Cmd`
cmd, err := client.Command("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 methods like Signal...
📂 File System Operations Via SFTP:
You can easily get a SFTP client from Goph client:
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.
🥙 Examples
See Examples.
🤝 Missing a Feature?
Feel free to open a new issue, or contact me.
📘 License
Goph is provided under the MIT License.
Documentation
¶
Index ¶
- Variables
- func AddKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) (err error)
- func CheckKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) (found bool, err error)
- func DefaultKnownHosts() (ssh.HostKeyCallback, error)
- func DefaultKnownHostsPath() (string, error)
- func Dial(proto string, c *Config) (*ssh.Client, error)
- func GetSigner(prvFile string, passphrase string) (ssh.Signer, error)
- func HasAgent() bool
- func KnownHosts(file string) (ssh.HostKeyCallback, error)
- type Auth
- type Client
- func (c Client) Close() error
- func (c Client) Command(name string, args ...string) (*Cmd, error)
- func (c Client) Download(remotePath string, localPath string) (err error)
- func (c Client) NewSftp(opts ...sftp.ClientOption) (*sftp.Client, error)
- func (c Client) Run(cmd string) ([]byte, error)
- func (c Client) Upload(localPath string, remotePath string) (err error)
- type Cmd
- type Config
Constants ¶
This section is empty.
Variables ¶
var DefaultTimeout = 20 * time.Second
DefaultTimeout is the timeout of ssh client connection.
Functions ¶
func AddKnownHost ¶ added in v0.3.0
AddKnownHost add a a host to known hosts file.
func CheckKnownHost ¶ added in v0.3.0
func CheckKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) (found bool, err error)
CheckKnownHost checks is host in known hosts file. it returns is the host found in known_hosts file and error, if the host found in known_hosts file and error not nil that means public key mismatch, maybe MAN IN THE MIDDLE ATTACK! you should not handshake.
func DefaultKnownHosts ¶
func DefaultKnownHosts() (ssh.HostKeyCallback, error)
DefaultKnownHosts returns host key callback from default known hosts path, and error if any.
func DefaultKnownHostsPath ¶ added in v1.1.0
DefaultKnownHostsPath returns default user knows hosts file.
func KnownHosts ¶
func KnownHosts(file string) (ssh.HostKeyCallback, error)
KnownHosts returns host key callback from a custom known hosts path.
Types ¶
type Auth ¶
type Auth []ssh.AuthMethod
Auth represents ssh auth methods.
type Client ¶
Client represents Goph client.
func NewUnknown ¶
NewUnknown starts a ssh connection get client without cheking knownhosts. PLEASE AVOID USING THIS, UNLESS YOU KNOW WHAT ARE YOU DOING! if there a "man in the middle proxy", this can harm you! You can add the key to know hosts and use New() func instead!
type Cmd ¶ added in v0.9.0
type Cmd struct {
// Path to command executable filename
Path string
// Command args.
Args []string
// Session env vars.
Env []string
// SSH session.
*ssh.Session
}
Cmd it's like os/exec.Cmd but for ssh session.
func (*Cmd) CombinedOutput ¶ added in v0.9.0
CombinedOutput runs cmd on the remote host and returns its combined stdout and stderr.
Source Files
Directories