config

Documentation

Overview

Package config with the global hub configuration struct and methods

Package hubconfig with logging configuration

Index

• Constants
• func GetOutboundIP(destination string) net.IP
• func LoadHubConfig(configFile string, clientID string, hubConfig *HubConfig) error
• func LoadYamlConfig(configFile string, config interface{}, substituteMap map[string]string) error
• func SetLogging(levelName string, filename string) error
• func SubstituteText(text string, substituteMap map[string]string) string
• func ValidateHubConfig(config *HubConfig) error
• type HubConfig
  • func CreateDefaultHubConfig(appFolder string) *HubConfig
  • func LoadAllConfig(args []string, appFolder string, clientID string, clientConfig interface{}) (*HubConfig, error)

Constants

const (
	DefaultMqttPortUnpw = 8883
	DefaultMqttPortCert = 8884
	DefaultMqttPortWS   = 8885
)

Default ports for connecting to the MQTT server

const (
	DefaultCaCertFile     = "caCert.pem"
	DefaultCaKeyFile      = "caKey.pem"
	DefaultPluginCertFile = "pluginCert.pem"
	DefaultPluginKeyFile  = "pluginKey.pem"
	DefaultServerCertFile = "serverCert.pem"
	DefaultServerKeyFile  = "serverKey.pem"
	DefaultAdminCertFile  = "adminCert.pem"
	DefaultAdminKeyFile   = "adminKey.pem"
)

Default certificate and private key file names

const DefaultBinFolder = "./bin"

DefaultBinFolder is the location of application binaries wrt installation folder

const DefaultCertsFolder = "./certs"

DefaultCertsFolder with the location of certificates

const DefaultConfigFolder = "./config"

DefaultConfigFolder is the location of config files wrt installation folder

const DefaultHubConfigName = "hub.yaml"

DefaultHubConfigName with the configuration file name of the hub

const DefaultLogsFolder = "./logs"

DefaultLogsFolder is the location of log files wrt wrt installation folder

const DefaultMqttTimeout = 3

const DefaultThingZone = "local"

DefaultThingZone is the zone the hub's things are published in.

Functions

func GetOutboundIP

func GetOutboundIP(destination string) net.IP

GetOutboundIP gets the default outbound IP address to reach the given hostname. Use a local hostname if a subnet other than the default one should be used. Use "" for the default route address

destination to reach or "" to use 1.1.1.1 (no connection will be established)

func LoadHubConfig

func LoadHubConfig(configFile string, clientID string, hubConfig *HubConfig) error

LoadHubConfig loads and validates the global hub configuration; loads certificates and sets logging. Intended to be used after CreateDefaultHubConfig()

Each client loads the global hub.yaml configuration. The following variables can be used in this file:

  {clientID}  is the device or plugin instance ID. Used for logfile and client cert
  {appFolder} is the default application folder (parent of application binary)
  {certsFolder} is the default certificate folder
  {configFolder} is the default configuration folder
  {logsFolder} is the default logging folder

configFile is optional. By default this loads hub.yaml in the default config folder of hubConfig.

Returns the hub configuration and error code in case of error

func LoadYamlConfig

func LoadYamlConfig(configFile string, config interface{}, substituteMap map[string]string) error

LoadYamlConfig loads a yaml configuration from file and substitutes keywords variables with values from the provided map.

This function doesn't really care what a keyword looks like but as convention "${name}" is used. If the keyword is not present in the given map then it will remain unchanged in the configFile.

configFile path to yaml configuration file
config interface to typed structure matching the config. Must have yaml tags
substituteMap map to substitude keys with value from map, nil to ignore

Returns nil if successful

func SetLogging

func SetLogging(levelName string, filename string) error

SetLogging sets the logging level and output file This sets the timeFormat to ISO8601 YYYY-MM-DDTHH:MM:SS.sss-TZ Intended for standardize logging in the hub and plugins

levelName is the requested logging level: error, warning, info, debug
filename is the output log file full name including path, use "" for stderr

func SubstituteText

func SubstituteText(text string, substituteMap map[string]string) string

SubstituteText substitutes template strings in the text This substitutes configuration values in the format ${name} with the given variable from the map. This format is compatible with JS templates. This is kept simple by requiring the full template keyword in the replacement map, eg use "${name}" and not "name" as the key in the map.

text to substitude template strings, eg "hello ${name}"
substituteMap with replacement keywords, eg {"${destination}":"world"}

Returns text with template strings replaced

func ValidateHubConfig

func ValidateHubConfig(config *HubConfig) error

ValidateHubConfig checks if values in the hub configuration are correct Returns an error if the config is invalid

Types

type HubConfig

