modulepackage
2.0.0-alpha.3
Repository: https://github.com/k0sproject/rig.git
Documentation: pkg.go.dev
# README
Note: The main branch contains a work in progress for rig v2. If you are looking for the stable version, please browse the tags of v0.x releases.
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 components to the multi-os support mechanism without breaking type safety and testability.
Protocols
Currently rig comes with the most common ways to connect to hosts:
- SSH for connecting to hosts that accept SSH connections. With ssh agent and config support and sane familiar defaults. Pageant or openssh agent can be used on Windows.
- OpenSSH for connecting to hosts using the system's own openssh "ssh" executable and utilizing session multiplexing for performance.
- WinRM as an alternative to SSH for windows hosts (SSH works too)
- Localhost for treating the local host as it was a remote host using go's os/exec.
Usage
TBD - for now see godoc, tests and sources.
# Packages
Package byteslice contains functions for working with byte slices.
Package cmd defines types and functions for running commands.
Package homedir provides functions for expanding paths like ~/.ssh.
Package initsystem provides a common interface for interacting with init systems like systemd, openrc, sysvinit, etc.
Package iostream contains various io.Reader and io.Writer implementations.
Package kv is for working with key-value pair files and strings often found in configuration files, environment variables, and other sources.
Package log contains rig's logging related types, constants and functions.
Package os provides remote OS release information detection.
Package packagemanager provides a generic interface for package managers.
Package plumbing defines generic types for the dependency injection mechanisms in rig.
Package powershell provides helpers for powershell command generation.
Package protocol contains the interfaces for the protocol implementations.
Package redact provides redaction of sensitive information from strings or streams.
Package remotefs provides fs.FS implementations for remote filesystems.
Package retry provides context based retry functionality for functions.
Package rigtest provides testing utilities for mocking functionality of the rig package.
Package sh provides tools to build and manipulate shell commands.
Package sshconfig provides a parser for OpenSSH ssh_config files as documented in the [man page].
Package stattime provides time comparison functions that work with times up to the finest common precision.
Package sudo provides support for various methods of running commands with elevated privileges.
No description provided by the author
# Functions
DefaultClientOptions returns a new Options struct with the default options applied.
DefaultPasswordCallback is a default implementation for PasswordCallback.
GetOSRelease returns the remote host's operating system information from the default provider.
GetPackageManager returns a package manager from the default provider.
GetRemoteFS returns a new remote FS instance from the default remote.FS provider.
GetService returns a manager for a single service using an auto-detected service manager implementation from the default providers.
GetServiceManager returns a ServiceManager for the current system from the default init system providers.
GetSudoRunner returns a new runner that uses sudo to execute commands.
NewClient returns a new Connection object with the given options.
NewClientOptions creates a new Options struct with the supplied options applied over the defaults.
NewRunner returns a new cmd.Runner for the connection.
WithConnection is a functional option that sets the client to use for connecting instead of getting it from the ConnectionConfigurer.
WithConnectionConfigurer is a functional option that sets the client configurer to use for connecting.
WithInitSystemProvider is a functional option that sets the init system provider to use for the connection's InitSystemService.
WithLogger is a functional option that sets the logger to use for the connection and its child components.
WithOSReleaseProvider is a functional option that sets the os release provider to use for the connection's OSReleaseService.
WithPackageManagerProvider is a functional option that sets the package manager provider to use for the connection's PackageManagerService.
WithRemoteFSProvider is a functional option that sets the filesystem provider to use for the connection's RemoteFSService.
WithRetry is a functional option that toggles the connection retry feature.
WithRunner is a functional option that sets the runner to use for executing commands.
WithSudoProvider is a functional option that sets the sudo provider to use for the connection's SudoService.
# Variables
ErrAbort is returned when retrying an action will not yield a different outcome.
ErrValidationFailed is returned when a validation check fails.
# Structs
Client is a swiss army knife client that can perform actions and run commands on target hosts running on multiple operating systems and using different protocols for communication.
ClientOptions is a struct that holds the variadic options for the rig package.
ClientWithConfig is a [Client] that is suitable for embedding into a host object that is unmarshalled from YAML configuration.
CompositeConfig is a composite configuration of all the protocols supported out of the box by rig.
Service running on a host.
# Interfaces
ConnectionConfigurer can create connections.
# Type aliases
ClientOption is a functional option type for the Options struct.
InitSystemService is a type alias for initsystem.Service.
OSReleaseService is a type alias for os.Service.
PackageManagerService is a type alias for packagemanager.Service.
RemoteFSService is a type alias for remotefs.Service.
SudoService is a type alias for sudo.Service.