ssh

README

Origin README see here

This ssh package contains helpers for working with ssh in go. The client.go file is a modified version of docker/machine/libmachine/ssh/client.go that only uses golang's native ssh client. It has also been improved to resize the tty as needed. The key functions are meant to be used by either client or server and will generate/store keys if not found.

Usage:

package main

import (
	"fmt"

	"github.com/nanobox-io/golang-ssh"
)

func main() {
	err := connect()
	if err != nil {
		fmt.Printf("Failed to connect - %s\n", err)
	}
}

func connect() error {
	nanPass := ssh.Auth{Passwords: []string{"pass"}}
	client, err := ssh.NewNativeClient("user", "localhost", "SSH-2.0-MyCustomClient-1.0", 2222, &nanPass, nil)
	if err != nil {
		return fmt.Errorf("Failed to create new client - %s", err)
	}

	err = client.Shell()
	if err != nil && err.Error() != "exit status 255" {
		return fmt.Errorf("Failed to request shell - %s", err)
	}

	return nil
}

Compile for Windows:

If you get this error:

go: github.com/Sirupsen/logrus@v1.2.0: parsing go.mod: unexpected module path "github.com/sirupsen/logrus"

when compile for Windows with go mod, see this issue for some hints and there was a walkaround:

go mod init
go get github.com/docker/docker@v0.0.0-20180422163414-57142e89befe
GOOS=windows GOARCH=amd64 go build

Documentation

Overview

Package ssh is a helper for working with ssh in go. The client implementation is a modified version of `docker/machine/libmachine/ssh/client.go` and only uses golang's native ssh client. It has also been improved to resize the tty accordingly. The key functions are meant to be used by either client or server and will generate/store keys if not found.

Index

• Constants
• func GenKeyPair() (string, string, error)
• func GetKeyPair(file string) (string, string, error)
• func NewNativeConfig(user, clientVersion string, auth *Auth, timeout time.Duration, ...) (ssh.ClientConfig, error)
• type Auth
• type Client
  • func NewNativeClient(user, clientVersion string, host string, port int, hostAuth *Auth, ...) (Client, error)
  • func NewNativeClientWithConfig(host string, port int, config ssh.ClientConfig) (Client, error)
• type Config
• type ExitError
  • func (err *ExitError) Cause() error
  • func (err *ExitError) Error() string
• type HopDetails
• type HostDetail
• type KeyPair
• type NativeClient
  • func (c *NativeClient) AddHop(host string, port int) (Client, error)
  • func (c *NativeClient) AddHopWithConfig(host string, port int, config *ssh.ClientConfig) (Client, error)
  • func (nclient *NativeClient) Connect(timeout time.Duration) (*ssh.Client, *SessionInfo, error)
  • func (c *NativeClient) Copy() *NativeClient
  • func (client *NativeClient) Output(command string) (string, error)
  • func (client *NativeClient) OutputWithPty(command string) (string, error)
  • func (client *NativeClient) OutputWithTimeout(command string, timeout time.Duration) (string, error)
  • func (c *NativeClient) RemoveLastHop() (interface{}, error)
  • func (nc *NativeClient) Session(timeout time.Duration) (*ssh.Session, *SessionInfo, error)
  • func (client *NativeClient) Shell(sin io.Reader, sout, serr io.Writer, args ...string) error
  • func (client *NativeClient) Start(command string) (sout io.ReadCloser, serr io.ReadCloser, sin io.WriteCloser, reterr error)
  • func (nc *NativeClient) StartPersistentConn(timeout time.Duration) error
  • func (nc *NativeClient) StopPersistentConn()
  • func (client *NativeClient) Wait() error
• type SessionInfo
  • func (s *SessionInfo) CloseAll()

Constants

const SSHKeepAliveInterval = 1 * time.Minute

const SSHKeepAliveTimeout = 30 * time.Minute

Functions

func GenKeyPair

func GenKeyPair() (string, string, error)

