instance

package
v1.30.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 41 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// TLSBASE is the base path for TLS parameters in the instance configuration
	TLSBASE = "tls"

	// CERTIFICATE TODO: Describe its purpose and intended use.
	CERTIFICATE = "certificate"
	// PRIVATEKEY TODO: Describe its purpose and intended use.
	PRIVATEKEY = "privatekey"
	// TLSVERIFY TODO: Describe its purpose and intended use.
	TLSVERIFY = "verify"
	// CABUNDLE TODO: Describe its purpose and intended use.
	CABUNDLE = "ca-bundle"
	// MINVERSION TODO: Describe its purpose and intended use.
	MINVERSION = "minimumversion"
	// TRUSTSTORE TODO: Describe its purpose and intended use.
	TRUSTSTORE = "truststore"
	// TRUSTSTORE_PASSWORD TODO: Describe its purpose and intended use.
	TRUSTSTORE_PASSWORD = "truststore-password"

	// CERTCHAIN TODO: Describe its purpose and intended use.
	CERTCHAIN = "certchain" // deprecated, old parameter
	// USECHAIN TODO: Describe its purpose and intended use.
	USECHAIN = "use-chain" // deprecated, old parameter
)

Variables

This section is empty.

Functions

func Add added in v1.30.0

func Add(h *geneos.Host, ct *geneos.Component, name string, options ...AddOption) (i geneos.Instance, err error)

Add add an instance of component type ct the the optional extra configuration values extras

func AllInstanceNames added in v1.28.0

func AllInstanceNames(h *geneos.Host, ct *geneos.Component) (names []string)

AllInstanceNames returns a slice of all the base names for instance directories for a given component ct on host h. No checking is done to validate that the directory contains a valid instance. AllInstanceNames are qualified with the host name. Regular files are ignored.

func AuditEvent added in v1.30.0

func AuditEvent(i geneos.Instance, result error, event string, args ...any)

AuditEvent writes an audit event for the given instance with the specified event name, the error result of the event ("success" if nil), and optional arguments. It is intended to be called from each instance package as the underlying function for `i.AuditEvent()` and should not be called directly.

func AuditFilepath added in v1.30.0

func AuditFilepath(i geneos.Instance) string

AuditFilepath returns the file path for the audit log of the given instance.

func AuditLogger added in v1.30.0

func AuditLogger(i geneos.Instance) (l *logger.AuditLogger)

AuditLogger returns an audit logger with the instance name, host and type in the context. Optional configuration to customize the audit logger can be provided through the instance's config under the `audit` key. The following sub-keys are supported (with their defaults):

  • `file` - Default is `TYPE-audit.log` relative to the working directory
  • `max-size` MiB - Default is `10`
  • `max-age` days - Default is `30`
  • `max-backups` - Default is `5`
  • `compression` - Default is `gzip`

Defaults are first taken from the global config keys of the same name, if they are defined.

NOTE: This only writes instance audit logs on LOCALHOST, for remote instances it will only write to any global audit destination

func BaseVersion added in v1.6.0

func BaseVersion(i geneos.Instance) (dir string)

BaseVersion returns the absolute path of the base package directory for the instance i.

func BuildCmd

func BuildCmd(i geneos.Instance, noDecode bool, options ...StartOption) (cmd *exec.Cmd, err error)

BuildCmd gathers the path to the binary, arguments and any environment variables for an instance and returns an exec.Cmd, almost ready for execution. Callers will add more details such as working directories, user and group etc.

If noDecode is set then any secure environment variables are not decoded, so can be used for display to a user without revealing secrets.

Any extras arguments are appended without further checks

func ByPort added in v1.26.0

func ByPort(h *geneos.Host, port uint16) (i geneos.Instance, err error)

ByPort returns an instance on host h that is configured to use port. Returns an error if no instance is found or if the configuration cannot be loaded for any instance on the host. Will not check if the port is actually in use by any process.

func CatInstance added in v1.30.0

func CatInstance(i geneos.Instance, args ...any) (resp *responses.General)

CatInstance TODO: Document its behavior, inputs, and effects.

func CheckPaths added in v1.14.2

func CheckPaths(i geneos.Instance, paths ...string) (missing []string)

CheckPaths checks paths for an existing file or directory, returning a list of missing paths. The check performed is a simple stat() for now.

func CheckPort added in v1.30.0

func CheckPort(i geneos.Instance, port uint16) (inUse bool, err error)

CheckPort checks if the given port is in use by the specified instance. Returns true if the port is in use, false otherwise. Returns an error if the instance's PID cannot be determined.

func Clean

func Clean(i geneos.Instance, options ...CleanOption) (err error)

Clean removes all the files and directories listed in the component type of the instance i for removal. First all entries in the CleanList are removed and then, if full is true, the instance is stopped and the entries in FullClean are removed. Any instances stopped are started up, but any that were already stopped will be left stopped.

func CompareVersion added in v1.4.1

func CompareVersion(i geneos.Instance, version string) int

CompareVersion returns -1, 0 or +1 if the version of the instance is less than, equal or greater than version respectively.

func ComponentFilename

func ComponentFilename(i geneos.Instance, extensions ...string) string

ComponentFilename returns the filename for the component used by the instance i with the extensions appended, joined with a ".". If no extensions are given then the current configuration file type is used, e.g. "json" or "yaml".

