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
- Variables
- func CleanRelativePath(path string) (clean string, err error)
- func CompareVersion(version1, version2 string) int
- func CurrentVersion(h *Host, ct *Component, base string) (version string, err error)
- func FilenameFromHTTPResp(resp *http.Response, u *url.URL) (filename string, err error)
- func GeneosInit(h *Host, options ...Options) (err error)
- func InitHosts(app string)
- func Initialise(app string)
- func Install(h *Host, ct *Component, options ...Options) (err error)
- func LatestArchive(r *Host, dir, filterString string, filterFunc func(os.DirEntry) bool) (latest string, err error)
- func LatestVersion(r *Host, ct *Component, prefix string) (v string, err error)
- func LoadHostConfig()
- func Open(source string, options ...Options) (from io.ReadCloser, filename string, err error)
- func ReadFrom(source string, options ...Options) (b []byte, err error)
- func Root() string
- func SaveHostConfig() error
- func Update(h *Host, ct *Component, options ...Options) (err error)
- type Component
- func (ct *Component) InstancesDir(h *Host) (dir string)
- func (ct *Component) InstancesDirs(h *Host) (dirs []string)
- func (ct Component) IsA(name ...string) bool
- func (ct *Component) MakeComponentDirs(h *Host) (err error)
- func (ct *Component) OrList(cts ...*Component) []*Component
- func (ct *Component) RegisterComponent(factory func(string) Instance)
- func (ct *Component) SharedPath(h *Host, subs ...interface{}) string
- func (ct Component) String() (name string)
- type DownloadBases
- type FileOwner
- type Host
- func (h *Host) Delete()
- func (h *Host) Exists() bool
- func (h *Host) Filepath(parts ...interface{}) string
- func (h *Host) FullName(name string) string
- func (h *Host) GetFileOwner(info fs.FileInfo) (s FileOwner)
- func (h *Host) Hidden() bool
- func (h *Host) OrList(hosts ...*Host) []*Host
- func (h *Host) SetOSReleaseEnv() (err error)
- func (h *Host) Valid()
- type Instance
- type Options
- func Archive(f string) Options
- func Basename(b string) Options
- func DoUpdate(r bool) Options
- func DownloadOnly(o bool) Options
- func Force(o bool) Options
- func LocalOnly(l bool) Options
- func NoSave(n bool) Options
- func OverrideVersion(s string) Options
- func Password(p *config.Plaintext) Options
- func PlatformID(id string) Options
- func Restart(r bool) Options
- func UseNexus() Options
- func UseRoot(h string) Options
- func UseSnapshots() Options
- func Username(u string) Options
- func Version(v string) Options
- type ReleaseDetails
- type Releases
- type Templates
Constants ¶
const ( LOCALHOST = "localhost" ALLHOSTS = "all" )
Default host labels that always exist
const DisableExtension = "disabled"
DisableExtension is the suffix added to instance config files to mark them disabled
const OldUserHostFile = "geneos-hosts.json"
OldUserHostFile is a legacy name that will be deprecated in the future
const RootComponentName = "root"
Variables ¶
var ( 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
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
var RootCAFile = "rootCA"
RootCAFile is the file base name for the root certificate authority created with the TLS commands
var RootComponent = Component{ Name: RootComponentName, RelatedTypes: nil, Aliases: []string{"any"}, RealComponent: false, DownloadBase: DownloadBases{Resources: "", Nexus: ""}, GlobalSettings: map[string]string{ config.Join("download", "url"): "https://resources.itrsgroup.com/download/latest/", "reservednames": "", "privatekeys": "id_rsa,id_ecdsa,id_ecdsa_sk,id_ed25519,id_ed25519_sk,id_dsa", // contains filtered or unexported fields }, Directories: []string{ "packages/downloads", }, }
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
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
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
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 ¶
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 GeneosInit ¶
GeneosInit initialises 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 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(app string)
Initialise is called from the main command initialisation
func Install ¶
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 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
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 Open ¶ added in v1.5.0
Open returns an io.ReadCloser and the base filename for the given source. The source can be a `https` or `http“ URL or a path to a file or '-' for STDIN.
URLs are Parsed and fetched with the `http.Get“ function and so support proxies and basic authentication as supported by the http package.
As a special case, if the file path begins '~/' then it is relative to the home directory of the calling user, otherwise it is opened relative to the working directory of the process. If passed the option `geneos.Homedir()“ then this is used instead of the calling user's home directory
If source is a path to a directory then `geneos.ErrIsADirectory` is returned. If any other stage fails then err is returned from the underlying package.
func ReadFrom ¶ added in v1.5.0
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
Types ¶
type Component ¶
type Component struct { // Name of a component Name string // Aliases are any aliases for component Aliases []string // 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 // 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 // RelatedTypes are any related component types. This could also be // derived from ParentType RelatedTypes []*Component // ParentType, if set, is the parent component that the component is // under, e.g. san has a parent of netprobe ParentType *Component RealComponent bool 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(interface{}) (int, error) // 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 FindComponent ¶ added in v1.5.0
FindComponent 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 have their `RealComponent` field set to true.
func UsesKeyFiles ¶ added in v1.5.0
func UsesKeyFiles() (cts []*Component)
UsesKeyFiles returns a slice of registered components that use key files
func (*Component) InstancesDir ¶ added in v1.4.1
InstancesDir return the parent directory for the instances of a component
func (*Component) InstancesDirs ¶ added in v1.6.0
InstancesDirs (plural) returns a list of possible instance directories to look for an instance.
func (Component) IsA ¶ added in v1.5.0
IsA returns true is any of the names match the any of the names defined in ComponentMatches.
func (*Component) MakeComponentDirs ¶ added in v1.4.1
MakeComponentDirs creates the directory structure for the component. 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
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) RegisterComponent ¶ added in v1.4.1
RegisterComponent 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) SharedPath ¶ added in v1.5.0
SharedPath return the shared directory for the component on host h joined to subdirectories and file given as subs.
type DownloadBases ¶
DownloadBases define the base names for the download archived for standard and nexus downloads
type Host ¶ added in v1.5.0
Host defines a host for seamless remote management
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
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
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
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
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
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) Filepath ¶ added in v1.5.0
Filepath 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 filepath.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) FullName ¶ added in v1.5.0
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 (*Host) OrList ¶ added in v1.5.0
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) SetOSReleaseEnv ¶ added in v1.5.0
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
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() bool // actions Add(template string, port uint16) error Command() ([]string, []string, string) Reload(params []string) (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
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 ¶
Basename sets the package binary basename, defaults to active_prod, for symlinks for update.
func DownloadOnly ¶ added in v1.6.6
DownloadOnly prevents the unarchiving of the selected packages. Downloads are stored in the directory given to Source() or the default packages/download directory
func OverrideVersion ¶
OverrideVersion forces a specific version to be used and failure if not available
func PlatformID ¶
PlatformID sets the (Linux) platform ID from the OS release info. Currently used to distinguish RHEL8 installs from others.
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
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.
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
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.