README
¶
config package
The config package wraps the common viper methods and types but adds some custom processing.
This probably could be done using custom decode hooks for viper, but I have not had time to understand them in detail.
Using a wrapper also allows custom methods on config for further functionality.
Unless the file format is given to LoadConfig then all the viper formats are supported.
Expansion of values
The following package functions and type methods are overridden to add expansion of embedded strings of the form ${name} and $name:
The string values are passed to ExpandString which supports a range of data substitutions.
Documentation
¶
Overview ¶
Package config adds support for value expansion over viper based configurations.
A number of the most common access methods from viper are replaced with local versions that add support for ExpandString. Additionally, there are a number of functions to simplify programs including LoadConfig.
Index ¶
- func Checksum(r io.Reader) (c uint32, err error)
- func ChecksumFile(path string) (c uint32, err error)
- func ChecksumString(in string) (c uint32, err error)
- func ExpandString(input string, values ...map[string]string) (value string)
- func GetString(s string, values ...map[string]string) string
- func GetStringMapString(s string, values ...map[string]string) map[string]string
- func GetStringSlice(s string, values ...map[string]string) []string
- func UserConfigDir(username ...string) (path string, err error)
- type AESValues
- func (a *AESValues) Checksum() (c uint32, err error)
- func (a AESValues) DecodeAES(in []byte) (out []byte, err error)
- func (a AESValues) DecodeAESString(in string) (out string, err error)
- func (a AESValues) EncodeAES(in []byte) (out []byte, err error)
- func (a AESValues) EncodeAESString(in string) (out string, err error)
- func (a AESValues) String() string
- func (a AESValues) WriteAESValues(w io.Writer) error
- type Config
- func (c *Config) ExpandAllSettings(values ...map[string]string) (all map[string]interface{})
- func (c *Config) ExpandString(input string, values ...map[string]string) (value string)
- func (c *Config) GetString(s string, values ...map[string]string) string
- func (c *Config) GetStringMapString(s string, values ...map[string]string) (m map[string]string)
- func (c *Config) GetStringSlice(s string, values ...map[string]string) (slice []string)
- func (c *Config) Sub(key string) *Config
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ChecksumFile ¶
func ChecksumString ¶
func ExpandString ¶ added in v1.3.0
ExpandString returns the input with all occurrences of the form ${name} replaced using an os.Expand-like function (but without support for bare names) for the formats (in the order of priority) below. It operates on the global config instance, referencing any other configuration values in the global package context.
${enc:keyfile[|keyfile...]:encodedvalue}
The item "encodedvalue" is an AES256 ciphertext in Geneos format
- or a reference to 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.
The "encodedvalue" must be either prefixed "+encs+" to align with
Geneos or will otherwise be looked up using the forms of any of
the other references below, but without the surrounding
dollar-brackets "${...}".
To minimise (but not wholly eliminate) any false-positive decodes
that occur in some circumstances when using the wrong key file,
the decoded value is only returned if it is a valid UTF-8 string
as per [utf8.Valid].
Examples:
* password: ${enc:~/.keyfile:+encs+9F2C3871E105EC21E4F0D5A7921A937D}
* password: ${enc:/etc/geneos/keyfile.aes:env:ENCODED_PASSWORD}
* password: ${enc:~/.config/geneos/keyfile1.aes:app.password}
* password: ${enc:~/.keyfile.aes:config:mySecret}
${config:key} or ${path.to.config}
Fetch the "key" configuration value (for single layered
configurations, where a sub-level dot cannot be used) or if any
value containing one or more dots "." will be looked-up in the
existing configuration that the method is called on. The
underlying configuration is not changed and values are resolved
each time ExpandString() is called. No locking of the
configuration is done.
${key}
"key" will be substituted with the value of the first matching
key from the maps "values...", in the order passed to the
function. If no "values" are passed (as opposed to the key not
being found in any of the maps) then name is looked up
as an environment variable, as 4. below.
${env:name}
"name" will be substituted with the contents of the environment
variable of the same name.
${~/file} or ${/path/to/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.
Examples:
* certfile ${file://etc/ssl/cert.pem}
* template: ${file:~/templates/autogen.gotmpl}
${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 bare form "$name" is NOT supported, unlike os.Expand as this can unexpectedly match values containing valid literal dollar signs.
Expansion is not recursive. Configuration values are read and stored as literals and are expanded each time they are used. For each substitution any leading and trailing whitespace are removed. External sources are fetched each time they are used and so there may be a performance impact as well as the value unexpectedly changing during a process lifetime.
Any errors (particularly from substitutions from external files or remote URLs) may result in an empty or corrupt string being returned. Error returns are intentionally discarded and an empty string substituted. Where a value contains multiple expandable items processing will continue even after an error for one of them.
It is not currently possible to escape the syntax supported by ExpandString and if it is necessary to have a configuration value be a literal of the form "${name}" then you can set an otherwise unused item to the value and refer to it using the dotted syntax, e.g. for YAML
config:
real: ${config.literal}
literal: "${unchanged}"
In the above a reference to ${config.real} will return the literal string ${unchanged} as there is no recursive lookups.
func GetString ¶
GetString functions like viper.GetString but additionally calls ExpandString with the configuration value, passing any "values" maps
func GetStringMapString ¶
GetStringMapString functions like viper.GetStringMapString but additionally calls ExpandString on each value element of the map, passing any "values" maps
func GetStringSlice ¶
GetStringSlice functions like viper.GetStringSlice but additionally calls ExpandString on each element of the slice, passing any "values" maps
func UserConfigDir ¶ added in v1.3.2
Types ¶
type AESValues ¶
An AESValues structure contains the values required to create a Geneos Gateway AES key file and then to encode and decode AES passwords in configurations
func NewAESValues ¶
NewAESValues returns a new AESValues structure or an error
func ReadAESValues ¶
ReadAESValues returns an AESValues struct populated with the contents read from r. The caller must close the Reader on return.
func ReadAESValuesFile ¶
ReadAESValuesFile returns an AESValues struct populated with the contents of the file passed as path.
func (AESValues) DecodeAESString ¶
DecodeAESString returns a plain text of the input or an error
func (AESValues) EncodeAESString ¶
func (AESValues) String ¶
String method for AESValues
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
type Config ¶
Config embeds Viper and also exposes the config type used
func LoadConfig ¶
LoadConfig loads configuration files from internal defaults, external defaults and the given configuration file. The configuration file can be passed as an option. Each layer is only loaded once, if given. Internal defaults are passed as a byte slice - this is typically loaded from an embedded file but can be supplied from any source. External defaults and the main configuration file are passed as ordered slices of strings. The first match is loaded.
LoadConfig("geneos")
//go:embed somefile.json
var myDefaults []byte
LoadConfig("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 ... find windows equiv
func (*Config) ExpandAllSettings ¶
ExpandAllSettings returns all the settings from c applying ExpandString() to all string values and all string slice values. "values" maps are passed to ExpandString as-is. Further types may be added over time.
func (*Config) ExpandString ¶
ExpandString works just like the package level ExpandString but on a specific config instance.
func (*Config) GetString ¶
GetString functions like viper.GetString on a Config instance, but additionally calls ExpandString with the configuration value, passing any "values" maps
func (*Config) GetStringMapString ¶
GetStringMapString functions like viper.GetStringMapString on a Config instance but additionally calls ExpandString on each value element of the map, passing any "values" maps
func (*Config) GetStringSlice ¶
GetStringSlice functions like viper.GetStringSlice on a Config instance but additionally calls ExpandString on each element of the slice, passing any "values" maps
type Options ¶
type Options func(*configOptions)
func AddConfigDirs ¶
AddConfigDirs() adds one or more directories to search for the configuration and defaults files. Directories are searched in FIFO order, so any directories given are checked before the built-in list. This option can be given multiple times as each call only appends to the list which has already bee initialised.
func IgnoreSystemDir ¶
func IgnoreSystemDir() Options
IgnoreSystemDir() tells LoadConfig() not to search in the system configuration directory. This only applies on UNIX-like systems and is normally /etc/[AppName]
func IgnoreUserConfDir ¶
func IgnoreUserConfDir() Options
IgnoreUserConfDir() tells LoadConfig() not to search under the user config directory (The user config directory is as per Go os.UserConfDir() and a sub-directory of AppName)
func IgnoreWorkingDir ¶
func IgnoreWorkingDir() Options
IgnoreWorkingDir() tells LoadConfig not to search the working directory for configuration files. This should be used when the caller may be running in an unknown or untrusted location.
func SetAppName ¶
SetAppName() overrides to mapping of the configName to the application name. AppName is used for directories while configName is used for the files in those directories.
func SetConfigFile ¶
SetConfigFile() allows the caller to override the searching for a config file in the given directories and instead loads only the given file (after defaults are loaded as normal).
func SetDefaults ¶
SetDefaults() takes a []byte slice and a format type to set defaults
Source Files