rig

README

Rig

A golang package for adding multi-protocol connectivity and multi-os operation functionality to your application's Host objects.

Design goals

Rig's intention is to be easy to use and extend.

It should be easy to add support for new operating systems and to add new commands to the multi-os support mechanism without breaking go's type checking.

All of the relevant structs have YAML tags and default values to make unmarshaling from YAML configurations as easy as possible.

Protocols

Currently rig comes with the most common ways to connect to hosts:

• SSH for connecting to hosts that accept SSH connections
• WinRM as an alternative to SSH for windows hosts (SSH works too)
• Local for treating the localhost as it was one of the remote hosts

Usage

The intended way to use rig is to embed the rig.Connection struct into your own.

Example:

package main

import "github.com/k0sproject/rig"

type host struct {
  rig.Connection
}

func main() {
  h := host{
    connection: rig.Connection{
      SSH: &rig.SSH{
        Address: 10.0.0.1
      }
    }
  }

  if err := h.Connect(); err != nil {
    panic(err)
  }

  output, err := h.ExecOutput("ls -al")
  if err != nil {
    panic(err)
  }
  println(output)
}

But of course you can use it directly on it's own too:

package main

import "github.com/k0sproject/rig"

func main() {
  h := rig.Connection{
    SSH: &rig.SSH{
      Address: 10.0.0.1
    }
  }

  if err := h.Connect(); err != nil {
    panic(err)
  }
}

See more usage examples in the examples/ directory.

Documentation

Overview

Package rig provides an easy way to add multi-protocol connectivity and multi-os operation support to your application's Host objects

Index

• Variables
• func SetLogger(logger log.Logger)
• type Connection
  • func (c *Connection) Connect() error
  • func (c *Connection) Disconnect()
  • func (c Connection) Exec(cmd string, opts ...exec.Option) error
  • func (c Connection) ExecInteractive(cmd string) error
  • func (c Connection) ExecOutput(cmd string, opts ...exec.Option) (string, error)
  • func (c Connection) ExecOutputf(s string, params ...interface{}) (string, error)
  • func (c Connection) Execf(s string, params ...interface{}) error
  • func (c *Connection) IsConnected() bool
  • func (c *Connection) IsWindows() (bool, error)
  • func (c *Connection) SetDefaults()
  • func (c Connection) String() string
  • func (c Connection) Upload(src, dst string) error
• type Localhost
  • func (c *Localhost) Connect() error
  • func (c *Localhost) Disconnect()
  • func (c *Localhost) Exec(cmd string, opts ...exec.Option) error
  • func (c *Localhost) ExecInteractive(cmd string) error
  • func (c *Localhost) IsConnected() bool
  • func (c *Localhost) IsWindows() bool
  • func (c *Localhost) String() string
  • func (c *Localhost) Upload(src, dst string) error
• type NotConnectedError
  • func (e *NotConnectedError) Error() string
• type OSVersion
  • func GetOSVersion(c *Connection) (OSVersion, error)
  • func (o *OSVersion) String() string
• type SSH
  • func (c *SSH) Connect() error
  • func (c *SSH) Disconnect()
  • func (c *SSH) Exec(cmd string, opts ...exec.Option) error
  • func (c *SSH) ExecInteractive(cmd string) error
  • func (c *SSH) IsConnected() bool
  • func (c *SSH) IsWindows() bool
  • func (c *SSH) SetDefaults()
  • func (c *SSH) String() string
  • func (c *SSH) Upload(src, dst string) error
• type WinRM
  • func (c *WinRM) Connect() error
  • func (c *WinRM) Disconnect()
  • func (c *WinRM) Exec(cmd string, opts ...exec.Option) error
  • func (c *WinRM) ExecInteractive(cmd string) error
  • func (c *WinRM) IsConnected() bool
  • func (c *WinRM) IsWindows() bool
  • func (c *WinRM) SetDefaults()
  • func (c *WinRM) String() string
  • func (c *WinRM) Upload(src, dst string) error

Variables

var Resolvers []resolveFunc

Resolvers exposes an array of resolve functions where you can add your own if you need to detect some OS rig doesn't already know about (consider making a PR)

Functions

