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... - Supports context.Context for command cancellation.
📄 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 timeout:
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:
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")
// 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 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 AutoPrompt
- type Client
- func (c Client) Close() error
- func (c Client) Command(name string, args ...string) (*Cmd, error)
- func (c Client) CommandContext(ctx context.Context, 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(cmds ...string) ([]byte, error)
- func (c Client) RunContext(ctx context.Context, name string) ([]byte, error)
- func (conn *Client) RunWithAutoPrompt(autoPrompts []AutoPrompt, cmds ...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 ¶
AddKnownHost add a a host to known hosts file.
func CheckKnownHost ¶
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 ¶
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 AutoPrompt ¶
AutoPrompt for RunWithAutoPrompt.
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!
func (Client) CommandContext ¶
Command returns new Cmd with context and error, if any.
func (Client) Run ¶
Run starts a new SSH session and runs the cmd, it returns CombinedOutput and err if any.
func (Client) RunContext ¶
Run starts a new SSH session with context and runs the cmd. It returns CombinedOutput and err if any.
func (*Client) RunWithAutoPrompt ¶
func (conn *Client) RunWithAutoPrompt(autoPrompts []AutoPrompt, cmds ...string) ([]byte, error)
type Cmd ¶
type Cmd struct {
// Path to command executable filename
Path string
// Command args.
Args []string
// Session env vars.
Env []string
// SSH session.
*ssh.Session
// Context for cancellation
Context context.Context
}
Cmd it's like os/exec.Cmd but for ssh session.
func (*Cmd) CombinedOutput ¶
CombinedOutput runs cmd on the remote host and returns its combined stdout and stderr.
Source Files
Directories