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. 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 GroupParams(params ...any) ([]exec.Option, []any)
- 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 ...any) (string, error)
- func (c Connection) Execf(s string, params ...any) 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 OSVersion
- 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) 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 ¶
This section is empty.
Variables ¶
var ( // ErrInvalidOSRelease is returned when the OS release file is invalid ErrInvalidOSRelease = errors.New("invalid or incomplete os-release file contents, at least ID and VERSION_ID required") // ErrUnableToDetermineOS is returned when the OS cannot be determined ErrUnableToDetermineOS = errors.New("unable to determine host os") // ErrNotLinux is returned when the host is not Linux ErrNotLinux = errors.New("not a linux host") // ErrNotDarwin is returned when the host is not a darwin host ErrNotDarwin = errors.New("not a darwin host") )
var ( // ErrNoSignerFound is returned when no signer is found for a key ErrNoSignerFound = errors.New("no signer found for key") // ErrDataInStderr is returned when data is received for stderr from a windows host ErrDataInStderr = errors.New("command failed (received output to stderr on windows)") // ErrUnexpectedCopyOutput is returned when the output of a copy command is not as expected ErrUnexpectedCopyOutput = errors.New("copy command did not output the expected JSON") // ErrCopyFileChecksumMismatch is returned when the checksum of the uploaded file does not match the source file ErrCopyFileChecksumMismatch = errors.New("copy file checksum mismatch") // ErrInvalidPath is returned for paths that are invalid or unusable ErrInvalidPath = errors.New("invalid path") )
var ErrNoSSHAgent = fmt.Errorf("no ssh agent found")
ErrNoSSHAgent is returned when SSH_AUTH_SOCK is not set
var ErrNoSudo = errors.New("user is not an administrator and passwordless access elevation has not been configured")
ErrNoSudo is returned when the connection does not have sudo capability but it is required
var ErrNonZeroExitCode = errors.New("non-zero exit code")
ErrNonZeroExitCode is returned when the remote command exits with non-zero exit code
var ErrNotConnected = errors.New("not connected")
ErrNotConnected is returned when a connection is used when it is not connected
var Resolvers = []resolveFunc{resolveLinux, resolveDarwin, resolveWindows}
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)
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 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 ...any) (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 ...any) 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 OSVersion ¶
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
type PasswordCallback ¶ added in v0.7.0
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|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:"-"`
// 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
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
rigtest
command
|
|
|
examples
|
|
|
confirmation
command
|
|
|
logging
command
|
|
|
os/stock
command
|
|
|
password
command
|
|
|
upload
command
|
|
|
Package exec provides helpers for setting execution options for commands
|
Package exec provides helpers for setting execution options for commands |
|
Package log provides a simple pluggable logging interface
|
Package log provides a simple pluggable logging interface |
|
Package os provides a platform-independent interface to operating system functionality.
|
Package os provides a platform-independent interface to operating system functionality. |
|
initsystem
Package initsystem provides an abstraction over several supported init systems.
|
Package initsystem provides an abstraction over several supported init systems. |
|
linux
Package linux contains configurers for various linux based distributions
|
Package linux contains configurers for various linux based distributions |
|
linux/enterpriselinux
Package enterpriselinux provides OS modules for Enterprise Linux based distributions
|
Package enterpriselinux provides OS modules for Enterprise Linux based distributions |
|
mac
Package darwin provides a configurer for macOS
|
Package darwin provides a configurer for macOS |
|
registry
Package registry is a registry of OS support modules
|
Package registry is a registry of OS support modules |
|
support
Package support can be imported to load all the stock os support packages.
|
Package support can be imported to load all the stock os support packages. |
|
windows
Package windows provides OS support for Windows.
|
Package windows provides OS support for Windows. |
|
pkg
|
|
|
ssh/hostkey
Package hostkey implements a callback for the ssh.ClientConfig.HostKeyCallback
|
Package hostkey implements a callback for the ssh.ClientConfig.HostKeyCallback |
|
Package powershell provides helpers for powershell command generation
|
Package powershell provides helpers for powershell command generation |