func SetLogger

func SetLogger(logger log.Logger)

SetLogger can be used to assign your own logger to rig

Types

type Connection

type Connection struct {
	WinRM     *WinRM     `yaml:"winRM,omitempty"`
	SSH       *SSH       `yaml:"ssh,omitempty"`
	Localhost *Localhost `yaml:"localhost,omitempty"`

	OSVersion OSVersion `yaml:"-"`
	// contains filtered or unexported fields
}

Connection is a Struct you can embed into your application's "Host" types to give them multi-protocol connectivity.

All of the important fields have YAML tags.

If you have a host like this:

type Host struct {
  rig.Connection `yaml:"connection"`
}

and a YAML like this:

hosts:
  - connection:
      ssh:
        address: 10.0.0.1
        port: 8022

you can then simply do this:

var hosts []*Host
if err := yaml.Unmarshal(data, &hosts); err != nil {
  panic(err)
}
for _, h := range hosts {
  err := h.Connect()
  if err != nil {
    panic(err)
  }
  output, err := h.ExecOutput("echo hello")
}

func (*Connection) Connect

func (c *Connection) Connect() error

Connect to the host and identify the operating system

func (*Connection) Disconnect

func (c *Connection) Disconnect()

Disconnect from the host

func (Connection) Exec

func (c Connection) Exec(cmd string, opts ...exec.Option) error

Exec runs a command on the host

func (Connection) ExecInteractive

func (c Connection) ExecInteractive(cmd string) error

ExecInteractive executes a command on the host and passes control of local input to the remote command

func (Connection) ExecOutput

func (c Connection) ExecOutput(cmd string, opts ...exec.Option) (string, error)

ExecOutput runs a command on the host and returns the output as a String

func (Connection) ExecOutputf

func (c Connection) ExecOutputf(s string, params ...interface{}) (string, error)

ExecOutputf is like ExecOutput but you can use Sprintf templating for the command

func (Connection) Execf

func (c Connection) Execf(s string, params ...interface{}) error

Execf is just like `Exec` but you can use Sprintf templating for the command

func (*Connection) IsConnected

func (c *Connection) IsConnected() bool

IsConnected returns true if the client is assumed to be connected. "Assumed" - as in `Connect()` has been called and no error was returned. The underlying client may actually have disconnected and has become inoperable, but rig won't know that until you try to execute commands on the connection.

func (*Connection) IsWindows

func (c *Connection) IsWindows() (bool, error)

IsWindows returns true on windows hosts

func (*Connection) SetDefaults

func (c *Connection) SetDefaults()

SetDefaults sets a connection

func (Connection) String

func (c Connection) String() string

String returns a printable representation of the connection, which will look like: `[ssh] address:port`

func (Connection) Upload

func (c Connection) Upload(src, dst string) error

Upload copies a file from a local path src to the remote host path dst. For smaller files you should probably use os.WriteFile

type Localhost

type Localhost struct {
	Enabled bool `yaml:"enabled" validate:"required,eq=true" default:"true"`
}

Localhost is a direct localhost connection

func (*Localhost) Connect

func (c *Localhost) Connect() error

Connect on local connection does nothing

func (*Localhost) Disconnect

func (c *Localhost) Disconnect()

Disconnect on local connection does nothing

func (*Localhost) Exec

func (c *Localhost) Exec(cmd string, opts ...exec.Option) error

Exec executes a command on the host

func (*Localhost) ExecInteractive

func (c *Localhost) ExecInteractive(cmd string) error

ExecInteractive executes a command on the host and copies stdin/stdout/stderr from local host

func (*Localhost) IsConnected

func (c *Localhost) IsConnected() bool

IsConnected for local connections is always true

func (*Localhost) IsWindows

func (c *Localhost) IsWindows() bool

IsWindows is true when running on a windows host

func (*Localhost) String

func (c *Localhost) String() string

String returns the connection's printable name

func (*Localhost) Upload

func (c *Localhost) Upload(src, dst string) error

Upload copies a larger file to another path on the host.

type NotConnectedError

type NotConnectedError rigError

NotConnectedError is returned when attempting to perform remote operations on Host when it is not connected

func (*NotConnectedError) Error

