ssh

README

Pure Go secure shell (SSH) functions

Documentation

Index

• Variables
• func Run(target string, ukey, hkey []byte, cmd, in string) (stdout, stderr string, err error)
• type Host
  • func NewHost(addr string, authkey []byte) (*Host, error)
• type MultiHostClient
  • func (c *MultiHostClient) Run(cmd, in string) (stdout, stderr string, err error)
• type User
  • func NewUser(name string, pemkey []byte) (*User, error)

Examples

• MultiHostClient (Run_assert_attempts)
• MultiHostClient (Run_assert_hosts)
• MultiHostClient (Run_assert_timeout)
• MultiHostClient (Run_assert_user)

Variables

var TCPTimeout = 300 * time.Second

TCPTimeout is the default number of seconds to wait to complete a TCP connection.

Functions

func Run

func Run(target string, ukey, hkey []byte, cmd, in string) (stdout, stderr string, err error)

Run wraps the ssh.Session.Run command with sensible, stand-alone defaults. This function has no dependencies on any underlying ssh host installation making it idea for light-weight, remote ssh calls.

Run combines several steps. First, a client secure shell connection is Dialed to the target (user@host:PORT) using the private PEM user key (ukey) and public host key in authorized_keys format (hkey, usually ecdsa-sha2-nistp256). Run then attempts to create a Session calling Run on it to execute the passed cmd feeding it any standard input (in) provided. The standard output, standard error are then buffered and returned as strings. The exit value is captured in err for any exit code other than 0. See the ssh.Session.Run method for more information.

Note that there are no limitations on the size of input and output meaning Run should only be used when calling remote commands that can be trusted not to produce too much output.

Types

type Host

type Host struct {
	Addr    string        // name or IP
	Auth    []byte        // authorized_hosts format
	Netkey  ssh.PublicKey // RFC 4235, section 6.6
	Pubkey  ssh.PublicKey // suitable for ssh.FixedHostkey
	Comment string        // authorized_hosts comment
	Options []string      // authorized_hosts options
}

func NewHost

func NewHost(addr string, authkey []byte) (*Host, error)

type MultiHostClient

type MultiHostClient struct {
	User     *User
	Hosts    []*Host
	Timeout  time.Duration
	Attempts int
	// contains filtered or unexported fields
}

Example (Run_assert_attempts)

package main

import (
	"fmt"
	"os"
	"time"

	"github.com/rwxrob/ssh"
)

func main() {

	c := new(ssh.MultiHostClient)
	defer func() {
		if p := recover(); p != nil {
			fmt.Println(p)
		}
	}()
	ukey, _ := os.ReadFile(`testdata/blahpriv`)
	c.User, _ = ssh.NewUser(`blah`, ukey)
	hkey, _ := os.ReadFile(`testdata/hostpubkey`)
	host, _ := ssh.NewHost(`localhost`, hkey)
	c.Hosts = []*ssh.Host{host}
	c.Timeout = 10 * time.Second

	c.Run(`ls -l ~`, "")
}

Output:

Attempts cannot be 0

Example (Run_assert_hosts)

package main

import (
	"fmt"
	"os"

	"github.com/rwxrob/ssh"
)

func main() {
	c := new(ssh.MultiHostClient)
	defer func() {
		if p := recover(); p != nil {
			fmt.Println(p)
		}
	}()
	key, _ := os.ReadFile(`testdata/blahpriv`)
	c.User, _ = ssh.NewUser(`blah`, key)
	c.Run(`ls -l ~`, "")
}

Output:

undefined Hosts

Example (Run_assert_timeout)

package main

import (
	"fmt"
	"os"

	"github.com/rwxrob/ssh"
)

func main() {
	c := new(ssh.MultiHostClient)
	defer func() {
		if p := recover(); p != nil {
			fmt.Println(p)
		}
	}()
	ukey, _ := os.ReadFile(`testdata/blahpriv`)
	c.User, _ = ssh.NewUser(`blah`, ukey)
	hkey, _ := os.ReadFile(`testdata/hostpubkey`)
	host, _ := ssh.NewHost(`localhost`, hkey)
	c.Hosts = []*ssh.Host{host}

	c.Run(`ls -l ~`, "")
}

Output:

Timeout cannot be 0

Example (Run_assert_user)

package main

import (
	"fmt"

	"github.com/rwxrob/ssh"
)

func main() {
	c := new(ssh.MultiHostClient)
	defer func() {
		if p := recover(); p != nil {
			fmt.Println(p)
		}
	}()
	c.Run(`ls -l ~`, "")

}

Output:

undefined User

func (*MultiHostClient) Run

func (c *MultiHostClient) Run(cmd, in string) (stdout, stderr string, err error)

Run attempts to dial a random host from Hosts and waits the Timeout duration for a TCP connection before moving to the next host in Hosts and attempting to Dial it repeating the cycle once until number of Attempts is reached. The first host to respond to Dial is used. Note that the err returned by a command does not cause additional attempts, only failed Dail attempts. Panics if any User, Hosts, Timeout, or Attempts is undefined.

type User

type User struct {
	Name   string
	Key    []byte // original pemkey
	Signer ssh.Signer
}

func NewUser

func NewUser(name string, pemkey []byte) (*User, error)