13. Configuration

13.1. 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. in-distribution configuration file (cdist/conf/cdist.cfg)
  7. 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.

13.2. Config file format

cdist configuration file is in the INI file format. Currently it supports only [GLOBAL] section.

Here you can find configuration file skeleton:

[GLOBAL]
# archiving
#     Use specified archiving. Valid values include:
#     none, tar, tgz, tbz2 and txz.
# archiving = tar
#
# beta
#     Enable beta functionality. It recognizes boolean values from
#     yes/no, on/off, true/false and 1/0
# beta = no
#
# cache_path_pattern
#     Specify cache path pattern.
# cache_path_pattern = %h
#
# 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.
# conf_dir = <dir1>:<dir2>
#
# init_manifest
#     Specify default initial manifest.
# init_mainfest = <path-to-init-manifst>
#
# inventory_dir
#     Specify inventory directory.
# inventory_dir = <path-to-inventory-dir>
#
# 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.
# jobs = 0
#
# local_shell
#     Shell command used for local execution.
# local_shell = /bin/sh
#
# out_path
#     Directory to save cdist output in.
# out_path = 
#
# 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.
# parallel = 0
#
# remote_copy
#     Command to use for remote copy (should behave like scp).
# remote_copy =
#
# remote_exec
#     Command to use for remote execution (should behave like ssh).
# remote_exec =
#
# remote_out_path
#     Directory to save cdist output in on the target host.
# remote_out_path = /var/lib/cdist
#
# remote_shell
#     Shell command at remote host used for remote execution.
# remote_shell = /bin/sh
#
# verbosity
#     Set verbosity level. Valid values are: 
#     ERROR, WARNING, INFO, VERBOSE, DEBUG, TRACE and OFF.
# verbosity = INFO