config

package
v1.26.1 Latest Latest
Warning

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

 Go to latest Published: Apr 24, 2026 License: Apache-2.0 Imports: 38 Imported by: 1

README

config package

The config package extends viper with local customisations.

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.

Credentials

Credentials are supported with memguard Enclaves and LockedBuffers. There are methods:

Expandable Formats

The documentation below is reproduced from the source comments for expand.go and should be kept in-sync by package maintainers (using go doc pkg/config as the primary source).

Expandable Formats

The Expand family of functions return 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:", disable 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 is 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.

    This prefix can be disabled with the config.NoDecode() option.

    Note: The keyfile(s) can be in Windows file path format as the fields for keyfiles and the encoded value are split based on the last colon (:) in the string and not any contained in a drive letter path. On Windows paths may also contain normal backslashes, they are not considered escape characters once extracted from the underlying configuration syntax (which may impose it's own rules, e.g. JSON)

    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 Expand*() 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)

    For Windows file paths you must use the URL style ${file:...} formats, otherwise any drive identifier will be treated as a partial expansion type and cause unexpected behaviour.

    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 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) will 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.

Documentation

Overview

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

Expandable Formats

The Expand family of functions return 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:", disable 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 is 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].

  This prefix can be disabled with the `config.NoDecode()` option.

  Note: The keyfile(s) can be in Windows file path format as the
  fields for keyfiles and the encoded value are split based on the
  last colon (`:`) in the string and not any contained in a drive
  letter path. On Windows paths may also contain normal backslashes,
  they are not considered escape characters once extracted from the
  underlying configuration syntax (which may impose it's own rules,
  e.g. JSON)

  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)

  For Windows file paths you must use the URL style `${file:...}`
  formats, otherwise any drive identifier will be treated as a
  partial expansion type and cause unexpected behaviour.

  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 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) will 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.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNoUserConfigDir = errors.New("cannot resolve user config directory, check $USER and $HOME exist")
View Source 
var ErrNotInteractive = errors.New("not an interactive session")

ErrNotInteractive is returned when input is required and STDIN is a named pipe

View Source 
var ExpandFieldsHook = func(opts ...ExpandOptions) mapstructure.DecodeHookFunc {
	return func(f reflect.Type, t reflect.Type, data any) (any, error) {
		if f.Kind() != reflect.String {
			return data, nil
		}

		str := data.(string)

		return expand[string](global, str, opts...), nil
	}
}

ExpandFieldsHook returns a mapstructure.DecodeHookFunc that expands string fields using the config.ExpandString function with the options given. This is intended to be used in Unmarshal calls to allow for dynamic values in the configuration file. The hook will only expand string fields, and will leave other types unchanged.

Functions

func AbbreviateHome added in v1.13.0 

func AbbreviateHome(p string) string

AbbreviateHome replaces the user's home directory prefix on path p with `~/` and cleans the result. If the home directory is not present, or there is an error resolving it, then a cleaned copy of the original string is returned. If the result is am empty string, return "."

func AddCreds added in v1.5.0 

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

AddCreds adds credentials 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 AppConfigDir added in v1.5.2 

func AppConfigDir() string

AppConfigDir returns the application configuration directory for the global configuration

func Checksum 

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

Checksum reads from io.Reader data until EOF (or other error) 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 DefaultFileExtension added in v1.6.0 

func DefaultFileExtension(extension string)

DefaultFileExtension sets the default file extension for all future calls to config.New() and config.Load(). The initial default is "json"

func DefaultKeyDelimiter added in v1.5.0 

func DefaultKeyDelimiter(delimiter string)

DefaultKeyDelimiter sets the default key delimiter for all future calls to config.New() and config.Load(). The default is ".". You can use "::" if your keys are likely to contain "." such as domains, ipv4 addresses or version numbers. Use something else if keys are likely to be ipv6 addresses.

func Delete added in v1.26.1 

func Delete(c *Config, key string)

func DeleteAllCreds added in v1.5.0 

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

DeleteAllCreds will remove all the credentials in the credentials file identified by options.

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 identified by options.

func Delimiter added in v1.8.0 

func Delimiter() string

Delimiter returns the global config key delimiter

func Expand added in v1.4.1 

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

