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 ParseOSReleaseFile(s string, version *OSVersion) error
- func ParseSSHPrivateKey(key []byte, callback PasswordCallback) ([]ssh.AuthMethod, error)
- func SetLogger(logger log.Logger)
- type Command
- 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) (exec.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) SetSudofn(f func(string) string)
- 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, perm fs.FileMode, 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) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (exec.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
- type OpenSSH
- func (c *OpenSSH) Connect() error
- func (c *OpenSSH) Disconnect()
- func (c *OpenSSH) Exec(cmdStr string, opts ...exec.Option) error
- func (c *OpenSSH) ExecInteractive(cmdStr string) error
- func (c *OpenSSH) ExecStreams(cmdStr string, stdin io.ReadCloser, stdout, stderr io.Writer, ...) (exec.Waiter, error)
- func (c *OpenSSH) IPAddress() string
- func (c *OpenSSH) IsConnected() bool
- func (c *OpenSSH) IsWindows() bool
- func (c *OpenSSH) Protocol() string
- func (c *OpenSSH) SetDefaults()
- func (c *OpenSSH) String() string
- type OpenSSHOptions
- type PasswordCallback
- type ResolveFunc
- 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) (exec.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) (exec.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
Constants ¶
This section is empty.
Variables ¶
var ( // ErrOS is returned when an action fails on local OS. ErrOS = errors.New("local os") // ErrInvalidPath is returned when a path is invalid. ErrInvalidPath = errors.New("invalid path") // ErrValidationFailed is returned when a validation fails. ErrValidationFailed = errors.New("validation failed") // ErrSudoRequired is returned when sudo is required. ErrSudoRequired = errors.New("sudo required") // ErrNotFound is returned when a resource is not found. ErrNotFound = errors.New("not found") // ErrNotImplemented is returned when a feature is not implemented. ErrNotImplemented = errors.New("not implemented") // ErrNotSupported is returned when a feature is not supported. ErrNotSupported = errors.New("not supported") // ErrAuthFailed is returned when authentication fails. ErrAuthFailed = errors.New("authentication failed") // ErrUploadFailed is returned when an upload fails. ErrUploadFailed = errors.New("upload failed") // ErrNotConnected is returned when a connection is not established. ErrNotConnected = errors.New("not connected") // ErrCantConnect is returned when a connection is not established and retrying will fail. ErrCantConnect = errors.New("can't connect") // ErrCommandFailed is returned when a command fails. ErrCommandFailed = errors.New("command failed") )
Error variables for rig package operations.
var DefaultOpenSSHOptions = OpenSSHOptions{ "ControlPath": "~/.ssh/ctrl-%C", "ControlMaster": false, "ServerAliveInterval": "60", "ServerAliveCountMax": "3", "StrictHostKeyChecking": false, "Compression": false, "ConnectTimeout": "10", }
DefaultOpenSSHOptions are the default options for the OpenSSH client
var ( // ErrChecksumMismatch is returned when the checksum of an uploaded file does not match expectation ErrChecksumMismatch = errors.New("checksum mismatch") )
var ErrControlPathNotSet = errors.New("controlpath not set")
ErrControlPathNotSet is returned when the controlpath is not set when disconnecting from a multiplexed connection
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 ¶ added in v0.14.0
DefaultPasswordCallback is a default implementation for PasswordCallback
func GroupParams ¶ added in v0.4.3
GroupParams separates exec.Options from other sprintf templating args
func ParseOSReleaseFile ¶ added in v0.18.0
ParseOSReleaseFile parses the contents of an os-release file into an OSVersion struct.
func ParseSSHPrivateKey ¶ added in v0.14.0
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.
Types ¶
type Command ¶ added in v0.11.0
type Command struct {
// contains filtered or unexported fields
}
Command implements the Waiter interface
type Connection ¶
type Connection struct {
// Connection configuration for WinRM targets
WinRM *WinRM `yaml:"winRM,omitempty" json:"winRM,omitempty"`
// Connection configuration for SSH targets
SSH *SSH `yaml:"ssh,omitempty" json:"ssh,omitempty"`
// Connection configuration for localhost
Localhost *Localhost `yaml:"localhost,omitempty" json:"localhost,omitempty"`
// Connection configuration for SSH targets over OpenSSH client integration
OpenSSH *OpenSSH `yaml:"openSSH,omitempty" json:"openSSH,omitempty"`
OSVersion *OSVersion `yaml:"-" json:"-"`
// 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) ExecStreams ¶ added in v0.11.0
func (c *Connection) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (exec.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 ¶ added in v0.11.0
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 ¶ added in v0.3.3
func (c *Connection) Protocol() string
Protocol returns the connection protocol name
func (*Connection) SetSudofn ¶ added in v0.19.0
func (c *Connection) SetSudofn(f func(string) string)
SetSudofn inject a sudofn into the connection before Connect() @NOTE this will avoid sudo detection if done before Connect()
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 ¶ added in v0.4.0
func (c *Connection) Sudo(cmd string) (string, error)
Sudo formats a command string to be run with elevated privileges
func (*Connection) SudoFsys ¶ added in v0.11.0
func (c *Connection) SudoFsys() rigfs.Fsys
SudoFsys returns a fs.FS compatible filesystem interface for accessing files on remote hosts with sudo permissions
type Localhost ¶
type Localhost struct {
// Enabled must be true for the connection to be valid
Enabled bool `` /* 160-byte string literal not displayed */
}
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) ExecStreams ¶ added in v0.11.0
func (c *Localhost) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (exec.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) IsConnected ¶
IsConnected for local connections is always true
type OSVersion ¶
type OSVersion struct {
ID string
IDLike string
Name string
Version string
ExtraFields map[string]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
type OpenSSH ¶ added in v0.15.0
type OpenSSH struct {
// Address of the remote host
Address string `yaml:"address" json:"address" validate:"required" jsonschema:"required,description=Address of the remote host"`
// Optional SSH user
User *string `yaml:"user,omitempty" json:"user,omitempty" jsonschema:"description=Optional SSH user"`
// Optional SSH port
Port *int `yaml:"port,omitempty" json:"port,omitempty" jsonschema:"minimum=1,maximum=65535,description=Optional SSH port"`
// Path to SSH private key
KeyPath *string `yaml:"keyPath,omitempty" json:"keyPath,omitempty" jsonschema:"description=Path to SSH private key"`
// Path to SSH config file
ConfigPath *string `yaml:"configPath,omitempty" json:"configPath,omitempty" jsonschema:"description=Path to SSH config file"`
// Additional SSH options as key-value pairs, such as StrictHostKeyChecking: false
Options OpenSSHOptions `` /* 152-byte string literal not displayed */
// Disable SSH connection multiplexing
DisableMultiplexing bool `` /* 148-byte string literal not displayed */
// contains filtered or unexported fields
}
OpenSSH is a rig.Connection implementation that uses the system openssh client "ssh" to connect to remote hosts. The connection is multiplexec over a control master, so that subsequent connections don't need to re-authenticate.
func (*OpenSSH) Connect ¶ added in v0.15.0
Connect connects to the remote host. If multiplexing is enabled, this will start a control master. If multiplexing is disabled, this will just run a noop command to check connectivity.
func (*OpenSSH) Disconnect ¶ added in v0.15.0
func (c *OpenSSH) Disconnect()
Disconnect disconnects from the remote host. If multiplexing is enabled, this will close the control master. If multiplexing is disabled, this will do nothing.
func (*OpenSSH) ExecInteractive ¶ added in v0.15.0
ExecInteractive executes an interactive command on the remote host, streaming stdin, stdout and stderr
func (*OpenSSH) ExecStreams ¶ added in v0.15.0
func (c *OpenSSH) ExecStreams(cmdStr string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (exec.Waiter, error)
ExecStreams executes a command on the remote host, streaming stdin, stdout and stderr
func (*OpenSSH) IsConnected ¶ added in v0.15.0
IsConnected returns true if the connection is connected
func (*OpenSSH) SetDefaults ¶ added in v0.15.0
func (c *OpenSSH) SetDefaults()
SetDefaults sets default values
type OpenSSHOptions ¶ added in v0.15.0
OpenSSHOptions are options for the OpenSSH client. For example StrictHostkeyChecking: false becomes -o StrictHostKeyChecking=no
func (OpenSSHOptions) Copy ¶ added in v0.15.0
func (o OpenSSHOptions) Copy() OpenSSHOptions
Copy returns a copy of the options
func (OpenSSHOptions) IsSet ¶ added in v0.15.0
func (o OpenSSHOptions) IsSet(key string) bool
IsSet returns true if the option is set
func (OpenSSHOptions) Set ¶ added in v0.15.0
func (o OpenSSHOptions) Set(key string, value any)
Set sets an option key to value
func (OpenSSHOptions) SetIfUnset ¶ added in v0.15.0
func (o OpenSSHOptions) SetIfUnset(key string, value any)
SetIfUnset sets the option if it's not already set
func (OpenSSHOptions) ToArgs ¶ added in v0.15.0
func (o OpenSSHOptions) ToArgs() []string
ToArgs converts the options to command line arguments
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 ResolveFunc ¶ added in v0.18.0
type ResolveFunc func(*Connection) (OSVersion, error)
ResolveFunc is a function that attempts to resolve the OS version of a connection.
type SSH ¶
type SSH struct {
// Address of the remote host (IP or hostname)
Address string `` /* 147-byte string literal not displayed */
// User to log in as
User string `` /* 136-byte string literal not displayed */
// SSH port, usually 22
Port int `` /* 154-byte string literal not displayed */
// Optional path to private key
KeyPath *string `yaml:"keyPath,omitempty" json:"keyPath,omitempty" validate:"omitempty" jsonschema:"description=Optional path to private key"`
// Optional known host key fingerprint
HostKey string `yaml:"hostKey,omitempty" json:"hostKey,omitempty" jsonschema:"description=Optional known host key fingerprint"`
// Optional bastion host
Bastion *SSH `yaml:"bastion,omitempty" json:"bastion,omitempty" jsonschema:"description=Optional bastion host"`
// Optional password callback function
PasswordCallback PasswordCallback `yaml:"-" json:"-"`
// 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:"-" json:"-"`
// 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) ExecStreams ¶ added in v0.11.0
func (c *SSH) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (exec.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) IsConnected ¶
IsConnected returns true if the client is connected
type WinRM ¶
type WinRM struct {
// Address of the remote host
Address string `` /* 130-byte string literal not displayed */
// User to authenticate as
User string `` /* 166-byte string literal not displayed */
// WinRM port
Port int `` /* 147-byte string literal not displayed */
// Password for WinRM authentication
Password string `yaml:"password,omitempty" json:"password,omitempty" jsonschema:"description=Password for WinRM authentication"`
// Use HTTPS for WinRM
UseHTTPS bool `yaml:"useHTTPS" json:"useHTTPS,omitempty" default:"false" jsonschema:"default=false,description=Use HTTPS for WinRM"`
// Accept invalid TLS certificates
Insecure bool `` /* 128-byte string literal not displayed */
// Use NTLM authentication
UseNTLM bool `yaml:"useNTLM" json:"useNTLM,omitempty" default:"false" jsonschema:"default=false,description=Use NTLM authentication"`
// Path to CA certificate
CACertPath string `` /* 129-byte string literal not displayed */
// Path to client certificate
CertPath string `` /* 129-byte string literal not displayed */
// Path to client key
KeyPath string `yaml:"keyPath,omitempty" json:"keyPath,omitempty" validate:"omitempty,file" jsonschema:"description=Path to client key"`
// TLS server name override
TLSServerName string `` /* 152-byte string literal not displayed */
// Optional SSH bastion
Bastion *SSH `yaml:"bastion,omitempty" json:"bastion,omitempty" jsonschema:"description=Optional SSH bastion"`
// 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) ExecStreams ¶ added in v0.11.0
func (c *WinRM) ExecStreams(cmd string, stdin io.ReadCloser, stdout, stderr io.Writer, opts ...exec.Option) (exec.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) IsConnected ¶
IsConnected returns true if the client is connected
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
confirmation
command
Package main demonstrates the confirmation/interactive prompt functionality.
|
Package main demonstrates the confirmation/interactive prompt functionality. |
|
logging
command
Package main demonstrates logging configuration for rig connections.
|
Package main demonstrates logging configuration for rig connections. |
|
os/stock
command
Package main demonstrates OS module registry and configurer interface usage.
|
Package main demonstrates OS module registry and configurer interface usage. |
|
password
command
Package main demonstrates SSH key password provider usage.
|
Package main demonstrates SSH key password provider usage. |
|
upload
command
Package main is a simple file uploader for testing.
|
Package main is a simple file uploader for testing. |
|
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
|
|
|
powershell
Package powershell provides helpers for powershell command generation
|
Package powershell provides helpers for powershell command generation |
|
rigfs
Package rigfs provides fs.FS implementations for remote filesystems.
|
Package rigfs provides fs.FS implementations for remote filesystems. |
|
ssh/agent
Package agent provides an implementation of the SSH agent protocol.
|
Package agent provides an implementation of the SSH agent protocol. |
|
ssh/hostkey
Package hostkey implements a callback for the ssh.ClientConfig.HostKeyCallback
|
Package hostkey implements a callback for the ssh.ClientConfig.HostKeyCallback |