Configuration Reference

Choria is configured using a set of text files that resembles key=val files. Values in the files are ordered as a hierarchy almost like a registry with . separating levels.

File locations and names

Choria supports many files for configuration, the complexity is in the Client - for server and broker you are required to supply a file.

Client Configuration

For Clients a number of files are parsed giving you the ability to operate entirely without user level configuration or by mapping in additional configuration over the system wide ones on a per project basis.

File	Description	Behavior
~/.choriarc	Default location for user configuration	Loaded as the initial configuration, no merging with others
~/.mcollective	Backward compatible location for user configuration	Loaded as the initial configuration, no merging with others
/etc/choria/client.conf	System wide Choria client configuration	Loaded as the initial configuration, no merging with others
/usr/local/etc/choria/client.conf	System wide Choria client configuration	Loaded as the initial configuration, no merging with others
/etc/puppetlabs/mcollective/client.cfg	System wide Choria client configuration. DEPRECATED	Loaded as the initial configuration, no merging with others

In the case of the last 3 locations a set of additional files are parsed, for example if the file is /etc/choria/client.conf then all files /etc/choria/plugin.d are parsed as plugin specific configuration. See later section about plugin configuration.

After parsing the initial configuration a per-project configuration is supported by loading choria.conf in the current directory, its parent directory, its parent directory and so forth up to /choria.conf in reverse order. Settings found are merged over those from the system or user configurations.

$ choria tool config
Configuration Files:

   User Config: /etc/choria/client.conf
  Loaded Files: /etc/choria/client.conf
                /etc/choria/plugin.d/actionpolicy.cfg
                /etc/choria/plugin.d/choria.cfg
                /etc/choria/plugin.d/login.cfg
                /etc/choria/plugin.d/nrpe.cfg
                /etc/choria/plugin.d/puppet.cfg
                /home/user/temp/choria.conf
                /home/user/temp/project/choria.conf

Server and Broker Configuration

Server and Brokers require the configuration to be supplied on the CLI using --config, these will always parse plugin configuration relative to the supplied configuration.

As of version 0.20.0 the live values of a server configuration can be inspected:

$ choria req rpcutil get_config_item item=plugin.choria.agent_provider.mcorpc.libdir
Discovering nodes using the inventory method .... 27
....
Summary of Value:

   ["/opt/puppetlabs/mcollective/plugins"]: 27


Finished processing 27 / 27 hosts in 1.402s

You can also access this in discovery using Compound Filters: -S 'config_item("plugin.choria.use_srv")==true

Configuration Format

Choria configuration files are key=value pairs, they tend to be organised in a hierarchy like plugin.security.provider, this is almost like a directory tree of settings.

plugin.security.provider = puppet

Choria supports a few data types when parsing configuration according to this table:

Type	Description	Go Type
`comma_split`	List of strings split by comma with spaces around the values trimmed	`[]string`
`colon_split`	List of strings split by a colon with spaces around the values trimmed	`[]string`
`path_split`	List of strings split by the OS specific PATH separator with spaces around the values trimmed	`[]string`
`enum`	List of strings with prescribed possible values	`[]string`
`int`	A number like 1, 2, 3 etc, no quotes	`int`
`duration`	A duration such as `1h`, `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`	`time.Duration`
`duration`	Numbers where the number is processed as 1 second, so a value of `60` is `60` seconds	`time.Duration`
`string`	Any normal string	`string`
`title_string`	Strings where the first character is turned into an upper case	`string`
`path_string`	Strings used for paths that is `~` aware	`string`
`bool`	`1`,`yes`, `true`, `y`, `t` for true and `0`, `no`, `false`, `n`, `f` for false	`bool`

Reference

All the known configuration keys can be queried using the choria tool config command, there are some unknowns though due to plugins having a dynamic nature, but the bulk of the settings can be found using the CLI.

First lets look at one config options:

$ choria tool config loglevel
Configuration Files:

   User Config: /etc/choria/client.conf
  Loaded Files: /etc/choria/client.conf
                /etc/choria/plugin.d/actionpolicy.cfg
                /etc/choria/plugin.d/choria.cfg
                /etc/choria/plugin.d/login.cfg
                /etc/choria/plugin.d/nrpe.cfg
                /etc/choria/plugin.d/puppet.cfg

Configuration item: loglevel

║        Value: warn
║    Data Type: string
║   Validation: enum=debug,info,warn,error,fatal
║      Default: info
║
║ The lowest level log to add to the logfile
╙─

Here we look at all configuration keys matching loglevel (regular expression supported), it shows us that:

Current in use value is warn
It’s a string data type - could be any in the table above
It validates so that only the enum list is accepted as valid
When not specified it defaults to info
There’s a short description.

In other examples you’ll be warned if it’s a deprecated setting, and you might also find links to further information. Try choria tool config . for all the configuration options.

An online version of this reference can be found in GitHub and is always up to date.

Additionally, we can also just get a list of available options which might help you explore deeper:

$ choria tool config --list
activate_agents
classesfile
collectives
color
....
ttl

We can also filter this list using regular expressions choria tool config --list plugin

Plugin Configuration

The final piece of the puzzle is plugin configuration, you’ll notice many configuration keys are like plugin.security.provider, these are traditionally not core mcollective configuration options, you can store these in settings files per plugin.

The above could be set in /etc/choria/plugin.d/security.cfg as provider=puppet.

These files are only parsed when the configuration is not one found in a home directory.