goph

README

Golang SSH Client.

Fast and easy golang ssh client module.

Installation ❘ Features ❘ Usage ❘ Examples ❘ License

Installation

go get github.com/melbahja/goph

Features

• Easy to use.
• 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.

Usage

Run a command via ssh:

package main

import (
	"log"
	"fmt"
	"github.com/melbahja/goph"
)

func main() {

	// Start new ssh connection with private key.
	client, err := goph.New("root", "192.1.1.3", goph.Key("/home/mohamed/.ssh/id_rsa", ""))

	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:

client, err := goph.New("root", "192.1.1.3", goph.Key("/home/mohamed/.ssh/id_rsa", "you_passphrase_here"))

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):

client, err := goph.New("root", "192.1.1.3", goph.UseAgent())

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;'`)

For more read the go docs.

Examples

See Examples.

License

Goph is provided under the MIT License.

Documentation

Index

• Constants
• func AddKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) error
• func CheckKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) (bool, error)
• func Conn(c *Client, cfg *ssh.ClientConfig) (err error)
• func DefaultKnownHosts() (ssh.HostKeyCallback, error)
• func Download(c *ssh.Client, src string, dest string) (err error)
• func GetSigner(prvFile string, passphrase string) (ssh.Signer, error)
• func KnownHosts(file string) (ssh.HostKeyCallback, error)
• func Upload(c *ssh.Client, src string, dest string) (err error)
• type Auth
  • func Key(prvFile string, passphrase string) Auth
  • func Password(pass string) Auth
  • func UseAgent() Auth
• type Client
  • func New(user string, addr string, auth Auth) (c *Client, err error)
  • func NewConn(user string, addr string, auth Auth, callback ssh.HostKeyCallback) (c *Client, err error)
  • func NewUnknown(user string, addr string, auth Auth) (*Client, error)
  • func (t Client) BindTunnel(ctx context.Context, wg *sync.WaitGroup)
  • func (c Client) Close() error
  • func (t Client) DialTunnel(ctx context.Context, wg *sync.WaitGroup, client *ssh.Client, cn1 net.Conn)
  • func (c Client) Download(remotePath string, localPath string) error
  • func (client *Client) Interact() error
  • func (c Client) NewSession() (*ssh.Session, error)
  • func (c Client) Run(cmd string) ([]byte, error)
  • func (c Client) Upload(localPath string, remotePath string) error
• type Interactive

Constants

const (
	UDP string = "udp"
	TCP string = "tcp"
)

Functions

func AddKnownHost

func AddKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) error

Add a host to knows hosts this function by @dixonwille see: https://github.com/melbahja/goph/issues/2

func CheckKnownHost

func CheckKnownHost(host string, remote net.Addr, key ssh.PublicKey, knownFile string) (bool, error)

Check 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 Conn

func Conn(c *Client, cfg *ssh.ClientConfig) (err error)

Set new net connection to a client.

func DefaultKnownHosts

func DefaultKnownHosts() (ssh.HostKeyCallback, error)

Use default known hosts files to verify host public key.

func Download

func Download(c *ssh.Client, src string, dest string) (err error)

Download remote file to local.

func GetSigner

func GetSigner(prvFile string, passphrase string) (ssh.Signer, error)

Get private key signer.

func KnownHosts

func KnownHosts(file string) (ssh.HostKeyCallback, error)

Get known hosts callback from a custom path.

func Upload

func Upload(c *ssh.Client, src string, dest string) (err error)

Upload local file to remote.

Types

type Auth

type Auth []ssh.AuthMethod

func Key

func Key(prvFile string, passphrase string) Auth

Get auth method from private key with or without passphrase.

func Password

func Password(pass string) Auth

Get auth method from raw password.

func UseAgent

func UseAgent() Auth

type Client

type Client struct {
	*sshtunnel.Tunnel
	*Interactive
	Auth
}

func New

func New(user string, addr string, auth Auth) (c *Client, err error)

Connect to ssh and get client, the host public key must be in known hosts.

func NewConn

func NewConn(user string, addr string, auth Auth, callback ssh.HostKeyCallback) (c *Client, err error)

Get new client connection.

func NewUnknown

func NewUnknown(user string, addr string, auth Auth) (*Client, error)

Connect to ssh and 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) BindTunnel

func (t Client) BindTunnel(ctx context.Context, wg *sync.WaitGroup)

func (Client) Close

func (c Client) Close() error

Close client net connection.

func (Client) DialTunnel

func (t Client) DialTunnel(ctx context.Context, wg *sync.WaitGroup, client *ssh.Client, cn1 net.Conn)

func (Client) Download

func (c Client) Download(remotePath string, localPath string) error

Download file from remote machine!

func (*Client) Interact

func (client *Client) Interact() error

func (Client) NewSession

func (c Client) NewSession() (*ssh.Session, error)

Get new ssh session from client connection See: https://pkg.go.dev/golang.org/x/crypto/ssh?tab=doc#Session

func (Client) Run

func (c Client) Run(cmd string) ([]byte, error)

Run a command over ssh connection

func (Client) Upload

func (c Client) Upload(localPath string, remotePath string) error

Upload a local file to remote machine!

type Interactive

type Interactive struct {
	Port  int
	Conn  *ssh.Client
	Proto string
}