GenKeyPair make a pair of public and private keys for SSH access. Public key is encoded in the format for inclusion in an OpenSSH authorized_keys file. Private Key generated is PEM encoded Due to difficulty handling changes to RSA signing names (i.e. OpenSSH < 7.6 refers to it as "rsa-sha256" but golang refers to it as "rsa-sha2-256-vert-v01@openssh.com", switch to using ed25519 certs instead.

func GetKeyPair

func GetKeyPair(file string) (string, string, error)

GetKeyPair will attempt to get the keypair from a file and will fail back to generating a new set and saving it to the file. Returns pub, priv, err

func NewNativeConfig

func NewNativeConfig(user, clientVersion string, auth *Auth, timeout time.Duration, hostKeyCallback ssh.HostKeyCallback) (ssh.ClientConfig, error)

NewNativeConfig returns a golang ssh client config struct for use by the NativeClient

Types

type Auth

type Auth struct {
	Passwords        []string                  // Passwords is a slice of passwords to submit to the server
	Keys             []string                  // Keys is a slice of filenames of keys to try
	RawKeys          [][]byte                  // RawKeys is a slice of private keys to try
	KeyPairs         []KeyPair                 // KeyPairs is a slice of signed public keys & private keys to try
	KeyPairsCallback func() ([]KeyPair, error) // Callback to get KeyPairs
}

Auth contains auth info

type Client

type Client interface {
	// Output returns the output of the command run on the host.
	Output(command string) (string, error)

	// OutputWithTimeout returns the output of the command run on the host.
	// call will timeout within a set timeout
	OutputWithTimeout(command string, Timeout time.Duration) (string, error)

	// Shell requests a shell from the remote. If an arg is passed, it tries to
	// exec them on the server.
	Shell(sin io.Reader, sout, serr io.Writer, args ...string) error

	// Start starts the specified command without waiting for it to finish. You
	// have to call the Wait function for that.
	//
	// The first two io.ReadCloser are the standard output and the standard
	// error of the executing command respectively. The returned error follows
	// the same logic as in the exec.Cmd.Start function.
	Start(command string) (io.ReadCloser, io.ReadCloser, io.WriteCloser, error)

	// Wait waits for the command started by the Start function to exit. The
	// returned error follows the same logic as in the exec.Cmd.Wait function.
	Wait() error
	// AddHop adds a new host to the end of the list and returns a new client.
	// The original client is unchanged.
	AddHop(host string, port int) (Client, error)

	// Connects to host and caches connection details for
	// same connection to be reused
	StartPersistentConn(timeout time.Duration) error

	// Stops cached sessions and close the connection
	StopPersistentConn()
}

Client is a relic interface that both native and external client matched

func NewNativeClient

func NewNativeClient(user, clientVersion string, host string, port int, hostAuth *Auth, timeout time.Duration, hostKeyCallback ssh.HostKeyCallback) (Client, error)

NewNativeClient creates a new Client using the golang ssh library

func NewNativeClientWithConfig

func NewNativeClientWithConfig(host string, port int, config ssh.ClientConfig) (Client, error)

type Config

type Config struct {
	User    string              // username to connect as, required
	Host    string              // hostname to connect to, required
	Version string              // ssh client version, "SSH-2.0-Go" by default
	Port    int                 // port to connect to, 22 by default
	Auth    *Auth               // authentication methods to use
	Timeout time.Duration       // connect timeout, 30s by default
	HostKey ssh.HostKeyCallback // callback for verifying server keys, ssh.InsecureIgnoreHostKey by default
}

Config is used to create new client.

type ExitError

type ExitError struct {
	Err      error
	ExitCode int
}

ExitError is a conveniance wrapper for (crypto/ssh).ExitError type.

func (*ExitError) Cause

func (err *ExitError) Cause() error

Cause implements errors.Causer interface.

func (*ExitError) Error

func (err *ExitError) Error() string

Error implements error interface.

type HopDetails

type HopDetails struct {
}

HopDetails stores open sessions and connections which need to be tracked so they can be properly cleaned up

type HostDetail

type HostDetail struct {
	HostName     string
	Port         int
	ClientConfig *ssh.ClientConfig
}

type KeyPair

type KeyPair struct {
	PublicRawKey  []byte
	PrivateRawKey []byte
}

type NativeClient

type NativeClient struct {
	HostDetails   []HostDetail // list of Hosts
	ClientVersion string       // ClientVersion is the version string to send to the server when identifying

	SessionInfo         *SessionInfo
	DefaultClientConfig *ssh.ClientConfig
	// contains filtered or unexported fields
}

NativeClient is the structure for native client use

func (*NativeClient) AddHop

func (c *NativeClient) AddHop(host string, port int) (Client, error)

AddHop adds a new host to the end of the list and returns a new client using the same config The original client is unchanged

func (*NativeClient) AddHopWithConfig

func (c *NativeClient) AddHopWithConfig(host string, port int, config *ssh.ClientConfig) (Client, error)

AddHopWithConfig adds a new host to the end of the list and returns a new client using the provided config The original client is unchanged

func (*NativeClient) Connect

func (nclient *NativeClient) Connect(timeout time.Duration) (*ssh.Client, *SessionInfo, error)

func (*NativeClient) Copy

func (c *NativeClient) Copy() *NativeClient

Copy copies the NativeClient with empty SessionInfo

func (*NativeClient) Output

func (client *NativeClient) Output(command string) (string, error)

Output returns the output of the command run on the remote host.

func (*NativeClient) OutputWithPty

func (client *NativeClient) OutputWithPty(command string) (string, error)

Output returns the output of the command run on the remote host as well as a pty.

func (*NativeClient) OutputWithTimeout

func (client *NativeClient) OutputWithTimeout(command string, timeout time.Duration) (string, error)

Output returns the output of the command run on the remote host.

func (*NativeClient) RemoveLastHop

func (c *NativeClient) RemoveLastHop() (interface{}, error)

RemoveLastHop returns a new client which is a copy of the original with the last hop removed

func (*NativeClient) Session

func (nc *NativeClient) Session(timeout time.Duration) (*ssh.Session, *SessionInfo, error)

func (*NativeClient) Shell

func (client *NativeClient) Shell(sin io.Reader, sout, serr io.Writer, args ...string) error

Shell requests a shell from the remote. If an arg is passed, it tries to exec them on the server.

func (*NativeClient) Start

func (client *NativeClient) Start(command string) (sout io.ReadCloser, serr io.ReadCloser, sin io.WriteCloser, reterr error)

Start starts the specified command without waiting for it to finish. You have to call the Wait function for that.

func (*NativeClient) StartPersistentConn

func (nc *NativeClient) StartPersistentConn(timeout time.Duration) error

func (*NativeClient) StopPersistentConn

func (nc *NativeClient) StopPersistentConn()

func (*NativeClient) Wait

func (client *NativeClient) Wait() error

Wait waits for the command started by the Start function to exit. The returned error follows the same logic as in the exec.Cmd.Wait function.

type SessionInfo

type SessionInfo struct {
	// contains filtered or unexported fields
}

SessionInfo contains artifacts from the session that need to be cleaned up

func (*SessionInfo) CloseAll

func (s *SessionInfo) CloseAll()