func ExpandStringSlice added in v1.6.0 

func ExpandStringSlice(input []string, options ...ExpandOptions) []string

ExpandStringSlice applies ExpandString to each member of the input slice

func Get added in v1.10.0 

func Get[T any](c *Config, key string, options ...ExpandOptions) (value T)

Get returns the value associated with the key in the configuration structure c, applying the options given. The type T is the expected type of the value, which can be one of:

  • bool
  • int
  • int64
  • uint
  • uint16
  • float64
  • string
  • []string
  • []byte
  • map[string]any
  • map[string]string
  • []map[string]string
  • time.Duration
  • *config.Secret

Other types are returned as-is and the caller is expected to do any necessary type assertion. Other specific types may be added in the future.

If the option [`config.Default`] is used, then the type must be identical to T. If it is not, then the default value is the zero value for the type T.

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 Lookup added in v1.26.1 

func Lookup[T any](c *Config, key string, options ...ExpandOptions) (value T, found bool)

func MigrateFile added in v1.14.2 

func MigrateFile(h host.Host, newPath string, oldPaths ...string) (dest string)

MigrateFile iterates over newPath and oldPaths and finds the first regular file that exists. If this is not newPath then the found file is renamed to the newPath. The resulting oldPath is returned.

If the newPath is an empty string then no rename takes place and the path of the first existing regular file is returned. If the newPath is a directory then the file is moved into that directory through a rename operation and a file with the first matching basename of any other arguments is returned (this avoids the second call returning nothing). Any empty strings in oldPaths is ignored.

func Path added in v1.5.0 

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

Path returns the full path to the that would be opened by Load given the same options.

If the config.MustExist() option is used then configuration files are tested for readability and the first matching path, base on other options, is returned.

If no file is found but internal default have been defined then the string "internal defaults" is returned.

If no internal defaults are defined then the string "none" is returned (unless config.MustExist() is used, in which case an empty string is returned).

func ReadPEM added in v1.26.1 

func ReadPEM(from, prompt string) (data []byte, err error)

ReadPEM reads and returns a PEM formatted input (without validation) from one of these sources:

  • If `from` is empty then an empty string is returned
  • If `from` is a dash (`-`) then data is read from STDIN the after the user is prompted with `Paste PEM formatted [PROMPT], end with newline + CTRL-D:` where `[PROMPT]` is taken from the prompt argument.
  • If `from` has the prefix `pem:` then the data is taken from the remainder of the argument.
  • If `from` has the prefix `http://` or `https://` then the data is fetched from the URL pointed to by `from` using an HTTP GET request.
  • Otherwise the file at the path pointed to by `from` is read and returned

Any error when reading the input is returned.

func ReadUserInputLine added in v1.13.0 

func ReadUserInputLine(format string, args ...any) (input string, err error)

ReadUserInputLine reads input from Stdin and returns the line unless there is an error. The prompt is made up from format and args (passed to fmt.Sprintf) and then shown to the user as-is. If STDIN is a named pipe (and not interactive) then a syscall.ENOTTY is returned.

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 ResolveHome added in v1.26.1 

func ResolveHome(p string) string

ResolveHome replaces any leading `~/` on p with the user's home directory. If p does not have a prefix of `~/` then a cleaned copy is returned. If there is an error resolving the user's home directory then the path is returned relative to the working directory, i.e. with just the `~/` removed (and cleaned).

func Set added in v1.5.0 

func Set[T any](c *Config, key string, value T, options ...ExpandOptions)

func UserConfigDir added in v1.3.2 

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

UserConfigDir returns the configuration directory for username, or is none given then the current user. If os.UserConfigDir() fails then we lookup the user and return a path relative to the homedir (which works around empty environments)

func UserHomeDir added in v1.11.0 

func UserHomeDir(username ...string) (home string, err error)

UserHomeDir returns the home directory for username, or if none given then the current user. This works around empty environments by falling back to looking up the user.

Types

type Config 

type Config struct {
	// contains filtered or unexported fields
}

Config structure

func FindCreds added in v1.5.0 

func FindCreds(p string, options ...FileOptions) (creds *Config)

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

func Global added in v1.4.1 

func Global() *Config

Global returns the global Config instance

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 Read added in v1.5.0 

