config

package
v1.5.0-beta Latest Latest
Warning

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

 Go to latest Published: May 15, 2023 License: MIT Imports: 28 Imported by: 1

README

config package

The config package wraps the common viper methods and types but adds some custom processing.

This probably could be done using custom decode hooks for viper, but I have not had time to understand them in detail.

Using a wrapper also allows custom methods on config for further functionality.

Unless the file format is given to Load then all the viper formats are supported.

Expansion of values

The following package functions and type methods are overridden to add expansion of embedded strings of the form ${name} and $name:

The string values are passed to ExpandString which supports a range of data substitutions.

Documentation

Overview

This package adds local extensions to viper as well as supporting Geneos encryption key files and basic encryption and decryption.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddCreds added in v1.5.0 

func AddCreds(creds Credentials, options ...FileOptions) (err error)

Add creds to the "credentials" file identified by the options. creds.Domain is used as the key for matching later on. Any existing credential with the same Domain is overwritten. If there is an error un the underlying routines it is returned without change.

func Checksum 

func Checksum(data io.Reader) (crc uint32, err error)

Checksum reads from io.Reader data until EOF and returns crc as the 32-bit IEEE checksum. data should be closed by the caller on return. If there is an error reading from r then err is returned with the reason.

func DefaultKeyDelimiter added in v1.5.0 

func DefaultKeyDelimiter(delimiter string)

DefaultKeyDelimiter sets the default key delimiter for all future calls to config.New(). The default is "."

func DeleteAllCreds added in v1.5.0 

func DeleteAllCreds(options ...FileOptions) (err error)

func DeleteCreds added in v1.5.0 

func DeleteCreds(domain string, options ...FileOptions) (err error)

DeleteCreds removes the entry for domain from the "credentials" file using FileOptions options.

func Expand added in v1.4.1 

func Expand(input string, options ...ExpandOptions) (value []byte)

Expand behaves like ExpandString but returns a byte slice.

This should be used where the return value may contain sensitive data and an immutable string cannot be destroyed after use.

func ExpandEnclave 

func ExpandEnclave(input string, options ...ExpandOptions) (value *memguard.Enclave)

ExpandEnclave expands the input string and returns a sealed enclave. The option TrimSpace is ignored.

func ExpandLockedBuffer 

func ExpandLockedBuffer(input string, options ...ExpandOptions) (value *memguard.LockedBuffer)

ExpandLockedBuffer expands the input string and returns a sealed enclave. The option TrimSpace is ignored.

func ExpandString added in v1.3.0 

func ExpandString(input string, options ...ExpandOptions) (value string)

ExpandString returns the input with all occurrences of the form ${name} replaced using an os.Expand-like function (but without support for $name in the input) for the built-in and optional formats (in the order of priority) below. The caller can use options to define additional expansion functions based on a "prefix:", disabled external lookups and also to pass in lookup tables referred to as value maps. 

${enc:keyfile[|keyfile...]:encodedvalue}

  "encodedvalue" is an AES256 ciphertext in Geneos format - or, if
  not prefixed with `+encs+` then it ss processed as an expandable
  string itself and can be a reference to another configuration key
  or a file or remote url containing one - which will be decoded
  using the key file(s) given. Each "keyfile" must be one of either
  an absolute path, a path relative to the working directory of the
  program, or if prefixed with "~/" then relative to the home
  directory of the user running the program. The first valid decode
  (see below) is returned.

  To minimise (but not wholly eliminate) any false-positive decodes
  that occur in some circumstances when using the wrong key file,
  the decoded value is only returned if it is a valid UTF-8 string
  as per [utf8.Valid].

  Examples:

   * password: ${enc:~/.keyfile:+encs+9F2C3871E105EC21E4F0D5A7921A937D}
   * password: ${enc:/etc/geneos/keyfile.aes:env:ENCODED_PASSWORD}
   * password: ${enc:~/.config/geneos/keyfile1.aes:app.password}
   * password: ${enc:~/.keyfile.aes:config:mySecret}

${config:key} or ${path.to.config}

   Fetch the "key" configuration value (for single layered
   configurations, where a sub-level dot cannot be used) or if any
   value containing one or more dots "." will be looked-up in the
   existing configuration that the method is called on. The
   underlying configuration is not changed and values are resolved
   each time ExpandString() is called. No locking of the
   configuration is done.