func ComponentFilepath

func ComponentFilepath(i geneos.Instance, extensions ...string) string

ComponentFilepath returns an absolute path to a file named for the component type of the instance with any extensions joined using ".", e.g. is c is a netprobe instance then

path := instance.ComponentFilepath(c, "xml", "orig")

will return /path/to/netprobe/netprobe.xml.orig

If no extensions are passed then the default us to add an extension of the instance.ConfigType, which defaults to "json", e.g. using the same instance as above:

path := instance.ComponentPath(c)

will return /path/to/netprobe/netprobe.json

func ConfigFileType added in v1.4.1

func ConfigFileType() (conftype string)

ConfigFileType returns the configuration file extension, defaulting to "json" if not set.

func ConfigFileTypes added in v1.4.1

func ConfigFileTypes() []string

ConfigFileTypes contains a list of supported configuration file extensions

func Copy added in v1.7.0

func Copy(ct *geneos.Component, source, destination string, options ...CopyOption) (err error)

Copy copies the instance named source to destination for component type ct. If the move argument is true then the source is deleted after the copy.

Both source and destination can include host labels as well as being only host labels to indicate all instances of type ct on that host. If source is in the form `@host` then destination must also be a host - and different - or the function returns an error, but is it valid to have a specific source and a destination of only `@host` and then the name of the instance is used, as with file system operations on files and directories normally.

If ct is nil that all component types are considered

func CreateAESKeyFile added in v1.13.0

func CreateAESKeyFile(i geneos.Instance) (keyfile config.KeyFile, crc uint32, err error)

CreateAESKeyFile creates a new key file, for secure passwords as per https://docs.itrsgroup.com/docs/geneos/current/Gateway_Reference_Guide/gateway_secure_passwords.htm

func Disable added in v1.5.0

func Disable(i geneos.Instance) (err error)

Disable the instance i. Does not try to stop a running instance and returns an error if it is running.

func DisplayName

func DisplayName(i geneos.Instance) string

DisplayName returns the type, name and non-local host as a string suitable for display.

func Do added in v1.8.0

func Do(action string, h *geneos.Host, ct *geneos.Component, names []string, fn func(i geneos.Instance, values ...any) *responses.General, values ...any) (rs responses.GeneralResponses)

Do calls function fn for each matching instance and gathers the return values into responses for handling by the caller. The functions are executed in goroutines and must be concurrency safe.

The values are passed to each function called and must not be changed by the called function. The called function should validate and cast values for use.

Do calls Instances() to resolve the names given to a list of matching instances on host h (which can be geneos.ALL to look on all hosts) and for type ct, which can be nil to look across all component types.

If the command annotations indicate that auditing is enabled, an audit event will be generated for each instance function called and the success or failure will be recorded in an attribute "result".

func DoInstances added in v1.26.0

func DoInstances(action string, instances []geneos.Instance, fn func(geneos.Instance, ...any) *responses.General, values ...any) (rs responses.GeneralResponses)

DoInstances is a variant of Do that takes a slice of instances instead of performing a look-up up by host, type and name. This is for use by functions that have already got the instances and need to call a function on them concurrently.

If the command annotations indicate that auditing is enabled, an audit event will be generated for each instance function called and the success or failure will be recorded in an attribute "result".

func DoSerial added in v1.27.0

func DoSerial(action string, h *geneos.Host, ct *geneos.Component, names []string, fn func(i geneos.Instance, values ...any) *responses.General, values ...any) (rs responses.GeneralResponses)

DoSerial is a variant of Do that executes the function calls serially. This is for use by functions that are not concurrency safe.

If the command annotations indicate that auditing is enabled, an audit event will be generated for each instance function called and the success or failure will be recorded in an attribute "result".

func Enable added in v1.5.0

func Enable(i geneos.Instance) (err error)

Enable removes the disabled flag, if any,m from instance i.

func EvalAddOptions added in v1.30.0

func EvalAddOptions(options ...any) *addOptions

EvalAddOptions TODO: Document its behavior, inputs, and effects.

func ExecuteTemplate added in v1.7.0

func ExecuteTemplate(i geneos.Instance, outputPath string, name string, defaultTemplate []byte, perms os.FileMode) (changed bool, err error)

ExecuteTemplate loads the template name from the component `templates` directory on the host for the instance i, parses it and executes it, writing the results to outputPath with the given permissions. If a template file is not found on the host, the defaultTemplate is used instead.

The output file is first written to a temporary file with a ".new" suffix, which is then renamed to the final outputPath with the permissions perms.

If an error occurs, any temporary file is removed and the error returned. The existing outputPath file is not modified until the final rename step.

func FileOf added in v1.7.0

func FileOf(i geneos.Instance, name string) (filename string)

FileOf returns the basename of the file identified by the instance parameter name.

If the parameter is unset or empty then an empty path is returned.

func FollowInstance added in v1.30.0

func FollowInstance(i geneos.Instance, args ...any) (resp *responses.General)

FollowInstanceLogs follows the logs for a given instance. It sets up watchers for the instance's logs and handles new log entries as they appear.

func FollowInstanceLogs added in v1.30.0

func FollowInstanceLogs(instances []geneos.Instance, options ...LogWatcherOptions)

FollowInstanceLogs sets up watchers for logs and never returns.

func FollowLog added in v1.30.0

