netgo

README

netgo

Overview

A module to ssh into devices and run commands. It supports running a single command in a remote session or running several commands in an interactive session.

Juniper Package

There is also a Juniper package that wraps around the base netgo package that has some logic built in to get structured data back from the devices. It also allows you to perform a "dry run" by logging in, applying a config, printing a diff, and then rolling it back before logging out of the device.

Authentication Methods

This package supports the following authentication methods:

• via username/password
• via an SSH key file

Usage

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/montybeatnik/netgo"
)

// Example with Password
func main() {
	devIP := "10.0.0.60"
	client := netgo.NewClient(
		os.Getenv("SSH_USER"),
		devIP,
		netgo.Password(os.Getenv("SSH_PASSWORD")),
	)
	out, err := client.Run("show version")
	if err != nil {
		log.Fatalf("command failed: %v", err)
	}
	fmt.Println(out)
}

// Example with Private Key
func main() {
	homeDir, err := os.UserHomeDir()
	if err != nil {
		log.Fatal(err)
	}
	keyFile := filepath.Join(homeDir, ".ssh/id_rsa")
	if err != nil {
		log.Fatal(err)
	}
	devIP := "10.0.0.60"
	client := netgo.NewClient(
		os.Getenv("SSH_USER"),
		devIP,
		netgo.PrivateKey(keyFile),
	)
	out, err := client.Run("show version")
	if err != nil {
		log.Fatalf("command failed: %v", err)
	}
	fmt.Println(out)
}

// Simple concurrency example with wait group

TODO

• Add support for public key auth.
• Add Juniper package
  • Config Differ
  • Apply Configs
  • First Operational Command Example

Profile

• go test -v -run Run -cpuprofile cpu.prof -memprofile mem.prof -bench .

Testing

Unit tests

All tests

go test -v

A specific test

go test -v -run RunCommand

Specific tests matching a pattern

go test -v -run Run

Benchmarks

go test -run RunCommand -bench=.

Documentation

Index

• Variables
• type Option
  • func WithHostKeyCallback(knownHostsFile string) Option
  • func WithPassword(pw string) Option
  • func WithPort(port string) Option
  • func WithPrivateKey(keyfile string) Option
  • func WithTimeout(seconds time.Duration) Option
• type SSHClient
  • func NewClient(user, target string, opts ...Option) *SSHClient
  • func (c *SSHClient) Run(cmd string) (string, error)
  • func (c *SSHClient) RunAll(cmds ...string) (string, error)

Variables

var (
	ErrAuthFailure = errors.New("failed authentication")
	ErrTimeout     = errors.New("timeout")
)

Types

type Option

type Option func(*SSHClient)

func WithHostKeyCallback

func WithHostKeyCallback(knownHostsFile string) Option

WithHostKeyCallback sets the SSHClient's initializes the client with an allow list of known trusted hosts.

func WithPassword

func WithPassword(pw string) Option

WithPassword sets SSHClient's password.

func WithPort

func WithPort(port string) Option

WithPort sets SSHClient's listening port.

func WithPrivateKey

func WithPrivateKey(keyfile string) Option

WithPrivateKey sets SSHClient's private key.

func WithTimeout

func WithTimeout(seconds time.Duration) Option

WithTimeout sets SSHClient's timeout value.

type SSHClient

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

SSHClient holds the elements to setup an SSH client

func NewClient

func NewClient(user, target string, opts ...Option) *SSHClient

NewClient is a factory function that takes in SSH parameters and returns a new client

func (*SSHClient) Run

func (c *SSHClient) Run(cmd string) (string, error)

Run takes in a command and attempts to establishe a remote session and run the command.

func (*SSHClient) RunAll

func (c *SSHClient) RunAll(cmds ...string) (string, error)

RunAll takes in one or more commands. It establishes a remote session with the target IP and attempts to run all of the commands supplied. You must remember to exit as this method does establish an interactive session.