geneos

package
v1.10.0 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2023 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package geneos provides internal features to manage a typical `Best Practice` installation layout and the conventions that have formed around that structure over many years.

Index

Constants

View Source 
const (
	LOCALHOST = "localhost"
	ALLHOSTS  = "all"
)

Default host labels that always exist

View Source 
const DisableExtension = "disabled"

DisableExtension is the suffix added to instance config files to mark them disabled

View Source 
const OldUserHostFile = "geneos-hosts.json"

OldUserHostFile is a legacy name that will be deprecated in the future

View Source 
const RootComponentName = "root"

Variables

View Source 
var (
	ErrRootNotSet   = errors.New("root directory not set")
	ErrInvalidArgs  = errors.New("invalid arguments")
	ErrNotSupported = errors.New("not supported")
	ErrIsADirectory = errors.New("is a directory")
	ErrExists       = errors.New("exists")
	ErrNotExist     = errors.New("does not exist")
	ErrDisabled     = errors.New("instance is disabled")
	ErrProtected    = errors.New("instance is protected")
	ErrRunning      = errors.New("instance is running")
	ErrNotRunning   = errors.New("instance is not running")
)

Useful errors for the package to return

Can also be used by other packages

View Source 
var ChainCertFile string

ChainCertFile the is file name (including extension, as this does not need to be used for keys) for the consolidated chain file used to verify instance certificates

View Source 
var RootCAFile = "rootCA"

RootCAFile is the file base name for the root certificate authority created with the TLS commands

View Source 
var RootComponent = Component{
	Name:         RootComponentName,
	PackageTypes: nil,
	Aliases:      []string{"any"},
	DownloadBase: DownloadBases{Resources: "", Nexus: ""},
	GlobalSettings: map[string]string{

		config.Join("download", "url"): "https://resources.itrsgroup.com/download/latest/",

		"reservednames": "all",

		"privatekeys": "id_rsa,id_ecdsa,id_ecdsa_sk,id_ed25519,id_ed25519_sk,id_dsa",
		// contains filtered or unexported fields
	},
	Directories: []string{
		"packages/downloads",
	},
}
View Source 
var SigningCertFile string

SigningCertFile is the file base name for the signing certificate created with the TLS commands

Functions

func CleanRelativePath added in v1.5.0 

func CleanRelativePath(p string) (clean string, err error)

CleanRelativePath given a path returns a cleaned version. If the cleaning results in an absolute path or one that tries to ascend the tree then return an error

func CompareVersion added in v1.5.0 

func CompareVersion(version1, version2 string) int

CompareVersion takes two Geneos package versions and returns an int that is 0 if they are identical, negative if version1 < version2 and positive is version1 > version2. If the version is prefixed with non numeric values then "GA" is always greater thn "RA" (general versus restricted availability) for the same numeric version, otherwise a lexical comparison is done on the prefixes.

If either version is empty or unparseable then the return value is set to favour the other version - or 0 if both are empty strings.

func CurrentVersion added in v1.6.0 

func CurrentVersion(h *Host, ct *Component, base string) (version string, err error)

CurrentVersion returns the version that base points to for the component ct on host h. If base is not a symlink then it is returned unchanged. Returns version set to "unknown" on error.

func FilenameFromHTTPResp 

func FilenameFromHTTPResp(resp *http.Response, u *url.URL) (filename string, err error)

FilenameFromHTTPResp decodes and returns the filename from the HTTP(S) request. It tried to extract the filename from the COntent-Disposition header and if that fails returns the basename of the URL Path.

func ImportCommons added in v1.7.0 

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

ImportCommons copies a file to an instance common directory.

func ImportFile added in v1.7.0 