func FollowLog(i geneos.Instance, options ...LogWatcherOptions)

FollowLog sets up a watcher for the logs of a single instance. It is used by both the logs command and the start command when --follow is set. It never returns.

func FollowLogs added in v1.30.0

func FollowLogs(cmdName string, h *geneos.Host, ct *geneos.Component, names []string, options ...LogWatcherOptions)

FollowLogs sets up watchers for logs and never returns. It is used by both the logs command and the start command when --follow is set.

func Get

func Get(ct *geneos.Component, name string) (instance geneos.Instance, err error)

Get return instance `name` of component type ct, and loads the config. It is an error if the config cannot be loaded. The instance is loaded from the host given in the name after any '@' or, if none, localhost is used.

func GetAllPorts added in v1.9.0

func GetAllPorts(h *geneos.Host) (ports map[uint16]struct{})

GetAllPorts gets all used ports in config files on a specific remote and also all listening ports on the same host. Returns a map of port to struct{} for each lookup.

func GetChildPIDs added in v1.27.0

func GetChildPIDs(i geneos.Instance) (children []int, err error)

GetChildPIDs returns a list of child processes for the instance i. If the process is not found then an err of os.ErrProcessDone is returned. A process cache is used to avoid repeated calls to the host to get the process entries, which can be expensive. The cache is updated every 5 seconds, or when the cache is empty.

func GetLivePID added in v1.14.2

func GetLivePID(i geneos.Instance) (pid int, err error)

GetLivePID returns the PID of the process running for the instance i. It resets the process cache to ensure the check is live. If not found then an err of os.ErrProcessDone is returned.

The process is identified by checking the conventions used to start Geneos processes. If a component type defines it's own GetPID() custom check then that is used instead.

func GetPID

func GetPID(i geneos.Instance) (pid int, err error)

GetPID returns the PID of the process running for the instance. If not found then an err of os.ErrProcessDone is returned.

The process is identified by checking the conventions used to start Geneos processes. If a component type defines it's own GetPID() custom check then that is used instead.

func GetWithHost added in v1.14.2

func GetWithHost(h *geneos.Host, ct *geneos.Component, name string) (instance geneos.Instance, err error)

GetWithHost return instance of component name of type ct from host h and loads the config. It is an error if the config cannot be loaded. If name has an embedded "@HOST" it must match h, else that is an error.

func Home added in v1.7.0

func Home(i geneos.Instance) (home string)

Home return the directory for the instance. It checks for the first existing directory from:

  • The one configured for the instance factory and in the configuration parameter "home"
  • In the default component instances directory (component.InstanceDir)
  • If the instance's component type has a parent component then in the legacy instances directory

If no directory is found then a default built using PathTo() is returned

func HomeRel added in v1.27.1

func HomeRel(i geneos.Instance, file string) (result string)

HomeRel returns an absolute path to file prepended with the instance working directory if file is not already an absolute path. If file is empty then an empty result is returned.

func IDString added in v1.14.2

func IDString(i geneos.Instance) string

IDString returns a string suitable as a unique rowname for Toolkit output and other places. For local instance it return `TYPE:NAME` and for remote instances it returns `TYPE:NAME@HOST`

func ImportCertificates added in v1.30.0

func ImportCertificates(i geneos.Instance, certBundlePath, privateKeyPath string, certBundlePassword config.Secret) (trustChainUpdated bool, err error)

ImportCertificates imports the certificate bundle and private key for the instance. It supports both PFX/P12 and PEM formats. It does not write the instance configuration, even when updating parameters, which the caller is responsible for.

func ImportFiles added in v1.6.0

func ImportFiles(i geneos.Instance, files ...string) (err error)

ImportFiles TODO: Document its behavior, inputs, and effects.

func Instances added in v1.14.2

func Instances(h *geneos.Host, ct *geneos.Component, options ...InstanceOption) (instances []geneos.Instance)

Instances returns a slice of all instances on host h of component type ct, where both can be nil in which case all hosts or component types are used respectively. The options allow filtering based on names or parameter matches.

func IsA added in v1.5.0

func IsA(i geneos.Instance, names ...string) bool

IsA returns true if instance i has a type that is component of one of names.

func IsAutoStart added in v1.6.1

func IsAutoStart(i geneos.Instance) bool

IsAutoStart returns true is the instance is set to autostart

func IsDisabled

func IsDisabled(i geneos.Instance) bool

IsDisabled returns true if the instance i is disabled.

func IsProtected

func IsProtected(i geneos.Instance) bool

IsProtected returns true if instance i is marked protected

func IsRunning added in v1.5.0

func IsRunning(i geneos.Instance) bool

IsRunning returns true if the instance is running

func IsTLSCapable added in v1.27.0

func IsTLSCapable(i geneos.Instance) bool

IsTLSCapable checks if TLS is enabled for the instance by checking for the presence of certificate and key paths in the configuration and that the files exist.

func LiveVersion added in v1.7.0

func LiveVersion(i geneos.Instance, pi *ProcessInfo) (base string, version string, actual string, err error)

LiveVersion returns the base package name, the underlying package version and the actual version in use for the instance i. If base is not a link, then base is also returned as the symlink. If there are more than 10 levels of symlink then return symlink set to "loop-detected" and err set to syscall.ELOOP to prevent infinite loops. If the instance is not running or the executable path cannot be determined then actual will be returned as "unknown".

