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. Pageant or openssh agent can be used on Windows.
• 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 its 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 DefaultPasswordCallback() (string, error)
• func GroupParams(params ...any) ([]exec.Option, []any)
• func ParseSSHPrivateKey(key []byte, callback PasswordCallback) ([]ssh.AuthMethod, error)
• func SetLogger(logger log.Logger)
• type Command
  • func (c *Command) Wait() error
• type Connection
  • func (c *Connection) Address() string
  • 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 ...any) (string, error)
  • func (c Connection) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (rigfs.Waiter, error)
  • func (c Connection) Execf(s string, params ...any) error
  • func (c *Connection) Fsys() rigfs.Fsys
  • func (c *Connection) IsConnected() bool
  • func (c *Connection) IsWindows() bool
  • func (c *Connection) Protocol() string
  • func (c *Connection) SetDefaults()
  • func (c Connection) String() string
  • func (c Connection) Sudo(cmd string) (string, error)
  • func (c *Connection) SudoFsys() rigfs.Fsys
  • func (c *Connection) Upload(src, dst string, _ ...exec.Option) 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) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (waiter, error)
  • func (c *Localhost) IPAddress() string
  • func (c *Localhost) IsConnected() bool
  • func (c *Localhost) IsWindows() bool
  • func (c *Localhost) Protocol() string
  • func (c *Localhost) String() string
• type OSVersion
  • func GetOSVersion(conn *Connection) (OSVersion, error)
  • func (o *OSVersion) String() string
• type PasswordCallback
• 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) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (waiter, error)
  • func (c *SSH) IPAddress() string
  • func (c *SSH) IsConnected() bool
  • func (c *SSH) IsWindows() bool
  • func (c *SSH) Protocol() string
  • func (c *SSH) SetDefaults()
  • func (c *SSH) String() string
• 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) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (waiter, error)
  • func (c *WinRM) IPAddress() string
  • func (c *WinRM) IsConnected() bool
  • func (c *WinRM) IsWindows() bool
  • func (c *WinRM) Protocol() string
  • func (c *WinRM) SetDefaults()
  • func (c *WinRM) String() string

Variables

var (
	ErrOS               = errors.New("local os")              // ErrOS is returned when an action fails on local OS
	ErrInvalidPath      = errors.New("invalid path")          // ErrInvalidPath is returned when a path is invalid
	ErrValidationFailed = errors.New("validation failed")     // ErrValidationFailed is returned when a validation fails
	ErrSudoRequired     = errors.New("sudo required")         // ErrSudoRequired is returned when sudo is required
	ErrNotFound         = errors.New("not found")             // ErrNotFound is returned when a resource is not found
	ErrNotImplemented   = errors.New("not implemented")       // ErrNotImplemented is returned when a feature is not implemented
	ErrNotSupported     = errors.New("not supported")         // ErrNotSupported is returned when a feature is not supported
	ErrAuthFailed       = errors.New("authentication failed") // ErrAuthFailed is returned when authentication fails
	ErrUploadFailed     = errors.New("upload failed")         // ErrUploadFailed is returned when an upload fails
	ErrNotConnected     = errors.New("not connected")         // ErrNotConnected is returned when a connection is not established
	ErrCantConnect      = errors.New("can't connect")         // ErrCantConnect is returned when a connection is not established and retrying will fail
	ErrCommandFailed    = errors.New("command failed")        // ErrCommandFailed is returned when a command fails
)

var (

	// ErrChecksumMismatch is returned when the checksum of an uploaded file does not match expectation
	ErrChecksumMismatch = errors.New("checksum mismatch")
)

var (
	// 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)
	Resolvers = []resolveFunc{resolveLinux, resolveDarwin, resolveWindows}
)

var SSHConfigGetAll = ssh_config.GetAll

SSHConfigGetAll by default points to ssh_config package's GetAll() function you can override it with your own implementation for testing purposes

Functions

func DefaultPasswordCallback

func DefaultPasswordCallback() (string, error)

DefaultPasswordCallback is a default implementation for PasswordCallback

func GroupParams

func GroupParams(params ...any) ([]exec.Option, []any)

GroupParams separates exec.Options from other sprintf templating args

func ParseSSHPrivateKey

func ParseSSHPrivateKey(key []byte, callback PasswordCallback) ([]ssh.AuthMethod, error)

ParseSSHPrivateKey is a convenience utility to parses a private key and return []ssh.AuthMethod to be used in SSH{} AuthMethods field. This way you can avoid importing golang.org/x/crypto/ssh in your code and handle the passphrase prompt in a callback function.