func Read(module string, options ...FileOptions) (cf *Config, err error)

Read reads configuration values for module from internal defaults, external defaults and configuration files or an io.Reader. The directories searched and the configuration file names can be controlled using options. The first match is read and returned 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.Read("geneos", config.SetGlobal())

//go:embed somefile.json
var myDefaults []byte

cf, err := config.Read("geneos",
  config.WithDefaults(myDefaults, "json"),
  config.SetConfigFile(configPath),
)
if err != nil {
  ...

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".

Is the SetConfigReader() option is passed to load the configuration from an io.Reader then this takes precedence over file discovery or SetConfigFile(). The configuration file format should be set with SetFileExtension() or it defaults as above.

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) AllKeys added in v1.10.0 

func (c *Config) AllKeys() (keys []string)

AllKeys returns a slice of all the keys in the configuration, excluding any that have been marked as deleted. The keys are returned in sorted order.

func (*Config) AllSettings added in v1.10.0 

func (c *Config) AllSettings() (value map[string]any)

AllSettings returns a map of all the settings in the configuration, excluding any that have been marked as deleted. Only the top-level keys are returned, i.e. nested keys are not included and are in the value from the map.

To return all the keys and values, use AllKeys to get the keys and then Get to get the values for each key.

func (*Config) AppConfigDir added in v1.5.2 

func (c *Config) AppConfigDir() string

AppConfigDir returns the application configuration directory for c

func (*Config) AutomaticEnv added in v1.10.0 

func (c *Config) AutomaticEnv()

func (*Config) BindEnv added in v1.10.0 

func (c *Config) BindEnv(input ...string) (err error)

func (*Config) BindPFlag added in v1.26.1 

func (c *Config) BindPFlag(key string, flag *pflag.Flag) (err error)

BindPFlag binds a pflag.Flag to a key in the configuration.

func (*Config) ConfigFileUsed added in v1.10.0 

func (c *Config) ConfigFileUsed() (f string)

func (*Config) ConfigType added in v1.26.1 

func (c *Config) ConfigType() string

func (*Config) Default added in v1.26.1 

func (c *Config) Default(key string, value any)

func (*Config) Delimiter added in v1.8.0 

func (c *Config) Delimiter() string

Delimiter returns the config c key delimiter

func (*Config) ExpandAllSettings 

func (c *Config) ExpandAllSettings(options ...ExpandOptions) (all map[string]any)

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) ExpandToPassword added in v1.13.0 

func (c *Config) ExpandToPassword(input string, options ...ExpandOptions) *Secret

ExpandPassword expands the input string and returns a *Secret. The TrimSPace option is ignored.

func (*Config) FindCreds added in v1.5.0 

func (c *Config) FindCreds(p string) (creds *Config)

FindCreds finds a set of credentials in the given config under the key "credentials" and returns the longest case-insensitive match, if any. The domains in the credentials file can use shell patterns, as per `file.Match()`. creds is nil if no matching credentials found.

func (*Config) IsSet added in v1.10.0 

func (c *Config) IsSet(key string) (value bool)

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) MergeConfigMap added in v1.10.0 

func (c *Config) MergeConfigMap(vals map[string]any) (err error)

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(p string) (err error)

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

func (*Config) RegisterAlias added in v1.10.0 

func (c *Config) RegisterAlias(alias, key string)

func (*Config) SetConfigType added in v1.26.1 

func (c *Config) SetConfigType(t string)

func (*Config) SetDefaultExpandOptions added in v1.26.1 

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

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

func (*Config) SetEnvPrefix added in v1.10.0 

func (c *Config) SetEnvPrefix(prefix string)

func (*Config) SetKeyValuePairs added in v1.26.1 

func (c *Config) SetKeyValuePairs(items ...string) (err error)

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

If the separator is either `+=` or `+` then the given value is appended to any existing setting. If the value is starts with a dash then it is considered a command line option and is appended with a space separator, otherwise it is simply concatenated.

func (*Config) Sub 

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

Sub returns a Config instance rooted at the key passed. If key does not exist then an empty config structure is returned, unlike viper which returns nil.

Note that viper.Sub() does NOT merge defaults

func (*Config) UnmarshalKey added in v1.7.2 

