The Salt system is amazingly simple and easy to configure, the two components of the Salt system each have a respective configuration file. The :command:`salt-master` is configured via the master configuration file, and the :command:`salt-minion` is configured via the minion configuration file.
.. seealso:: :ref:`Example master configuration file <configuration-examples-master>`.
The configuration file for the salt-master is located at :file:`/etc/salt/master` by default. A notable exception is FreeBSD, where the configuration file is located at :file:`/usr/local/etc/salt`. The available options are as follows:
.. conf_master:: interface
Default: 0.0.0.0
(all interfaces)
The local interface to bind to.
interface: 192.168.0.1
.. conf_master:: ipv6
Default: False
Whether the master should listen for IPv6 connections. If this is set to True, the interface option must be adjusted too (for example: "interface: '::'")
ipv6: True
.. conf_master:: publish_port
Default: 4505
The network port to set up the publication interface.
publish_port: 4505
.. conf_master:: master_id
Default: None
The id to be passed in the publish job to minions. This is used for MultiSyndics to return the job to the requesting master.
Note
This must be the same string as the syndic is configured with.
master_id: MasterOfMaster
.. conf_master:: user
Default: root
The user to run the Salt processes
user: root
.. conf_master:: max_open_files
Default: 100000
Each minion connecting to the master uses AT LEAST one file descriptor, the master subscription connection. If enough minions connect you might start seeing on the console(and then salt-master crashes):
Too many open files (tcp_listener.cpp:335)
Aborted (core dumped)
max_open_files: 100000
By default this value will be the one of ulimit -Hn, i.e., the hard limit for max open files.
To set a different value than the default one, uncomment, and configure this setting. Remember that this value CANNOT be higher than the hard limit. Raising the hard limit depends on the OS and/or distribution, a good way to find the limit is to search the internet for something like this:
raise max open files hard limit debian
.. conf_master:: worker_threads
Default: 5
The number of threads to start for receiving commands and replies from minions. If minions are stalling on replies because you have many minions, raise the worker_threads value.
Worker threads should not be put below 3 when using the peer system, but can drop down to 1 worker otherwise.
Note
When the master daemon starts, it is expected behaviour to see multiple salt-master processes, even if 'worker_threads' is set to '1'. At a minimum, a controlling process will start along with a Publisher, an EventPublisher, and a number of MWorker processes will be started. The number of MWorker processes is tuneable by the 'worker_threads' configuration value while the others are not.
worker_threads: 5
.. conf_master:: ret_port
Default: 4506
The port used by the return server, this is the server used by Salt to receive execution returns and command executions.
ret_port: 4506
.. conf_master:: pidfile
Default: /var/run/salt-master.pid
Specify the location of the master pidfile.
pidfile: /var/run/salt-master.pid
.. conf_master:: root_dir
Default: /
The system root directory to operate from, change this to make Salt run from an alternative root.
root_dir: /
Note
This directory is prepended to the following options: :conf_master:`pki_dir`, :conf_master:`cachedir`, :conf_master:`sock_dir`, :conf_master:`log_file`, :conf_master:`autosign_file`, :conf_master:`autoreject_file`, :conf_master:`pidfile`.
.. conf_master:: conf_file
Default: /etc/salt/master
The path to the master's configuration file.
conf_file: /etc/salt/master
.. conf_master:: pki_dir
Default: /etc/salt/pki/master
The directory to store the pki authentication keys.
pki_dir: /etc/salt/pki/master
.. conf_master:: extension_modules
.. versionchanged:: 2016.3.0 The default location for this directory has been moved. Prior to this version, the location was a directory named ``extmods`` in the Salt cachedir (on most platforms, ``/var/cache/salt/extmods``). It has been moved into the master cachedir (on most platforms, ``/var/cache/salt/master/extmods``).
Directory for custom modules. This directory can contain subdirectories for
each of Salt's module types such as runners
, output
, wheel
,
modules
, states
, returners
, engines
, etc. This path is appended to
:conf_master:`root_dir`.
extension_modules: /root/salt_extmods
.. conf_minion:: module_dirs
Default: []
Like extension_modules
, but a list of extra directories to search
for Salt modules.
module_dirs:
- /var/cache/salt/minion/extmods
.. conf_master:: cachedir
Default: /var/cache/salt/master
The location used to store cache information, particularly the job information for executed salt commands.
This directory may contain sensitive data and should be protected accordingly.
cachedir: /var/cache/salt/master
.. conf_master:: verify_env
Default: True
Verify and set permissions on configuration directories at startup.
verify_env: True
.. conf_master:: keep_jobs
Default: 24
Set the number of hours to keep old job information. Note that setting this option
to 0
disables the cache cleaner.
keep_jobs: 24
.. conf_master:: gather_job_timeout
.. versionadded:: 2014.7.0
Default: 10
The number of seconds to wait when the client is requesting information about running jobs.
gather_job_timeout: 10
.. conf_master:: timeout
Default: 5
Set the default timeout for the salt command and api.
.. conf_master:: loop_interval
Default: 60
The loop_interval option controls the seconds for the master's maintenance process check cycle. This process updates file server backends, cleans the job cache and executes the scheduler.
.. conf_master:: output
Default: nested
Set the default outputter used by the salt command.
.. conf_master:: output_file
Default: None
Set the default output file used by the salt command. Default is to output to the CLI and not to a file. Functions the same way as the "--out-file" CLI option, only sets this to a single file for all salt commands.
output_file: /path/output/file
.. conf_master:: color
Default: True
By default output is colored, to disable colored output set the color value to False.
color: False
.. conf_master:: cli_summary
Default: False
When set to True
, displays a summary of the number of minions targeted,
the number of minions returned, and the number of minions that did not
return.
cli_summary: False
.. conf_master:: sock_dir
Default: :file:`/var/run/salt/master`
Set the location to use for creating Unix sockets for master process communication.
sock_dir: /var/run/salt/master
.. conf_master:: enable_gpu_grains
Default: True
Enable GPU hardware data for your master. Be aware that the master can take a while to start up when lspci and/or dmidecode is used to populate the grains for the master.
.. conf_master:: job_cache
Default: True
The master maintains a temporary job cache. While this is a great addition, it can be a burden on the master for larger deployments (over 5000 minions). Disabling the job cache will make previously executed jobs unavailable to the jobs system and is not generally recommended. Normally it is wise to make sure the master has access to a faster IO system or a tmpfs is mounted to the jobs dir.
job_cache: True
Note
Setting the job_cache
to False
will not cache minion returns, but
the JID directory for each job is still created. The creation of the JID
directories is necessary because Salt uses those directories to check for
JID collisions. By setting this option to False
, the job cache
directory, which is /var/cache/salt/master/jobs/
by default, will be
smaller, but the JID directories will still be present.
Note that the :conf_master:`keep_jobs` option can be set to a lower value,
such as 1
, to limit the number of hours jobs are stored in the job
cache. (The default is 24 hours.)
Please see the :ref:`Managing the Job Cache <managing_the_job_cache>` documentation for more information.
.. conf_master:: minion_data_cache
Default: True
The minion data cache is a cache of information about the minions stored on the master, this information is primarily the pillar and grains data. The data is cached in the Master cachedir under the name of the minion and used to predetermine what minions are expected to reply from executions.
minion_data_cache: True
.. conf_master:: ext_job_cache
Default: ''
Used to specify a default returner for all minions. When this option is set, the specified returner needs to be properly configured and the minions will always default to sending returns to this returner. This will also disable the local job cache on the master.
ext_job_cache: redis
.. conf_master:: event_return
.. versionadded:: 2015.5.0
Default: ''
Specify the returner(s) to use to log events. Each returner may have installation and configuration requirements. Read the returner's documentation.
Note
Not all returners support event returns. Verify that a returner has an
event_return()
function before configuring this option with a returner.
event_return:
- syslog
- splunk
.. conf_master:: event_return_queue
.. versionadded:: 2015.5.0
Default: 0
On busy systems, enabling event_returns can cause a considerable load on the storage system for returners. Events can be queued on the master and stored in a batched fashion using a single transaction for multiple events. By default, events are not queued.
event_return_queue: 0
.. conf_master:: event_return_whitelist
.. versionadded:: 2015.5.0
Default: []
Only return events matching tags in a whitelist.
.. versionchanged:: 2016.11.0 Supports glob matching patterns.
event_return_whitelist:
- salt/master/a_tag
- salt/run/*/ret
.. conf_master:: event_return_blacklist
.. versionadded:: 2015.5.0
Default: []
Store all event returns _except_ the tags in a blacklist.
.. versionchanged:: 2016.11.0 Supports glob matching patterns.
event_return_blacklist:
- salt/master/not_this_tag
- salt/wheel/*/ret
.. conf_master:: max_event_size
.. versionadded:: 2014.7.0
Default: 1048576
Passing very large events can cause the minion to consume large amounts of memory. This value tunes the maximum size of a message allowed onto the master event bus. The value is expressed in bytes.
max_event_size: 1048576
.. conf_master:: master_job_cache
.. versionadded:: 2014.7.0
Default: local_cache
Specify the returner to use for the job cache. The job cache will only be interacted with from the salt master and therefore does not need to be accessible from the minions.
master_job_cache: redis
.. conf_master:: enforce_mine_cache
Default: False
By-default when disabling the minion_data_cache mine will stop working since it is based on cached data, by enabling this option we explicitly enabling only the cache for the mine system.
enforce_mine_cache: False
.. conf_master:: max_minions
Default: 0
The maximum number of minion connections allowed by the master. Use this to
accommodate the number of minions per master if you have different types of
hardware serving your minions. The default of 0
means unlimited connections.
Please note that this can slow down the authentication process a bit in large
setups.
max_minions: 100
Default: False
If max_minions is used in large installations, the master might experience high-load situations because of having to check the number of connected minions for every authentication. This cache provides the minion-ids of all connected minions to all MWorker-processes and greatly improves the performance of max_minions.
con_cache: True
.. conf_master:: presence_events
Default: False
Causes the master to periodically look for actively connected minions. :ref:`Presence events <event-master_presence>` are fired on the event bus on a regular interval with a list of connected minions, as well as events with lists of newly connected or disconnected minions. This is a master-only operation that does not send executions to minions. Note, this does not detect minions that connect to a master via localhost.
presence_events: False
.. conf_master:: transport
Default: zeromq
Changes the underlying transport layer. ZeroMQ is the recommended transport
while additional transport layers are under development. Supported values are
zeromq
, raet
(experimental), and tcp
(experimental). This setting has
a significant impact on performance and should not be changed unless you know
what you are doing! Transports are explained in :ref:`Salt Transports
<transports>`.
transport: zeromq
Default: {}
(experimental) Starts multiple transports and overrides options for each transport with the provided dictionary This setting has a significant impact on performance and should not be changed unless you know what you are doing! Transports are explained in :ref:`Salt Transports <transports>`. The following example shows how to start a TCP transport alongside a ZMQ transport.
transport_opts:
tcp:
publish_port: 4605
ret_port: 4606
zeromq: []
.. conf_master:: roster_file
Default: /etc/salt/roster
Pass in an alternative location for the salt-ssh roster file.
roster_file: /root/roster
.. conf_master:: ssh_minion_opts
Default: None
Pass in minion option overrides that will be inserted into the SHIM for
salt-ssh calls. The local minion config is not used for salt-ssh. Can be
overridden on a per-minion basis in the roster (minion_opts
)
ssh_minion_opts:
gpg_keydir: /root/gpg
Default: False
Set this to True to default to using ~/.ssh/id_rsa
for salt-ssh
authentication with minions
ssh_use_home_key: False
Default: None
List of additional modules, needed to be included into the Salt Thin. Pass a list of importable Python modules that are typically located in the site-packages Python directory so they will be also always included into the Salt Thin, once generated.
.. conf_master:: open_mode
Default: False
Open mode is a dangerous security feature. One problem encountered with pki
authentication systems is that keys can become "mixed up" and authentication
begins to fail. Open mode turns off authentication and tells the master to
accept all authentication. This will clean up the pki keys received from the
minions. Open mode should not be turned on for general use. Open mode should
only be used for a short period of time to clean up pki keys. To turn on open
mode set this value to True
.
open_mode: False
.. conf_master:: auto_accept
Default: False
Enable auto_accept. This setting will automatically accept all incoming public keys from minions.
auto_accept: False
.. conf_master:: autosign_timeout
.. versionadded:: 2014.7.0
Default: 120
Time in minutes that a incoming public key with a matching name found in pki_dir/minion_autosign/keyid is automatically accepted. Expired autosign keys are removed when the master checks the minion_autosign directory. This method to auto accept minions can be safer than an autosign_file because the keyid record can expire and is limited to being an exact name match. This should still be considered a less than secure option, due to the fact that trust is based on just the requesting minion id.
.. conf_master:: autosign_file
Default: not defined
If the autosign_file
is specified incoming keys specified in the autosign_file
will be automatically accepted. Matches will be searched for first by string
comparison, then by globbing, then by full-string regex matching.
This should still be considered a less than secure option, due to the fact
that trust is based on just the requesting minion id.
.. conf_master:: autoreject_file
.. versionadded:: 2014.1.0
Default: not defined
Works like :conf_master:`autosign_file`, but instead allows you to specify minion IDs for which keys will automatically be rejected. Will override both membership in the :conf_master:`autosign_file` and the :conf_master:`auto_accept` setting.
.. conf_master:: publisher_acl
Default: {}
Enable user accounts on the master to execute specific modules. These modules can be expressed as regular expressions. Note that client_acl option is deprecated by publisher_acl option and will be removed in future releases.
publisher_acl:
fred:
- test.ping
- pkg.*
.. conf_master:: publisher_acl_blacklist
Default: {}
Blacklist users or modules
This example would blacklist all non sudo users, including root from running any commands. It would also blacklist any use of the "cmd" module. Note that client_acl_blacklist option is deprecated by publisher_acl_blacklist option and will be removed in future releases.
This is completely disabled by default.
publisher_acl_blacklist:
users:
- root
- '^(?!sudo_).*$' # all non sudo users
modules:
- cmd
.. conf_master:: external_auth
Default: {}
The external auth system uses the Salt auth modules to authenticate and validate users to access areas of the Salt system.
external_auth:
pam:
fred:
- test.*
.. conf_master:: token_expire
Default: 43200
Time (in seconds) for a newly generated token to live.
Default: 12 hours
token_expire: 43200
.. conf_master:: token_expire_user_override
Default: False
Allow eauth users to specify the expiry time of the tokens they generate.
A boolean applies to all users or a dictionary of whitelisted eauth backends and usernames may be given:
token_expire_user_override:
pam:
- fred
- tom
ldap:
- gary
.. conf_master:: file_recv
Default: False
Allow minions to push files to the master. This is disabled by default, for security purposes.
file_recv: False
.. conf_master:: file_recv_max_size
.. versionadded:: 2014.7.0
Default: 100
Set a hard-limit on the size of the files that can be pushed to the master. It will be interpreted as megabytes.
file_recv_max_size: 100
.. conf_master:: master_sign_pubkey
Default: False
Sign the master auth-replies with a cryptographic signature of the master's public key. Please see the tutorial how to use these settings in the Multimaster-PKI with Failover Tutorial
master_sign_pubkey: True
.. conf_master:: master_sign_key_name
Default: master_sign
The customizable name of the signing-key-pair without suffix.
master_sign_key_name: <filename_without_suffix>
.. conf_master:: master_pubkey_signature
Default: master_pubkey_signature
The name of the file in the master's pki-directory that holds the pre-calculated signature of the master's public-key.
master_pubkey_signature: <filename>
.. conf_master:: master_use_pubkey_signature
Default: False
Instead of computing the signature for each auth-reply, use a pre-calculated signature. The :conf_master:`master_pubkey_signature` must also be set for this.
master_use_pubkey_signature: True
.. conf_master:: rotate_aes_key
Default: True
Rotate the salt-masters AES-key when a minion-public is deleted with salt-key. This is a very important security-setting. Disabling it will enable deleted minions to still listen in on the messages published by the salt-master. Do not disable this unless it is absolutely clear what this does.
rotate_aes_key: True
.. conf_master:: ssl
.. versionadded:: 2016.11.0
Default: None
TLS/SSL connection options. This could be set to a dictionary containing
arguments corresponding to python ssl.wrap_socket
method. For details see
Tornado
and Python
documentation.
Note: to set enum arguments values like cert_reqs
and ssl_version
use
constant names without ssl module prefix: CERT_REQUIRED
or PROTOCOL_SSLv23
.
ssl:
keyfile: <path_to_keyfile>
certfile: <path_to_certfile>
ssl_version: PROTOCOL_TLSv1_2
.. conf_master:: runner_dirs
Default: []
Set additional directories to search for runner modules.
runner_dirs:
- /var/lib/salt/runners
.. conf_master:: cython_enable
Default: False
Set to true to enable Cython modules (.pyx files) to be compiled on the fly on the Salt master.
cython_enable: False
.. conf_master:: state_top
Default: top.sls
The state system uses a "top" file to tell the minions what environment to use and what modules to use. The state_top file is defined relative to the root of the base environment.
state_top: top.sls
.. conf_master:: master_tops
Default: {}
The master_tops option replaces the external_nodes option by creating a pluggable system for the generation of external top data. The external_nodes option is deprecated by the master_tops option. To gain the capabilities of the classic external_nodes system, use the following configuration:
master_tops:
ext_nodes: <Shell command which returns yaml>
.. conf_master:: external_nodes
Default: None
The external_nodes option allows Salt to gather data that would normally be placed in a top file from and external node controller. The external_nodes option is the executable that will return the ENC data. Remember that Salt will look for external nodes AND top files and combine the results if both are enabled and available!
external_nodes: cobbler-ext-nodes
.. conf_master:: renderer
Default: yaml_jinja
The renderer to use on the minions to render the state data.
renderer: yaml_jinja
.. conf_master:: jinja_trim_blocks
.. versionadded:: 2014.1.0
Default: False
If this is set to True
, the first newline after a Jinja block is
removed (block, not variable tag!). Defaults to False
and corresponds
to the Jinja environment init variable trim_blocks
.
jinja_trim_blocks: False
.. conf_master:: jinja_lstrip_blocks
.. versionadded:: 2014.1.0
Default: False
If this is set to True
, leading spaces and tabs are stripped from the
start of a line to a block. Defaults to False
and corresponds to the
Jinja environment init variable lstrip_blocks
.
jinja_lstrip_blocks: False
.. conf_master:: failhard
Default: False
Set the global failhard flag. This informs all states to stop running states at the moment a single state fails.
failhard: False
.. conf_master:: state_verbose
Default: True
Controls the verbosity of state runs. By default, the results of all states are
returned, but setting this value to False
will cause salt to only display
output for states that failed or states that have changes.
state_verbose: False
.. conf_master:: state_output
Default: full
The state_output setting changes if the output is the full multi line output for each changed state if set to 'full', but if set to 'terse' the output will be shortened to a single line. If set to 'mixed', the output will be terse unless a state failed, in which case that output will be full. If set to 'changes', the output will be full unless the state didn't change.
state_output: full
.. conf_master:: state_aggregate
Default: False
Automatically aggregate all states that have support for mod_aggregate by
setting to True
. Or pass a list of state module names to automatically
aggregate just those types.
state_aggregate:
- pkg
state_aggregate: True
.. conf_master:: state_events
Default: False
Send progress events as each function in a state run completes execution
by setting to True
. Progress events are in the format
salt/job/<JID>/prog/<MID>/<RUN NUM>
.
state_events: True
.. conf_master:: yaml_utf8
Default: False
Enable extra routines for YAML renderer used states containing UTF characters.
yaml_utf8: False
.. conf_master:: test
Default: False
Set all state calls to only test if they are going to actually make changes or just post what changes are going to be made.
test: False
.. conf_master:: runner_returns
Default: False
If set to True
, runner jobs will be saved to job cache (defined by
:conf_master:`master_job_cache`).
runner_returns: True
.. conf_master:: fileserver_backend
Default: ['roots']
Salt supports a modular fileserver backend system, this system allows the salt
master to link directly to third party systems to gather and manage the files
available to minions. Multiple backends can be configured and will be searched
for the requested file in the order in which they are defined here. The default
setting only enables the standard backend roots
, which is configured using
the :conf_master:`file_roots` option.
Example:
fileserver_backend:
- roots
- git
Note
For masterless Salt, this parameter must be specified in the minion config file.
.. conf_master:: fileserver_followsymlinks
.. versionadded:: 2014.1.0
Default: True
By default, the file_server follows symlinks when walking the filesystem tree. Currently this only applies to the default roots fileserver_backend.
fileserver_followsymlinks: True
.. conf_master:: fileserver_ignoresymlinks
.. versionadded:: 2014.1.0
Default: False
If you do not want symlinks to be treated as the files they are pointing to,
set fileserver_ignoresymlinks
to True
. By default this is set to
False. When set to True
, any detected symlink while listing files on the
Master will not be returned to the Minion.
fileserver_ignoresymlinks: False
.. conf_master:: fileserver_limit_traversal
.. versionadded:: 2014.1.0
Default: False
By default, the Salt fileserver recurses fully into all defined environments
to attempt to find files. To limit this behavior so that the fileserver only
traverses directories with SLS files and special Salt directories like _modules,
set fileserver_limit_traversal
to True
. This might be useful for
installations where a file root has a very large number of files and performance
is impacted.
fileserver_limit_traversal: False
.. conf_master:: fileserver_list_cache_time
.. versionadded:: 2014.1.0
.. versionchanged:: 2016.11.0 The default was changed from ``30`` seconds to ``20``.
Default: 20
Salt caches the list of files/symlinks/directories for each fileserver backend and environment as they are requested, to guard against a performance bottleneck at scale when many minions all ask the fileserver which files are available simultaneously. This configuration parameter allows for the max age of that cache to be altered.
Set this value to 0
to disable use of this cache altogether, but keep in
mind that this may increase the CPU load on the master when running a highstate
on a large number of minions.
Note
Rather than altering this configuration parameter, it may be advisable to use the :mod:`fileserver.clear_list_cache <salt.runners.fileserver.clear_list_cache>` runner to clear these caches.
fileserver_list_cache_time: 5
.. conf_master:: hash_type
Default: md5
The hash_type is the hash to use when discovering the hash of a file on the master server. The default is md5, but sha1, sha224, sha256, sha384, and sha512 are also supported.
hash_type: md5
.. conf_master:: file_buffer_size
Default: 1048576
The buffer size in the file server in bytes.
file_buffer_size: 1048576
.. conf_master:: file_ignore_regex
Default: ''
A regular expression (or a list of expressions) that will be matched against the file path before syncing the modules and states to the minions. This includes files affected by the file.recurse state. For example, if you manage your custom modules and states in subversion and don't want all the '.svn' folders and content synced to your minions, you could set this to '/.svn($|/)'. By default nothing is ignored.
file_ignore_regex:
- '/\.svn($|/)'
- '/\.git($|/)'
.. conf_master:: file_ignore_glob
Default ''
A file glob (or list of file globs) that will be matched against the file path before syncing the modules and states to the minions. This is similar to file_ignore_regex above, but works on globs instead of regex. By default nothing is ignored.
file_ignore_glob:
- '\*.pyc'
- '\*/somefolder/\*.bak'
- '\*.swp'
Note
Vim's .swp files are a common cause of Unicode errors in
:py:func:`file.recurse <salt.states.file.recurse>` states which use
templating. Unless there is a good reason to distribute them via the
fileserver, it is good practice to include '\*.swp'
in the
:conf_master:`file_ignore_glob`.
.. conf_master:: file_roots
Default:
base:
- /srv/salt
Salt runs a lightweight file server written in ZeroMQ to deliver files to minions. This file server is built into the master daemon and does not require a dedicated port.
The file server works on environments passed to the master. Each environment can have multiple root directories. The subdirectories in the multiple file roots cannot match, otherwise the downloaded files will not be able to be reliably ensured. A base environment is required to house the top file.
Example:
file_roots:
base:
- /srv/salt
dev:
- /srv/salt/dev/services
- /srv/salt/dev/states
prod:
- /srv/salt/prod/services
- /srv/salt/prod/states
Note
For masterless Salt, this parameter must be specified in the minion config file.
.. conf_master:: gitfs_remotes
Default: []
When using the git
fileserver backend at least one git remote needs to be
defined. The user running the salt master will need read access to the repo.
The repos will be searched in order to find the file requested by a client and the first repo to have the file will return it. Branches and tags are translated into salt environments.
gitfs_remotes:
- git://github.com/saltstack/salt-states.git
- file:///var/git/saltmaster
Note
file://
repos will be treated as a remote and copied into the master's
gitfs cache, so only the local refs for those repos will be exposed as
fileserver environments.
As of 2014.7.0, it is possible to have per-repo versions of several of the gitfs configuration parameters. For more information, see the :ref:`GitFS Walkthrough <gitfs-per-remote-config>`.
.. conf_master:: gitfs_provider
.. versionadded:: 2014.7.0
Optional parameter used to specify the provider to be used for gitfs. More information can be found in the :ref:`GitFS Walkthrough <gitfs-dependencies>`.
Must be one of the following: pygit2
, gitpython
, or dulwich
. If
unset, then each will be tried in that same order, and the first one with a
compatible version installed will be the provider that is used.
gitfs_provider: dulwich
.. conf_master:: gitfs_ssl_verify
.. versionchanged:: 2016.11.0
Default: True
Specifies whether or not to ignore SSL certificate errors when contacting the
remote repository. The False
setting is useful if you're using a
git repo that uses a self-signed certificate. However, keep in mind that
setting this to anything other True
is a considered insecure, and using an
SSH-based transport (if available) may be a better option.
In the 2016.11.0 release, the default config value changed from False
to
True
.
gitfs_ssl_verify: True
.. conf_master:: gitfs_mountpoint
.. versionadded:: 2014.7.0
Default: ''
Specifies a path on the salt fileserver which will be prepended to all files served by gitfs. This option can be used in conjunction with :conf_master:`gitfs_root`. It can also be configured on a per-remote basis, see :ref:`here <gitfs-per-remote-config>` for more info.
gitfs_mountpoint: salt://foo/bar
Note
The salt://
protocol designation can be left off (in other words,
foo/bar
and salt://foo/bar
are equivalent). Assuming a file
baz.sh
in the root of a gitfs remote, and the above example mountpoint,
this file would be served up via salt://foo/bar/baz.sh
.
.. conf_master:: gitfs_root
Default: ''
Relative path to a subdirectory within the repository from which Salt should begin to serve files. This is useful when there are files in the repository that should not be available to the Salt fileserver. Can be used in conjunction with :conf_master:`gitfs_mountpoint`. If used, then from Salt's perspective the directories above the one specified will be ignored and the relative path will (for the purposes of gitfs) be considered as the root of the repo.
gitfs_root: somefolder/otherfolder
.. versionchanged:: 2014.7.0 Ability to specify gitfs roots on a per-remote basis was added. See :ref:`here <gitfs-per-remote-config>` for more info.
.. conf_master:: gitfs_base
Default: master
Defines which branch/tag should be used as the base
environment.
gitfs_base: salt
.. versionchanged:: 2014.7.0 Ability to specify the base on a per-remote basis was added. See :ref:`here <gitfs-per-remote-config>` for more info.
.. conf_master:: gitfs_saltenv
.. versionadded:: 2016.11.0
Default: []
Global settings for :ref:`per-saltenv configuration parameters
<gitfs-per-saltenv-config>`. Though per-saltenv configuration parameters are
typically one-off changes specific to a single gitfs remote, and thus more
often configured on a per-remote basis, this parameter can be used to specify
per-saltenv changes which should apply to all remotes. For example, the below
configuration will map the develop
branch to the dev
saltenv for all
gitfs remotes.
gitfs_saltenv:
- dev:
- ref: develop
.. conf_master:: gitfs_env_whitelist
.. versionadded:: 2014.7.0
Default: []
Used to restrict which environments are made available. Can speed up state runs if the repos in :conf_master:`gitfs_remotes` contain many branches/tags. More information can be found in the :ref:`GitFS Walkthrough <gitfs-whitelist-blacklist>`.
gitfs_env_whitelist:
- base
- v1.*
- 'mybranch\d+'
.. conf_master:: gitfs_env_blacklist
.. versionadded:: 2014.7.0
Default: []
Used to restrict which environments are made available. Can speed up state runs if the repos in :conf_master:`gitfs_remotes` contain many branches/tags. More information can be found in the :ref:`GitFS Walkthrough <gitfs-whitelist-blacklist>`.
gitfs_env_blacklist:
- base
- v1.*
- 'mybranch\d+'
.. conf_master:: gitfs_global_lock
.. versionadded:: 2015.8.9
Default: True
When set to False
, if there is an update lock for a gitfs remote and the
pid written to it is not running on the master, the lock file will be
automatically cleared and a new lock will be obtained. When set to True
,
Salt will simply log a warning when there is an update lock present.
On single-master deployments, disabling this option can help automatically deal with instances where the master was shutdown/restarted during the middle of a gitfs update, leaving a update lock in place.
However, on multi-master deployments with the gitfs cachedir shared via GlusterFS, nfs, or another network filesystem, it is strongly recommended not to disable this option as doing so will cause lock files to be removed if they were created by a different master.
# Disable global lock
gitfs_global_lock: False
These parameters only currently apply to the pygit2 gitfs provider. Examples of how to use these can be found in the :ref:`GitFS Walkthrough <gitfs-authentication>`.
.. conf_master:: gitfs_user
.. versionadded:: 2014.7.0
Default: ''
Along with :conf_master:`gitfs_password`, is used to authenticate to HTTPS remotes.
gitfs_user: git
.. conf_master:: gitfs_password
.. versionadded:: 2014.7.0
Default: ''
Along with :conf_master:`gitfs_user`, is used to authenticate to HTTPS remotes. This parameter is not required if the repository does not use authentication.
gitfs_password: mypassword
.. conf_master:: gitfs_insecure_auth
.. versionadded:: 2014.7.0
Default: False
By default, Salt will not authenticate to an HTTP (non-HTTPS) remote. This parameter enables authentication over HTTP. Enable this at your own risk.
gitfs_insecure_auth: True
.. conf_master:: gitfs_pubkey
.. versionadded:: 2014.7.0
Default: ''
Along with :conf_master:`gitfs_privkey` (and optionally :conf_master:`gitfs_passphrase`), is used to authenticate to SSH remotes. This parameter (or its :ref:`per-remote counterpart <gitfs-per-remote-config>`) is required for SSH remotes.
gitfs_pubkey: /path/to/key.pub
.. conf_master:: gitfs_privkey
.. versionadded:: 2014.7.0
Default: ''
Along with :conf_master:`gitfs_pubkey` (and optionally :conf_master:`gitfs_passphrase`), is used to authenticate to SSH remotes. This parameter (or its :ref:`per-remote counterpart <gitfs-per-remote-config>`) is required for SSH remotes.
gitfs_privkey: /path/to/key
.. conf_master:: gitfs_passphrase
.. versionadded:: 2014.7.0
Default: ''
This parameter is optional, required only when the SSH key being used to authenticate is protected by a passphrase.
gitfs_passphrase: mypassphrase
.. conf_master:: hgfs_remotes
.. versionadded:: 0.17.0
Default: []
When using the hg
fileserver backend at least one mercurial remote needs to
be defined. The user running the salt master will need read access to the repo.
The repos will be searched in order to find the file requested by a client and the first repo to have the file will return it. Branches and/or bookmarks are translated into salt environments, as defined by the :conf_master:`hgfs_branch_method` parameter.
hgfs_remotes:
- https://[email protected]/username/reponame
Note
As of 2014.7.0, it is possible to have per-repo versions of the :conf_master:`hgfs_root`, :conf_master:`hgfs_mountpoint`, :conf_master:`hgfs_base`, and :conf_master:`hgfs_branch_method` parameters. For example:
hgfs_remotes:
- https://[email protected]/username/repo1
- base: saltstates
- https://[email protected]/username/repo2:
- root: salt
- mountpoint: salt://foo/bar/baz
- https://[email protected]/username/repo3:
- root: salt/states
- branch_method: mixed
.. conf_master:: hgfs_branch_method
.. versionadded:: 0.17.0
Default: branches
Defines the objects that will be used as fileserver environments.
branches
- Only branches and tags will be usedbookmarks
- Only bookmarks and tags will be usedmixed
- Branches, bookmarks, and tags will be used
hgfs_branch_method: mixed
Note
Starting in version 2014.1.0, the value of the :conf_master:`hgfs_base`
parameter defines which branch is used as the base
environment,
allowing for a base
environment to be used with an
:conf_master:`hgfs_branch_method` of bookmarks
.
Prior to this release, the default
branch will be used as the base
environment.
.. conf_master:: hgfs_mountpoint
.. versionadded:: 2014.7.0
Default: ''
Specifies a path on the salt fileserver which will be prepended to all files served by hgfs. This option can be used in conjunction with :conf_master:`hgfs_root`. It can also be configured on a per-remote basis, see :conf_master:`here <hgfs_remotes>` for more info.
hgfs_mountpoint: salt://foo/bar
Note
The salt://
protocol designation can be left off (in other words,
foo/bar
and salt://foo/bar
are equivalent). Assuming a file
baz.sh
in the root of an hgfs remote, this file would be served up via
salt://foo/bar/baz.sh
.
.. conf_master:: hgfs_root
.. versionadded:: 0.17.0
Default: ''
Relative path to a subdirectory within the repository from which Salt should begin to serve files. This is useful when there are files in the repository that should not be available to the Salt fileserver. Can be used in conjunction with :conf_master:`hgfs_mountpoint`. If used, then from Salt's perspective the directories above the one specified will be ignored and the relative path will (for the purposes of hgfs) be considered as the root of the repo.
hgfs_root: somefolder/otherfolder
.. versionchanged:: 2014.7.0 Ability to specify hgfs roots on a per-remote basis was added. See :conf_master:`here <hgfs_remotes>` for more info.
.. conf_master:: hgfs_base
.. versionadded:: 2014.1.0
Default: default
Defines which branch should be used as the base
environment. Change this if
:conf_master:`hgfs_branch_method` is set to bookmarks
to specify which
bookmark should be used as the base
environment.
hgfs_base: salt
.. conf_master:: hgfs_env_whitelist
.. versionadded:: 2014.7.0
Default: []
Used to restrict which environments are made available. Can speed up state runs if your hgfs remotes contain many branches/bookmarks/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID.
If used, only branches/bookmarks/tags which match one of the specified expressions will be exposed as fileserver environments.
If used in conjunction with :conf_master:`hgfs_env_blacklist`, then the subset of branches/bookmarks/tags which match the whitelist but do not match the blacklist will be exposed as fileserver environments.
hgfs_env_whitelist:
- base
- v1.*
- 'mybranch\d+'
.. conf_master:: hgfs_env_blacklist
.. versionadded:: 2014.7.0
Default: []
Used to restrict which environments are made available. Can speed up state runs if your hgfs remotes contain many branches/bookmarks/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID.
If used, branches/bookmarks/tags which match one of the specified expressions will not be exposed as fileserver environments.
If used in conjunction with :conf_master:`hgfs_env_whitelist`, then the subset of branches/bookmarks/tags which match the whitelist but do not match the blacklist will be exposed as fileserver environments.
hgfs_env_blacklist:
- base
- v1.*
- 'mybranch\d+'
.. conf_master:: svnfs_remotes
.. versionadded:: 0.17.0
Default: []
When using the svn
fileserver backend at least one subversion remote needs
to be defined. The user running the salt master will need read access to the
repo.
The repos will be searched in order to find the file requested by a client and
the first repo to have the file will return it. The trunk, branches, and tags
become environments, with the trunk being the base
environment.
svnfs_remotes:
- svn://foo.com/svn/myproject
Note
As of 2014.7.0, it is possible to have per-repo versions of the following configuration parameters:
- :conf_master:`svnfs_root`
- :conf_master:`svnfs_mountpoint`
- :conf_master:`svnfs_trunk`
- :conf_master:`svnfs_branches`
- :conf_master:`svnfs_tags`
For example:
svnfs_remotes:
- svn://foo.com/svn/project1
- svn://foo.com/svn/project2:
- root: salt
- mountpoint: salt://foo/bar/baz
- svn//foo.com/svn/project3:
- root: salt/states
- branches: branch
- tags: tag
.. conf_master:: svnfs_mountpoint
.. versionadded:: 2014.7.0
Default: ''
Specifies a path on the salt fileserver which will be prepended to all files served by hgfs. This option can be used in conjunction with :conf_master:`svnfs_root`. It can also be configured on a per-remote basis, see :conf_master:`here <svnfs_remotes>` for more info.
svnfs_mountpoint: salt://foo/bar
Note
The salt://
protocol designation can be left off (in other words,
foo/bar
and salt://foo/bar
are equivalent). Assuming a file
baz.sh
in the root of an svnfs remote, this file would be served up via
salt://foo/bar/baz.sh
.
.. conf_master:: svnfs_root
.. versionadded:: 0.17.0
Default: ''
Relative path to a subdirectory within the repository from which Salt should begin to serve files. This is useful when there are files in the repository that should not be available to the Salt fileserver. Can be used in conjunction with :conf_master:`svnfs_mountpoint`. If used, then from Salt's perspective the directories above the one specified will be ignored and the relative path will (for the purposes of svnfs) be considered as the root of the repo.
svnfs_root: somefolder/otherfolder
.. versionchanged:: 2014.7.0 Ability to specify svnfs roots on a per-remote basis was added. See :conf_master:`here <svnfs_remotes>` for more info.
.. conf_master:: svnfs_trunk
.. versionadded:: 2014.7.0
Default: trunk
Path relative to the root of the repository where the trunk is located. Can also be configured on a per-remote basis, see :conf_master:`here <svnfs_remotes>` for more info.
svnfs_trunk: trunk
.. conf_master:: svnfs_branches
.. versionadded:: 2014.7.0
Default: branches
Path relative to the root of the repository where the branches are located. Can also be configured on a per-remote basis, see :conf_master:`here <svnfs_remotes>` for more info.
svnfs_branches: branches
.. conf_master:: svnfs_tags
.. versionadded:: 2014.7.0
Default: tags
Path relative to the root of the repository where the tags are located. Can also be configured on a per-remote basis, see :conf_master:`here <svnfs_remotes>` for more info.
svnfs_tags: tags
.. conf_master:: svnfs_env_whitelist
.. versionadded:: 2014.7.0
Default: []
Used to restrict which environments are made available. Can speed up state runs if your svnfs remotes contain many branches/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID.
If used, only branches/tags which match one of the specified expressions will be exposed as fileserver environments.
If used in conjunction with :conf_master:`svnfs_env_blacklist`, then the subset of branches/tags which match the whitelist but do not match the blacklist will be exposed as fileserver environments.
svnfs_env_whitelist:
- base
- v1.*
- 'mybranch\d+'
.. conf_master:: svnfs_env_blacklist
.. versionadded:: 2014.7.0
Default: []
Used to restrict which environments are made available. Can speed up state runs if your svnfs remotes contain many branches/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID.
If used, branches/tags which match one of the specified expressions will not be exposed as fileserver environments.
If used in conjunction with :conf_master:`svnfs_env_whitelist`, then the subset of branches/tags which match the whitelist but do not match the blacklist will be exposed as fileserver environments.
svnfs_env_blacklist:
- base
- v1.*
- 'mybranch\d+'
.. conf_master:: minionfs_env
.. versionadded:: 2014.7.0
Default: base
Environment from which MinionFS files are made available.
minionfs_env: minionfs
.. conf_master:: minionfs_mountpoint
.. versionadded:: 2014.7.0
Default: ''
Specifies a path on the salt fileserver from which minionfs files are served.
minionfs_mountpoint: salt://foo/bar
Note
The salt://
protocol designation can be left off (in other words,
foo/bar
and salt://foo/bar
are equivalent).
.. conf_master:: minionfs_whitelist
.. versionadded:: 2014.7.0
Default: []
Used to restrict which minions' pushed files are exposed via minionfs. If using a regular expression, the expression must match the entire minion ID.
If used, only the pushed files from minions which match one of the specified expressions will be exposed.
If used in conjunction with :conf_master:`minionfs_blacklist`, then the subset of hosts which match the whitelist but do not match the blacklist will be exposed.
minionfs_whitelist:
- server01
- dev*
- 'mail\d+.mydomain.tld'
.. conf_master:: minionfs_blacklist
.. versionadded:: 2014.7.0
Default: []
Used to restrict which minions' pushed files are exposed via minionfs. If using a regular expression, the expression must match the entire minion ID.
If used, only the pushed files from minions which match one of the specified expressions will not be exposed.
If used in conjunction with :conf_master:`minionfs_whitelist`, then the subset of hosts which match the whitelist but do not match the blacklist will be exposed.
minionfs_blacklist:
- server01
- dev*
- 'mail\d+.mydomain.tld'
.. conf_master:: pillar_roots
Default:
base:
- /srv/pillar
Set the environments and directories used to hold pillar sls data. This configuration is the same as :conf_master:`file_roots`:
pillar_roots:
base:
- /srv/pillar
dev:
- /srv/pillar/dev
prod:
- /srv/pillar/prod
.. conf_master:: pillar_opts
Default: False
The pillar_opts
option adds the master configuration file data to a dict in
the pillar called master
. This can be used to set simple configurations in
the master config file that can then be used on minions.
Note that setting this option to True
means the master config file will be
included in all minion's pillars. While this makes global configuration of services
and systems easy, it may not be desired if sensitive data is stored in the master
configuration.
pillar_opts: False
.. conf_master:: ext_pillar
The ext_pillar option allows for any number of external pillar interfaces to be called when populating pillar data. The configuration is based on ext_pillar functions. The available ext_pillar functions can be found herein:
By default, the ext_pillar interface is not configured to run.
Default: []
ext_pillar:
- hiera: /etc/hiera.yaml
- cmd_yaml: cat /etc/salt/yaml
- reclass:
inventory_base_uri: /etc/reclass
There are additional details at :ref:`salt-pillars`
.. conf_master:: ext_pillar_first
.. versionadded:: 2015.5.0
Default: False
This option allows for external pillar sources to be evaluated before :conf_master:`pillar_roots`. This allows for targeting file system pillar from ext_pillar.
ext_pillar_first: False
.. conf_master:: pillar_raise_on_missing
.. versionadded:: 2015.5.0
Default: False
Set this option to True
to force a KeyError
to be raised whenever an
attempt to retrieve a named value from pillar fails. When this option is set
to False
, the failed attempt returns an empty string.
.. conf_master:: git_pillar_provider
.. versionadded:: 2015.8.0
Specify the provider to be used for git_pillar. Must be either pygit2
or
gitpython
. If unset, then both will be tried in that same order, and the
first one with a compatible version installed will be the provider that is
used.
git_pillar_provider: gitpython
.. conf_master:: git_pillar_base
.. versionadded:: 2015.8.0
Default: master
If the desired branch matches this value, and the environment is omitted from
the git_pillar configuration, then the environment for that git_pillar remote
will be base
. For example, in the configuration below, the foo
branch/tag would be assigned to the base
environment, while bar
would
be mapped to the bar
environment.
git_pillar_base: foo
ext_pillar:
- git:
- foo https://mygitserver/git-pillar.git
- bar https://mygitserver/git-pillar.git
.. conf_master:: git_pillar_branch
.. versionadded:: 2015.8.0
Default: master
If the branch is omitted from a git_pillar remote, then this branch will be
used instead. For example, in the configuration below, the first two remotes
would use the pillardata
branch/tag, while the third would use the foo
branch/tag.
git_pillar_branch: pillardata
ext_pillar:
- git:
- https://mygitserver/pillar1.git
- https://mygitserver/pillar2.git:
- root: pillar
- foo https://mygitserver/pillar3.git
.. conf_master:: git_pillar_env
.. versionadded:: 2015.8.0
Default: ''
(unset)
Environment to use for git_pillar remotes. This is normally derived from the
branch/tag (or from a per-remote env
parameter), but if set this will
override the process of deriving the env from the branch/tag name. For example,
in the configuration below the foo
branch would be assigned to the base
environment, while the bar
branch would need to explicitly have bar
configured as it's environment to keep it from also being mapped to the
base
environment.
git_pillar_env: base
ext_pillar:
- git:
- foo https://mygitserver/git-pillar.git
- bar https://mygitserver/git-pillar.git:
- env: bar
For this reason, this option is recommended to be left unset, unless the use case calls for all (or almost all) of the git_pillar remotes to use the same environment irrespective of the branch/tag being used.
.. conf_master:: git_pillar_root
.. versionadded:: 2015.8.0
Default: ''
Path relative to the root of the repository where the git_pillar top file and
SLS files are located. In the below configuration, the pillar top file and SLS
files would be looked for in a subdirectory called pillar
.
git_pillar_root: pillar
ext_pillar:
- git:
- master https://mygitserver/pillar1.git
- master https://mygitserver/pillar2.git
Note
This is a global option. If only one or two repos need to have their files sourced from a subdirectory, then :conf_master:`git_pillar_root` can be omitted and the root can be specified on a per-remote basis, like so:
ext_pillar:
- git:
- master https://mygitserver/pillar1.git
- master https://mygitserver/pillar2.git:
- root: pillar
In this example, for the first remote the top file and SLS files would be
looked for in the root of the repository, while in the second remote the
pillar data would be retrieved from the pillar
subdirectory.
.. conf_master:: git_pillar_ssl_verify
.. versionadded:: 2015.8.0
.. versionchanged:: 2016.11.0
Default: False
Specifies whether or not to ignore SSL certificate errors when contacting the
remote repository. The False
setting is useful if you're using a
git repo that uses a self-signed certificate. However, keep in mind that
setting this to anything other True
is a considered insecure, and using an
SSH-based transport (if available) may be a better option.
In the 2016.11.0 release, the default config value changed from False
to
True
.
git_pillar_ssl_verify: True
.. conf_master:: git_pillar_global_lock
.. versionadded:: 2015.8.9
Default: True
When set to False
, if there is an update/checkout lock for a git_pillar
remote and the pid written to it is not running on the master, the lock file
will be automatically cleared and a new lock will be obtained. When set to
True
, Salt will simply log a warning when there is an lock present.
On single-master deployments, disabling this option can help automatically deal with instances where the master was shutdown/restarted during the middle of a git_pillar update/checkout, leaving a lock in place.
However, on multi-master deployments with the git_pillar cachedir shared via GlusterFS, nfs, or another network filesystem, it is strongly recommended not to disable this option as doing so will cause lock files to be removed if they were created by a different master.
# Disable global lock
git_pillar_global_lock: False
These parameters only currently apply to the pygit2
:conf_master:`git_pillar_provider`. Authentication works the same as it does
in gitfs, as outlined in the :ref:`GitFS Walkthrough <gitfs-authentication>`,
though the global configuration options are named differently to reflect that
they are for git_pillar instead of gitfs.
.. conf_master:: git_pillar_user
.. versionadded:: 2015.8.0
Default: ''
Along with :conf_master:`git_pillar_password`, is used to authenticate to HTTPS remotes.
git_pillar_user: git
.. conf_master:: git_pillar_password
.. versionadded:: 2015.8.0
Default: ''
Along with :conf_master:`git_pillar_user`, is used to authenticate to HTTPS remotes. This parameter is not required if the repository does not use authentication.
git_pillar_password: mypassword
.. conf_master:: git_pillar_insecure_auth
.. versionadded:: 2015.8.0
Default: False
By default, Salt will not authenticate to an HTTP (non-HTTPS) remote. This parameter enables authentication over HTTP. Enable this at your own risk.
git_pillar_insecure_auth: True
.. conf_master:: git_pillar_pubkey
.. versionadded:: 2015.8.0
Default: ''
Along with :conf_master:`git_pillar_privkey` (and optionally :conf_master:`git_pillar_passphrase`), is used to authenticate to SSH remotes.
git_pillar_pubkey: /path/to/key.pub
.. conf_master:: git_pillar_privkey
.. versionadded:: 2015.8.0
Default: ''
Along with :conf_master:`git_pillar_pubkey` (and optionally :conf_master:`git_pillar_passphrase`), is used to authenticate to SSH remotes.
git_pillar_privkey: /path/to/key
.. conf_master:: git_pillar_passphrase
.. versionadded:: 2015.8.0
Default: ''
This parameter is optional, required only when the SSH key being used to authenticate is protected by a passphrase.
git_pillar_passphrase: mypassphrase
.. conf_master:: pillar_source_merging_strategy
.. versionadded:: 2014.7.0
Default: smart
The pillar_source_merging_strategy option allows you to configure merging strategy between different sources. It accepts 5 values:
none
:
.. versionadded:: 2016.3.4 It will not do any merging at all and only parse the pillar data from the passed environment and 'base' if no environment was specified.
recurse
:it will merge recursively mapping of data. For example, theses 2 sources:
foo: 42 bar: element1: True
bar: element2: True baz: quux
will be merged as:
foo: 42 bar: element1: True element2: True baz: quux
aggregate
:instructs aggregation of elements between sources that use the #!yamlex renderer.
For example, these two documents:
#!yamlex foo: 42 bar: !aggregate { element1: True } baz: !aggregate quux
#!yamlex bar: !aggregate { element2: True } baz: !aggregate quux2
will be merged as:
foo: 42 bar: element1: True element2: True baz: - quux - quux2
overwrite
:Will use the behaviour of the 2014.1 branch and earlier.
Overwrites elements according the order in which they are processed.
First pillar processed:
A: first_key: blah second_key: blah
Second pillar processed:
A: third_key: blah fourth_key: blah
will be merged as:
A: third_key: blah fourth_key: blah
smart
(default):Guesses the best strategy based on the "renderer" setting.
.. conf_master:: pillar_merge_lists
.. versionadded:: 2015.8.0
Default: False
Recursively merge lists by aggregating them instead of replacing them.
pillar_merge_lists: False
.. conf_master:: pillar_cache
.. versionadded:: 2015.8.8
Default: False
A master can cache pillars locally to bypass the expense of having to render them for each minion on every request. This feature should only be enabled in cases where pillar rendering time is known to be unsatisfactory and any attendant security concerns about storing pillars in a master cache have been addressed.
When enabling this feature, be certain to read through the additional pillar_cache_*
configuration options to fully understand the tunable parameters and their implications.
pillar_cache: False
Note
Setting pillar_cache: True
has no effect on
:ref:`targeting minions with pillar <targeting-pillar>`.
.. conf_master:: pillar_cache_ttl
.. versionadded:: 2015.8.8
Default: 3600
If and only if a master has set pillar_cache: True
, the cache TTL controls the amount
of time, in seconds, before the cache is considered invalid by a master and a fresh
pillar is recompiled and stored.
.. conf_master:: pillar_cache_backend
.. versionadded:: 2015.8.8
Default: disk
If an only if a master has set pillar_cache: True
, one of several storage providers
can be utilized:
disk
(default):The default storage backend. This caches rendered pillars to the master cache. Rendered pillars are serialized and deserialized as
msgpack
structures for speed. Note that pillars are stored UNENCRYPTED. Ensure that the master cache has permissions set appropriately (sane defaults are provided).memory
[EXPERIMENTAL]:An optional backend for pillar caches which uses a pure-Python in-memory data structure for maximal performance. There are several caveats, however. First, because each master worker contains its own in-memory cache, there is no guarantee of cache consistency between minion requests. This works best in situations where the pillar rarely if ever changes. Secondly, and perhaps more importantly, this means that unencrypted pillars will be accessible to any process which can examine the memory of the
salt-master
! This may represent a substantial security risk.
pillar_cache_backend: disk
A Salt syndic is a Salt master used to pass commands from a higher Salt master to minions below the syndic. Using the syndic is simple. If this is a master that will have syndic servers(s) below it, set the "order_masters" setting to True.
If this is a master that will be running a syndic daemon for passthrough the "syndic_master" setting needs to be set to the location of the master server.
Do not not forget that, in other words, it means that it shares with the local minion its ID and PKI_DIR.
.. conf_master:: order_masters
Default: False
Extra data needs to be sent with publications if the master is controlling a lower level master via a syndic minion. If this is the case the order_masters value must be set to True
order_masters: False
.. conf_master:: syndic_master
Default: ''
If this master will be running a salt-syndic to connect to a higher level master, specify the higher level master with this configuration value.
syndic_master: masterofmasters
You can optionally connect a syndic to multiple higher level masters by setting the 'syndic_master' value to a list:
syndic_master:
- masterofmasters1
- masterofmasters2
Each higher level master must be set up in a multimaster configuration.
.. conf_master:: syndic_master_port
Default: 4506
If this master will be running a salt-syndic to connect to a higher level master, specify the higher level master port with this configuration value.
syndic_master_port: 4506
.. conf_master:: syndic_pidfile
Default: salt-syndic.pid
If this master will be running a salt-syndic to connect to a higher level master, specify the pidfile of the syndic daemon.
syndic_pidfile: syndic.pid
.. conf_master:: syndic_log_file
Default: syndic.log
If this master will be running a salt-syndic to connect to a higher level master, specify the log_file of the syndic daemon.
syndic_log_file: salt-syndic.log
.. conf_master:: syndic_failover
.. versionadded:: 2016.3.0
Default: random
The behaviour of the multi-syndic when connection to a master of masters failed.
Can specify random
(default) or ordered
. If set to random
, masters
will be iterated in random order. If ordered
is specified, the configured
order will be used.
syndic_failover: random
Salt minions can send commands to other minions, but only if the minion is allowed to. By default "Peer Publication" is disabled, and when enabled it is enabled for specific minions and specific commands. This allows secure compartmentalization of commands based on individual minions.
.. conf_master:: peer
Default: {}
The configuration uses regular expressions to match minions and then a list of regular expressions to match functions. The following will allow the minion authenticated as foo.example.com to execute functions from the test and pkg modules.
peer:
foo.example.com:
- test.*
- pkg.*
This will allow all minions to execute all commands:
peer:
.*:
- .*
This is not recommended, since it would allow anyone who gets root on any single minion to instantly have root on all of the minions!
By adding an additional layer you can limit the target hosts in addition to the accessible commands:
peer:
foo.example.com:
'db*':
- test.*
- pkg.*
.. conf_master:: peer_run
Default: {}
The peer_run option is used to open up runners on the master to access from the minions. The peer_run configuration matches the format of the peer configuration.
The following example would allow foo.example.com to execute the manage.up runner:
peer_run:
foo.example.com:
- manage.up
.. conf_master:: log_file
Default: /var/log/salt/master
The master log can be sent to a regular file, local path name, or network location. See also :conf_log:`log_file`.
Examples:
log_file: /var/log/salt/master
log_file: file:///dev/log
log_file: udp://loghost:10514
.. conf_master:: log_level
Default: warning
The level of messages to send to the console. See also :conf_log:`log_level`.
log_level: warning
.. conf_master:: log_level_logfile
Default: warning
The level of messages to send to the log file. See also :conf_log:`log_level_logfile`. When it is not set explicitly it will inherit the level set by :conf_log:`log_level` option.
log_level_logfile: warning
.. conf_master:: log_datefmt
Default: %H:%M:%S
The date and time format used in console log messages. See also :conf_log:`log_datefmt`.
log_datefmt: '%H:%M:%S'
.. conf_master:: log_datefmt_logfile
Default: %Y-%m-%d %H:%M:%S
The date and time format used in log file messages. See also :conf_log:`log_datefmt_logfile`.
log_datefmt_logfile: '%Y-%m-%d %H:%M:%S'
.. conf_master:: log_fmt_console
Default: [%(levelname)-8s] %(message)s
The format of the console logging messages. See also :conf_log:`log_fmt_console`.
Note
Log colors are enabled in log_fmt_console
rather than the
:conf_master:`color` config since the logging system is loaded before the
master config.
Console log colors are specified by these additional formatters:
%(colorlevel)s %(colorname)s %(colorprocess)s %(colormsg)s
Since it is desirable to include the surrounding brackets, '[' and ']', in the coloring of the messages, these color formatters also include padding as well. Color LogRecord attributes are only available for console logging.
log_fmt_console: '%(colorlevel)s %(colormsg)s'
log_fmt_console: '[%(levelname)-8s] %(message)s'
.. conf_master:: log_fmt_logfile
Default: %(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(message)s
The format of the log file logging messages. See also :conf_log:`log_fmt_logfile`.
log_fmt_logfile: '%(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(message)s'
.. conf_master:: log_granular_levels
Default: {}
This can be used to control logging levels more specifically. See also :conf_log:`log_granular_levels`.
.. conf_master:: nodegroups
Default: {}
Node groups allow for logical groupings of minion nodes. A group consists of a group name and a compound target.
nodegroups:
group1: '[email protected],bar.domain.com,baz.domain.com or bl*.domain.com'
group2: 'G@os:Debian and foo.domain.com'
group3: 'G@os:Debian and N@group1'
group4:
- 'G@foo:bar'
- 'or'
- 'G@foo:baz'
More information on using nodegroups can be found :ref:`here <targeting-nodegroups>`.
.. conf_master:: range_server
Default: 'range:80'
The range server (and optional port) that serves your cluster information https://github.com/ytoolshed/range/wiki/%22yamlfile%22-module-file-spec
range_server: range:80
.. conf_master:: default_include
Default: master.d/*.conf
The master can include configuration from other files. Per default the
master will automatically include all config files from master.d/*.conf
where master.d
is relative to the directory of the master configuration
file.
Note
Salt creates files in the master.d
directory for its own use. These
files are prefixed with an underscore. A common example of this is the
_schedule.conf
file.
.. conf_master:: include
Default: not defined
The master can include configuration from other files. To enable this, pass a list of paths to this option. The paths can be either relative or absolute; if relative, they are considered to be relative to the directory the main minion configuration file lives in. Paths can make use of shell-style globbing. If no files are matched by a path passed to this option then the master will log a warning message.
# Include files from a master.d directory in the same
# directory as the master config file
include: master.d/*
# Include a single extra file into the configuration
include: /etc/roles/webserver
# Include several files and the master.d directory
include:
- extra_config
- master.d/*
- /etc/roles/webserver
.. conf_master:: winrepo_provider
.. versionadded:: 2015.8.0
Specify the provider to be used for winrepo. Must be either pygit2
or
gitpython
. If unset, then both will be tried in that same order, and the
first one with a compatible version installed will be the provider that is
used.
winrepo_provider: gitpython
.. conf_master:: winrepo_dir
.. conf_master:: win_repo
.. versionchanged:: 2015.8.0 Renamed from ``win_repo`` to ``winrepo_dir``.
Default: /srv/salt/win/repo
Location on the master where the :conf_master:`winrepo_remotes` are checked out for pre-2015.8.0 minions. 2015.8.0 and later minions use :conf_master:`winrepo_remotes_ng <winrepo_remotes_ng>` instead.
winrepo_dir: /srv/salt/win/repo
.. conf_master:: winrepo_dir_ng
.. versionadded:: 2015.8.0 A new :ref:`ng <windows-package-manager>` repo was added.
Default: /srv/salt/win/repo-ng
Location on the master where the :conf_master:`winrepo_remotes_ng` are checked out for 2015.8.0 and later minions.
winrepo_dir_ng: /srv/salt/win/repo-ng
.. conf_master:: winrepo_cachefile
.. conf_master:: win_repo_mastercachefile
.. versionchanged:: 2015.8.0 Renamed from ``win_repo_mastercachefile`` to ``winrepo_cachefile``
Note
2015.8.0 and later minions do not use this setting since the cachefile is now located on the minion.
Default: winrepo.p
Path relative to :conf_master:`winrepo_dir` where the winrepo cache should be created.
winrepo_cachefile: winrepo.p
.. conf_master:: winrepo_remotes
.. conf_master:: win_gitrepos
.. versionchanged:: 2015.8.0 Renamed from ``win_gitrepos`` to ``winrepo_remotes``.
Default: ['https://github.com/saltstack/salt-winrepo.git']
List of git repositories to checkout and include in the winrepo for pre-2015.8.0 minions. 2015.8.0 and later minions use :conf_master:`winrepo_remotes_ng <winrepo_remotes_ng>` instead.
winrepo_remotes:
- https://github.com/saltstack/salt-winrepo.git
To specify a specific revision of the repository, prepend a commit ID to the URL of the repository:
winrepo_remotes:
- '<commit_id> https://github.com/saltstack/salt-winrepo.git'
Replace <commit_id>
with the SHA1 hash of a commit ID. Specifying a commit
ID is useful in that it allows one to revert back to a previous version in the
event that an error is introduced in the latest revision of the repo.
.. conf_master:: winrepo_remotes_ng
.. versionadded:: 2015.8.0 A new :ref:`ng <windows-package-manager>` repo was added.
Default: ['https://github.com/saltstack/salt-winrepo-ng.git']
List of git repositories to checkout and include in the winrepo for 2015.8.0 and later minions.
winrepo_remotes_ng:
- https://github.com/saltstack/salt-winrepo-ng.git
To specify a specific revision of the repository, prepend a commit ID to the URL of the repository:
winrepo_remotes:
- '<commit_id> https://github.com/saltstack/salt-winrepo-ng.git'
Replace <commit_id>
with the SHA1 hash of a commit ID. Specifying a commit
ID is useful in that it allows one to revert back to a previous version in the
event that an error is introduced in the latest revision of the repo.
.. conf_master:: winrepo_branch
.. versionadded:: 2015.8.0
Default: master
If the branch is omitted from a winrepo remote, then this branch will be
used instead. For example, in the configuration below, the first two remotes
would use the winrepo
branch/tag, while the third would use the foo
branch/tag.
winrepo_branch: winrepo
ext_pillar:
- git:
- https://mygitserver/winrepo1.git
- https://mygitserver/winrepo2.git:
- foo https://mygitserver/winrepo3.git
.. conf_master:: winrepo_ssl_verify
.. versionadded:: 2015.8.0
.. versionchanged:: 2016.11.0
Default: False
Specifies whether or not to ignore SSL certificate errors when contacting the
remote repository. The False
setting is useful if you're using a
git repo that uses a self-signed certificate. However, keep in mind that
setting this to anything other True
is a considered insecure, and using an
SSH-based transport (if available) may be a better option.
In the 2016.11.0 release, the default config value changed from False
to
True
.
winrepo_ssl_verify: True
These parameters only currently apply to the pygit2
:conf_master:`winrepo_provider`. Authentication works the same as it does in
gitfs, as outlined in the :ref:`GitFS Walkthrough <gitfs-authentication>`,
though the global configuration options are named differently to reflect that
they are for winrepo instead of gitfs.
.. conf_master:: winrepo_user
.. versionadded:: 2015.8.0
Default: ''
Along with :conf_master:`winrepo_password`, is used to authenticate to HTTPS remotes.
winrepo_user: git
.. conf_master:: winrepo_password
.. versionadded:: 2015.8.0
Default: ''
Along with :conf_master:`winrepo_user`, is used to authenticate to HTTPS remotes. This parameter is not required if the repository does not use authentication.
winrepo_password: mypassword
.. conf_master:: winrepo_insecure_auth
.. versionadded:: 2015.8.0
Default: False
By default, Salt will not authenticate to an HTTP (non-HTTPS) remote. This parameter enables authentication over HTTP. Enable this at your own risk.
winrepo_insecure_auth: True
.. conf_master:: winrepo_pubkey
.. versionadded:: 2015.8.0
Default: ''
Along with :conf_master:`winrepo_privkey` (and optionally :conf_master:`winrepo_passphrase`), is used to authenticate to SSH remotes.
winrepo_pubkey: /path/to/key.pub
.. conf_master:: winrepo_privkey
.. versionadded:: 2015.8.0
Default: ''
Along with :conf_master:`winrepo_pubkey` (and optionally :conf_master:`winrepo_passphrase`), is used to authenticate to SSH remotes.
winrepo_privkey: /path/to/key
.. conf_master:: winrepo_passphrase
.. versionadded:: 2015.8.0
Default: ''
This parameter is optional, required only when the SSH key being used to authenticate is protected by a passphrase.
winrepo_passphrase: mypassphrase