Configuration File¶
Topics
- Configuration File
- Getting the most current configuration
- Environmental Variables
- Command Line Options
- Values by Section
- General Defaults
- Extra Vars
- _check_mode
- _async
- async_timeout
- enable_uhash
- generate_resources
- output
- layouts_folder
- topologies_folder
- roles_folder
- inventories_folder
- hooks_folder
- resources_folder
- schemas_folder
- playbooks_folder
- default_schemas_path
- default_topologies_path
- default_layouts_path
- default_inventories_path
- default_resources_path
- default_roles_path
- schema_v3
- schema_v4
- default_credentials_path
- inventory_path
- default_ssh_key_path
- libvirt_image_path
- libvirt_user
- libvirt_become
- Initialization Settings
- Logger Settings
- Hooks Settings
- File Extensions
- Playbook Settings
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
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
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": ""}
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/
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.
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.
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.
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
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
- LinchPin on Github
- Code Contributions and Latest Software
- webchat.freenode.net
- #linchpin IRC chat channel
- LinchPin on PyPi
- Latest Release of LinchPin