func LogFilePath added in v1.7.0

func LogFilePath(i geneos.Instance) (logfile string)

LogFilePath returns the full path to the log file for the instance.

func LogGroup added in v1.30.0

func LogGroup(i geneos.Instance) slog.Attr

LogGroup returns a slog attribute group containing the instance's component, name, and host.

func Logger added in v1.30.0

func Logger(i geneos.Instance, groups ...string) (l *slog.Logger)

Logger returns a logger with the instance name, host and type in the context. The logger is configured with the "logger" prefix and an indent, and is set to the Info level.

func Match

func Match(h *geneos.Host, ct *geneos.Component, keepHosts bool, mustMatch bool, patterns ...string) (names []string, err error)

Match applies file glob patterns to all instance names (stripped of hostname) on the host h and of the component type ct and returns all matches. Valid patterns are the same as for path.Match.

The returned slice is sorted and duplicates are removed.

Patterns that resolve to empty (e.g. @hostname) are returned unchanged and unchecked against valid names.

Patterns that have no globbing special characters are returned as-is and the caller is expected to validate them.

func Migrate

func Migrate(i geneos.Instance) (resp *responses.General)

Migrate is a helper that checks if the configuration was loaded from a legacy .rc file and if it has it then saves the current configuration (it does not reload the .rc file) in a new format file and renames the .rc file to .rc.orig to allow Revert to work.

Also now check if instance directory path has changed. If so move it.

func NewCertificate added in v1.26.0

func NewCertificate(i geneos.Instance, options ...certs.TemplateOption) (resp *responses.General)

NewCertificate creates a new certificate for an instance.

this also creates a new private key

skip if certificate exists and is valid

func NextFreePort added in v1.14.2

func NextFreePort(h *geneos.Host, ct *geneos.Component) uint16

NextFreePort returns the next available (unallocated and unused) TCP listening port for component ct on host h.

The range of ports available for a component is defined in the configuration for the user and for each component type. A port is available if it is neither allocated to any other instance on the same host (of any component type) and also is not in use by any other process which may not be a Geneos instance.

Each range is a comma separated list of single port number, e.g. "7036", a min-max inclusive range, e.g. "7036-8036" or a 'start-' open ended range, e.g. "7041-". Ranges can also be denoted by double-dot in addition to single dashes '-'.

some limits based on https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

not concurrency safe at this time

func ParseName added in v1.26.0

func ParseName(name string, defaultHost ...*geneos.Host) (host *geneos.Host, ct *geneos.Component, instance string)

ParseName returns the parts of an instance name in the format [TYPE:]NAME[@HOST]. ct defaults to nil and host to localhost unless an optional default host is passed as a var arg.

func PathTo added in v1.26.0

func PathTo(i geneos.Instance, name string) string

PathTo returns the full path to the file identified by the configuration parameter name. If the parameters value is already an absolute path then it is returned as-is, otherwise it is joined with the home directory of the instance and returned. The path is only useful on the host that instance i is on.

If the parameter is unset or empty then an empty path is returned.

func PathsTo added in v1.26.0

func PathsTo(i geneos.Instance, names ...string) (filenames []string)

PathsTo returns the full paths to the files identified by names.

If the instance configuration is valid an empty slice is returned. If a parameter is unset or empty then an empty path is returned.

func PortInUse added in v1.28.0

func PortInUse(h *geneos.Host, port uint16) (inUse bool, err error)

PortInUse checks if the given port is in use on the given host.

func Read added in v1.26.0

func Read(i geneos.Instance) (err error)

Read will load the instance config file if available, otherwise try to load the "legacy" .rc file. The instance struct must be initialised before the call.

The modtime of the underlying config file is recorded in ConfigLoaded and checked before re-loading

support cache?

error check core values - e.g. Name

func ReadAESKeyFile added in v1.13.0

func ReadAESKeyFile(i geneos.Instance, setting ...string) (keyfile config.KeyFile, kv *config.KeyValues, crc uint32, err error)

ReadAESKeyFile locates the path to the keyfile in the instance configuration, using the first setting if passed otherwise defaulting to `keyfile`. If found, return the key values in kv or an error,

func ReadCertificates added in v1.26.0

func ReadCertificates(i geneos.Instance, ext ...string) (certChain []*x509.Certificate, err error)

ReadCertificates reads the instance certificate and returns a slice of certificates.

For older Geneos versions that do not support full chains, this will check for an also load a chain file. The chain file path is taken from the `certchain` parameter if set and no optional extensions are added.

func ReadCertificatesWithKey added in v1.26.0

func ReadCertificatesWithKey(i geneos.Instance, ext ...string) (certChain []*x509.Certificate, key certs.PrivateKey, err error)

ReadCertificatesWithKey TODO: Document its behavior, inputs, and effects.

func ReadGatewaySetup added in v1.30.0

func ReadGatewaySetup(i geneos.Instance) (*geneosxml.Gateway, error)

ReadGatewaySetup reads the gateway setup XML file for the given instance and returns a parsed Gateway structure (from pkg/geneos).

func ReadKVConfig added in v1.13.0

func ReadKVConfig(r host.Host, p string) (kvs map[string]string, err error)

ReadKVConfig reads a file containing key=value lines, returning a map of key to value. We need this to preserve the case of keys, which config forces to lowercase, when writing this file back out via WriteKVConfig().