func SetLogger

func SetLogger(logger log.Logger)

SetLogger can be used to assign your own logger to rig

Types

type Command

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

Command implements the Waiter interface

func (*Command) Wait

func (c *Command) Wait() error

Wait blocks until the command finishes

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) Address

func (c *Connection) Address() string

Address returns the connection address

func (*Connection) Connect

func (c *Connection) Connect() error

Connect to the host and identify the operating system and sudo capability

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 ...any) (string, error)

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

func (Connection) ExecStreams

func (c Connection) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (rigfs.Waiter, error)

ExecStreams executes a command on the remote host and uses the passed in streams for stdin, stdout and stderr. It returns a Waiter with a .Wait() function that blocks until the command finishes and returns an error if the exit code is not zero.

func (Connection) Execf

func (c Connection) Execf(s string, params ...any) error

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

func (*Connection) Fsys

func (c *Connection) Fsys() rigfs.Fsys

Fsys returns a fs.FS compatible filesystem interface for accessing files on remote hosts

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

IsWindows returns true on windows hosts

func (*Connection) Protocol

func (c *Connection) Protocol() string

Protocol returns the connection protocol name

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) Sudo

func (c Connection) Sudo(cmd string) (string, error)

Sudo formats a command string to be run with elevated privileges

func (*Connection) SudoFsys

func (c *Connection) SudoFsys() rigfs.Fsys

SudoFsys returns a fs.FS compatible filesystem interface for accessing files on remote hosts with sudo permissions

func (*Connection) Upload

func (c *Connection) Upload(src, dst string, _ ...exec.Option) 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) ExecStreams

func (c *Localhost) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (waiter, error)

ExecStreams executes a command on the remote host and uses the passed in streams for stdin, stdout and stderr. It returns a Waiter with a .Wait() function that blocks until the command finishes and returns an error if the exit code is not zero.

func (*Localhost) IPAddress

func (c *Localhost) IPAddress() string

IPAddress returns the connection address

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) Protocol

func (c *Localhost) Protocol() string

Protocol returns the protocol name, "Local"

func (*Localhost) String

func (c *Localhost) String() string

String returns the connection's printable name

type OSVersion

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

OSVersion host operating system version information

func GetOSVersion

func GetOSVersion(conn *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 PasswordCallback

type PasswordCallback func() (secret string, err error)

PasswordCallback is a function that is called when a passphrase is needed to decrypt a private key

type SSH

type SSH struct {
	Address          string           `yaml:"address" validate:"required,hostname_rfc1123|ip"`
	User             string           `yaml:"user" validate:"required" default:"root"`
	Port             int              `yaml:"port" default:"22" validate:"gt=0,lte=65535"`
	KeyPath          *string          `yaml:"keyPath" validate:"omitempty"`
	HostKey          string           `yaml:"hostKey,omitempty"`
	Bastion          *SSH             `yaml:"bastion,omitempty"`
	PasswordCallback PasswordCallback `yaml:"-"`

	// AuthMethods can be used to pass in a list of ssh.AuthMethod objects
	// for example to use a private key from memory:
	//   ssh.PublicKeys(privateKey)
	// For convenience, you can use ParseSSHPrivateKey() to parse a private key:
	//   authMethods, err := rig.ParseSSHPrivateKey(key, rig.DefaultPassphraseCallback)
	AuthMethods []ssh.AuthMethod `yaml:"-"`
	// 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) ExecStreams

func (c *SSH) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (waiter, error)

ExecStreams executes a command on the remote host and uses the passed in streams for stdin, stdout and stderr. It returns a Waiter with a .Wait() function that blocks until the command finishes and returns an error if the exit code is not zero.

func (*SSH) IPAddress

func (c *SSH) IPAddress() string

IPAddress returns the connection address

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) Protocol

func (c *SSH) Protocol() string

Protocol returns the protocol name, "SSH"

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

type WinRM

type WinRM struct {
	Address       string `yaml:"address" validate:"required,hostname_rfc1123|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_rfc1123|ip"`
	Bastion       *SSH   `yaml:"bastion,omitempty"`
	// 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) ExecStreams

func (c *WinRM) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (waiter, error)

ExecStreams executes a command on the remote host and uses the passed in streams for stdin, stdout and stderr. It returns a Waiter with a .Wait() function that blocks until the command finishes and returns an error if the exit code is not zero.

func (*WinRM) IPAddress

func (c *WinRM) IPAddress() string

IPAddress returns the connection address

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) Protocol

func (c *WinRM) Protocol() string

Protocol returns the protocol name, "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