func (c *Config) UnmarshalKey(key string, rawVal any, opts ...viper.DecoderConfigOption) error

func (*Config) Write added in v1.26.1 

func (c *Config) Write(module string, options ...FileOptions) (err error)

Write a configuration file for the named module.

The configuration can be written to an io.Writer, using config.Writer() option, or to a file determined by the following order of precedence:

  • The file specified by config.SetConfigFile()
  • A file name.ext in the first directory give with config.AddDirs()
  • A file name.ext in the user config directory + appname

The filesystem target for the configuration object is updated to match the remote destination, which can be set by Host() option with a default of "localhost"

Write writes to a temporary file with the process ID and original extension appended and then tries to atomically rename the file to the target name. This is to avoid leaving a partially written file if the write operation is interrupted. It may result in a temporary file being left behind if the rename operation fails, but this is preferable to leaving a corrupted configuration file. The temporary file is named with the process ID to avoid conflicts with other processes that may be writing to the same configuration file. The original extension is preserved to ensure that the temporary file is recognized as a configuration file by any tools that may be monitoring the directory for changes.

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 DefaultValue added in v1.26.1 

func DefaultValue(value any) ExpandOptions

DefaultValue sets a default value to be returned if the resulting expansion of the config key is the zero value for the type (after any optional trimming of leading and trailing spaces).

The type of the default value must be the same as the type of the configuration item being used, otherwise the default value is ignored. e.g. 

config.Get[uint16]("config.value", config.DefaultValue(uint16(1234)))

func ExpandNonStringToCSV added in v1.14.2 

func ExpandNonStringToCSV() ExpandOptions

ExpandNonStringToCSV causes any non-string configuration item expansions of lists to return a comma-separated list of any strings in that list. Non-string values are skipped.

func ExpandNonStringToJSON added in v1.14.2 

func ExpandNonStringToJSON() ExpandOptions

ExpandNonStringToJSON causes any non-string configuration expansions to be returned as a JSON encoded string of the item

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 InitialValue added in v1.26.1 

func InitialValue(value any) ExpandOptions

InitialValue sets an initial value to be used if the configuration item is empty (or nil) to start. This differs from DefaultValue() which supplies a value to use if the value if empty after expansion. The initial value, if used, is expanded as would any configuration value.

If config.NoExpand() is also used then this initial value is used as a secondary default - i.e. if config.DefaultValue() is empty.

func LookupTable added in v1.4.1 

func LookupTable(values ...map[string]string) ExpandOptions

LookupTable adds lookup maps, of name/value pairs, to the Expand functions. If there are no lookup tables defined then `${item}` is treated 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 environment variables are not checked.

func LookupTables deprecated added in v1.6.0 

func LookupTables(values []map[string]string) ExpandOptions

LookupTables sets the expansion lookup tables to the slice of maps passed as values. Any existing lookup tables are discarded.

Deprecated: Use the singular LookupTable with a variadic list of tables instead.

func NoDecode added in v1.5.0 

func NoDecode(n bool) ExpandOptions

NoDecode disables the expansion of encoded (`enc:`) values. Use this option if you want the expanded value of the configuration item but without decoding sensitive data such as secrets and passwords.

func NoExpand added in v1.5.0 

func NoExpand() ExpandOptions

