config

package
v1.15.0-beta Latest Latest
Warning

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

 Go to latest Published: Jun 19, 2024 License: Apache-2.0 Imports: 44 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

View Source 
const DefaultKeyType = "ecdh"

DefaultKeyType is the default key type

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

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.

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

func AllKeys() []string

func AllSettings added in v1.10.0 

func AllSettings() map[string]any

func AppConfigDir added in v1.5.2 

func AppConfigDir() string

AppConfigDir returns the application configuration directory

func AutomaticEnv added in v1.10.0 

func AutomaticEnv()

func BindEnv added in v1.10.0 

func BindEnv(input ...string) error

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

func ConfigFileUsed() string

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

func ExpandHome(p string) string

ExpandHome replaces a 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 root directory, i.e. with just the `~` removed (and cleaned).

func ExpandHomeBytes added in v1.13.2 

func ExpandHomeBytes(p []byte) []byte

ExpandHomeBytes replaces a 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 root directory, i.e. with just the `~` removed (and cleaned).

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

func ExtractCertificatePEM(h host.Host, path string) (data []byte, err error)

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

func ExtractPrivateKeyPEM added in v1.13.0 

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

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

func Get added in v1.10.0 

func Get(key string) any

func GetBool added in v1.10.0 

func GetBool(key string) bool

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

func GetDuration(key string) time.Duration

func GetFloat64 added in v1.11.0 

func GetFloat64(key string) float64

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

func GetStringMap(key string) any

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

func GetStringMapStringSlice(key string) map[string][]string

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

func GetUint(key string) uint

func GetUint16 added in v1.10.0 

func GetUint16(key string) uint16

func IsSet added in v1.10.0 

func IsSet(key string) bool

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

func MatchKey(cert *x509.Certificate, derkeys []*memguard.Enclave) int

MatchKey tests the slice derkeys of private keys against the x509 cert and returns the index of the first match, or -1 if none of the keys match.

func MergeConfigMap added in v1.10.0 

func MergeConfigMap(vals map[string]any) error

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, path string) (pool *x509.CertPool)

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

func ReadCertificates added in v1.13.0 

func ReadCertificates(h host.Host, path string) (certs []*x509.Certificate)

ReadCerts reads and decodes all certificates from the PEM file on host h at path.

func ReadInputPEMString added in v1.13.0 

func ReadInputPEMString(from, prompt string) (data string, err error)

ReadInputPEMString 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.
  • Otherwise the file at the path pointed to by `from` is read and returned

Any error when reading the input is returned.

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

func ReadPrivateKeyBytes(pembytes []byte) (key *memguard.Enclave, err error)

ReadPrivateKeyBytes looks for the first "PRIVATE KEY" in the PEM formatted data slice and returns it as a memguard enclave. If no key is found an error 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 RegisterAlias added in v1.10.0 

func RegisterAlias(alias, key string)

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

func SetDefault(key string, value any)

func SetEnvPrefix added in v1.10.0 

func SetEnvPrefix(prefix string)

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

func SetString(key, value string, options ...ExpandOptions)

SetString sets the key to the value with options applied. This applies to the global configuration struct. See the other SetString for detailed behaviour.

func SetStringMapString added in v1.4.3 

func SetStringMapString(m string, vals map[string]string, options ...ExpandOptions)

SetStringMapString 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 SetStringSlice added in v1.10.0 

func SetStringSlice(key string, values []string, options ...ExpandOptions)

SetStringSlice sets the key to a slice of strings applying the replacement options as for SetString to each member of the slice

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

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.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) (cf *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

	cf, err := config.Load("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 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 Sub added in v1.11.0 

func 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. It uses the mutex pointer from the caller so that locking of sub-config objects also applies to the original.

Note that viper.Sub() does NOT merge defaults

func (*Config) AllKeys added in v1.10.0 

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

func (*Config) AllSettings added in v1.10.0 

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

func (*Config) AppConfigDir added in v1.5.2 

func (c *Config) AppConfigDir() string

AppConfigDir returns the application configuration directory

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

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

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

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

ExpandPassword expands the input string and returns a *Plaintext. The TrimSPace option 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) Get added in v1.10.0 

func (c *Config) Get(key string) (value any)

func (*Config) GetBool added in v1.10.0 

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

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

func (c *Config) GetDuration(key string) (value time.Duration)

func (*Config) GetFloat64 added in v1.11.0 

func (c *Config) GetFloat64(key string) (value float64)

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

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

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

func (c *Config) GetStringMapStringSlice(key string) (values map[string][]string)

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

func (c *Config) GetUint(key string) (value uint)

func (*Config) GetUint16 added in v1.10.0 

func (c *Config) GetUint16(key string) (value uint16)

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

func (c *Config) Set(key string, value interface{})

Set sets the key to value

func (*Config) SetDefault added in v1.10.0 

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

func (*Config) SetEnvPrefix added in v1.10.0 

func (c *Config) SetEnvPrefix(prefix string)

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.

If the separator is either `+=` or `+` then the given value is appended to any existing setting with a space.

func (*Config) SetString added in v1.10.0 

func (c *Config) SetString(key, value string, options ...ExpandOptions)

SetString sets the key to the string given after processing options. Options include replacing substrings with configuration items that match *at the time of the SetString call*. This allows the abstraction of a static string based on the other config values given. E.g. 

cf.SetString("setup", "/path/to/myname/setup.json", config.Replace("name"))

This would check the value of the "name" key in cf and do a global replace. Multiple Replace options are processed in order. If "name" was "myname" at the time of the call then the resulting value is `/path/to/${config:name}/setup.json`

Existing expand options are left unchanged. All replacements are case sensitive.

func (*Config) SetStringMapString added in v1.4.3 

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

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

func (c *Config) SetStringSlice(key string, values []string, options ...ExpandOptions)

SetStringSlice sets the key to a slice of strings applying the replacement options as for SetString to each member of the slice

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. It uses the mutex pointer from the caller so that locking of sub-config objects also applies to the original.

Note that viper.Sub() does NOT merge defaults

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 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 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 `}`. A boolean parameter trims white space from the result if true.

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 ${home} is "/home/user" then: 

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

results in path being set to "${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(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.

func UseKeyfile added in v1.15.0 

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 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 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 SetConfigReader added in v1.9.2 

func SetConfigReader(in io.Reader) FileOptions

SetConfigReader sets Load to read the main configuration from an io.Reader in. The input is read until EOF or error.

The caller must close the reader on return.

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

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

func (k *KeyFile) DecodeEnclave(h host.Host, 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(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, 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(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 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(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) ReadOrCreate added in v1.13.0 

func (k *KeyFile) ReadOrCreate(h host.Host, create bool) (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 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 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) 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 ExpandToPassword added in v1.13.0 

func ExpandToPassword(input string, options ...ExpandOptions) *Plaintext

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

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) Bytes added in v1.12.1 

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

Bytes returns the secret as a byte slice

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.