func ReadLeafCertificate added in v1.26.0

func ReadLeafCertificate(i geneos.Instance, ext ...string) (cert *x509.Certificate, err error)

ReadLeafCertificate reads the instance certificate and returns the leaf certificate.

func ReadPrivateKey added in v1.26.0

func ReadPrivateKey(i geneos.Instance, ext ...string) (key certs.PrivateKey, err error)

ReadPrivateKey reads the instance RSA private key

func ReadRCConfig added in v1.8.0

func ReadRCConfig(r host.Host, cf *config.Config, p string, prefix string, aliases map[string]string) (err error)

ReadRCConfig reads an old-style, legacy Geneos "ctl" layout configuration file and sets values in cf corresponding to updated equivalents.

All empty lines and those beginning with "#" comments are ignored.

The rest of the lines are treated as `name=value` pairs and are processed as follows:

  • If `name` is either `binsuffix` (case-insensitive) or `prefix`+`name` then it saved as a config item. This is looked up in the `aliases` map and if there is a match then this new name is used.
  • All other `name=value` entries are saved as environment variables in the configuration for the instance under the `Env` key.

func RefactorConfig added in v1.26.0

func RefactorConfig(h *geneos.Host, ct *geneos.Component, cf *config.Config, options ...ConfigOption) (err error)

RefactorConfig updates the instance config cf for the new instance name and directory, based on the old home value in the config file and the new home value based on the destination instance directory.

Unless the option config.KeepPort() is passed, ports are updated to avoid clashes with existing instances on the destination host. Paths are updated based on the old home value in the config file and the new home value based on the destination instance directory. Ports are updated to avoid clashes with existing instances on the destination host. Legacy parameters are removed.

Any `user` setting is removed from the config, as this is no longer supported.

All paths with a instance directory prefix are updated to use `${config:home}` instead.

`libpaths` is updated to replace any paths with the old install prefix to use `${config:install}` instead, and any paths with the old version suffix to use `${config:version}` instead.

func RemovePaths

func RemovePaths(i geneos.Instance, list ...string) (err error)

RemovePaths removes all files and directories in list

func ReservedName

func ReservedName(name string) (ok bool)

ReservedName returns true if name is a reserved word. Reserved names are checked against all the values registered by components at start-up.

func RollAESKeyFile added in v1.13.0

func RollAESKeyFile(i geneos.Instance, nkv *config.KeyValues, backup string) (keyfile config.KeyFile, crc uint32, err error)

RollAESKeyFile moves any existing instance key file to a "previous" filename unless it is in a shared keyfiles directory, in which case it sets `prevkeyfile` to this path and saves the new key file values nkv to the instance directory.

Otherwise, the current keyfile is renamed to a file where the backup string is appended to the base name before the extension and the key file values nkv are written to a new file and the instance settings updated.

TODO: on update, check for encoded values in instance config and re-encode with new key if necessary, or at least warn about it, writing config back if changed which triggers rebuild and reload

func RollFiles added in v1.26.0

func RollFiles(i geneos.Instance, newSuffix, oldSuffix string, params ...string) error

RollFiles atomically rolls files indicated by params with the given suffixes for the instance. The newSuffix files are moved to the active files, and existing active files are backed up with the oldSuffix. If an error occurs, any files that were successfully rolled are unrolled back to their original state.

Each file is rolled individually and atomically using a lock directory to prevent concurrent modifications. If any file fails to roll, the function attempts to unroll (revert) all previously rolled files in this operation by calling itself with swapped suffixes and the list of completed files. A lock directory is created for each file, but not for the whole operation.

func SecureArgs added in v1.26.0

func SecureArgs(i geneos.Instance) (args []string, env []string, fileChecks []string, err error)

SecureArgs returns command line arguments, environment variables, and any files that need to be checked for secure connections based on the TLS configuration of the instance.

If the instance has not been migrated to the new TLS parameters then it calls SetSecureArgs() instead, but with the addition of file checks for any args that are not prefixed with a dash (`-`).

func SetDefaults

func SetDefaults(i geneos.Instance, name string) (err error)

SetDefaults is a common function called by component factory functions to iterate over the component specific instance struct and set the defaults as defined in the 'defaults' struct tags.

func Shared added in v1.7.0

func Shared(i geneos.Instance, subs ...any) string

Shared returns the full path to a directory or file in the instances component type shared directory joined to any parts subs - the last element can be a filename. If the instance is not loaded then "." is returned for the current directory.

func ShortName added in v1.14.2

func ShortName(i geneos.Instance) string

ShortName returns the instance name with the "@HOST" suffix as a string

func Signal

func Signal(i geneos.Instance, signal syscall.Signal) (err error)

Signal sends the signal to the instance

func SnapshotDataviews added in v1.30.0

func SnapshotDataviews(i geneos.Instance, paths []string, options ...SnapshotOptions) (dataviews []*commands.Dataview, err error)

SnapshotDataviews TODO: Document its behavior, inputs, and effects.

func Start

func Start(i geneos.Instance, options ...any) error

Start runs the instance. Options must be StartOption types but the signature will accept 'any' to avoid import loops from the geneos package.

func Stop

func Stop(i geneos.Instance, options ...any) (err error)

