Introduction

As cdist grows it has more and more options. Some of them you have to type every time, because "this is the way I run cdist". Now this is simplified. From version 4.7.0 cdist will have configuration, i.e. config file support.

Description

cdist obtains configuration data from the following sources in the following order:

1. command-line options

2. configuration file specified at command-line using -g command line option

3. configuration file specified in CDIST_CONFIG_FILE environment variable

4. environment variables

5. user's configuration file (first one found of ~/.cdist.cfg, $XDG_CONFIG_HOME/cdist/cdist.cfg, in specified order)

6. system-wide configuration file (/etc/cdist.cfg)

if one exists.

Configuration source with lower ordering number from above has a higher precedence. Configuration option value read from source with higher precedence will overwrite option value, if exists, read from source with lower precedence. That means that command-line option wins them all.

Users can decide on the local conifguration file location. It can be either ~/.cdist.cfg or $XDG_CONFIG_HOME/cdist/cdist.cfg. Note that, if both exist, then ~/.cdist.cfg is used.

For a per-project configuration, particular environment variables or better, CDIST_CONFIG_FILE environment variable or -g CONFIG_FILE command line option, can be used.

Config file format

cdist configuration file is in the INI file format. Currently it supports only [GLOBAL] section. The possible keywords and their meanings are as follows:

archiving

Use specified archiving. Valid values include: 'none', 'tar', 'tgz', 'tbz2' and 'txz'.

beta

Enable beta functionality. It recognizes boolean values from 'yes'/'no', 'on'/'off', 'true'/'false' and '1'/'0'.

cache_path_pattern

Specify cache path pattern.

conf_dir

List of configuration directories separated with the character conventionally used by the operating system to separate search path components (as in PATH), such as ':' for POSIX or ';' for Windows. If also specified at command line then values from command line are appended to this value.

init_manifest

Specify default initial manifest.

inventory_dir

Specify inventory directory.

jobs

Specify number of jobs for parallel processing. If -1 then the default, number of CPU's in the system is used. If 0 then parallel processing in jobs is disabled. If set to positive number then specified maximum number of processes will be used.

local_shell

Shell command used for local execution.

out_path

Directory to save cdist output in.

parallel

Process hosts in parallel. If -1 then the default, number of CPU's in the system is used. If 0 then parallel processing of hosts is disabled. If set to positive number then specified maximum number of processes will be used.

remote_copy

Command to use for remote copy (should behave like scp).

remote_exec

Command to use for remote execution (should behave like ssh).

remote_out_path

Directory to save cdist output in on the target host.

remote_shell

Shell command at remote host used for remote execution.

verbosity

Set verbosity level. Valid values are: 'ERROR', 'WARNING', 'INFO', 'VERBOSE', 'DEBUG', 'TRACE' and 'OFF'.

Example config file

/home/you/.cdist.cfg:

    [GLOBAL]
    archiving = tar
    beta = yes
    jobs = -1
    parallel = -1
    verbosity = INFO
    inventory_dir = /home/you/.cdist/inventory
    init_manifest = /home/you/.cdist/manifest/init

With the above config file you can run cdist, e.g. for configuring all hosts tagged with web-servers tag:

    $ cdist config -t web-servers

cdist will run with options specified in config file; it will use archiving (tar), beta functionality will be turned on (which is needed for example jobs option), hosts will be processed in parallel and using parallel jobs with maximum number of processes equal to number of CPUs, default verbosity level will be set to INFO and it will use specified inventory directory and specified initial manifest.