hqgossh

README

hqgossh

A Go(Golang) package to provide a simple abstraction around SSH (Secure Shell) and SFTP (SSH File Transfer Protocol) packages.

Resources

• Features
• Usage
  • Authentication with password
  • Authentication with key with passphrase
  • Authentication with Key without passphrase
  • Run remote commands
  • Attach interactive shell
  • Files upload and download
    • Upload Local File/Directory to Remote
    • Download Remote File/Directory to Local
• Contribution

Features

• Establishing SSH connections:
  • ... password.
  • ... key with passphrase.
  • ... key without passphrase.
• Running remote commands over SSH.
• Openning interactive shells over SSH.
• Transferring files over SFTP.

Installation

go get -v -u github.com/hueristiq/hqgossh

Usage

Authentication with password

auth, err := authentication.Password("Password")
if err != nil {
	log.Fatal(err)
}

client, err := ssh.New(&ssh.Configuration{
	Host:            "xxx.xxx.xxx.xxx",
	Port:            22,
	User:            "some-user",
	Authentication:  auth,
	HostKeyCallback: ssh.InsecureIgnoreHostKey(),
})
if err != nil {
    log.Println(err)
}

defer client.Close()

Authentication with key with passphrase

auth, err := authentication.KeyWithPassphrase(privateKey, "Passphrase")
if err != nil {
	log.Fatal(err)
}

client, err := ssh.New(&ssh.Configuration{
	Host:            "xxx.xxx.xxx.xxx",
	Port:            22,
	User:            "some-user",
	Authentication:  auth,
	HostKeyCallback: ssh.InsecureIgnoreHostKey(),
})
if err != nil {
	log.Println(err)
}

defer client.Close()

Authentication with key without passphrase

auth, err := authentication.Key(privateKey)
if err != nil {
	log.Fatal(err)
}

client, err := ssh.New(&ssh.Configuration{
	Host:            "xxx.xxx.xxx.xxx",
	Port:            22,
	User:            "some-user",
	Authentication:  auth,
	HostKeyCallback: ssh.InsecureIgnoreHostKey(),
})
if err != nil {
	log.Println(err)
}

defer client.Close()

Run remote commands

if err = client.Run(&ssh.Command{
	CMD:    "echo ${LC_TEST}",
	ENV:    map[string]string{"LC_TEST":"working"},
	Stdin:  os.Stdin,
	Stdout: os.Stdout,
	Stderr: os.Stderr,
}); err != nil {
	log.Fatal(err)
}

Attach interactive shell

if err = client.Shell(); err != nil {
	log.Println(err)
}

Files upload and download

Upload Local File/Directory to Remote

if err := client.Upload("/path/to/local/file", "/path/to/remote/file"); err != nil {
	log.Println(err)
}

Download Remote File/Directory to Local

if err := client.Download("/path/to/remote/file", "/path/to/local/file"); err != nil {
	log.Println(err)
}

Contributing

Issues and Pull Requests are welcome! Check out the contribution guidelines.

Licensing

This package is distributed under the MIT license.

Documentation

Index

• Variables
• type Client
  • func New(options *Options) (client *Client, err error)
  • func (client *Client) Close() (err error)
  • func (client *Client) Download(SRC, DEST string) (err error)
  • func (client *Client) DownloadDirectory(SRC, DEST string) (err error)
  • func (client *Client) DownloadFile(SRC, DEST string) (err error)
  • func (client *Client) Run(command *Command) (err error)
  • func (client *Client) Shell() (err error)
  • func (client *Client) Upload(SRC, DEST string) (err error)
  • func (client *Client) UploadDirectory(SRC, DEST string) (err error)
  • func (client *Client) UploadFile(SRC, DEST string) (err error)
• type Command
• type Options

Variables

var (
	ErrSourceNotFound    = errors.New("source not found")
	ErrSourceIsDirectory = errors.New("source is directory")
	ErrSourceIsFile      = errors.New("source is file")
)

Types

type Client

type Client struct {
	SSH  *ssh.Client
	SFTP *sftp.Client
}

Client wraps SSH and SFTP clients.

func New

func New(options *Options) (client *Client, err error)

New creates a new Client with provided Options. It establishes both SSH and SFTP clients.

func (*Client) Close

func (client *Client) Close() (err error)

Close closes the SFTP and SSH clients.

func (*Client) Download

func (client *Client) Download(SRC, DEST string) (err error)

Download transfers remote directories and files to local host. This works by calling DownloadDirectory or DownloadFile depending on the source.

func (*Client) DownloadDirectory

func (client *Client) DownloadDirectory(SRC, DEST string) (err error)

DownloadDirectory transfers remote directories and contained files recursively to local host

func (*Client) DownloadFile

func (client *Client) DownloadFile(SRC, DEST string) (err error)

DownloadFile transfers remote files to local host

func (*Client) Run

func (client *Client) Run(command *Command) (err error)

Run runs remote commands over SSH.

func (*Client) Shell

func (client *Client) Shell() (err error)

Shell opens an interactive shell over SSH.

func (*Client) Upload

func (client *Client) Upload(SRC, DEST string) (err error)

Upload transfers local directories and files to remote host. This works by calling UploadDirectory or UploadFile depending on the source.

func (*Client) UploadDirectory

func (client *Client) UploadDirectory(SRC, DEST string) (err error)

UploadDirectory transfers local directories and contained files recursively to remote host

func (*Client) UploadFile

func (client *Client) UploadFile(SRC, DEST string) (err error)

UploadFile transfers local files to remote host

type Command

type Command struct {
	CMD    string
	ENV    map[string]string
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

Command represents remote commands structure.

type Options

type Options struct {
	Host            string
	Port            int
	User            string
	Authentication  authentication.Authentication
	HostKeyCallback ssh.HostKeyCallback
}

Options represents the options required to establish a SSH/SFTP connection.