Stop an instance. Options must be StopOption types but the signature will accept 'any' to avoid import loops from the geneos package.

TODO: check for managed CAs and wait for those too.

func TailInstance added in v1.30.0

func TailInstance(i geneos.Instance, args ...any) (resp *responses.General)

TailInstance TODO: Document its behavior, inputs, and effects.

func ValidName added in v1.7.0

func ValidName(name string) bool

ValidName TODO: Document its behavior, inputs, and effects.

func Version

func Version(i geneos.Instance) (base string, version string, err error)

Version returns the base package name, the underlying package version and the actual version in use for the instance i. If base is not a link, then base is also returned as the symlink. If there are more than 10 levels of symlink then return symlink set to "loop-detected" and err set to syscall.ELOOP to prevent infinite loops. If the instance is not running or the executable path cannot be determined then actual will be returned as "unknown".

func Write added in v1.26.0

func Write(i geneos.Instance, options ...ConfigOption) (resp *responses.General)

Write will write and rebuild the instance, returning a response with any errors and a list of completed steps. On success it also triggers a reload of the instance to pick up any changes to the config that are made by the rebuild.

Options to not rebuild or reload the instance can be passed as instance.NoRebuild() and instance.NoReload() respectively.

func WriteAESKeyFile added in v1.13.0

func WriteAESKeyFile(i geneos.Instance, kv *config.KeyValues) (keyfile config.KeyFile, crc uint32, err error)

WriteAESKeyFile writes key values to a an instance key file, for secure passwords as per:

https://docs.itrsgroup.com/docs/geneos/current/Gateway_Reference_Guide/gateway_secure_passwords.htm

If the instance config is updated then it is also saved.

func WriteCertificateAndKey added in v1.26.0

func WriteCertificateAndKey(i geneos.Instance, key certs.PrivateKey, certChain ...*x509.Certificate) (err error)

WriteCertificateAndKey writes the certificates and, if given, the private key to the instance i using standard file names and updates the instance configuration. It will set the instance `tls.certificate` and, when given a key, the `tls.privatekey` parameters and clear any values in the old style `certificate` and `privatekey` parameters. It does not write the instance configuration, expecting the caller to do so after any other updates.

func WriteCertificateBundle added in v1.30.0

func WriteCertificateBundle(i geneos.Instance, bundle *certs.CertificateBundle) (trustChainUpdated bool, err error)

WriteCertificateBundle writes the certificate, key and trust chain to the instance. It returns a boolean indicating if the trust chain was updated and any error encountered. If the trust chain is updated, the instance configuration `tls.ca-bundle` parameter is also updated.

func WriteKVConfig added in v1.13.0

func WriteKVConfig(r host.Host, p string, kvs map[string]string) (err error)

WriteKVConfig writes out the map kvs to the file on host r at path p.

TODO: write to tmp file and rotate to protect

Types

type AddOption added in v1.30.0

type AddOption func(*addOptions)

AddOption TODO: Describe its purpose and intended use.

func Base added in v1.30.0

func Base(base string) AddOption

Base TODO: Document its behavior, inputs, and effects.

func Insecure added in v1.30.0

func Insecure(insecure bool) AddOption

Insecure TODO: Document its behavior, inputs, and effects.

func KeyfileCRC added in v1.30.0

func KeyfileCRC(crc string) AddOption

KeyfileCRC TODO: Document its behavior, inputs, and effects.

func LogsAfterAdd added in v1.30.0

func LogsAfterAdd(logs bool) AddOption

LogsAfterAdd TODO: Document its behavior, inputs, and effects.

func StartAfterAdd added in v1.30.0

func StartAfterAdd(start bool) AddOption

StartAfterAdd TODO: Document its behavior, inputs, and effects.

func WithCertBundle added in v1.30.0

func WithCertBundle(bundle string) AddOption

WithCertBundle TODO: Document its behavior, inputs, and effects.

func WithCertBundlePassword added in v1.30.0

func WithCertBundlePassword(password config.Secret) AddOption

WithCertBundlePassword TODO: Document its behavior, inputs, and effects.

func WithFlags added in v1.30.0

func WithFlags(flags *pflag.FlagSet) AddOption

WithFlags TODO: Document its behavior, inputs, and effects.

func WithImports added in v1.30.0

func WithImports(imports []string) AddOption

WithImports TODO: Document its behavior, inputs, and effects.

func WithKeyfile added in v1.30.0

func WithKeyfile(keyfile string) AddOption

WithKeyfile TODO: Document its behavior, inputs, and effects.

func WithPort added in v1.30.0

func WithPort(port uint16) AddOption

WithPort TODO: Document its behavior, inputs, and effects.

func WithProfiles added in v1.30.0

func WithProfiles(profiles *config.Config) AddOption

WithProfiles TODO: Document its behavior, inputs, and effects.

func WithTemplate added in v1.30.0

func WithTemplate(template string) AddOption

WithTemplate TODO: Document its behavior, inputs, and effects.

func WithValues added in v1.30.0

func WithValues(values values.Values) AddOption

WithValues TODO: Document its behavior, inputs, and effects.

type CleanOption added in v1.27.0

type CleanOption func(*cleanOptions)

CleanOption TODO: Describe its purpose and intended use.

func ForceClean added in v1.27.0

func ForceClean(force bool) CleanOption

ForceClean TODO: Document its behavior, inputs, and effects.

