General Configuration¶

Managing LinchPin requires a few configuration files. Beyond linchpin.conf, there are a few other configurations that are checked . When running linchpin, four different locations are checked for linchpin.conf files. Files are checked in the following order:

linchpin/library/path/linchpin.conf
/etc/linchpin.conf
~/.config/linchpin/linchpin.conf
path/to/workspace/linchpin.conf

The LinchPin configuration parser supports overriding and extension of configurations. Therefore, the existing configuration files are read. If linchpin finds the same configuration section header in more than one file, the header that was parsed more recently will provide the configuration for that section. In this way user can override the general configurations. Commonly, this is done by placing a linchpin.conf in the root of the workspace.

Adding a Section¶

Adding a section to the configuration is simple. The best approach is to create a linchpin.conf in the appropriate location from the locations above.

Once created, add a section. The section can be a new section, or it can overwrite an existing section.

[lp]
# move the rundb_connection to a global scope
rundb_conn = %(default_config_path)s/rundb/rundb-::mac::.json

module_folder = library

rundb_type = TinyRunDB
rundb_conn_type = file
rundb_schema = {"action": "",
                "inputs": [],
                "outputs": [],
                "start": "",
                "end": "",
                "rc": 0,
                "uhash": ""}
rundb_hash = sha256

dateformat = %%m/%%d/%%Y %%I:%%M:%%S %%p
default_pinfile = PinFile

For instance above, the configuration has been updated to use a different path to the rundb_conn. This section now uses a system-wide RunDB, which can be useful to some.

Warning

If overwriting a section, all entries from the entire section must be updated.

Note

A common thing to do is to put the items updated at the top of the new section. It may even be a good idea to add a comment stating why it was updated.

Useful Configuration Options¶

These are some configuration options that may be useful to adjust for your needs. Each configuration option listed here is in a format of section.option.

Note

For clarity, this would appear in a configuration file where the section is in brackets (eg. [section]) and the option would have a option = value set within the section.

lp.external_providers_path

New in version 1.5.0

Default value: %(default_config_path)s/linchpin-x

Providers playbooks can be created outside of the core of linchpin, if desired. When using these external providers, linchpin will use the external_providers_path to lookup the playbooks and attempt to run them.

See Providers for more information.

lp.rundb_conn

New in version 1.2.0

Default value:

v1.2.0: /home/user/.config/linchpin/rundb-<macaddress>.json
v1.2.2+: /path/to/workspace/.rundb/rundb.json

The RunDB is a single json file, which records each transaction involving resources. A run_id and uHash are assigned, along with other useful information. The lp.rundb_conn describes the location to store the RunDB so data can be retrieved during execution.

evars._async

Updated in version 1.2.0

Default value: False

Previous key name: evars.async

Some providers (eg. openstack, aws, ovirt) support asynchronous provisioning. This means that a topology containing many resources would provision or destroy all at once. LinchPin then waits for responses from these asynchronous tasks, and returns the success or failure. If the amount of resources is large, asynchronous tasks reduce the wait time immensely.

Reason for change: Avoiding conflict with existing Ansible variable.

Starting in Ansible 2.4.x, the async variable could not be set internally. The _async value is now passed in and sets the Ansible async variable to its value.

evars.default_credentials_path

Default value: %(default_config_path)s

Storing credentials for multiple providers can be useful. It also may be useful to change the default here to point to a given location.

Note

The --creds-path option, or $CREDS_PATH environment variable overrides this option

evars.inventory_file

Default value: None

If the unique-hash feature is turned on, the default inventory_file value is built up by combining the workspace path, inventories_folder topology_name, the uhash, and the extensions.inventory configuration value. The resulting file might look like this:

It may be desired to store the inventory without the uhash, or define a completely different structure altogether.

ansible.console

Default value: False

This configuration option controls whether the output from the Ansible console is printed. In the linchpin CLI tool, it’s the equivalent of the -v (--verbose) option.