instance

package
v1.7.0-beta3 Latest Latest
Warning

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

 Go to latest Published: Jul 10, 2023 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const AttributesOptionsText = "An attribute in the format NAME=VALUE\n(Repeat as required, san only)"
View Source 
const EnvsOptionsText = "An environment variable for instance start-up\n(Repeat as required)"
View Source 
const GatewaysOptionstext = "A gateway connection in the format HOSTNAME:PORT\n(Repeat as required, san and floating only)"
View Source 
const IncludeValuesOptionsText = "An include file in the format `PRIORITY:[PATH|URL]`\n(Repeat as required, gateway only)"

IncludeValuesOptionsText is the default help text for command to use for options setting include files

View Source 
const TypesOptionsText = "A type NAME\n(Repeat as required, san only)"
View Source 
const VarsOptionsText = "A variable in the format [TYPE:]NAME=VALUE\n(Repeat as required, san only)"

Variables

This section is empty.

Functions

func Abs 

func Abs(c geneos.Instance, file string) (result string)

Abs returns an absolute path to file prepended with the instance working directory if file is not already an absolute path.

func AllListeningPorts added in v1.6.3 

func AllListeningPorts(h *geneos.Host, min, max int) (ports []int)

AllListeningPorts returns a sorted list of all listening TCP ports on host h between min and max (inclusive). If min or max is -1 then no limit is imposed.

func AtLeastVersion added in v1.5.0 

func AtLeastVersion(c geneos.Instance, version string) bool

AtLeastVersion returns true if the installed version for instance c is version or greater. If the version of the instance is somehow unparseable then this returns false.

func BaseVersion added in v1.6.0 

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

BaseVersion returns the absolute path of the base package directory for the instance c. No longer references the instance "install" parameter.

func BuildCmd 

func BuildCmd(c geneos.Instance, noDecode bool) (cmd *exec.Cmd, env []string, home string)

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

func Clean 

func Clean(c geneos.Instance, full bool) (err error)

Clean removes all the files and directories listed in the component type of the instance c 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 ComponentFilename 

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

