Configuration File

Below is full coverage of each of the sections of the values available in linchpin.conf.

Getting the most current configuration

If you are installing LinchPin from a package manager (pip or RPM), the latest linchpin.conf is already included in the library.

An example linchpin.conf is available on Github.

For in-depth details of all the options, see the Configuration Reference document.

Environmental Variables

LinchPin allows configuration adjustments via environment variables in some cases. If these environment variables are set, they will take precedence over any settings in the configuration file.

A full listing of available environment variables, see the Configuration Reference document.

Command Line Options

Some configuration options are also present in the command line. Settings passed via the command line will override those passed through the configuration file and the environment.

The full list of options is covered in the Commands (CLI) document.

Values by Section

The configuration file is broken into sections. Each section controls a specific functionality in LinchPin.

General Defaults

The following settings are in the [DEFAULT] section of the linchpin.conf

Warning

The configurations in this section should NOT be changed unless you know what you are doing.

pkg

This defines the package name. Many components base paths and other information from this setting.

pkg = linchpin

default_config_path

New in version 1.2.0

Where configuration files might land, such as the workspaces.conf, or credentials. Generally used in combination with other configurations.

default_config_path = ~/.config/linchpin

external_providers_path

New in version 1.5.0

Developers can provide additional provider playbooks and schemas. This configuration is used to set the path(s) to look for additional providers.

external_providers_path = %(default_config_path)s/linchpin-x

The following settings are in the [init] section of the linchpin.conf

source

Source path of files provided for the linchpin init command.

source = templates/

pinfile

Formal name of the PinFile. Can be changed as desired.

pinfile = PinFile

The following settings are in the [lp] section of the linchpin.conf

module_folder

Load custom ansible modules from this directory

module_folder = library

rundb_type

New in version 1.2.0

RunDB supports additional drivers, currently the only driver is TinyRunDB, based upon tinydb.

rundb_type = TinyRunDB

rundb_conn

New in version 1.2.0

The resource path to the RunDB connection. The TinyRunDB version (default) is a file.

Default: {{ workspace }}/.rundb/rundb.json

The configuration file has this option commented out. Uncommenting it could enable a system-central rundb, if desired.

#rundb_conn = %(default_config_path)s/rundb/rundb-::mac::.json

rundb_conn_type

New in version 1.2.0

Set this value if the RunDB resource is anything but a file. This setting is linked to the rundb_conn configuration.

rundb_conn_type = file

rundb_conn_schema

New in version 1.2.0

The schema used to store records in the TinyRunDb. Many other databases will likely not use this value, but must honor the configuration item.

rundb_schema = {"action": "",
                "inputs": [],
                "outputs": [],
                "start": "",
                "end": "",
                "rc": 0,
                "uhash": ""}

rundb_hash

New in version 1.2.0

Hashing algorithm used to create the uHash.

rundb_hash = sha256

dateformat

New in version 1.2.0

The dateformat to use when writing out start and end times to the RunDB.

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

default_pinfile

New in version 1.2.0

The dateformat to use when writing out start and end times to the RunDB.

default_pinfile = PinFile

Extra Vars

The following settings are in the [evars] section of the linchpin.conf

LinchPin sets several extra_vars values, which are passed to the provisioning playbooks.

Note

Default paths in playbooks exist. lp_path = <src_dir>/linchpin determined in the load_config method of linchpin.cli.LinchpinCliContext if either of these change, the value in linchpin/templates must also change

_check_mode

Enables the Ansible check_mode, or Dry Run functionality. Most provisioners currently DO NOT support this option

_check_mode = False

_async

LinchPin supports the Ansible async mode for certain Providers. Setting async = True here enables the feature.

_async = False

async_timeout

Works in conjunction with the async setting, defaulting the async wait time to {{ async_timeout }} in provider playbooks

async_timeout = 1000

enable_uhash

In older versions of Linchpin, the uhash value was not used. If set to true, the unique-ish hash (uhash) will be appended to instances (for providers who support naming) and the inventory_path.

enable_uhash = False

generate_resources

In older versions of linchpin (<v1.0.4), a resources folder exists, which dumped the data that is now stored in the RunDB.

generate_resources = True

output

Deprecated in version 1.2.0 Removed in version 1.5.0

Horribly named variable, no longer used

output = True

layouts_folder

Used in lookup for a specific layout within a workspace. The PinFile specifies the layout without a path, this is the relative location.

