gommander

README

Gommander

A Go library for commanding multiple servers over ssh. This library uses crypto.go/ssh for the basic SSH functionality, but provides the ability to:

• Execute commands across all or subset of servers.
• Copy files to the remote server(s).
• Write files on the remote server(s).

Usage

The following is an example of managing a cluster of Vagrant instances.

package main

import (
	"golang.org/x/crypto/ssh"
	. "github.com/aerospike/gommander"

	"fmt"
)

func printResponse(responses chan Response, err error) {
	if err != nil {
		panic(err)
	}

	for r := range responses {
		switch r.ExitCode {
		case 0: // Success!
			fmt.Printf("\033[0;97m%s > %s\033[0m\n", r.Node.Host, r.Stdout.String())
		default: // Failure!
			fmt.Printf("\033[0;91m%s > %s\033[0m\n", r.Node.Host, r.Stderr.String())
		}
	}
}

func main() {

	// Parse the ssh key. This is the Vagrant SSH private key.
	vagrantKey, err := Parsekey("/Users/ME/.vagrant.d/insecure_private_key")
	if err != nil {
		panic(err)
	}

	// Array of auth methods, needed for authenticating w/ each node
	authMethods := []ssh.AuthMethod{ssh.PublicKeys(vagrantKey)}

	// The nodes we are using
	nodes := NodeList{
		NewNode("127.0.0.1", 2221, "vagrant", authMethods),
		NewNode("127.0.0.1", 2222, "vagrant", authMethods),
	}

	// Connect to the nodes
	nodes.Connect()

	// Say Hello
	printResponse(nodes.Run("echo hello"))
	
	// Use pipes
	printResponse(nodes.Run("echo \"abc\" | tr \"a-z\" \"A-Z\""))

	// Close the connections to the cluster
	nodes.Close()
}

License

This software is made availabled under the terms of the Apache License, Version 2, as stated in the file LICENSE.

Individual files may be made available under their own specific license, all compatible with Apache License, Version 2. Please see individual files for details.

Documentation

Index

• func Parsekey(file string) (private ssh.Signer, err error)
• type Node
  • func NewNode(host string, port uint, user string, auth []ssh.AuthMethod) *Node
  • func (n *Node) Close() error
  • func (n *Node) Connect() error
  • func (n *Node) Execute(req Request) error
• type NodeList
  • func (l NodeList) Close() error
  • func (l NodeList) Connect() error
  • func (l NodeList) Copy(src string, dest string) (chan Response, error)
  • func (l NodeList) Each(fn func(*Node, func(Response) error) error) (chan Response, error)
  • func (l NodeList) Execute(req Request) (chan Response, error)
  • func (l NodeList) Filter(fn func(*Node) bool) NodeList
  • func (l NodeList) Run(command string) (chan Response, error)
  • func (l NodeList) Write(dest string, content *bytes.Reader) (chan Response, error)
  • func (l NodeList) WriteBytes(dest string, content []byte) (chan Response, error)
• type Request
• type Response

Functions

func Parsekey

func Parsekey(file string) (private ssh.Signer, err error)

A utility function to simplify the reasing and parsing of SSH Private Keys.

Types

type Node

type Node struct {

	// Address of the node
	Host string

	// Port of the node
	Port uint

	// Username for user to authenticate
	User string

	// Authentication Method
	Auth []ssh.AuthMethod
	// contains filtered or unexported fields
}

Node describes a server which will be managed.

func NewNode

func NewNode(host string, port uint, user string, auth []ssh.AuthMethod) *Node

Create a new Node. The []AuthMethod used for each Node, can be unique to the specific Node or share amongst Nodes.

func (*Node) Close

func (n *Node) Close() error

Close the SSH connection.

func (*Node) Connect

func (n *Node) Connect() error

Connect to the node over SSH.

func (*Node) Execute

func (n *Node) Execute(req Request) error

Execute a request against the Node. This sends the request to the Node receive channel, for processing.

type NodeList

type NodeList []*Node

func (NodeList) Close

func (l NodeList) Close() error

Close the connections for each Node in the NodeList.

func (NodeList) Connect

func (l NodeList) Connect() error

Connect each Node in NodeList to their respective servers.

func (NodeList) Copy

func (l NodeList) Copy(src string, dest string) (chan Response, error)

Copy a file from src to dest on each Node. The result will be channel of Responses for each Node in the NodeList.

func (NodeList) Each

func (l NodeList) Each(fn func(*Node, func(Response) error) error) (chan Response, error)

Perform an operation against each Node in the NodeList. The result will be channel of Responses for each Node in the NodeList.

func (NodeList) Execute

func (l NodeList) Execute(req Request) (chan Response, error)

Execute a Request against each Node in the NodeList. The result will be channel of Responses for each Node in the NodeList.

func (NodeList) Filter

func (l NodeList) Filter(fn func(*Node) bool) NodeList

Filter a NodeList based on a predicate function. The predicate function should return true, if the Node in the list should be kept. Otherwise false should be returned. The result is a new NodeList containing the Nodes which the predicate function returned true for.

func (NodeList) Run

func (l NodeList) Run(command string) (chan Response, error)

Run a command against each Node in the NodeList. The result will be channel of Responses for each Node in the NodeList.

func (NodeList) Write

func (l NodeList) Write(dest string, content *bytes.Reader) (chan Response, error)

Write a file from at dest on each Node. The result will be channel of Responses for each Node in the NodeList.

func (NodeList) WriteBytes

func (l NodeList) WriteBytes(dest string, content []byte) (chan Response, error)

Write a file from at dest on each Node. The result will be channel of Responses for each Node in the NodeList.

type Request

type Request struct {

	// Command to execute
	Command string

	// Stdin Buffer
	Stdin []byte

	// Response Channel
	Respond func(Response) error
}

Request represents the command, stdin and callback responder to be executed by a Node.

type Response

type Response struct {

	// Node
	Node *Node

	// Exit Code
	ExitCode int

	// Stdout Buffer
	Stdout *bytes.Buffer

	// Stderr Buffer
	Stderr *bytes.Buffer
}

Response represents the result of a command executed on a Node, including exit code, stdout and stderr.