type HubConfig struct {

	// Server address of auth, idprov, mqtt, directory services. The default "" is the outbound IP address
	// If DNS is used override this with the server domain name.
	// Clients that use the hubconfig must override this with the discovered server address as provided by idprov
	Address string `yaml:"address,omitempty"`
	// MQTT TLS port for certificate based authentication. Default is DefaultMqttPortCert
	MqttPortCert int `yaml:"mqttPortCert,omitempty"`
	// MQTT TLS port for login/password authentication. Default is DefaultMqttPortUnpw
	MqttPortUnpw int `yaml:"mqttPortUnpw,omitempty"`
	// Websocket TLS port for login/password authentication. Default is DefaultMqttPortWS
	MqttPortWS int `yaml:"mqttPortWS,omitempty"`
	// plugin mqtt connection timeout in seconds. 0 for indefinite. Default is DefaultMqttTimeout (3 sec)
	MqttTimeout int `yaml:"mqttTimeout,omitempty"`

	// Zone that published Things belong to. Default is 'local'
	// Zones are useful for separating devices from Hubs on large networks. Normally 'local' is sufficient.
	//
	// When Things are bridged, the bridge can be configured to replace the zone by that of the bridge.
	// This is intended for access control to Things from a different zone.
	Zone string `yaml:"zone"`

	// Files and Folders
	Loglevel    string `yaml:"logLevel"`    // debug, info, warning, error. Default is warning
	LogsFolder  string `yaml:"logsFolder"`  // location of Wost log files
	LogFile     string `yaml:"logFile"`     // log filename is pluginID.log
	AppFolder   string `yaml:"appFolder"`   // Folder containing the application installation
	BinFolder   string `yaml:"binFolder"`   // Folder containing plugin binaries, default is {appFolder}/bin
	CertsFolder string `yaml:"certsFolder"` // Folder containing certificates, default is {appFolder}/certsclient
	// ConfigFolder the location of additional configuration files. Default is {appFolder}/config
	ConfigFolder string `yaml:"configFolder"`

	// Keep server certificate on startup. Default is false
	// enable to keep using access tokens between restarts
	KeepServerCertOnStartup bool `yaml:"keepServerCertOnStartup"`

	// path to CA certificate in PEM format. Default is certsclient/caCert.pem
	CaCertPath string `yaml:"caCertPath"`
	// path to client x509 certificate in PEM format. Default is certsclient/{clientID}Cert.pem
	ClientCertPath string `yaml:"clientCertPath"`
	// path to client private key in PEM format. Default is certsclient/{clientID}Key.pem
	ClientKeyPath string `yaml:"clientKeyPath"`
	// path to plugin client x509 certificate in PEM format. Default is certsclient/PluginCert.pem
	PluginCertPath string `yaml:"pluginCertPath"`
	// path to plugin client private key in PEM format. Default is certsclient/PluginKey.pem
	PluginKeyPath string `yaml:"pluginKeyPath"`

	// CaCert contains the loaded CA certificate needed for establishing trusted connections to the
	// MQTT message bus and other services. Loading takes place in LoadHubConfig()
	CaCert *x509.Certificate

	// ClientCert contains the loaded TLS client certificate and key if available.
	// Loading takes place in LoadHubConfig()
	// * For plugins this is the plugin certificate and private key
	// * For servers this is the server certificate and private key
	// * For devices this is the provisioned device certificate and private key
	ClientCert *tls.Certificate

	// PluginCert contains the TLS client certificate for use by plugins
	// Intended for use by plugin clients. This is nil of the plugin certificate is not available or accessible
	// Loading takes place in LoadHubConfig()
	PluginCert *tls.Certificate
}

HubConfig contains the global configuration for using the Hub by its clients.

Intended for use by:

1. Hub plugins that needs to know the location of files, certificates and service address and ports
2. Remote devices or services that uses a local copy of the hub config for manual configuration of certificates MQTT server address and ports.

func CreateDefaultHubConfig

func CreateDefaultHubConfig(appFolder string) *HubConfig

CreateDefaultHubConfig with default values appFolder is the hub installation folder and home to plugins, logs and configuration folders. Use "" for default: parent of application binary When relative path is given, it is relative to the application binary

See also LoadHubConfig to load the actual configuration including certificates.

func LoadAllConfig

func LoadAllConfig(args []string, appFolder string, clientID string, clientConfig interface{}) (*HubConfig, error)

LoadAllConfig is a helper to load all configuration from commandline, hubconfig and client config This:

1. Determine application defaults

2. parse commandline arguments for options -c hub.yaml -a appFolder or -h

3. Load the hub global configuration file hub.yaml, if found

4. Load the client configuration file {clientID}.yaml, if found

   args is the os.argv list. Use nil to ignore commandline args appFolder is the installation folder, "" for default parent folder of app binary clientID is the server, plugin or device instance ID. Used when connecting to servers clientConfig is an instance of the client's configuration object

This returns the hub global configuration with an error if something went wrong