Also used in combination with default_layouts_path <conf_def_layout_path>, which isn’t generally used.

layouts_folder = layouts

topologies_folder

Used in lookup for a specific topology within a workspace. The PinFile specifies the topology without a path, this is the relative location.

Also used in combination with default_topologies_path<conf_def_topo_path>, which isn’t generally used.

topologies_folder = topologies

roles_folder

New in version 1.5.0

Used in combination with default_roles_path <conf_def_roles_path> for external provider roles

roles_folder = roles

inventories_folder

Relative location where inventories will be written. Usually combined with the default_inventories_path, but could be relative tothe workspace.

_check_mode = False

inventories_folder = inventories

hooks_folder

Relative location within the workspace where hooks data is stored

hooks_folder = hooks

resources_folder

Deprecated in version 1.5.0

Relative location of the resources destination path. Generally combined with the default_resource_path

resources_folder = resources

schemas_folder

Deprecated in version 1.2.0

Relative location of the schemas within the LinchPin codebase

schemas_folder = schemas

playbooks_folder

Relative location of the Ansible playbooks and roles within the LinchPin codebase

playbooks_folder = provision

default_schemas_path

Deprecated in version 1.5.0

Used to locate default schemas, usually schema_v4 or schema_v3

default_schemas_path = {{ lp_path }}/defaults/%(schemas_folder)s

default_topologies_path

Deprecated in version 1.2.0

Default location for topologies in cases where topology or topology_file is not set.

default_topologies_path = {{ lp_path }}/defaults/%(topologies_folder)s

default_layouts_path

Deprecated in version 1.2.0

When inventories are processed, layouts are looked up here if layout_file is not set

default_layouts_path = {{ lp_path }}/defaults/%(layouts_folder)s

default_inventories_path

Deprecated in version 1.2.0

When writing out inventories, this path is used if inventory_file is not set

default_inventories_path = {{ lp_path }}/defaults/%(inventories_folder)s

default_resources_path

Deprecated in version 1.2.0

When writing out resources files, this path is used if inventory_file is not set

default_inventories_path = {{ lp_path }}/defaults/%(inventories_folder)s

default_roles_path

When using an external provider, this path points back to some of the core roles needed in the provider’s playbook.

default_roles_path = {{ lp_path }}/%(playbooks_folder)s/%(roles_folder)s

default_roles_path = {{ lp_path }}/%(playbooks_folder)s/%(roles_folder)s

schema_v3

Deprecated in v1.5.0

Full path to the location of the schema_v3.json file, which is used to perform validation of the topology.

_check_mode = False

schema_v3 = %(default_schemas_path)s/schema_v3.json

schema_v4

Deprecated in v1.5.0

Full path to the location of the schema_v4.json file, which is used to perform validation of the topology.

schema_v4 = %(default_schemas_path)s/schema_v4.json

default_credentials_path

If the --creds-path option or $CREDS_PATH environment variable are not set, use this location to look up credentials files defined in a topology.

default_credentials_path = %(default_config_path)s

inventory_path

New in version 1.5.0

The inventory_path is used to set the value of the resulting inventory file which is generated by LinchPin. This value is dynamically generated by default.

Note

This should not be confused with the inventory_file which is an input to the LinchPin ansible playbooks.

#inventory_path = {{ workspace }}/{{inventories_folder}}/happy.inventory

default_ssh_key_path

New in version 1.2.0

Used solely in the libvirt provider <prov_libvirt>. Could be used to set a default location for ssh keys that might be passed via a cloud-config setup.

default_ssh_key_path = ~/.ssh

libvirt_image_path

Where to store the libvirt images for copying/booting instances. This can be adjusted to a user accessible location if permissions are an issue.

Note

Ensure the libvirt_user and libvirt_become options below are also adjusted according to proper permissions.

libvirt_image_path = /var/lib/libvirt/images/

libvirt_user

What user to use to access the libvirt services.

Note

Specifying root means that linchpin will attempt to access the libvirt service as the root user. If the linchpin user is not root, sudo without password must be setup.

libvirt_user = root

libvirt_become

When using root or any privileged user, this must be set to yes.

Note

If the linchpin user is not root, sudo without password must also be setup.

libvirt_become = yes

Initialization Settings

The following settings are in the [init] section of the linchpin.conf.

These settings specifically pertain to linchpin init, which stores templates in the source code to generate a simple example workspace.

source