NoExpand overrides all other options except DefaultValue() and InitialValue() and returns the value 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(configItems map[string]any, name string, trim 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 as a map[string]any, and the contents of the expansion including the prefix (for URLs) but stripped of the opening `${` and closing `}`. A boolean parameter trims white space from the final result if true.

The function MUST NOT call other configuration functions or lock the configuration mutex as the calling function will have already done so. The function should return an error if the prefix matches but the value is invalid for any reason, such as a network error when fetching a URL or a missing file when fetching from the file system.

func Replace added in v1.10.0 

func Replace(name string) ExpandOptions

Replace is used by config.Set* (except config.Set itself) functions to replace substrings with the formatted configuration item given as name with an equivalent expand string, where the value of the name key is only tested as Set time.

e.g. if ${config:home} is "/home/user" then: 

config.SetString("path", "/home/user/file.txt", config.Replace("home"))

results in path being set to "${config:home}/file.txt" for future expansion, as "home" may change

Replace can be used multiple times, each name being checked in order.

Expand strings in the value are never substituted.

name is not checked for self-referencing

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(trim 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.

func UseKeyfile added in v1.14.2 

func UseKeyfile(file string) ExpandOptions

UseKeyfile overrides the path to the embedded keyfile in the `${enc:/path:xxx}` value. This can be useful when the keyfile is placed in an alternative location.

type FileOptions added in v1.5.0 

type FileOptions func(*fileOptions)

FileOptions can be passed to the Load or Save functions to set values.

func AppName added in v1.26.1 

func AppName(name string) FileOptions

AppName 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.AppName("basename"))

Then one valid location of a configuration file would be: 

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

func DefaultExpandOptions added in v1.26.1 

func DefaultExpandOptions(options ...ExpandOptions) FileOptions

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 DefaultsFrom added in v1.26.1 

func DefaultsFrom(cf *Config) FileOptions

func ExpandOnSave added in v1.26.1 

func ExpandOnSave(options ...ExpandOptions) FileOptions

ExpandOnSave tells Save to pass the configuration through config.Expand before writing it to the file. This allows for dynamic values in the configuration to be expanded on save, for example to include values from the environment or from other configuration items. This is off by default, and the configuration is saved as-is.

Typically used with SaveTo() to write to an io.Writer such as os.Stdout or a remote host, where the configuration is not being read back in and so does not need to be expanded on load.

func FilePath added in v1.26.1 

func FilePath(p string) FileOptions

FilePath forces config.Read() to load only the configuration at the given path or config.Write() to only write to this path (unless config.Writer() is also given). This path must include the file extension. Defaults are still loaded from all the normal directories unless config.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 Format added in v1.26.1 

func Format(extension string) FileOptions

Format sets the expected file extension and, by implication, the format for the configuration. If this is not set and the configuration file loaded has an extension then that is used. This applies to both defaults and main configuration files (but not embedded defaults). The default is "json". Any leading "." is ignored.

func FromDir added in v1.6.0 

func FromDir(dir string) FileOptions

FromDir 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 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 IgnoreKeys added in v1.26.1 

func IgnoreKeys(keys ...string) FileOptions

IgnoreKeys tells config.Write() to ignore the specified keys when writing the configuration. This is empty by default, and all keys are written regardless of their name.

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 MergeSources added in v1.26.1 

func MergeSources() FileOptions

MergeSources 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.

MergeSources 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 sets config.Read() or config.Path() to return an error if the main configuration file is not found.

func OmitEmptyValues added in v1.26.1 

func OmitEmptyValues() FileOptions

OmitEmptyValues tells config.Write() to ignore any keys with empty values when writing the configuration. This is false by default, and all keys are written regardless of their value. This can be useful to avoid writing empty values to a configuration file, which can help to keep the file clean and easier to read.

func Reader added in v1.26.1 

func Reader(in io.Reader) FileOptions

Reader sets the source for the main configuration from io.Reader in. The input is read until EOF or error.

The caller must close the reader on return.

func SearchDirs added in v1.26.1 

func SearchDirs(paths ...string) FileOptions

SearchDirs 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 SkipSystemDir added in v1.26.1 

func SkipSystemDir() FileOptions

SkipSystemDir tells config.Read() 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 SkipUserConfDir added in v1.26.1 

func SkipUserConfDir() FileOptions

SkipUserConfDir tells config.Read() not to search under the user config directory. The user configuration directory is as per os.UserConfDir

func SkipWorkingDir added in v1.26.1 

func SkipWorkingDir() FileOptions

SkipWorkingDir tells config.Read() 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 StopOnInternalDefaultsErrors added in v1.12.1 

func StopOnInternalDefaultsErrors() FileOptions

StopOnInternalDefaultsErrors returns an error if the internal defaults cause a parsing error. This can be because the file contains repeated keys or has format errors for the chosen format. Off by default, and errors in the defaults are ignored.

func UseDefaults added in v1.4.1 

func UseDefaults(b bool) FileOptions

UseDefaults tells Read 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.

func UseGlobal 

func UseGlobal() FileOptions

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

func WatchConfig added in v1.10.0 

func WatchConfig(notify ...func(fsnotify.Event)) FileOptions

WatchConfig enables the underlying viper instance to watch the finally loaded config file. Is disabled if MergeSettings() is used. Using this option is not concurrency safe on future calls to config methods, use carefully.

If a notify function is specified then this is passed to viper.OnConfigChange. Only the first notify function is used.

func WithDefaults added in v1.7.0 

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

WithDefaults 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.WithDefaults(defaults, "yaml"))

