The highest tagged major version is
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 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 ¶
- Constants
- Variables
- func GroupParams(params ...interface{}) (opts []exec.Option, args []interface{})
- func SetLogger(logger log.Logger)
- 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 ...interface{}) (string, error)
- func (c Connection) Execf(s string, params ...interface{}) error
- 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) Upload(src, dst string, opts ...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) IPAddress() string
- func (c *Localhost) IsConnected() bool
- func (c *Localhost) IsWindows() bool
- func (c *Localhost) Protocol() string
- func (c *Localhost) String() string
- func (c *Localhost) Upload(src, dst string, opts ...exec.Option) error
- type NotConnectedError
- type OSVersion
- 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) 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
- func (c *SSH) Upload(src, dst string, opts ...exec.Option) 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) 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
- func (c *WinRM) Upload(src, dst string, opts ...exec.Option) error
Constants ¶
const DefaultKeypath = "~/.ssh/id_rsa"
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 GroupParams ¶ added in v0.4.3
GroupParams separates exec.Options from other sprintf templating args
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) Address ¶ added in v0.3.3
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) 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 ¶
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
IsWindows returns true on windows hosts
func (*Connection) Protocol ¶ added in v0.3.3
func (c *Connection) Protocol() string
Protocol returns the connection protocol name
func (Connection) String ¶
func (c Connection) String() string
String returns a printable representation of the connection, which will look like: `[ssh] address:port`
type Localhost ¶
type Localhost struct {
Enabled bool `yaml:"enabled" validate:"required,eq=true" default:"true"`
}
Localhost is a direct localhost connection
func (*Localhost) Disconnect ¶
func (c *Localhost) Disconnect()
Disconnect on local connection does nothing
func (*Localhost) ExecInteractive ¶
ExecInteractive executes a command on the host and copies stdin/stdout/stderr from local host
func (*Localhost) IsConnected ¶
IsConnected for local connections is always true
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 ¶
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
type SSH ¶
type SSH struct {
Address string `yaml:"address" validate:"required,hostname|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"`
// contains filtered or unexported fields
}
SSH describes an SSH connection
func (*SSH) ExecInteractive ¶
ExecInteractive executes a command on the host and copies stdin/stdout/stderr from local host
func (*SSH) IsConnected ¶
IsConnected returns true if the client is connected
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"`
Bastion *SSH `yaml:"bastion,omitempty"`
// contains filtered or unexported fields
}
WinRM describes a WinRM connection with its configuration options
func (*WinRM) ExecInteractive ¶
ExecInteractive executes a command on the host and copies stdin/stdout/stderr from local host
func (*WinRM) IsConnected ¶
IsConnected returns true if the client is connected
Source Files
Directories