ComponentFilename returns the filename for the component used by the instance c 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(c 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 current primary configuration file extension

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, move bool) (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 CreateCert 

func CreateCert(c geneos.Instance) (err error)

CreateCert creates a new certificate for an instance

this also creates a new private key

skip if certificate exists and is valid

func CreateConfigFromTemplate 

func CreateConfigFromTemplate(c geneos.Instance, p string, name string, defaultTemplate []byte) (err error)

CreateConfigFromTemplate loads templates from TYPE/templates/[tmpl]* and parse them, using the instance data write it out to a single file. If tmpl is empty, load all files

func DeleteSettingFromMap added in v1.4.1 

func DeleteSettingFromMap(c geneos.Instance, from map[string]interface{}, key string)

DeleteSettingFromMap removes key from the map from and if it is registered as an alias it also removes the key that alias refers to.

func Disable added in v1.5.0 

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

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

func DisplayName 

func DisplayName(c geneos.Instance) string

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

func Enable added in v1.5.0 

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

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

func Filename 

func Filename(c geneos.Instance, name string) (filename string)

Filename returns the basename of the file identified by the configuration parameter name.

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

func Filepaths added in v1.6.3 

func Filepaths(c geneos.Instance, names ...string) (filenames []string)

Filepaths returns the full paths to the files identified by the list of parameters in 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 Files 

func Files(c geneos.Instance) (openfiles map[int]OpenFiles)

Files returns a map of file descriptor (int) to file details (InstanceProcFiles) for all open, real, files for the process running as the instance. All paths that are not absolute paths are ignored. An empty map is returned if the process cannot be found.

func ForAll 

func ForAll(ct *geneos.Component, hostname string, fn func(geneos.Instance, []string) error, args []string, params []string) (err error)

ForAll calls the supplied function for each matching instance. It sends any returned error on STDOUT and the only error returned is os.ErrNotExist if there are no matching instances.

func ForAllWithResults added in v1.4.1 

func ForAllWithResults(
	ct *geneos.Component,
	hostname string,
	fn func(geneos.Instance, []string) (interface{}, error),
	args []string,
	params []string,
) (results []interface{}, err error)

ForAllWithResults calls the function fn for each matching instance and gather the return values into a slice of interfaces for handling upstream. The slice is sorted by host, type and name. Errors are printed on STDOUT for each call and the only error returned ErrNotExist if there are no matches.

func Get 

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

Get return an instance of component ct, and loads the config. It is an error if the config cannot be loaded.

func GetAll 

func GetAll(h *geneos.Host, ct *geneos.Component) (confs []geneos.Instance)

GetAll returns a slice of instances for a given component type on remote h

func GetPID 

func GetPID(c 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.

func GetPIDInfo 

func GetPIDInfo(c geneos.Instance) (pid int, uid int, gid int, mtime time.Time, err error)

GetPIDInfo returns the PID of the process for the instance c along with the owner uid and gid and the start time.

func GetPorts 

func GetPorts(r *geneos.Host) (ports map[uint16]*geneos.Component)

GetPorts gets all used ports in config files on a specific remote this will not work for ports assigned in component config files, such as gateway setup or netprobe collection agent

returns a map

func HomeDir added in v1.6.2 

func HomeDir(c geneos.Instance) (home string)

HomeDir 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 ImportCommons 

func ImportCommons(r *geneos.Host, ct *geneos.Component, common string, params []string) (filename string, err error)

ImportCommons copies a file to an instance common directory.

func ImportFile 

func ImportFile(h *geneos.Host, dir string, source string) (filename string, err error)

ImportFile copies the file from source to the directory dir on host h. The destination filename can be given as a "NAME=" prefix in source. If no filename is given then it is derived from the source.

source can be a path to a file or a http/https URL.

func ImportKeyFile added in v1.6.0 

func ImportKeyFile(h *geneos.Host, ct *geneos.Component, keyfile config.KeyFile) (crc uint32, err error)

ImportKeyFile copies the keyfile to the host h and component type ct shared directory. Host can be geneos.ALL and ct can be nil, in which case they are treated as wildcards.

func ImportKeyValues added in v1.6.0 

func ImportKeyValues(h *geneos.Host, ct *geneos.Component, kv *config.KeyValues) (crc uint32, err error)

ImportKeyValues saves a keyfile with values kv to the host h and component type ct shared directory. Host can be geneos.ALL and ct can be nil, in which case they are treated as wildcards.

func IsA added in v1.5.0 

func IsA(c geneos.Instance, name string) bool

IsA returns true if instance c has a type that is component of the type name. If name is not a known component type then false is returned without checking the instance.

func IsAutoStart added in v1.6.1 

func IsAutoStart(c geneos.Instance) bool

IsAutoStart returns true is the instance is set to autostart

func IsDisabled 

func IsDisabled(c geneos.Instance) bool

IsDisabled returns true if the instance c is disabled.

func IsProtected 

func IsProtected(c geneos.Instance) bool

IsProtected returns true if instance c is marked protected

func IsRunning added in v1.5.0 

func IsRunning(c geneos.Instance) bool

IsRunning returns true if the instance is running

func KeyFileNormalise added in v1.6.0 

func KeyFileNormalise(in string) (out string)

KeyFileNormalise returns the input in for format "DIR/HEX.aes" where HEX is an 8 hexadecimal digit string in uppercase and DIR is any leading path before the file name. If the input is not either an 8 digit hex string (in any case) with or without the extension ".aes" (in any case) then the input is returned unchanged.

func ListeningPorts added in v1.6.3 

func ListeningPorts(c geneos.Instance) (ports []int)

ListeningPorts returns all TCP ports currently open for the process running as the instance. An empty slice is returned if the process cannot be found. The instance may be on a remote host.

func ListeningPortsStrings added in v1.7.0 

func ListeningPortsStrings(c geneos.Instance) (ports []string)

ListeningPorts returns all TCP ports currently open for the process running as the instance. An empty slice is returned if the process cannot be found. The instance may be on a remote host.

func LiveVersion added in v1.7.0 

func LiveVersion(c geneos.Instance, pid int) (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 c. 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 LoadConfig 

func LoadConfig(c geneos.Instance) (err error)

LoadConfig will load the JSON config file if available, otherwise try to load the "legacy" .rc file

support cache?

error check core values - e.g. Name

func LogFilePath added in v1.7.0 

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

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

func Match 

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

Match looks for exactly one matching instance across types and hosts returns Invalid Args if zero of more than 1 match

func MatchAll 

func MatchAll(h *geneos.Host, ct *geneos.Component, name string) (c []geneos.Instance)

MatchAll constructs and returns a slice of instances that have a matching name

func MatchKeyValue 

func MatchKeyValue(h *geneos.Host, ct *geneos.Component, key, value string) (confs []geneos.Instance)

MatchKeyValue returns a slice of instances where the instance configuration key matches the value given.

func Migrate 

func Migrate(c geneos.Instance) (err error)

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 convert 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 NameParts added in v1.7.0 

func NameParts(in string, defaultHost *geneos.Host) (ct *geneos.Component, name string, h *geneos.Host)

NameParts returns the parts of an instance name given an instance name in the format [TYPE:]NAME[@HOST] and a default host, return a *geneos.Component for the TYPE if given, a string for the NAME and a *geneos.Host - the latter being either from the name or the default provided

func Names added in v1.7.0 

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

Names returns a slice of all instance names for a given component ct on host h. No checking is done to validate that the directory is a populated instance.

To support the move to parent types we do a little more, looking for legacy locations in here

func NextPort 

func NextPort(r *geneos.Host, ct *geneos.Component) uint16

given a range, find the first unused port

range is comma or two-dot separated list of single number, e.g. "7036" min-max inclusive range, e.g. "7036-8036" start- open ended range, e.g. "7041-"

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

not concurrency safe at this time

func PathOf added in v1.7.0 

func PathOf(c geneos.Instance, name string) string

PathOf 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 c is on.

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

func ReadCert 

func ReadCert(c geneos.Instance) (cert *x509.Certificate, valid bool, err error)

ReadCert reads the instance certificate

func ReadKey 

func ReadKey(c geneos.Instance) (key *memguard.Enclave, err error)

ReadKey reads the instance RSA private key

func ReadRootCert 

func ReadRootCert() (cert *x509.Certificate, err error)

ReadRootCert reads the root certificate from the user's app config directory. It "promotes" old cert and key files from the previous tls directory if files do not already exist in the user app config directory.

func ReadSigningCert 

func ReadSigningCert() (cert *x509.Certificate, err error)

ReadSigningCert reads the signing certificate from the user's app config directory. It "promotes" old cert and key files from the previous tls directory if files do not already exist in the user app config directory.

func RemovePaths 

func RemovePaths(c geneos.Instance, paths string) (err error)

RemovePaths removes all files and directories in paths, each file or directory is separated by ListSeperator

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 SaveConfig added in v1.7.0 

func SaveConfig(c geneos.Instance) (err error)

SaveConfig writes the instance configuration to the standard file for that instance

func SaveKeyFileShared added in v1.6.0 

func SaveKeyFileShared(h *geneos.Host, ct *geneos.Component, a *config.KeyValues) (err error)

SaveKeyFileShared saves a key file with values a to the shared keyfile directory for component ct on host h

func SetDefaults 

func SetDefaults(c 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 SetInstanceValues added in v1.7.0 

func SetInstanceValues(c geneos.Instance, values SetConfigValues, keyfile config.KeyFile) (err error)

SetInstanceValues applies the settings in values to instance c by iterating through the fields and calling the appropriate helper function. SecureEnvs overwrite any set by Envs earlier.

func SetSecureArgs 

func SetSecureArgs(c geneos.Instance) (args []string)

SetSecureArgs returns a slice of arguments to enable secure connections if the correct configuration values are set. These command line options are common to all core Geneos components except the gateway, which is special-cased

func SharedPath added in v1.5.0 

func SharedPath(c geneos.Instance, subs ...interface{}) string

SharedPath returns the full path 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 Signal 

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

Signal sends the signal to the instance

func Start 

func Start(c geneos.Instance) (err error)

Start runs the instance.

func Stop 

func Stop(c geneos.Instance, force, kill bool) (err error)

Stop an instance

func UnsetInstanceValues added in v1.7.0 

func UnsetInstanceValues(c geneos.Instance, x UnsetConfigValues) (changed bool, err error)

XXX abstract this for a general case

func UseKeyFile added in v1.6.0 

func UseKeyFile(h *geneos.Host, ct *geneos.Component, keyfile config.KeyFile, keycrc string) (crc string, err error)

UseKeyFile sets the keyfile for component ct from either the given (local) keyfile or the CRC for an existing file.

func ValidName added in v1.7.0 

func ValidName(name string) (ok bool)

ValidName returns true if name is considered a valid instance name. It is not checked against the list of reserved names.

XXX used to consume instance names until parameters are then passed down

func Version 

func Version(c 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 c. 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 WriteCert 

func WriteCert(c geneos.Instance, cert *x509.Certificate) (err error)

WriteCert writes the certificate for the instance c

func WriteConfigValues 

func WriteConfigValues(c geneos.Instance, values map[string]interface{}) (err error)

WriteConfigValues writes the given values to the configuration file for instance c. It does not merge values with the existing configuration values.

func WriteKey 

func WriteKey(c geneos.Instance, key *memguard.Enclave) (err error)

WriteKey writes the key for the instance c and updates the config if required

Types

type Gateways added in v1.7.0 

type Gateways map[string]string

gateway - name:port

func (*Gateways) Set added in v1.7.0 

func (i *Gateways) Set(value string) error

func (*Gateways) String added in v1.7.0 

func (i *Gateways) String() string

func (*Gateways) Type added in v1.7.0 

func (i *Gateways) Type() string

type ImportFiles added in v1.6.0 

type ImportFiles []string

ImportFiles fulfills the Var interface for pflag

func (*ImportFiles) Set added in v1.6.0 

func (i *ImportFiles) Set(value string) error

func (*ImportFiles) String added in v1.6.0 

func (i *ImportFiles) String() string

func (*ImportFiles) Type added in v1.6.0 

func (i *ImportFiles) Type() string

type Includes added in v1.7.0 

type Includes map[string]string

Includes is a map of include file priority to path include file - priority:url|path

func (*Includes) Set added in v1.7.0 

func (i *Includes) Set(value string) error

func (*Includes) String added in v1.7.0 

func (i *Includes) String() string

String is the string method for the IncludeValues type

func (*Includes) Type added in v1.7.0 

func (i *Includes) Type() string

type Instance 

type Instance struct {
	geneos.Instance `json:"-"`
	Conf            *config.Config    `json:"-"`
	InstanceHost    *geneos.Host      `json:"-"`
	Component       *geneos.Component `json:"-"`
	ConfigLoaded    bool              `json:"-"`
}

The Instance type is the common data shared by all instances

type NameValue added in v1.7.0 

type NameValue []string

attribute - name=value

func (*NameValue) Set added in v1.7.0 

func (i *NameValue) Set(value string) error

func (*NameValue) String added in v1.7.0 

func (i *NameValue) String() string

func (*NameValue) Type added in v1.7.0 

func (i *NameValue) Type() string

type OpenFiles added in v1.4.3 

type OpenFiles struct {
	Path   string
	Stat   fs.FileInfo
	FD     string
	FDMode fs.FileMode
}

type SecureValue added in v1.7.0 

type SecureValue struct {
	Value      string
	Plaintext  *config.Plaintext
	Ciphertext string
}

type SecureValues added in v1.7.0 

type SecureValues []*SecureValue

func (*SecureValues) Set added in v1.7.0 

func (p *SecureValues) Set(v string) error

Set a SecureValue. If there is a "=VALUE" part then this is saved in Plaintext, otherwise only the NAME is set. This allows later processing to either encode the Plaintext into Ciphertext or to prompt the user for a plaintext

func (*SecureValues) String added in v1.7.0 

func (p *SecureValues) String() string

func (*SecureValues) Type added in v1.7.0 

func (p *SecureValues) Type() string

type SetConfigValues added in v1.7.0 

type SetConfigValues struct {
	// Includes are include files for Gateway templates, keyed by priority
	Includes Includes

	// Gateways are gateway connections for SAN templates
	Gateways Gateways

	// Attributes are name=value pairs for attributes for Gateway templates
	Attributes NameValue

	// Environment variables for all instances as name=value pairs
	Envs NameValue

	// Variables for SAN templates, keyed by variable name
	Variables Vars

	// Types for SAN templates
	Types Types

	// Params are key=value pairs set directly in the configuration after checking
	Params []string

	// SecureParams parameters name[=value] where value will be prompted
	// for if not supplied and are encoded with a keyfile
	SecureParams SecureValues

	// SecureEnvs are environment variables in the form name[=value]
	// where value will be prompted for if not supplied and are encoded
	// with a keyfile
	SecureEnvs SecureValues
}

SetConfigValues defined the set of non-simple configuration options that can be accepted by various commands

type SortInstanceResults added in v1.7.0 

type SortInstanceResults struct {
	Instances []geneos.Instance
	Results   []interface{}
}

func (SortInstanceResults) Len added in v1.7.0 

func (s SortInstanceResults) Len() int

func (SortInstanceResults) Less added in v1.7.0 

func (s SortInstanceResults) Less(i, j int) bool

func (SortInstanceResults) Swap added in v1.7.0 

func (s SortInstanceResults) Swap(i, j int)

type Types added in v1.7.0 

type Types []string

attribute - name=value

func (*Types) Set added in v1.7.0 

func (i *Types) Set(value string) error

func (*Types) String added in v1.7.0 

func (i *Types) String() string

func (*Types) Type added in v1.7.0 

func (i *Types) Type() string

type UnsetConfigValues added in v1.5.0 

type UnsetConfigValues struct {
	Attributes UnsetValues
	Envs       UnsetValues
	Gateways   UnsetValues
	Includes   UnsetValues
	Keys       UnsetValues
	Types      UnsetValues
	Variables  UnsetVars
}

type UnsetValues added in v1.5.0 

type UnsetValues []string

unset Var flags take just the key, either a name or a priority for include files

func (*UnsetValues) Set added in v1.7.0 

func (i *UnsetValues) Set(value string) error

func (*UnsetValues) String added in v1.7.0 

func (i *UnsetValues) String() string

func (*UnsetValues) Type added in v1.7.0 

func (i *UnsetValues) Type() string

type UnsetVars added in v1.7.0 

type UnsetVars []string

func (*UnsetVars) Set added in v1.7.0 

func (i *UnsetVars) Set(value string) error

func (*UnsetVars) String added in v1.7.0 

func (i *UnsetVars) String() string

func (*UnsetVars) Type added in v1.7.0 

func (i *UnsetVars) Type() string

type VarValue added in v1.5.0 

type VarValue struct {
	Type  string
	Name  string
	Value string
}

variables - [TYPE:]NAME=VALUE

type Vars added in v1.7.0 

type Vars map[string]VarValue

func (*Vars) Set added in v1.7.0 

func (i *Vars) Set(value string) error

func (*Vars) String added in v1.7.0 

func (i *Vars) String() string

func (*Vars) Type added in v1.7.0 

func (i *Vars) Type() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.