func ImportFile(h *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.

If source is a (local) file and it is the same as the destination then an ErrExists is returned.

func ImportKeyFile added in v1.7.0 

func ImportKeyFile(h *Host, ct *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 ALL and ct can be nil, in which case they are treated as wildcards.

func ImportKeyValues added in v1.7.0 

func ImportKeyValues(h *Host, ct *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 ALL and ct can be nil, in which case they are treated as wildcards.

func Init 

func Init(app string)

Init is called from the main command initialisation

func InitHosts added in v1.5.0 

func InitHosts(app string)

InitHosts initialises the host settings and is only called from the root command to set the initial values of host.LOCAL and host.ALL and reads the host configuration file. LOCAL and ALL cannot be initialised outside a function as there would be a definition loop.

func Initialise added in v1.5.0 

func Initialise(h *Host, options ...Options) (err error)

Initialise a Geneos environment by creating a directory structure and then it calls the initialisation functions for each component type registered.

If the directory is not empty and the Force() option is not passed then nothing is changed

func Install 

func Install(h *Host, ct *Component, options ...Options) (err error)

Install a Geneos software release. The destination host h and the component type ct must be given. options controls behaviour like local only and restarts of affected instances.

func KeyFileNormalise added in v1.7.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 neither an 8 digit hex string (in upper or lower case) with or without the extension ".aes" (in upper or lower case) then the input is returned unchanged.

func LatestArchive added in v1.5.0 

func LatestArchive(r *Host, dir, filterString string, filterFunc func(os.DirEntry) bool) (latest string, err error)

LatestArchive returns the latest archive file for component ct on host r based on semver. A prefix filter can be used to limit matches and a filter function to further refine matches.

If there is semver metadata, check for platform_id on host and remove any non-platform metadata from list before sorting

func LatestVersion added in v1.5.0 

func LatestVersion(r *Host, ct *Component, prefix string) (v string, err error)

LatestVersion returns the name of the latest release for component type ct on host h. The comparison is done using semantic versioning and any metadata is ignored. The matching is limited by the optional prefix filter. An error is returned if there are problems accessing the directories or parsing any names as semantic versions.

func LoadHostConfig added in v1.5.0 

func LoadHostConfig()

LoadHostConfig loads configuration entries from the host configuration file.

func ReadFrom added in v1.5.0 

func ReadFrom(source string, options ...Options) (b []byte, err error)

ReadFrom opens and, if successful, reads the contents of the source passed, returning a byte slice of the contents or an error. source can be a local file or a URL.

func Root 

func Root() string

Root return the absolute path to the local Geneos installation. If run on an older installation it may return the value from the legacy configuration item `itrshome` if `geneos` is not set.

func SaveHostConfig added in v1.5.0 

func SaveHostConfig() error

SaveHostConfig writes the current hosts to the users hosts configuration file

func SaveKeyFileShared added in v1.7.0 

func SaveKeyFileShared(h *Host, ct *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 Update 

func Update(h *Host, ct *Component, options ...Options) (err error)

Update will check and update the base link given in the options. If the base link exists then the force option must be used to update it, otherwise it is created as expected. When called from unarchive() this allows new installs to work without explicitly calling update.

func UseKeyFile added in v1.7.0 

func UseKeyFile(h *Host, ct *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.

Types

type Component 

type Component struct {
	// Name of a component
	Name string

	// Aliases are any names for the component (including the Name, above)
	Aliases []string

	// LegacyPrefix is the three or four letter prefix from legacy `ctl`
	// commands
	LegacyPrefix string

	// LegacyParameters is a map of legacy parameters (including prefix)
	// to new parameter names
	LegacyParameters map[string]string

	// ParentType, if set, is the parent component that the component is
	// under, e.g. 'fa2' has a parent of 'netprobe'. See PackageTypes
	// below.
	ParentType *Component

	// PackageTypes is a list of packages that can be used to support
	// this component. For example, a 'san' could be either a plain
	// 'netprobe' or an 'fa2'. The entries must reference components
	// that do not have PackageTypes set to avoid recursion.
	PackageTypes []*Component

	// Defaults are name=value templates that are "run" for each new
	// instance
	//
	// They are run in order, as later defaults may depend on earlier
	// settings, and so this cannot be a map
	Defaults []string

	UsesKeyfiles bool

	// Directories to be created (under Geneos home) on initialisation
	Directories []string

	// Templates are any templates for the component. Each Template has
	// a filename and default content
	Templates []Templates

	DownloadBase  DownloadBases
	DownloadInfix string // if set replace this string with component name for download matches

	GlobalSettings map[string]string

	PortRange string
	CleanList string
	PurgeList string

	// Initialise a component. Callback after the component is registered
	Initialise func(*Host, *Component)

	// New is the factory method for the component. It has to be added
	// during initialisation to avoid loops
	New func(string) Instance

	// GetPID returns the process ID of an instance - if nil a standard
	// function is used
	GetPID func(string, interface{}, string, [][]byte) bool // if set, use this to get the PID of an instance
}

Component defines a registered component

func AllComponents 

func AllComponents() (cts []*Component)

AllComponents returns a slice of all registered components, include the Root component type

func ParseComponent added in v1.7.0 

func ParseComponent(component string) *Component

ParseComponent returns the component type by iterating over all the names registered by components and returning as soon as any value matches. The comparison is case-insensitive. nil is returned if the component does not match any known name.

func RealComponents 

func RealComponents() (cts []*Component)

RealComponents returns a slice of all registered components that are not the root

func UsesKeyFiles added in v1.5.0 

func UsesKeyFiles() (cts []*Component)

UsesKeyFiles returns a slice of registered components that use key files

func (*Component) Dir added in v1.7.0 

func (ct *Component) Dir(h *Host) (dir string)

Dir return the parent directory for the instances of a component

func (*Component) InstancesDir added in v1.4.1 

func (ct *Component) InstancesDir(h *Host) (dirs []string)

InstancesDir returns a list of possible instance directories to look for an instance.

func (*Component) IsA added in v1.5.0 

func (ct *Component) IsA(names ...string) bool

IsA returns true is any of the names match the any of the names defined in ComponentMatches. The check is case-insensitive.

func (*Component) MakeDirs added in v1.7.0 

func (ct *Component) MakeDirs(h *Host) (err error)

MakeDirs creates the directory structure for the component ct. If ct is nil then the Root component type is used. If there is an error creating the directory then the error is immediately returned and the list of directories may only be partially created.

func (*Component) OrList added in v1.5.0 

func (ct *Component) OrList(cts ...*Component) []*Component

OrList will return receiver, if not nil, or the list of component types passed as args. If no arguments are passed then all 'real' components (those with the `RealComponent` field set to true) are returned.

func (*Component) Register added in v1.7.0 

func (ct *Component) Register(factory func(string) Instance)

Register adds the given Component ct to the internal list of component types. The factory parameter is the Component's New() function, which has to be passed in to avoid initialisation loops as the function refers to the type being registered.

func (*Component) Shared added in v1.7.0 

func (ct *Component) Shared(h *Host, subs ...interface{}) string

Shared return the shared directory for the component on host h joined to subdirectories and file given as subs.

func (*Component) String 

func (ct *Component) String() (name string)

type DownloadBases 

type DownloadBases struct {
	Resources string
	Nexus     string
}

DownloadBases define the base names for the download archived for standard and nexus downloads

type FileOwner added in v1.5.0 

type FileOwner struct {
	Uid int
	Gid int
}

FileOwner is only available on Linux localhost

type Host added in v1.5.0 

type Host struct {
	host.Host
	*config.Config
	// contains filtered or unexported fields
}

Host defines a host for seamless remote management 

var (
	LOCAL *Host
	ALL   *Host
)

LOCAL and ALL are the global Host values that represent LOCALHOST and ALLHOSTS from above, and must always exist

func AllHosts added in v1.5.0 

func AllHosts() (hs []*Host)

AllHosts returns a slice of all hosts, including LOCAL

func GetHost added in v1.5.0 

func GetHost(name string) (h *Host)

GetHost returns a pointer to Host value. If passed an empty name, returns nil. If passed the special values LOCALHOST or ALLHOSTS then it will return the respective special values LOCAL or ALL. Otherwise it tries to lookup an existing host with the given name.

It will return nil if the named host is not found. Use NewHost() to initialise a new host

func Match added in v1.5.0 

func Match(h string) (r []*Host)

Match returns a slice of all matching Hosts. Intended for use in range loops where the host could be specific or 'all'. If passed an empty string then returns an empty slice.

func NewHost added in v1.5.0 

func NewHost(name string, options ...any) (h *Host)

NewHost is a factory method for Host. It returns an initialised Host and will store it in the global map. If name is "localhost" or "all" then it returns pseudo-hosts used for testing and ranges.

func RemoteHosts added in v1.5.0 

func RemoteHosts(includeHidden bool) (hs []*Host)

RemoteHosts returns a slice of all valid (loaded and reachable) remote hosts

func (*Host) Delete added in v1.5.0 

func (h *Host) Delete()

Delete host h from the internal list of hosts. Does not change the on-disk configuration file

func (*Host) Exists added in v1.5.0 

func (h *Host) Exists() bool

Exists returns true if the host h has an initialised configuration

To check is a host can be contacted use the IsAvailable() instead

func (*Host) FullName added in v1.5.0 

func (h *Host) FullName(name string) string

FullName returns name with the host h label appended if there is no existing host label in the form `instance@host`. Any existing label is not checked or changed.

func (*Host) GetFileOwner added in v1.5.0 

func (h *Host) GetFileOwner(info fs.FileInfo) (s FileOwner)

func (*Host) Hidden added in v1.6.4 

func (h *Host) Hidden() bool

Hidden returns true is the host is marked hidden

func (*Host) OrList added in v1.5.0 

func (h *Host) OrList(hosts ...*Host) []*Host

OrList will return the receiver unless it is nil, or the list of all hosts passed as args. If no args are given and the receiver is nil then all hosts are returned.

func (*Host) PathTo added in v1.7.0 

func (h *Host) PathTo(parts ...interface{}) string

PathTo builds an absolute path based on the Geneos root of the host h (using the executable name as the key) and the parts passed as arguments. Each part can be a pointer to a geneos.Component, in which case the component name or the parent component name is used, or any other type is passed to fmt.Sprint to be stringified. The path is returned from path.Join

If calling this against the "packages" directory remember to use ct.String() to not deference the parent type, which is done if a part is a *Component

func (*Host) SetOSReleaseEnv added in v1.5.0 

func (h *Host) SetOSReleaseEnv() (err error)

SetOSReleaseEnv sets the `osinfo` configuration map to the values from either `/etc/os-release` (or `/usr/lib/os-release`) on Linux or simulates the values for Windows

func (*Host) String added in v1.7.0 

func (h *Host) String() string

func (*Host) Valid added in v1.5.0 

func (h *Host) Valid()

Valid marks the host loaded and so qualified for saving to the hosts config file

type Instance 

type Instance interface {
	Config() *config.Config

	// getters and setters
	Name() string
	Home() string
	Type() *Component
	Host() *Host
	String() string

	// config
	Load() error
	Unload() error
	Loaded() time.Time
	SetLoaded(time.Time)

	// actions
	Add(template string, port uint16) error
	Command() ([]string, []string, string)
	Reload() (err error)
	Rebuild(bool) error
}

Instance interfaces contains the method set for an instance of a registered Component

type Options 

type Options func(*geneosOptions)

Options can be passed to various function and influence behaviour

func Archive added in v1.6.6 

func Archive(f string) Options

Archive is the archive source or destination. It can be a directory, in which case that directory is used for the appropriate archive file(s)

func Basename 

func Basename(b string) Options

Basename sets the package binary basename, defaults to active_prod, for symlinks for update.

func DoUpdate added in v1.4.1 

func DoUpdate(r bool) Options

DoUpdate sets the option to also do an update after an install

func DownloadOnly added in v1.6.6 

func DownloadOnly(o bool) Options

DownloadOnly prevents the unarchiving of the selected packages. Downloads are stored in the directory given to Source() or the default packages/download directory

func Force 

func Force(o bool) Options

Force ignores existing directories or files and also overrides protection for running instances in upgrades

func LocalOnly 

func LocalOnly(l bool) Options

LocalOnly stops downloads from external locations

func NoSave 

func NoSave(n bool) Options

NoSave prevents downloads from being saved in the archive directory

func OverrideVersion 

func OverrideVersion(s string) Options

OverrideVersion forces a specific version to be used and failure if not available

func Password 

func Password(p *config.Plaintext) Options

Password is the remote access password for downloads

func PlatformID 

func PlatformID(id string) Options

PlatformID sets the (Linux) platform ID from the OS release info. Currently used to distinguish RHEL8 installs from others.

func Restart 

func Restart(i ...Instance) Options

Restart sets the instances to be restarted around the update

func StartFunc added in v1.8.1 

func StartFunc(start func(Instance, ...any) error) Options

StartFunc sets the start function to call for each instance given in Restart(). It is required to avoid import loops.

func StopFunc added in v1.8.1 

func StopFunc(stop func(Instance, bool, bool) error) Options

StopFunc sets the start function to call for each instance given in Restart(). It is required to avoid import loops.

func UseNexus 

func UseNexus() Options

UseNexus sets the flag to use nexus.itrsgroup.com for internal downloads instead of the default download URL in the settings. This also influences the way the remote path is searched and build, not just the base URL.

func UseRoot added in v1.5.0 

func UseRoot(h string) Options

UseRoot sets the Geneos installation home directory (aka `geneos` in the settings)

func UseSnapshots 

func UseSnapshots() Options

UseSnapshots set the flag to use Nexus Snapshots rather than Releases.

func Username 

func Username(u string) Options

Username is the remote access username for downloads

func Version 

func Version(v string) Options

Version sets the desired version number, defaults to "latest" in most cases. The version number is in the form `[GA]X.Y.Z` (or `RA` for snapshots)

type ReleaseDetails added in v1.5.0 

type ReleaseDetails struct {
	Component string    `json:"Component"`
	Host      string    `json:"Host"`
	Version   string    `json:"Version"`
	Latest    bool      `json:"Latest,string"`
	Links     []string  `json:"Links,omitempty"`
	ModTime   time.Time `json:"LastModified"`
	Path      string    `json:"Path"`
}

ReleaseDetails is a set of values for a release

type Releases added in v1.5.0 

type Releases []ReleaseDetails

Releases is a slice of ReleaseDetails, used for sorting ReleaseDetails

func GetReleases added in v1.5.0 

func GetReleases(h *Host, ct *Component) (releases Releases, err error)

GetReleases returns a slice of PackageDetails containing all the directories Geneos packages directory on the given host. Symlinks in the packages directory are matches to any targets and unmatched symlinks are ignored.

No validation is done on the contents, only that a directory exists.

func (Releases) Len added in v1.5.0 

func (r Releases) Len() int

func (Releases) Less added in v1.5.0 

func (r Releases) Less(i, j int) bool

func (Releases) Swap added in v1.5.0 

func (r Releases) Swap(i, j int)

type Templates added in v1.5.0 

type Templates struct {
	Filename string
	Content  []byte
}

Templates define the filename and embedded content for template files

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.