Location of templates stored in the source code. The structure is built to resemble the directory structure explained in linchpin init.

source = templates/

pinfile

Formal name of the PinFile. Can be changed as desired.

pinfile = PinFile

Logger Settings

The following settings are in the [logger] section of the linchpin.conf.

Note

These settings are ONLY used for the Command Line Interface. The API configures a console output only logger and expects the functionality to be overwritten in subclasses.

enable

Whether logging to a file is enabled

enable = True

file

Name of the file to write the log. A relative or full path is acceptable.

file = linchpin.log

format

The format in which logs are written. See https://docs.python.org/2/library/logging.html#logrecord-attributes for more detail and available options.

format = %%(levelname)s %%(asctime)s %%(message)s

dateformat

How to display the date in logs. See https://docs.python.org/2/library/datetime.html#strftime-strptime-behavior for more detail and available options.

Note

This action was never implemented.

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

level

Default logging level

level = logging.DEBUG

The following settings are in the [console] section of the linchpin.conf.

Each of these settings is for logging output to the console, except for Ansible output.

format

The format in which console output is written. See https://docs.python.org/2/library/logging.html#logrecord-attributes for more detail and available options.

format = %%(message)s

level

Default logging level

level = logging.INFO

Hooks Settings

The following settings are in the [states] section of the linchpin.conf.

These settings define the state names, which are useful in hooks.

preup

Define the name of the so called preup state. This state is set and executed prior to the ‘up’ action being called, but after the PinFile data is loaded.

preup = preup

predestroy

Define the name of the so called predestroy state. This state is set and executed prior to the ‘destroy’ action being called, but after the PinFile data is loaded.

predestroy = predestroy

postup

Define the name of the so called postup state. This state is set and executed after to the ‘up’ action is completed, and after the postinv state is executed.

postup = postup

postdestroy = postdestroy ~~

Define the name of the so called postdestroy state. This state is set and executed after to the ‘destroy’ action is completed.

postdestroy = postdestroy

postinv

Define the name of the so called postinv state. This state is set and executed after to the ‘up’ action is completed, and before the postup state is executed. This is eventually going to be the inventory generation hook.

postinv = inventory

The following settings are in the [hookstates] section of the linchpin.conf.

These settings define the ‘STATES’ each action uses in hooks.

up

For the ‘up’ action, types of hook states are available for execution

up = pre,post,inv

destroy

For the ‘destroy’ action, types of hook states are available for execution

destroy = pre,post

inv

New in version 1.2.0

For the inventory generation, which only happens on an ‘up’ state.

Note

The postinv state currently doesn’t do anything. In the future, it will provide a way to generate inventories besides the standard Ansible static inventory.

inv = post

File Extensions

The following settings are in the [extensions] section of the linchpin.conf.

These settings define the file extensions certain files have..

resource

Deprecated in version 1.2.0

Removed in version 1.5.0

When generating resource output files, append this extension

resource = .output

inventory

When generating Ansible static inventory files, append this extension

inventory = .inventory

playbooks

New in version 1.5.0

Since playbooks fundamentially changed between v1.2.0 and v1.5.0, this option was added for looking up a provider playbook. It’s unlikely this value will change.

playbooks = .yml

Playbook Settings

The following settings are in the [playbooks] section of the linchpin.conf.

Note

The entirety of this section is removed in version 1.5.0+. The redesign of the LinchPin API now calls individual playbooks based upon the resource_group_type value.

up

Removed in version 1.5.0

Name of the playbook associated with the ‘up’ (provision) action

up = site.yml

destroy

Removed in version 1.5.0

Name of the playbook associated with the ‘destroy’ (teardown) action

destroy = site.yml

down

Removed in version 1.5.0

Name of the playbook associated with the ‘down’ (halt) action

Note

This action has not been implemented.

down = site.yml

schema_check

Removed in version 1.5.0

Name of the playbook associated with the ‘schema_check’ action.

Note

This action was never implemented.

schema_check = schemacheck.yml

inv_gen

Removed in version 1.5.0

Name of the playbook associated with the ‘inv_gen’ action.

Note

This action was never implemented.

inv_gen = invgen.yml

test

Removed in version 1.5.0

Name of the playbook associated with the ‘test’ action.

Note

This action was never implemented.

test = test.yml

See also

User Mailing List
Subscribe and participate. A great place for Q&A
irc.freenode.net
#linchpin IRC chat channel