func FullClean added in v1.27.0

func FullClean(full bool) CleanOption

FullClean TODO: Document its behavior, inputs, and effects.

type ConfigOption added in v1.26.0

type ConfigOption func(*configOptions)

ConfigOption TODO: Describe its purpose and intended use.

func KeepPort added in v1.26.0

func KeepPort() ConfigOption

KeepPort controls whether to keep the same port number in the new config or to update it to avoid clashes with existing instances on the destination host. By default ports are updated to avoid clashes. This option is used when copying an instance within the same host, where there will be no clashes, and we want to keep the same port numbers.

func NewDir added in v1.26.0

func NewDir(dir string) ConfigOption

NewDir returns a ConfigOption that sets the new instance directory in the config options, which is used by RefactorConfig to set the new home in the config file. If not set, RefactorConfig will use the default directory for the instance type on the destination host. This option is used when copying an instance within the same host, where we want to keep the same directory and just update the name, and therefore the default would not be correct. It can also be used to specify a custom directory for the new instance.

func NewName added in v1.26.0

func NewName(name string) ConfigOption

NewName returns a ConfigOption that sets the new instance name in the config options, which is used by RefactorConfig to set the new name in the config file. If not set, RefactorConfig will not update the name of the instance.

func NoRebuild added in v1.27.0

func NoRebuild() ConfigOption

NoRebuild controls whether to skip the rebuild step after writing the configuration in instance.Commit()

func NoReload added in v1.27.0

func NoReload() ConfigOption

NoReload controls whether to skip the reload step after writing the configuration in instance.Commit() and after a successful rebuild if supported. NoRebuild implies NoReload.

type CopyOption added in v1.27.0

type CopyOption func(*copyOptions)

CopyOption TODO: Describe its purpose and intended use.

func Move added in v1.11.0

func Move() CopyOption

Move tells Copy to remove the source instance(s) after the copy.

func Params added in v1.11.0

func Params(p ...string) CopyOption

Params add key=value parameters to the copied/moved destination, overriding the values of the source. Currently only supports plain paramaters, not structured ones like environments.

type Instance

type Instance struct {
	Conf         *config.Config      `json:"-"`
	InstanceHost *geneos.Host        `json:"-"`
	Component    *geneos.Component   `json:"-"`
	ConfigLoaded time.Time           `json:"-"`
	Logger       *slog.Logger        `json:"-"`
	AuditLogger  *logger.AuditLogger `json:"-"`
}

The Instance type is the common data shared by all instances

type InstanceOption added in v1.27.0

type InstanceOption func(*instanceOptions)

InstanceOption TODO: Describe its purpose and intended use.

func MatchNames added in v1.27.0

func MatchNames(names ...string) InstanceOption

MatchNames returns an InstanceOption that filters instances based on matching names. The names should be in the form [TYPE:]NAME[@HOST] and are ORed together. If a name is not in that form it is ignored.

func MatchParameters added in v1.27.0

func MatchParameters(parameters ...string) InstanceOption

MatchParameters returns an InstanceOption that filters instances based on matching config parameters. The parameters should be in the form "key=value" and are ANDed together. If a parameter is not in that form it is ignored.

func MatchParentPackage added in v1.27.1

func MatchParentPackage() InstanceOption

MatchParentPackage returns an InstanceOption that filters instances to those whose component could be a parent type for another component *and* the package type matches. For example, a `netprobe` may use a `pkgtype` of `minimal`, so when looking for `minimal` instances, also include `netprobe` instances that have a `pkgtype` of `minimal`.

type LogWatcherOptions added in v1.30.0

type LogWatcherOptions func(*logWatcherOptions)

LogWatcherOptions TODO: Describe its purpose and intended use.

func IgnoreMatches added in v1.30.0

func IgnoreMatches(ignore string) LogWatcherOptions

IgnoreMatches TODO: Document its behavior, inputs, and effects.

func Matching added in v1.30.0

func Matching(match string) LogWatcherOptions

Matching TODO: Document its behavior, inputs, and effects.

func MaxLines added in v1.30.0

func MaxLines(lines int) LogWatcherOptions

MaxLines TODO: Document its behavior, inputs, and effects.

func ShowAuditLogs added in v1.30.0

func ShowAuditLogs(audit bool) LogWatcherOptions

ShowAuditLogs TODO: Document its behavior, inputs, and effects.

func WithCALog added in v1.30.0

func WithCALog(caLog bool) LogWatcherOptions

WithCALog TODO: Document its behavior, inputs, and effects.

func WithNoHeaders added in v1.30.0

func WithNoHeaders(noHeaders bool) LogWatcherOptions

WithNoHeaders TODO: Document its behavior, inputs, and effects.

func WithStderr added in v1.30.0

func WithStderr(stderr bool) LogWatcherOptions

WithStderr TODO: Document its behavior, inputs, and effects.

func WithoutNormal added in v1.30.0

func WithoutNormal(noNormal bool) LogWatcherOptions

WithoutNormal TODO: Document its behavior, inputs, and effects.

type ProcessInfo added in v1.27.1