func (e *NotConnectedError) Error() string

Error returns the error message

type OSVersion

type OSVersion struct {
	ID      string
	IDLike  string
	Name    string
	Version string
}

OSVersion host operating system version information

func GetOSVersion

func GetOSVersion(c *Connection) (OSVersion, error)

GetOSVersion runs through the Resolvers and tries to figure out the OS version information

func (*OSVersion) String

func (o *OSVersion) String() string

String returns a human readable representation of OSVersion

type SSH

type SSH struct {
	Address string `yaml:"address" validate:"required,hostname|ip"`
	User    string `yaml:"user" validate:"omitempty,gt=2" default:"root"`
	Port    int    `yaml:"port" default:"22" validate:"gt=0,lte=65535"`
	KeyPath string `yaml:"keyPath" validate:"omitempty,file" default:"~/.ssh/id_rsa"`
	// contains filtered or unexported fields
}

SSH describes an SSH connection

func (*SSH) Connect

func (c *SSH) Connect() error

Connect opens the SSH connection

func (*SSH) Disconnect

func (c *SSH) Disconnect()

Disconnect closes the SSH connection

func (*SSH) Exec

func (c *SSH) Exec(cmd string, opts ...exec.Option) error

Exec executes a command on the host

func (*SSH) ExecInteractive

func (c *SSH) ExecInteractive(cmd string) error

ExecInteractive executes a command on the host and copies stdin/stdout/stderr from local host

func (*SSH) IsConnected

func (c *SSH) IsConnected() bool

IsConnected returns true if the client is connected

func (*SSH) IsWindows

func (c *SSH) IsWindows() bool

IsWindows is true when the host is running windows

func (*SSH) SetDefaults

func (c *SSH) SetDefaults()

SetDefaults sets various default values

func (*SSH) String

func (c *SSH) String() string

String returns the connection's printable name

func (*SSH) Upload

func (c *SSH) Upload(src, dst string) error

Upload uploads a larger file to the host. Use instead of configurer.WriteFile when it seems appropriate

type WinRM

type WinRM struct {
	Address       string `yaml:"address" validate:"required,hostname|ip"`
	User          string `yaml:"user" validate:"omitempty,gt=2" default:"Administrator"`
	Port          int    `yaml:"port" default:"5985" validate:"gt=0,lte=65535"`
	Password      string `yaml:"password,omitempty"`
	UseHTTPS      bool   `yaml:"useHTTPS" default:"false"`
	Insecure      bool   `yaml:"insecure" default:"false"`
	UseNTLM       bool   `yaml:"useNTLM" default:"false"`
	CACertPath    string `yaml:"caCertPath,omitempty" validate:"omitempty,file"`
	CertPath      string `yaml:"certPath,omitempty" validate:"omitempty,file"`
	KeyPath       string `yaml:"keyPath,omitempty" validate:"omitempty,file"`
	TLSServerName string `yaml:"tlsServerName,omitempty" validate:"omitempty,hostname|ip"`
	// contains filtered or unexported fields
}

WinRM describes a WinRM connection with its configuration options

func (*WinRM) Connect

func (c *WinRM) Connect() error

Connect opens the WinRM connection

func (*WinRM) Disconnect

func (c *WinRM) Disconnect()

Disconnect closes the WinRM connection

func (*WinRM) Exec

func (c *WinRM) Exec(cmd string, opts ...exec.Option) error

Exec executes a command on the host

func (*WinRM) ExecInteractive

func (c *WinRM) ExecInteractive(cmd string) error

ExecInteractive executes a command on the host and copies stdin/stdout/stderr from local host

func (*WinRM) IsConnected

func (c *WinRM) IsConnected() bool

IsConnected returns true if the client is connected

func (*WinRM) IsWindows

func (c *WinRM) IsWindows() bool

IsWindows always returns true on winrm

func (*WinRM) SetDefaults

func (c *WinRM) SetDefaults()

SetDefaults sets various default values

func (*WinRM) String

func (c *WinRM) String() string

String returns the connection's printable name

func (*WinRM) Upload

func (c *WinRM) Upload(src, dst string) error

Upload uploads a file from local src path to remote dst path