${key}

  "key" will be substituted with the value of the first matching key
  from the tables set using config.LookupTable(), in the order passed
  to the function. If no lookup tables are set (as opposed to the
  key not being found in any of the tables) then name is looked up
  as an environment variable, as below.

${env:name}

  "name" will be substituted with the contents of the environment
  variable of the same name. If no environment variable with name
  exists then the value returned is an empty string.

The additional prefixes below are enabled by default. They can be
disabled using the config.ExternalLookups() option.

${.../path/to/file} or ${~/file} or ${file://path/to/file} or ${file:~/path/to/file}

  The contents of the referenced file will be read. Multiline files
  are used as-is; this can, for example, be used to read PEM
  certificate files or keys. If the path is prefixed with "~/" (or
  as an addition to a standard file url, if the first "/" is
  replaced with a tilde "~") then the path is relative to the home
  directory of the user running the process.

  Any name that contains a `/` but not a `:` will be treated as a
  file, if file reading is enabled. File paths can be absolute or
  relative to the working directory (or relative to the home
  directory, as above)

  Examples:

  * certfile: ${file://etc/ssl/cert.pem}
  * template: ${file:~/templates/autogen.gotmpl}
  * relative: ${./file.txt}

${https://host/path} or ${http://host/path}

  The contents of the URL are fetched and used similarly as for
  local files above. The URL is passed to [http.Get] and supports
  proxies, embedded Basic Authentication and other features from
  that function.

The prefix below can be enabled with the config.Expressions() option.

${expr:EXPRESSION}

  EXPRESSION is evaluated using https://github.com/maja42/goval. Inside
  the expression all configuration items are available as variables
  with the top level map `env` set to the environment variables
  available. All results are returned as strings. An empty string
  may mean there was an error in evaluating the expression.

Additional custom lookup prefixes can be added with the config.Prefix() option.

The bare form "$name" is NOT supported, unlike os.Expand as this can unexpectedly match values containing valid literal dollar signs.

Expansion is not recursive. Configuration values are read and stored as literals and are expanded each time they are used. For each substitution any leading and trailing whitespace are removed. External sources are fetched each time they are used and so there may be a performance impact as well as the value unexpectedly changing during a process lifetime.

Any errors (particularly from substitutions from external files or remote URLs) may result in an empty or corrupt string being returned. Error returns are intentionally discarded and an empty string substituted. Where a value contains multiple expandable items processing will continue even after an error for one of them.

It is not currently possible to escape the syntax supported by ExpandString and if it is necessary to have a configuration value be a literal of the form "${name}" then you can set an otherwise unused item to the value and refer to it using the dotted syntax, e.g. for YAML 

config:
  real: ${config.literal}
  literal: "${unchanged}"

In the above a reference to ${config.real} will return the literal string ${unchanged} as there is no recursive lookups.

func GetBytes added in v1.5.0 

func GetBytes(s string, options ...ExpandOptions) []byte

GetBytes functions like viper.GetString but additionally calls Expand with the configuration value, passing any "values" maps and returning a byte slice

func GetEnclave 

func GetEnclave(s string, options ...ExpandOptions) *memguard.Enclave

GetEnclave returns a sealed enclave containing the configuration item identified by key and expanded using the Expand function with the options supplied.

func GetInt added in v1.4.3 

func GetInt(s string, options ...ExpandOptions) int

GetInt functions like viper.GetInt but additionally calls ExpandString with the configuration value, passing any "values" maps. If the conversion fails then the value returned will be the one from strconv.ParseInt - typically 0 but can be the maximum integer value

func GetInt64 added in v1.4.3 

func GetInt64(s string, options ...ExpandOptions) int64

GetInt64 functions like viper.GetInt but additionally calls ExpandString with the configuration value, passing any "values" maps. If the conversion fails then the value returned will be the one from strconv.ParseInt - typically 0 but can be the maximum integer value

func GetString 

func GetString(s string, options ...ExpandOptions) string

GetString functions like viper.GetString but additionally calls ExpandString with the configuration value, passing any "values" maps

func GetStringMapString 

func GetStringMapString(s string, options ...ExpandOptions) map[string]string

GetStringMapString functions like viper.GetStringMapString but additionally calls ExpandString on each value element of the map, passing any "values" maps

func GetStringSlice 

func GetStringSlice(s string, options ...ExpandOptions) []string

GetStringSlice functions like viper.GetStringSlice but additionally calls ExpandString on each element of the slice, passing any "values" maps

func Join added in v1.5.0 

func Join(parts ...string) string

Join returns a configuration key made up of parts joined with the default delimiter for the global configuration object.

func Path added in v1.5.0 

func Path(name string, options ...FileOptions) string

Path returns the full path to the first regular file found that would be opened by Load() given the same options. If no file is found then a path to the expected file in the first configured directory is returned. This allows for a default value to be returned for new files. If no directories are used then the plain filename is returned.

func PromoteFile added in v1.5.0 

func PromoteFile(r host.Host, paths ...string) (final string)

PromoteFile iterates over paths and finds the first regular file that exists. If this is not the first element in the paths slice then the found file is renamed to the path of the first element. The resulting final path is returned.

If the first element of paths is an empty string then no rename takes place and the first existing file is returned. If the first element is a directory then the file is moved into that directory through a rename operation.

func ReadPasswordInput added in v1.5.0 

func ReadPasswordInput(match bool, maxtries int, prompt ...string) (pw *memguard.Enclave, err error)

ReadPasswordInput prompts the user for a password without echoing the input. This is returned as a memguard LockBuffer. If match is true then the user is prompted twice and the two instances checked for a match. Up to maxtries attempts are allowed after which an error is returned. If maxtries is 0 then a default of 3 attempts is set.

If prompt is given then it must either be one or two strings, depending on match set. The prompt(s) are suffixed with ": " in both cases. The defaults are "Password" and "Re-enter Password".

On error the pw is empty and does not need to be Destory()ed.

func ReadUserInput added in v1.5.0 

func ReadUserInput(prompt string) (input string, err error)

ReadUserInput reads input from Stdin and returns the input unless there is an error. The prompt is shown to the user as-is.

func ResetConfig added in v1.5.0 

func ResetConfig(options ...FileOptions)

ResetConfig reinitialises the global configuration object. Existing settings will be copied over. This is primarily to be able to change the default delimiter after start-up.

func Save added in v1.5.0 

func Save(name string, options ...FileOptions) (err error)

Save writes the global configuration to a configuration file defined by the component name and options

func Set added in v1.5.0 

func Set(key string, value interface{})

Set sets the key to value

func SetKeyValues added in v1.5.0 

func SetKeyValues(items ...string)

SetKeyValues takes a list of `key-value` pairs as strings and applies them to the global configuration object. Items without an `=` are skipped.

func SetStringMapString added in v1.4.3 

func SetStringMapString(m string, vals map[string]string)

SetMap iterates over a map[string]string and sets each key to the value given. Viper's Set() doesn't support maps until the configuration is written to and read back from a file.

func UserConfigDir added in v1.3.2 

func UserConfigDir(username ...string) (path string, err error)

Types

type Config 

type Config struct {
	*viper.Viper
	Type string // The type of configuration file loaded
	// contains filtered or unexported fields
}

Config embeds Viper

func FindCreds added in v1.5.0 

func FindCreds(path string, options ...FileOptions) (cred *Config)

FindCreds looks for matching credentials in a default "credentials" file. options are the same as for Load but the default KeyDelimiter is set to "::" as credential domains are likely to be hostnames or URLs. The longest match wins.

func GetConfig 

func GetConfig() *Config

GetConfig returns the global Config instance

func Load added in v1.5.0 

func Load(name string, options ...FileOptions) (c *Config, err error)

Load reads configuration values from internal defaults, external defaults and configuration files. The directories searched and the configuration file names can be controlled using options. The first match is loaded unless the config.MergeSettings() option is used, in which case all defaults are merged and then all non-defaults are merged in the order they were given.

Examples: 

config.Load("geneos", config.SetGlobal())

//go:embed somefile.json
var myDefaults []byte
Load("geneos", config.SetDefaults(myDefaults, "json"), config.SetConfigFile(configPath))

Options can be passed to change the default behaviour and to pass any embedded defaults or an existing viper.

for defaults see: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

Regardless of errors loading configurations a configuration object is always returned.

The returned config object may be made up from multiple sources so there is no simple way of getting the name of the final configuration file used.

If the LoadFrom() option is set then all file access is via the given remote. Defaults and the primary configuration cannot be loaded from different remotes. The default is "localhost".

TBD: windows equiv of above

func New 

func New(options ...FileOptions) *Config

New returns a Config instance initialised with a new viper instance. Can be called with config.DefaultExpandOptions(...) to set defaults for future calls that use Expand.

func ReadHOCONFile added in v1.4.1 

func ReadHOCONFile(file string) (c *Config, err error)

ReadHOCONFile loads a HOCON format configuration from file. To control behaviour and options like config.Load() use MergeHOCONConfig() or MergeHOCONFile() with an existing config.Config structure.

func (*Config) DefaultExpandOptions added in v1.4.1 

func (c *Config) DefaultExpandOptions(options ...ExpandOptions)

DefaultExpandOptions sets defaults to all subsequent calls to functions that perform configuration expansion. These defaults can be reset by calling DefaultExpandOptions with no arguments.

func (*Config) Expand added in v1.4.1 

func (c *Config) Expand(input string, options ...ExpandOptions) (value []byte)

Expand behaves like the ExpandString method but returns a byte slice.

func (*Config) ExpandAllSettings 

func (c *Config) ExpandAllSettings(options ...ExpandOptions) (all map[string]interface{})

ExpandAllSettings returns all the settings from config structure c applying ExpandString to all string values and all string slice values. Non-string types are left unchanged. Further types, e.g. maps of strings, may be added in future releases.

func (*Config) ExpandEnclave 

func (c *Config) ExpandEnclave(input string, options ...ExpandOptions) (value *memguard.Enclave)

ExpandEnclave expands the input string and returns a sealed enclave. The option TrimSpace is ignored.

func (*Config) ExpandLockedBuffer 

func (c *Config) ExpandLockedBuffer(input string, options ...ExpandOptions) (value *memguard.LockedBuffer)

ExpandLockedBuffer expands the input string and returns a sealed enclave. The option TrimSpace is ignored.

func (*Config) ExpandRawString added in v1.5.0 

func (c *Config) ExpandRawString(s string, options ...ExpandOptions) (value string, err error)

ExpandRawString expands the string s using the same rules and options as ExpandString but treats the whole of s as if it were wrapped in '${...}'. The function does most of the core work for configuration expansion but is also exported for use without the decoration required for configuration values, allowing use against command line flag values, for example.

func (*Config) ExpandString 

func (c *Config) ExpandString(input string, options ...ExpandOptions) (value string)

ExpandString works just like the package level ExpandString but on a specific config instance. The return value is always a freshly allocated string.

func (*Config) FindCreds added in v1.5.0 

func (cf *Config) FindCreds(path string) (creds *Config)

FindCreds finds a set of credentials in the given config structure under the key "credentials" and tries to match the longest one, if any. creds is nil if not matching credentials found.

func (*Config) GetBytes added in v1.5.0 

func (c *Config) GetBytes(s string, options ...ExpandOptions) []byte

GetBytes functions like viper.GetString on a Config instance, but additionally calls Expand with the configuration value, passing any "values" maps and returning a byte slice

func (*Config) GetEnclave 

func (c *Config) GetEnclave(key string, options ...ExpandOptions) *memguard.Enclave

GetEnclave returns a sealed enclave containing the configuration item identified by key and expanded using the Expand function with the options supplied.

func (*Config) GetInt added in v1.4.3 

func (c *Config) GetInt(s string, options ...ExpandOptions) (i int)

GetInt functions like viper.GetInt on a Config instance, but additionally calls ExpandString with the configuration value, passing any "values" maps, before converting the result to an int. If the conversion fails then the value returned will be the one from strconv.ParseInt - typically 0 but can be the maximum integer value

func (*Config) GetInt64 added in v1.4.3 

func (c *Config) GetInt64(s string, options ...ExpandOptions) (i int64)

GetInt64 functions like viper.GetInt on a Config instance, but additionally calls ExpandString with the configuration value, passing any "values" maps, before converting the result to an int. If the conversion fails then the value returned will be the one from strconv.ParseInt - typically 0 but can be the maximum integer value

func (*Config) GetString 

func (c *Config) GetString(s string, options ...ExpandOptions) string

GetString functions like viper.GetString on a Config instance, but additionally calls ExpandString with the configuration value, passing any "values" maps

func (*Config) GetStringMapString 

func (c *Config) GetStringMapString(s string, options ...ExpandOptions) (m map[string]string)

GetStringMapString functions like viper.GetStringMapString on a Config instance but additionally calls ExpandString on each value element of the map, passing any "values" maps

func (*Config) GetStringSlice 

func (c *Config) GetStringSlice(s string, options ...ExpandOptions) (slice []string)

GetStringSlice functions like viper.GetStringSlice on a Config instance but additionally calls ExpandString on each element of the slice, passing any "values" maps

func (*Config) Join added in v1.5.0 

func (c *Config) Join(parts ...string) string

Join returns a configuration settings key joined with the delimiter for the c config object.

func (*Config) MergeHOCONConfig added in v1.4.1 

func (c *Config) MergeHOCONConfig(conf string) (err error)

MergeHOCONConfig parses the HOCON configuration in conf and merges the results into the cf *config.Config object

func (*Config) MergeHOCONFile added in v1.4.1 

func (c *Config) MergeHOCONFile(path string) (err error)

MergeHOCONFile reads a HOCON configuration file in path and merges the settings into the cf *config.Config object

func (*Config) ReadRCConfig added in v1.5.0 

func (cf *Config) ReadRCConfig(r host.Host, path 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 (*Config) Save added in v1.5.0 

func (cf *Config) Save(name string, options ...FileOptions) (err error)

Save a configuration file for the component name. The filesystem target for the configuration object is updated to match the remote destination, which can be set by SaveTo() or defaults to "localhost"

func (*Config) SetKeyValues added in v1.5.0 

func (c *Config) SetKeyValues(items ...string)

SetKeyValues takes a list of `key=value` pairs as strings and applies them to the config object. Any item without an `=` is skipped.

func (*Config) SetStringMapString added in v1.4.3 

func (c *Config) SetStringMapString(m string, vals map[string]string)

SetMap iterates over a map[string]string and sets each key to the value given. Viper's Set() doesn't support maps until the configuration is written to and read back from a file.

func (*Config) Sub 

func (c *Config) Sub(key string) *Config

Sub returns a Config instance rooted at the key passed

type Credentials added in v1.5.0 

type Credentials struct {
	Domain       string `json:"domain,omitempty"`
	Username     string `json:"username,omitempty"`
	Password     string `json:"password,omitempty"`
	ClientID     string `json:"client_id,omitempty"`
	ClientSecret string `json:"client_secret,omitempty"`
	Token        string `json:"token,omitempty"`
	Renewal      string `json:"renewal,omitempty"`
}

Credentials can carry a number of different credential types. Add more as required. Eventually this will go into memguard.

type ExpandOptions added in v1.4.1 

type ExpandOptions func(*expandOptions)

ExpandOptions control the way configuration options undergo string expansion through the underlying ExpandString functions. ExpandOptions can be passed to any of the normal lookup functions that are provided to override viper versions, such as GetString.

e.g. 

s := config.GetString("config.value", ExternalLookups(false), LookupTable(configMap), Prefix("myconf", myFunc))

func Default added in v1.4.3 

func Default(value any) ExpandOptions

Default sets a default value to be returned if the resulting expansion of the whole config value is empty (after any optional trimming of leading and trailing spaces). This includes cases where external lookups fail or a configuration item is not found. If TrimSpace is false and the returned value consists wholly of whitespace then this is returned and not the default given here.

func Expressions added in v1.4.1 

func Expressions(yes bool) ExpandOptions

Expressions enables or disables the built-in expansion for expressions via the `github.com/maja42/goval` package. The default is false.

func ExternalLookups added in v1.4.1 

func ExternalLookups(yes bool) ExpandOptions

ExternalLookups enables or disables the built-in expansion options that fetch data from outside the program, such as URLs and file paths. The default is true.

func LookupTable added in v1.4.1 

func LookupTable(values map[string]string) ExpandOptions

LookupTable adds a lookup map to the Expand functions. If there are no maps defined then `${item}` is looked up as an environment variable. When string expansion is done to a plain word, ie. without a prefix, then `${item}` is looked up in each map, in the order the LookupTable options are given, and first match, if any, wins. If there is no match in any of the lookup maps then a nil value is returned and the environment variables are not checked.

func NoExpand added in v1.5.0 

func NoExpand() ExpandOptions

NoExpand overrides all other options except Default and returns the value (or the default) as-is with no expansion applied. This is to allow the normal functions and methods to be called but to receive the underlying configuration item, such as an encoded password.

func Prefix added in v1.4.1 

func Prefix(prefix string, fn func(*Config, string, bool) (string, error)) ExpandOptions

Prefix defines a custom mapping for the given prefix to an expand-like function. The prefix should not include the terminating ":". If the configuration prefix matches during expansion then the function is called with the config data and the contents of the expansion including the prefix (for URLs) but stripped of the opening `${` and closing `}`

func TrimPrefix added in v1.4.1 

func TrimPrefix() ExpandOptions

TrimPrefix enables the removal of the prefix from the string passed to expansion functions. If this is not set then URLs can be passed as-is since the prefix is part of the URL. If set then URLs would need the schema explicitly added after the prefix. Using this option allows standard function like strings.ToUpper to be used without additional wrappers.

func TrimSpace added in v1.4.3 

func TrimSpace(yes bool) ExpandOptions

TrimSpace enables the removal of leading and trailing spaces on all values in an expansion. The default is `true`. If a default value is given using the Default() then this is never trimmed.

type FileOptions added in v1.5.0 

type FileOptions func(*fileOptions)

FileOptions can be passed to the Load function to influence it's behaviour.

func AddConfigDirs 

func AddConfigDirs(paths ...string) FileOptions

AddConfigDirs adds paths as directories to search for the configuration and defaults files. Directories are searched in the order given, and any directories added with this option are checked before any built-in list. This option can be given multiple times and each call appends to the existing list.

func Host added in v1.5.0 

func Host(r host.Host) FileOptions

Host sets the source/destination for the configuration file. It defaults to localhost

func IgnoreSystemDir 

func IgnoreSystemDir() FileOptions

IgnoreSystemDir tells Load() not to search in the system configuration directory. This only applies on UNIX-like systems and is normally `/etc` and a sub-directory of AppName.

func IgnoreUserConfDir 

func IgnoreUserConfDir() FileOptions

IgnoreUserConfDir tells Load not to search under the user config directory. The user configuration directory is as per os.UserConfDir

func IgnoreWorkingDir 

func IgnoreWorkingDir() FileOptions

IgnoreWorkingDir tells Load not to search the working directory of the process for configuration files. This should be used when the caller may be running from an unknown or untrusted location.

func KeyDelimiter added in v1.5.0 

func KeyDelimiter(delimiter string) FileOptions

KeyDelimiter sets the delimiter for keys in the configuration loaded with Load. This can only be changed at the time of creation of the configuration object so will not apply if used with SetGlobal().

func LoadDir added in v1.5.0 

func LoadDir(dir string) FileOptions

LoadDir sets the only directory to search for the configuration files. It disables searching in the working directory, the user config directory and the system directory.

func MergeSettings added in v1.4.1 

func MergeSettings() FileOptions

MergeSettings change the default behaviour of Load which is to load the first configuration file found, instead loading each configuration file found and merging the settings together. Merging is done using viper.MergeConfigMap and should result in the last definition of each configuration item being used.

MergeSettings applies to both default and main settings, but separately, i.e. all defaults are first merged and applied then the main configuration files are merged and loaded.

func MustExist added in v1.5.0 

func MustExist() FileOptions

MustExist makes Load() return an error if the configuration file is not found. This does not apply to defaults.

func SaveDir added in v1.5.0 

func SaveDir(dir string) FileOptions

SaveDir sets the parent / top-most configuration directory to save the configuration. The configuration is saved in a sub-directory named after the application name.

func SetAppName 

func SetAppName(name string) FileOptions

SetAppName overrides to use of the Load `name` argument as the application name, `AppName`, which is used for sub-directories while `name` is used as the prefix for files in those directories.

For example, if Load is called like this: 

Load("myprogram", config.SetAppName("basename"))

Then one valid location of a configuration file would be: 

${HOME}/.config/basename/myprogram.yaml

func SetConfigFile 

func SetConfigFile(path string) FileOptions

SetConfigFile forces Load to load only the configuration at the given path. This path must include the file extension. Defaults are still loaded from all the normal directories unless [IgnoreDefaults] is also passed as an option.

If the argument is an empty string then the option is not used. This also means it can be called with a command line flag value which can default to an empty string

func SetDefaults 

func SetDefaults(defaults []byte, format string) FileOptions

SetDefaults takes a []byte slice and a format type to set configuration defaults. This can be used in conjunction with `embed` to set embedded default configuration values so that a program can function without a configuration file, e.g. 

//go:embed "defaults.yaml"
var defaults []byte
...
c, err := config.Load("appname", config.SetDefaults(defaults, "yaml"))

func SetFileFormat added in v1.5.0 

func SetFileFormat(extension string) FileOptions

SetFileFormat sets the file format for the configuration. If the type is not set and the configuration file loaded has an extension then that is used. This appliles to both defaults and main configuration files (but not embedded defaults). The default is "json".

func SetGlobal added in v1.5.0 

func SetGlobal() FileOptions

SetGlobal tells Load to set values in the global configuration structure instead of creating a new one. The global configuration is then returned by Load.

func UseDefaults added in v1.4.1 

func UseDefaults(b bool) FileOptions

UseDefaults tells Load whether to load defaults or not. The default is true. Defaults are loaded from a file with the same name as the main on but with an extra `.defaults` suffix before the extension, i.e. for `config.yaml` the defaults file would be `config.defaults.yaml` but it is searched in all the directories and may be located elsewhere to the main configuration.

type KeyFile added in v1.5.0 

type KeyFile string

KeyFile is a type that represents the path to a keyfile

func (*KeyFile) Base added in v1.5.0 

func (k *KeyFile) Base() string

Base returns the last component of the file path to keyfile

func (*KeyFile) Check added in v1.5.0 

func (k *KeyFile) Check(create bool) (crc32 uint32, created bool, err error)

Check will return the CRC32 checksum of the keyfile at path. If the file does not exist and create is true then a new keyfile will be created along with any intermediate directories and the checksum of the new file will be returned. On error the checksum is undefined and err will be set appropriately. If create is true then directories and a file may have been created even on error.

func (*KeyFile) Concat added in v1.5.0 

func (k *KeyFile) Concat(extras ...string) string

Concat returns a path made up of the path to the keyfile concatenated with extras. No separators are added. Typical use is to construct a backup file path for an existing keyfile.

func (*KeyFile) Decode added in v1.5.0 

func (k *KeyFile) Decode(input []byte) (plaintext []byte, err error)

Decode input as a byte slice using keyfile and return byte slice plaintext. An error is returned if the keyfile is not readable.

func (*KeyFile) DecodeEnclave added in v1.5.0 

func (k *KeyFile) DecodeEnclave(input []byte) (plaintext *memguard.Enclave, err error)

func (*KeyFile) DecodeString added in v1.5.0 

func (k *KeyFile) DecodeString(input string) (plaintext string, err error)

Decode input as a string using keyfile and return plaintext. An error is returned if the keyfile is not readable.

func (*KeyFile) Dir added in v1.5.0 

func (k *KeyFile) Dir() string

Dir returns the path to the directory containing keyfile

func (*KeyFile) Encode added in v1.5.0 

func (k *KeyFile) Encode(plaintext *memguard.Enclave, expandable bool) (out []byte, err error)

Encode encodes the plaintext using the keyfile. The encoded password is returned in `Geneos AES256` format, with the `+encs+` prefix, unless expandable is set to true in which case it is returned in a format that can be used with the Expand function and includes a reference to the keyfile.

If the keyfile is located under the user's configuration directory, as defined by UserConfigDir, then the function will replace any home directory prefix with `~/' to shorten the keyfile path.

func (*KeyFile) EncodePasswordInput added in v1.5.0 

func (k *KeyFile) EncodePasswordInput(expandable bool) (out string, err error)

EncodePasswordInput prompts the user for a password and again to verify, offering up to three attempts until the password match. When the two match the plaintext is encoded using the keyfile. If expandable is true then the encoded password is returned in a format useable by the Expand function which includes a path to the keyfile used at the time.

func (*KeyFile) EncodeString added in v1.5.0 

func (k *KeyFile) EncodeString(plaintext string, expandable bool) (out string, err error)

EncodeString encodes the plaintext using the keyfile. The encoded password is returned in `Geneos AES256` format, with the `+encs+` prefix, unless expandable is set to true in which case it is returned in a format that can be used with the Expand function and includes a reference to the keyfile.

If the keyfile is located under the user's configuration directory, as defined by UserConfigDir, then the function will replace any home directory prefix with `~/' to shorten the keyfile path.

func (*KeyFile) Read added in v1.5.0 

func (k *KeyFile) Read() (kv *KeyValues, err error)

Read returns an KeyValues struct populated with the contents of the file passed as path. If the keyfile is not in a valid format and err is returned.

func (*KeyFile) RollKeyfile added in v1.5.0 

func (k *KeyFile) RollKeyfile(backup string) (crc uint32, err error)

RollKeyfile will create a new keyfile at path. It will backup any existing file with the suffix backup unless backup is an empty string, in which case any existing file is overwritten and no backup made.

func (*KeyFile) Set added in v1.5.0 

func (k *KeyFile) Set(value string) error

Set is required to satisfy the pflag Values interface

func (*KeyFile) String added in v1.5.0 

func (k *KeyFile) String() string

String returns the path to the keyfile as a string

func (*KeyFile) Type added in v1.5.0 

func (k *KeyFile) Type() string

Type is required to satisfy the pflag Values interface

func (*KeyFile) Write added in v1.5.0 

func (k *KeyFile) Write(kv KeyValues) (err error)

type KeyValues added in v1.5.0 

type KeyValues struct {
	*memguard.Enclave
}

KeyValues contains the values required to create a Geneos Gateway AES key file and then to encode and decode AES passwords in configurations. It is handled as a memguard Enclave to protect the plaintext as much as possible.

func NewKeyValues added in v1.5.0 

func NewKeyValues() (kv *KeyValues)

func NewRandomKeyValues added in v1.5.0 

func NewRandomKeyValues() (kv *KeyValues)

NewRandomKeyValues returns a new KeyValues structure with a key and iv generated using the memguard.

func Read added in v1.5.0 

func Read(r io.Reader) (kv *KeyValues)

Read KeyValues from the io.Reader r and return a locked buffer keyvalues kv. m should be destroyed after use.

func (*KeyValues) Checksum added in v1.5.0 

func (kv *KeyValues) Checksum() (c uint32, err error)

Checksum returns the CRC32 checksum of the KeyValues

func (*KeyValues) Decode added in v1.5.0 

func (kv *KeyValues) Decode(in []byte) (out []byte, err error)

Decode returns the decoded value of in bytes using the KeyValues given as the method receiver. Any prefix of "+encs+" is trimmed before decode. If decoding fails then out is returned empty and err will contain the reason.

func (*KeyValues) DecodeEnclave added in v1.5.0 

func (kv *KeyValues) DecodeEnclave(in []byte) (out *memguard.Enclave, err error)

func (*KeyValues) DecodeString added in v1.5.0 

func (kv *KeyValues) DecodeString(in string) (out string, err error)

DecodeString returns plaintext of the input or an error

func (*KeyValues) Encode added in v1.5.0 

func (kv *KeyValues) Encode(in *memguard.Enclave) (out []byte, err error)

func (*KeyValues) EncodeString added in v1.5.0 

func (kv *KeyValues) EncodeString(in string) (out string, err error)

func (*KeyValues) String added in v1.5.0 

func (kv *KeyValues) String() string

String method for KeyValues

The output is in the format for suitable for use as a gateway key file for secure passwords as described in: https://docs.itrsgroup.com/docs/geneos/current/Gateway_Reference_Guide/gateway_secure_passwords.htm

func (*KeyValues) Write added in v1.5.0 

func (kv *KeyValues) Write(w io.Writer) error

Write writes the KeyValues structure to the io.Writer.

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.