type ProcessInfo struct {
	PID             int           `proc_pid_stat:"0" json:"-"`
	PPID            int           `proc_pid_stat:"3"`
	Utime           time.Duration `proc_pid_stat:"13"`
	Stime           time.Duration `proc_pid_stat:"14"`
	CUtime          time.Duration `proc_pid_stat:"15"`
	CStime          time.Duration `proc_pid_stat:"16"`
	UIDs            []string      `proc_pid_status:"Uid" json:"-"`
	GIDs            []string      `proc_pid_status:"Gid" json:"-"`
	State           string        `proc_pid_status:"State"`
	Threads         int64         `proc_pid_status:"Threads"`
	VmRSS           int64         `proc_pid_status:"VmRSS"`
	VmHWM           int64         `proc_pid_status:"VmHWM"`
	RssAnon         int64         `proc_pid_status:"RssAnon"`
	RssFile         int64         `proc_pid_status:"RssFile"`
	RssShmem        int64         `proc_pid_status:"RssShmem"`
	CpusAllowedList string        `proc_pid_status:"Cpus_allowed_list"`

	// special fields that are not from /proc/PID/stat or
	// /proc/PID/status but are calculated from other information, such
	// as the number of open files and sockets
	//
	// filling in these fields for all processes can be expensive, so
	// they are marked with `cache:"lazy"` to indicate that they should
	// be filled on demand when requested, rather than when the process
	// information is first retrieved.
	OpenFiles      []process.ProcessFDs `cache:"lazy" json:"-"` // calculated from /proc/PID/fd
	OpenSockets    int64                `cache:"lazy" json:"-"` // calculated from /proc/PID/fd and /proc/PID/net/tcp and /proc/PID/net/udp
	ListeningPorts string               `cache:"lazy" json:"-"` // calculated from /proc/PID/net/tcp and /proc/PID/net/udp

	Cwd       string    `json:"-"` // calculated from /proc/PID/cwd
	Exe       string    `json:"-"`
	Cmdline   []string  `json:"-"`
	StartTime time.Time `json:"-"`
	Children  []int     `json:"-"`
	UID       int       `json:"-"` // real UID
	EUID      int       `json:"-"` // effective UID
	GID       int       `json:"-"` // real GID
	EGID      int       `json:"-"` // effective GID
	Username  string    `json:"-"`
	Groupname string    `json:"-"`
}

ProcessInfo is an example of a structure to pass to instance.ProcessStatus, using a field number for `stat` and a line prefix for `status` tags. OpenFiles and OpenSockets fields are counts of their respective names. Some fields may be expensive to fill for all processes, so they are marked with `cache:"lazy"` to indicate that they should be filled on demand when requested, rather than when the process information is first retrieved.

func GetProcessInfo added in v1.27.0

func GetProcessInfo(i geneos.Instance) (pi *ProcessInfo, err error)

GetProcessInfo returns process information for the instance i. If the process is not found then an err of os.ErrProcessDone is returned. A process cache is used to avoid repeated calls to the host to get the process entries, which can be expensive. The cache is updated every 5 seconds, or when the cache is empty.

type SnapshotOptions added in v1.30.0

type SnapshotOptions func(*snapshotOptions)

SnapshotOptions TODO: Describe its purpose and intended use.

func SnapshotMaxItems added in v1.30.0

func SnapshotMaxItems(maxitems int) SnapshotOptions

SnapshotMaxItems TODO: Document its behavior, inputs, and effects.

func SnapshotPassword added in v1.30.0

func SnapshotPassword(password config.Secret) SnapshotOptions

SnapshotPassword TODO: Document its behavior, inputs, and effects.

func SnapshotScopes added in v1.30.0

func SnapshotScopes(scopes commands.Scope) SnapshotOptions

SnapshotScopes TODO: Document its behavior, inputs, and effects.

func SnapshotUsername added in v1.30.0

func SnapshotUsername(username string) SnapshotOptions

SnapshotUsername TODO: Document its behavior, inputs, and effects.

func SnapshotXPathOnly added in v1.30.0

func SnapshotXPathOnly(xpathOnly bool) SnapshotOptions

SnapshotXPathOnly TODO: Document its behavior, inputs, and effects.

type StartOption added in v1.27.0

type StartOption func(*startOptions)

StartOption TODO: Describe its purpose and intended use.

func SkipFileCheck added in v1.14.2

func SkipFileCheck() StartOption

SkipFileCheck TODO: Document its behavior, inputs, and effects.

func StartingEnvs added in v1.8.0

func StartingEnvs(envs []string) StartOption

StartingEnvs takes a list of extra environment variables (as name=value pairs) to append to the standard list for the instance.

func StartingExtras added in v1.8.0

func StartingExtras(extras string) StartOption

StartingExtras sets extra command line parameters by splitting extras on spaces. Quotes, escaping and other shell-like separators are ignored.

func WithoutAudit added in v1.29.0

func WithoutAudit() StartOption

WithoutAudit suppresses the operational audit log entry for this start.

type StopOption added in v1.29.0

type StopOption func(*stopOptions)

StopOption TODO: Describe its purpose and intended use.

func WithStopForce added in v1.30.0

func WithStopForce(force bool) StopOption

WithStopForce TODO: Document its behavior, inputs, and effects.

func WithStopKill added in v1.30.0

func WithStopKill(kill bool) StopOption

WithStopKill TODO: Document its behavior, inputs, and effects.

func WithoutStopAudit added in v1.29.0

func WithoutStopAudit() StopOption

WithoutStopAudit suppresses the operational audit log entry for this stop.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL