config

package
v1.9.1 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2023 License: MIT Imports: 41 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

This package 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

View Source 
const DefaultKeyType = "ecdh"

DefaultKeyType is the default key type

Variables

View Source 
var ErrNotInteractive = errors.New("not an interactive session")

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

Functions

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

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

func CreateCertificateAndKey(template, parent *x509.Certificate, signingKeyDER, existingKeyDER *memguard.Enclave) (cert *x509.Certificate, certKeyDER *memguard.Enclave, err error)

CreateCertificateAndKey is a wrapper to create a new certificate given the signing cert and key and an optional private key to (re)use for the certificate creation. Returns a certificate and private key. Keys are usually PKCS#8 encoded and so need parsing after unsealing.

func CreateRootCert added in v1.5.1 

func CreateRootCert(h host.Host, basefilepath string, cn string, overwrite bool, keytype string) (err error)

CreateRootCert creates a new root certificate and private key and saves it with dir and file basefilepath with .pem and .key extensions. If overwrite is true then any existing certificate and key is overwritten.

func CreateSigningCert added in v1.5.1 

func CreateSigningCert(h host.Host, basefilepath string, rootbasefilepath string, cn string, overwrite bool) (err error)

CreateSigningCert creates a new signing certificate and private key with the path and file bane name basefilepath. You must provide a valid root certificate and key in rootbasefilepath. If overwrite is true than any existing cert and key are overwritten.

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 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(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 ExpandString added in v1.3.0 

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

ExpandString returns the global configuration value for input as an expanded string. The returned string is always a freshly allocated value.

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

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

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

func ExpandToLockedBuffer added in v1.5.0 

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

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

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 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 GetSliceStringMapString added in v1.6.0 

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

GetSliceStringMapString returns a slice of string maps for the key s, it iterates over all values in all maps and applies the ExpandString with the options given

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 NewPrivateKey added in v1.5.1 

func NewPrivateKey(keytype string) (der *memguard.Enclave, err error)

NewPrivateKey returns a PKCS#8 DER encoded private key as an enclave.

func ParseCertificate added in v1.7.0 

func ParseCertificate(h host.Host, certfile string) (cert *x509.Certificate, err error)

ParseCertificate reads a PEM encoded cert from path on host h, return the first found as a parsed certificate. The returned certificate is not verified or validated beyond that of the underlying Go x509 package parsing functions.

func ParseCertificates added in v1.7.0 

func ParseCertificates(h host.Host, p string) (certs []*x509.Certificate, err error)

ParseCertificates reads a PEM encoded file from host h and returns all the certificates found (using the same rules as x509.ParseCertificates). The returned certificates are not verified or validated beyond that of the underlying Go x509 package parsing functions.

func ParseKey added in v1.7.0 

func ParseKey(der *memguard.Enclave) (privateKey any, publickey crypto.PublicKey, err error)

ParseKey tries to parse the DER encoded private key enclave, first as PKCS#8 and then as a PKCS#1 and finally as SEC1 (EC) if that fails. It returns the private and public keys or an error

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 (potentially on a remote host if config.Remote() is used) 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 PrivateKeyType added in v1.8.0 

func PrivateKeyType(der *memguard.Enclave) (keytype string)

PrivateKeyType returns the type of the DER encoded private key, suitable for use to NewPrivateKey

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 and a file with the first matching basename of any other arguments is returned (this avoids the second call returning nothing).

func PublicKey added in v1.8.0 

func PublicKey(der *memguard.Enclave) (publickey crypto.PublicKey, err error)

PublicKey parses the DER encoded private key enclave and returns the public key if successful. It will first try as PKCS#8 and then PKCS#1 if that fails. Using this over the more general ParseKey() ensures the decoded private key is not returned to the caller when not required.

func ReadCertChain added in v1.8.0 

func ReadCertChain(h host.Host, p string) (pool *x509.CertPool)

ReadCertChain returns a certificate pool loaded from the file on host h at path p. If there is any error a nil pointer is returned.

func ReadCertificatePEM added in v1.9.0 

func ReadCertificatePEM(h host.Host, pt string) (data []byte, err error)

ReadCertificatePEM reads a PEM encoded certificate from file at path p on host h and returns the block

func ReadPrivateKey added in v1.7.0 

func ReadPrivateKey(h host.Host, pt string) (key *memguard.Enclave, err error)

ReadPrivateKey reads a unencrypted, PEM-encoded private key and saves the der format key in a memguard.Enclave

func ReadPrivateKeyPEM added in v1.9.0 

func ReadPrivateKeyPEM(h host.Host, pt string) (key *memguard.Enclave, err error)

ReadPrivateKeyPEM reads a unencrypted, PEM-encoded private key as a memguard Enclave

func ReadUserInput added in v1.5.0 

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

ReadUserInput reads input from Stdin and returns the input 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 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 UnmarshalKey added in v1.7.2 

func UnmarshalKey(key string, rawVal interface{}, opts ...viper.DecoderConfigOption) error

func UserConfigDir added in v1.3.2 

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

func WriteCert added in v1.5.1 

func WriteCert(h host.Host, p string, cert *x509.Certificate) (err error)

WriteCert writes cert as PEM to file p on host h

func WriteCertChain added in v1.8.0 

func WriteCertChain(h host.Host, p string, certs ...*x509.Certificate) (err error)

WriteCertChain concatenate certs and writes to path on host h

func WritePrivateKey added in v1.7.0 

func WritePrivateKey(h host.Host, pt string, key *memguard.Enclave) (err error)

WritePrivateKey writes a DER encoded private key as a PKCS#8 encoded PEM file to path on host h. sets file permissions to 0600 (before umask)

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(p string, options ...FileOptions) (creds *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) AppConfigDir added in v1.5.2 

func (c *Config) AppConfigDir() string

AppConfigDir returns the application configuration directory

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) Delimiter added in v1.8.0 

func (c *Config) Delimiter() string

Delimiter returns the config c key delimiter

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) 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 returns the configuration c value for input as an expanded string. The returned string is always a freshly allocated value.

func (*Config) ExpandStringSlice added in v1.6.0 

func (c *Config) ExpandStringSlice(input []string, options ...ExpandOptions) (vals []string)

ExpandStringSlice applies ExpandString to each member of the input slice

func (*Config) ExpandToEnclave added in v1.5.0 

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

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

func (*Config) ExpandToLockedBuffer added in v1.5.0 

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

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

func (*Config) FindCreds added in v1.5.0 

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

FindCreds finds a set of credentials in the given config under the key "credentials" and returns the longest match, if any. creds is nil if no 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) 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) GetPassword added in v1.5.0 

func (c *Config) GetPassword(key string, options ...ExpandOptions) *Plaintext

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

func (*Config) GetSliceStringMapString added in v1.6.0 

func (c *Config) GetSliceStringMapString(s string, options ...ExpandOptions) (result []map[string]string)

GetSliceStringMapString returns a slice of string maps for the key s, it iterates over all values in all maps and applies the ExpandString with the options given

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(key 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

Use a version of https://github.com/spf13/viper/pull/1504 to fix viper bug #1106

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

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

func (*Config) Save added in v1.5.0 

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

Save a configuration file for the module name.

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

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

func (*Config) UnmarshalKey added in v1.7.2 

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

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 Initial added in v1.6.6 

func Initial(value any) ExpandOptions

Initial sets an initial default value to be used if the configuration item is empty (or nil) to start. This differs from Default() 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.Default() is empty.

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

func NoDecode added in v1.5.0 

func NoDecode(n bool) ExpandOptions

NoDecode disables the expansion of encoded values.

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 or Save functions to influence behaviour.

func AddDirs added in v1.6.0 

func AddDirs(paths ...string) FileOptions

AddDirs 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 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 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 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 a configuration file is not found. This does not apply to default configuration files.

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(p 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 SetFileExtension added in v1.6.0 

func SetFileExtension(extension string) FileOptions

SetFileExtension sets the file extension and, by implication, the format for the configuration. If the type 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 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.

func UseGlobal 

func UseGlobal() FileOptions

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

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)

DecodeEnclave decodes the input using the keyfile k and returns a memguard.Enclave

func (*KeyFile) DecodeString added in v1.5.0 

func (k *KeyFile) DecodeString(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(plaintext *Plaintext, 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(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 the argument 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 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)

DecodeEnclave decodes the input using kv and returns a *memguard.Enclave

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(plaintext *Plaintext) (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 Plaintext added in v1.5.0 

type Plaintext struct {
	*memguard.Enclave
}

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

func GetPassword added in v1.5.0 

func GetPassword(s string, options ...ExpandOptions) *Plaintext

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

func NewPlaintext added in v1.5.0 

func NewPlaintext(buf []byte) *Plaintext

NewPlaintext returns a memguard Enclave initialised with buf

func ReadPasswordInput added in v1.5.0 

func ReadPasswordInput(match bool, maxtries int, prompt ...string) (plaintext *Plaintext, 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 (*Plaintext) IsNil added in v1.5.0 

func (secret *Plaintext) IsNil() bool

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

func (*Plaintext) Set added in v1.5.0 

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

Set is required to satisfy the pflag Values interface

func (*Plaintext) String added in v1.5.0 

func (secret *Plaintext) String() string

String returns the secret as a string

func (*Plaintext) Type added in v1.5.0 

func (secret *Plaintext) 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.