func WithEnvs added in v1.7.0 

func WithEnvs(prefix string, delimiter string) FileOptions

WithEnvs enables the use of environment variables using viper's AutomaticEnv() functionality. If empty delimiter defaults to an underscore.

func Writer added in v1.26.1 

func Writer(out io.Writer) FileOptions

Writer sets the destination for the configuration file to an io.Writer. This overrides any file paths or directories set by other options.

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) 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) CreateWithBackup added in v1.13.0 

func (k *KeyFile) CreateWithBackup(h host.Host, backup string) (crc uint32, err error)

CreateWithBackup will create a new keyfile at path. It will rename any existing file with backup appended to the filename before the extension, unless backup is an empty string, in which case any existing file is overwritten and no backup made.

func (*KeyFile) Decode added in v1.5.0 

func (k *KeyFile) Decode(h host.Host, 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) DecodeString added in v1.5.0 

func (k *KeyFile) DecodeString(h host.Host, input string) (plaintext string, err error)

DecodeString decodes the 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(h host.Host, secret *Secret, expandable bool) (out string, 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(h host.Host, 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 secret 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(h host.Host, 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(h host.Host) (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) ReadCRC added in v1.14.2 

func (k *KeyFile) ReadCRC(h host.Host) (crc32 uint32, err error)

ReadCRC will return the CRC32 checksum of an existing keyfile, or an error if the file cannot be read.

func (*KeyFile) ReadOrCreate added in v1.13.0 

func (k *KeyFile) ReadOrCreate(h host.Host) (crc32 uint32, created bool, err error)

ReadOrCreate will either return the CRC32 checksum of an existing keyfile or, if the file does not exist and create is true then a keyfile will be created with new contents along with any intermediate directories, and the checksum of the new file will be returned. On error the checksum is undefined and err will indicate why. If create is true then directories and a file may have been created even on error.

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(h host.Host, 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 secret as much as possible.

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 ReadKeyValues added in v1.11.0 

func ReadKeyValues(r io.Reader) (kv *KeyValues, err error)

ReadKeyValues from the io.Reader r and return a locked buffer key values kv.

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) ChecksumString added in v1.13.0 

func (kv *KeyValues) ChecksumString() (c string, 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) 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(secret *Secret) (out []byte, err error)

Encode the plaintext using kv, return a byte slice

func (*KeyValues) EncodeString added in v1.5.0 

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

EncodeString encodes the plaintext string using kv, return as a string

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.

type Secret added in v1.26.1 

type Secret struct {
	*memguard.Enclave
}

Secret is a type that represents a plaintext string that should be protected

func NewSecret added in v1.26.1 

func NewSecret[T string | []byte](buf T) *Secret

NewSecret returns a memguard Enclave initialised with buf. The contents of buf are destroyed.

func ReadPasswordInput added in v1.5.0 

func ReadPasswordInput(match bool, maxtries int, prompt ...string) (secret *Secret, 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 Destroy()ed.

If STDIN is not a terminal then config.ErrNotInteractive is returned.

func (*Secret) Bytes added in v1.26.1 

func (secret *Secret) Bytes() []byte

Bytes returns the secret as a byte slice. After use, call memguard.WipeBytes() on the buffer

func (*Secret) IsNil added in v1.26.1 

func (secret *Secret) IsNil() bool

IsNil returns true if the secret or the underlying memguard Enclave is nil

func (*Secret) Set added in v1.26.1 

func (secret *Secret) Set(value string) error

Set is required to satisfy the pflag Values interface

func (*Secret) String added in v1.26.1 

func (secret *Secret) String() string

String returns the secret as a string. Use Bytes() where possible and memguard.WipeBytes() after use. This method retruns a cloned string for those cases there a downstream API requires a credential as a string value. In Go you can't securely zero strings after use.

func (*Secret) Type added in v1.26.1 

func (secret *Secret) Type() string

Type is required to satisfy the pflag Values interface

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.