FreeBSD Manual Pages

SALT(7) Salt SALT(7)

NAME
salt - Salt Documentation

INTRODUCTION TO SALT
Weare not just talking about NaCl..SS The 30 second summary

Salt is:

o A configuration management system. Salt is capable of maintaining re-
mote nodes in defined states. For example, it can ensure that spe-
cific packages are installed and that specific services are running.

o A distributed remote execution system used to execute commands and
query data on remote nodes. Salt can query and execute commands ei-
ther on individual nodes or by using an arbitrary selection criteria.

It was developed in order to bring the best solutions found in the
world of remote execution together and make them better, faster, and
more malleable. Salt accomplishes this through its ability to handle
large loads of information, and not just dozens but hundreds and even
thousands of individual servers quickly through a simple and manageable
interface.

Simplicity
Providing versatility between massive scale deployments and smaller
systems may seem daunting, but Salt is very simple to set up and main-
tain, regardless of the size of the project. The architecture of Salt
is designed to work with any number of servers, from a handful of local
network systems to international deployments across different data cen-
ters. The topology is a simple server/client model with the needed
functionality built into a single set of daemons. While the default
configuration will work with little to no modification, Salt can be
fine tuned to meet specific needs.

Parallel execution
The core functions of Salt:

o enable commands to remote systems to be called in parallel rather
than serially

o use a secure and encrypted protocol

o use the smallest and fastest network payloads possible

o provide a simple programming interface

Salt also introduces more granular controls to the realm of remote exe-
cution, allowing systems to be targeted not just by hostname, but also
by system properties.

Builds on proven technology
Salt takes advantage of a number of technologies and techniques. The
networking layer is built with the excellent ZeroMQ networking library,
so the Salt daemon includes a viable and transparent AMQ broker. Salt
uses public keys for authentication with the master daemon, then uses
faster AES encryption for payload communication; authentication and en-
cryption are integral to Salt. Salt takes advantage of communication
via msgpack, enabling fast and light network traffic.

Python client interface
In order to allow for simple expansion, Salt execution routines can be
written as plain Python modules. The data collected from Salt execu-
tions can be sent back to the master server, or to any arbitrary pro-
gram. Salt can be called from a simple Python API, or from the command
line, so that Salt can be used to execute one-off commands as well as
operate as an integral part of a larger application.

Fast, flexible, scalable
The result is a system that can execute commands at high speed on tar-
get server groups ranging from one to very many servers. Salt is very
fast, easy to set up, amazingly malleable and provides a single remote
execution architecture that can manage the diverse requirements of any
number of servers. The Salt infrastructure brings together the best of
the remote execution world, amplifies its capabilities and expands its
range, resulting in a system that is as versatile as it is practical,
suitable for any network.

Open
Salt is developed under the Apache 2.0 license, and can be used for
open and proprietary projects. Please submit your expansions back to
the Salt project so that we can all benefit together as Salt grows.
Please feel free to sprinkle Salt around your systems and let the deli-
ciousness come forth.

Salt Community
Join the Salt!

There are many ways to participate in and communicate with the Salt
community.

Salt has an active IRC channel and a mailing list.

Mailing List
Join the salt-users mailing list. It is the best place to ask questions
about Salt and see whats going on with Salt development! The Salt mail-
ing list is hosted by Google Groups. It is open to new members.

Additionally, all users of Salt should be subscribed to the Announce-
ments mailing list which contains important updates about Salt, such as
new releaes and security-related announcements. This list is low-traf-
fic.

IRC
The #salt IRC channel is hosted on the popular Freenode network. You
can use the Freenode webchat client right from your browser. Logs of
the IRC channel activity are also available.

If you wish to discuss the development of Salt itself join us in
#salt-devel.

Follow on Github
The Salt code is developed via Github. Follow Salt for constant updates
on what is happening in Salt development:

https://github.com/saltstack/salt

Long-term planning and strategic decisions are handled via Salt En-
hancement Proposals and can be found on GitHub.

Blogs
SaltStack Inc. keeps a blog with recent news and advancements:

http://www.saltstack.com/blog/

Example Salt States
The official salt-states repository is:
https://github.com/SS-archive/salt-states

A few examples of salt states from the community:

o https://github.com/blast-hardcheese/blast-salt-states

o https://github.com/kevingranade/kevingranade-salt-state

o https://github.com/uggedal/states

o https://github.com/mattmcclean/salt-openstack/tree/master/salt

o https://github.com/rentalita/ubuntu-setup/

o https://github.com/brutasse/states

o https://github.com/bclermont/states

o https://github.com/pcrews/salt-data

Follow on Open Hub
https://www.openhub.net/p/salt

SEE ALSO:
static-custom-grains

Statically assigns grains to the minion.

grains:
roles:
- webserver
- memcache
deployment: datacenter4
cabinet: 13
cab_u: 14-15

grains_blacklist
Default: []

Each grains key will be compared against each of the expressions in
this list. Any keys which match will be filtered from the grains. Ex-
act matches, glob matches, and regular expressions are supported.

NOTE:
Some states and execution modules depend on grains. Filtering may
cause them to be unavailable or run unreliably.

New in version 3000.

grains_blacklist:
- cpu_flags
- zmq*
- ipv[46]

grains_cache
Default: False

The minion can locally cache grain data instead of refreshing the data
each time the grain is referenced. By default this feature is disabled,
to enable set grains_cache to True.

grains_cache: False

grains_cache_expiration
Default: 300

Grains cache expiration, in seconds. If the cache file is older than
this number of seconds then the grains cache will be dumped and fully
re-populated with fresh data. Defaults to 5 minutes. Will have no ef-
fect if grains_cache is not enabled.

grains_cache_expiration: 300

grains_deep_merge
New in version 2016.3.0.

Default: False

The grains can be merged, instead of overridden, using this option.
This allows custom grains to defined different subvalues of a dictio-
nary grain. By default this feature is disabled, to enable set
grains_deep_merge to True.

grains_deep_merge: False

For example, with these custom grains functions:

def custom1_k1():
return {"custom1": {"k1": "v1"}}

def custom1_k2():
return {"custom1": {"k2": "v2"}}

Without grains_deep_merge, the result would be:

custom1:
k1: v1

With grains_deep_merge, the result will be:

custom1:
k1: v1
k2: v2

grains_refresh_every
Default: 0

The grains_refresh_every setting allows for a minion to periodically
check its grains to see if they have changed and, if so, to inform the
master of the new grains. This operation is moderately expensive,
therefore care should be taken not to set this value too low.

Note: This value is expressed in minutes.

A value of 10 minutes is a reasonable default.

grains_refresh_every: 0

metadata_server_grains
New in version 2017.7.0.

Default: False

Set this option to enable gathering of cloud metadata from
http://169.254.169.254/latest for use in grains (see here for more in-
formation).

metadata_server_grains: True

fibre_channel_grains
Default: False

The fibre_channel_grains setting will enable the fc_wwn grain for Fibre
Channel WWN's on the minion. Since this grain is expensive, it is dis-
abled by default.

fibre_channel_grains: True

iscsi_grains
Default: False

The iscsi_grains setting will enable the iscsi_iqn grain on the minion.
Since this grain is expensive, it is disabled by default.

iscsi_grains: True

nvme_grains
Default: False

The nvme_grains setting will enable the nvme_nqn grain on the minion.
Since this grain is expensive, it is disabled by default.

nvme_grains: True

mine_enabled
New in version 2015.8.10.

Default: True

Determines whether or not the salt minion should run scheduled mine up-
dates. If this is set to False then the mine update function will not
get added to the scheduler for the minion.

mine_enabled: True

mine_return_job
New in version 2015.8.10.

Default: False

Determines whether or not scheduled mine updates should be accompanied
by a job return for the job cache.

mine_return_job: False

mine_functions
Default: Empty

Designate which functions should be executed at mine_interval intervals
on each minion. See this documentation on the Salt Mine for more in-
formation. Note these can be defined in the pillar for a minion as
well.
example minion configuration file

mine_functions:
test.ping: []
network.ip_addrs:
interface: eth0
cidr: '10.0.0.0/8'

mine_interval
Default: 60

The number of minutes between mine updates.

mine_interval: 60

sock_dir
Default: /var/run/salt/minion

The directory where Unix sockets will be kept.

sock_dir: /var/run/salt/minion

enable_fqdns_grains
Default: True

In order to calculate the fqdns grain, all the IP addresses from the
minion are processed with underlying calls to socket.gethostbyaddr
which can take 5 seconds to be released (after reaching socket.timeout)
when there is no fqdn for that IP. These calls to socket.gethostbyaddr
are processed asynchronously, however, it still adds 5 seconds every
time grains are generated if an IP does not resolve. In Windows grains
are regenerated each time a new process is spawned. Therefore, the de-
fault for Windows is False. In many cases this value does not make
sense to include for proxy minions as it will be FQDN for the host run-
ning the proxy minion process, so the default for proxy minions is
False`. All other OSes default to True. This options was added here.

enable_fqdns_grains: False

enable_gpu_grains
Default: True

Enable GPU hardware data for your master. Be aware that the minion can
take a while to start up when lspci and/or dmidecode is used to popu-
late the grains for the minion, so this can be set to False if you do
not need these grains.

enable_gpu_grains: False

outputter_dirs
Default: []

A list of additional directories to search for salt outputters in.

outputter_dirs: []

backup_mode
Default: ''

Make backups of files replaced by file.managed and file.recurse state
modules under cachedir in file_backup subdirectory preserving original
paths. Refer to File State Backups documentation for more details.

backup_mode: minion

acceptance_wait_time
Default: 10

The number of seconds to wait until attempting to re-authenticate with
the master.

acceptance_wait_time: 10

acceptance_wait_time_max
Default: 0

The maximum number of seconds to wait until attempting to re-authenti-
cate with the master. If set, the wait will increase by
acceptance_wait_time seconds each iteration.

acceptance_wait_time_max: 0

rejected_retry
Default: False

If the master rejects the minion's public key, retry instead of exit-
ing. Rejected keys will be handled the same as waiting on acceptance.

rejected_retry: False

random_reauth_delay
Default: 10

When the master key changes, the minion will try to re-auth itself to
receive the new master key. In larger environments this can cause a
syn-flood on the master because all minions try to re-auth immediately.
To prevent this and have a minion wait for a random amount of time, use
this optional parameter. The wait-time will be a random number of sec-
onds between 0 and the defined value.

random_reauth_delay: 60

master_tries
New in version 2016.3.0.

Default: 1

The number of attempts to connect to a master before giving up. Set
this to -1 for unlimited attempts. This allows for a master to have
downtime and the minion to reconnect to it later when it comes back up.
In 'failover' mode, which is set in the master_type configuration, this
value is the number of attempts for each set of masters. In this mode,
it will cycle through the list of masters for each attempt.

master_tries is different than auth_tries because auth_tries attempts
to retry auth attempts with a single master. auth_tries is under the
assumption that you can connect to the master but not gain authoriza-
tion from it. master_tries will still cycle through all of the masters
in a given try, so it is appropriate if you expect occasional downtime
from the master(s).

master_tries: 1

auth_tries
New in version 2014.7.0.

Default: 7

The number of attempts to authenticate to a master before giving up.
Or, more technically, the number of consecutive SaltReqTimeoutErrors
that are acceptable when trying to authenticate to the master.

auth_tries: 7

auth_timeout
New in version 2014.7.0.

Default: 60

When waiting for a master to accept the minion's public key, salt will
continuously attempt to reconnect until successful. This is the timeout
value, in seconds, for each individual attempt. After this timeout ex-
pires, the minion will wait for acceptance_wait_time seconds before
trying again. Unless your master is under unusually heavy load, this
should be left at the default.

auth_timeout: 60

auth_safemode
New in version 2014.7.0.

Default: False

If authentication fails due to SaltReqTimeoutError during a ping_inter-
val, this setting, when set to True, will cause a sub-minion process to
restart.

auth_safemode: False

ping_interval
Default: 0

Instructs the minion to ping its master(s) every n number of minutes.
Used primarily as a mitigation technique against minion disconnects.

ping_interval: 0

random_startup_delay
Default: 0

The maximum bound for an interval in which a minion will randomly sleep
upon starting up prior to attempting to connect to a master. This can
be used to splay connection attempts for cases where many minions
starting up at once may place undue load on a master.

For example, setting this to 5 will tell a minion to sleep for a value
between 0 and 5 seconds.

random_startup_delay: 5

recon_default
Default: 1000

The interval in milliseconds that the socket should wait before trying
to reconnect to the master (1000ms = 1 second).

recon_default: 1000

recon_max
Default: 10000

The maximum time a socket should wait. Each interval the time to wait
is calculated by doubling the previous time. If recon_max is reached,
it starts again at the recon_default.

Short example:

o reconnect 1: the socket will wait 'recon_default' milliseconds

o reconnect 2: 'recon_default' * 2

o reconnect 3: ('recon_default' * 2) * 2

o reconnect 4: value from previous interval * 2

o reconnect 5: value from previous interval * 2

o reconnect x: if value >= recon_max, it starts again with re-
con_default

recon_max: 10000

recon_randomize
Default: True

Generate a random wait time on minion start. The wait time will be a
random value between recon_default and recon_default + recon_max. Hav-
ing all minions reconnect with the same recon_default and recon_max
value kind of defeats the purpose of being able to change these set-
tings. If all minions have the same values and the setup is quite large
(several thousand minions), they will still flood the master. The de-
sired behavior is to have time-frame within all minions try to recon-
nect.

recon_randomize: True

loop_interval
Default: 1

The loop_interval sets how long in seconds the minion will wait between
evaluating the scheduler and running cleanup tasks. This defaults to 1
second on the minion scheduler.

loop_interval: 1

pub_ret
Default: True

Some installations choose to start all job returns in a cache or a re-
turner and forgo sending the results back to a master. In this work-
flow, jobs are most often executed with --async from the Salt CLI and
then results are evaluated by examining job caches on the minions or
any configured returners. WARNING: Setting this to False will disable
returns back to the master.

pub_ret: True

return_retry_timer
Default: 5

The default timeout for a minion return attempt.

return_retry_timer: 5

return_retry_timer_max
Default: 10

The maximum timeout for a minion return attempt. If non-zero the minion
return retry timeout will be a random int between return_retry_timer
and return_retry_timer_max

return_retry_timer_max: 10

cache_sreqs
Default: True

The connection to the master ret_port is kept open. When set to False,
the minion creates a new connection for every return to the master.

cache_sreqs: True

ipc_mode
Default: ipc

Windows platforms lack POSIX IPC and must rely on slower TCP based in-
ter- process communications. ipc_mode is set to tcp on such systems.

ipc_mode: ipc

tcp_pub_port
Default: 4510

Publish port used when ipc_mode is set to tcp.

tcp_pub_port: 4510

tcp_pull_port
Default: 4511

Pull port used when ipc_mode is set to tcp.

tcp_pull_port: 4511

transport
Default: zeromq

transport: zeromq

syndic_finger
Default: ''

The key fingerprint of the higher-level master for the syndic to verify
it is talking to the intended master.

syndic_finger: 'ab:30:65:2a:d6:9e:20:4f:d8:b2:f3:a7:d4:65:50:10'

http_connect_timeout
New in version 2019.2.0.

Default: 20

HTTP connection timeout in seconds. Applied when fetching files using
tornado back-end. Should be greater than overall download time.

http_connect_timeout: 20

http_request_timeout
New in version 2015.8.0.

Default: 3600

HTTP request timeout in seconds. Applied when fetching files using
tornado back-end. Should be greater than overall download time.

http_request_timeout: 3600

proxy_host
Default: ''

The hostname used for HTTP proxy access.

proxy_host: proxy.my-domain

proxy_port
Default: 0

The port number used for HTTP proxy access.

proxy_port: 31337

proxy_username
Default: ''

The username used for HTTP proxy access.

proxy_username: charon

proxy_password
Default: ''

The password used for HTTP proxy access.

proxy_password: obolus

no_proxy
New in version 2019.2.0.

Default: []

List of hosts to bypass HTTP proxy

NOTE:
This key does nothing unless proxy_host etc is configured, it does
not support any kind of wildcards.

no_proxy: [ '127.0.0.1', 'foo.tld' ]

use_yamlloader_old
New in version 2019.2.1.

Default: False

Use the pre-2019.2 YAML renderer. Uses legacy YAML rendering to sup-
port some legacy inline data structures. See the 2019.2.1 release
notes for more details.

use_yamlloader_old: False

Docker Configuration
docker.update_mine
New in version 2017.7.8,2018.3.3.

Changed in version 2019.2.0: The default value is now False

Default: True

If enabled, when containers are added, removed, stopped, started, etc.,
the mine will be updated with the results of docker.ps verbose=True
all=True host=True. This mine data is used by mine.get_docker. Set this
option to False to keep Salt from updating the mine with this informa-
tion.

NOTE:
This option can also be set in Grains or Pillar data, with Grains
overriding Pillar and the minion config file overriding Grains.

NOTE:
Disabling this will of course keep mine.get_docker from returning
any information for a given minion.

docker.update_mine: False

docker.compare_container_networks
New in version 2018.3.0.

Default: {'static': ['Aliases', 'Links', 'IPAMConfig'], 'automatic':
['IPAddress', 'Gateway', 'GlobalIPv6Address', 'IPv6Gateway']}

Specifies which keys are examined by docker.compare_container_networks.

NOTE:
This should not need to be modified unless new features added to
Docker result in new keys added to the network configuration which
must be compared to determine if two containers have different net-
work configs. This config option exists solely as a way to allow
users to continue using Salt to manage their containers after an API
change, without waiting for a new Salt release to catch up to the
changes in the Docker API.

docker.compare_container_networks:
static:
- Aliases
- Links
- IPAMConfig
automatic:
- IPAddress
- Gateway
- GlobalIPv6Address
- IPv6Gateway

optimization_order
Default: [0, 1, 2]

In cases where Salt is distributed without .py files, this option de-
termines the priority of optimization level(s) Salt's module loader
should prefer.

NOTE:
This option is only supported on Python 3.5+.

optimization_order:
- 2
- 0
- 1

Minion Execution Module Management
disable_modules
Default: [] (all execution modules are enabled by default)

The event may occur in which the administrator desires that a minion
should not be able to execute a certain module.

However, the sys module is built into the minion and cannot be dis-
abled.

This setting can also tune the minion. Because all modules are loaded
into system memory, disabling modules will lower the minion's memory
footprint.

Modules should be specified according to their file name on the system
and not by their virtual name. For example, to disable cmd, use the
string cmdmod which corresponds to salt.modules.cmdmod.

disable_modules:
- test
- solr

disable_returners
Default: [] (all returners are enabled by default)

If certain returners should be disabled, this is the place

disable_returners:
- mongo_return

whitelist_modules
Default: [] (Module whitelisting is disabled. Adding anything to the
config option will cause only the listed modules to be enabled. Mod-
ules not in the list will not be loaded.)

This option is the reverse of disable_modules. If enabled, only execu-
tion modules in this list will be loaded and executed on the minion.

Note that this is a very large hammer and it can be quite difficult to
keep the minion working the way you think it should since Salt uses
many modules internally itself. At a bare minimum you need the follow-
ing enabled or else the minion won't start.

whitelist_modules:
- cmdmod
- test
- config

module_dirs
Default: []

A list of extra directories to search for Salt modules

module_dirs:
- /var/lib/salt/modules

returner_dirs
Default: []

A list of extra directories to search for Salt returners

returner_dirs:
- /var/lib/salt/returners

states_dirs
Default: []

A list of extra directories to search for Salt states

states_dirs:
- /var/lib/salt/states

grains_dirs
Default: []

A list of extra directories to search for Salt grains

grains_dirs:
- /var/lib/salt/grains

render_dirs
Default: []

A list of extra directories to search for Salt renderers

render_dirs:
- /var/lib/salt/renderers

utils_dirs
Default: []

A list of extra directories to search for Salt utilities

utils_dirs:
- /var/lib/salt/utils

cython_enable
Default: False

Set this value to true to enable auto-loading and compiling of .pyx
modules, This setting requires that gcc and cython are installed on the
minion.

cython_enable: False

enable_zip_modules
New in version 2015.8.0.

Default: False

Set this value to true to enable loading of zip archives as extension
modules. This allows for packing module code with specific dependen-
cies to avoid conflicts and/or having to install specific modules' de-
pendencies in system libraries.

enable_zip_modules: False

providers
Default: (empty)

A module provider can be statically overwritten or extended for the
minion via the providers option. This can be done on an individual ba-
sis in an SLS file, or globally here in the minion config, like below.

providers:
service: systemd

modules_max_memory
Default: -1

Specify a max size (in bytes) for modules on import. This feature is
currently only supported on *NIX operating systems and requires psutil.

modules_max_memory: -1

extmod_whitelist/extmod_blacklist
New in version 2017.7.0.

By using this dictionary, the modules that are synced to the minion's
extmod cache using saltutil.sync_* can be limited. If nothing is set
to a specific type, then all modules are accepted. To block all mod-
ules of a specific type, whitelist an empty list.

extmod_whitelist:
modules:
- custom_module
engines:
- custom_engine
pillars: []

extmod_blacklist:
modules:
- specific_module

Valid options:

o beacons

o clouds

o sdb

o modules

o states

o grains

o renderers

o returners

o proxy

o engines

o output

o utils

o pillar

Top File Settings
These parameters only have an effect if running a masterless minion.

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

state_top_saltenv
This option has no default value. Set it to an environment name to en-
sure that only the top file from that environment is considered during
a highstate.

state_top_saltenv: dev

top_file_merging_strategy
Changed in version 2016.11.0: A merge_all strategy has been added.

Default: merge

top_file_merging_strategy: same

env_order
Default: []

When top_file_merging_strategy is set to merge, and no environment is
specified for a highstate, this config option allows for the order in
which top files are evaluated to be explicitly defined.

env_order:
- base
- dev
- qa

default_top
Default: base

When top_file_merging_strategy is set to same, and no environment is
specified for a highstate (i.e. environment is not set for the min-
ion), this config option specifies a fallback environment in which to
look for a top file if an environment lacks one.

default_top: dev

startup_states
Default: ''

States to run when the minion daemon starts. To enable, set
startup_states to:

o highstate: Execute state.highstate

o sls: Read in the sls_list option and execute the named sls files

o top: Read top_file option and execute based on that file on the Mas-
ter

startup_states: ''

sls_list
Default: []

List of states to run when the minion starts up if startup_states is
set to sls.

sls_list:
- edit.vim
- hyper

start_event_grains
Default: []

List of grains to pass in start event when minion starts up.

start_event_grains:
- machine_id
- uuid

top_file
Default: ''

Top file to execute if startup_states is set to top.

top_file: ''

State Management Settings
renderer
Default: jinja|yaml

The default renderer used for local state executions

renderer: jinja|json

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

state_verbose
Default: True

state_verbose: True

state_output
Default: full

The state_output setting controls which results will be output full
multi line:

o full, terse - each state will be full/terse

o mixed - only states with errors will be full

o changes - states with changes and errors will be full

full_id, mixed_id, changes_id and terse_id are also allowed; when set,
the state ID will be used as name in the output.

state_output: full

state_output_diff
Default: False

state_output_diff: False

autoload_dynamic_modules
Default: True

autoload_dynamic_modules turns on automatic loading of modules found in
the environments on the master. This is turned on by default. To turn
off auto-loading modules when states run, set this value to False.

autoload_dynamic_modules: True

clean_dynamic_modules
Default: True

clean_dynamic_modules keeps the dynamic modules on the minion in sync
with the dynamic modules on the master. This means that if a dynamic
module is not on the master it will be deleted from the minion. By de-
fault this is enabled and can be disabled by changing this value to
False.

clean_dynamic_modules: True

NOTE:
If extmod_whitelist is specified, modules which are not whitelisted
will also be cleaned here.

saltenv
Changed in version 2018.3.0: Renamed from environment to saltenv. If
environment is used, saltenv will take its value. If both are used, en-
vironment will be ignored and saltenv will be used.

Normally the minion is not isolated to any single environment on the
master when running states, but the environment can be isolated on the
minion side by statically setting it. Remember that the recommended way
to manage environments is to isolate via the top file.

saltenv: dev

lock_saltenv
New in version 2018.3.0.

Default: False

For purposes of running states, this option prevents using the saltenv
argument to manually set the environment. This is useful to keep a min-
ion which has the saltenv option set to dev from running states from an
environment other than dev.

lock_saltenv: True

snapper_states
Default: False

The snapper_states value is used to enable taking snapper snapshots be-
fore and after salt state runs. This allows for state runs to be rolled
back.

For snapper states to function properly snapper needs to be installed
and enabled.

snapper_states: True

snapper_states_config
Default: root

Snapper can execute based on a snapper configuration. The configuration
needs to be set up before snapper can use it. The default configuration
is root, this default makes snapper run on SUSE systems using the de-
fault configuration set up at install time.

snapper_states_config: root

File Directory Settings
file_client
Default: remote

The client defaults to looking on the master server for files, but can
be directed to look on the minion by setting this parameter to local.

file_client: remote

use_master_when_local
Default: False

When using a local file_client, this parameter is used to allow the
client to connect to a master for remote execution.

use_master_when_local: False

file_roots
Default:

base:
- /usr/local/etc/salt/states

When using a local file_client, this parameter is used to setup the
fileserver's environments. This parameter operates identically to the
master config parameter of the same name.

fileserver_followsymlinks
New in version 2014.1.0.

Default: True

By default, the file_server follows symlinks when walking the filesys-
tem tree. Currently this only applies to the default roots file-
server_backend.

fileserver_followsymlinks: True

fileserver_ignoresymlinks
New in version 2014.1.0.

Default: False

fileserver_ignoresymlinks: False

fileserver_limit_traversal
New in version 2014.1.0.

Default: False

fileserver_limit_traversal: False

hash_type
Default: sha256

The hash_type is the hash to use when discovering the hash of a file on
the local fileserver. The default is sha256, but md5, sha1, sha224,
sha384, and sha512 are also supported.

hash_type: sha256

Pillar Configuration
pillar_roots
Default:

base:
- /usr/local/etc/salt/pillar

When using a local file_client, this parameter is used to setup the
pillar environments.

pillar_roots:
base:
- /usr/local/etc/salt/pillar
dev:
- /usr/local/etc/salt/pillar/dev
prod:
- /usr/local/etc/salt/pillar/prod

on_demand_ext_pillar
New in version 2016.3.6,2016.11.3,2017.7.0.

Default: ['libvirt', 'virtkey']

When using a local file_client, this option controls which external
pillars are permitted to be used on-demand using pillar.ext.

on_demand_ext_pillar:
- libvirt
- virtkey
- git

WARNING:
This will allow a masterless minion to request specific pillar data
via pillar.ext, and may be considered a security risk. However, pil-
lar data generated in this way will not affect the in-memory pillar
data, so this risk is limited to instances in which states/mod-
ules/etc. (built-in or custom) rely upon pillar data generated by
pillar.ext.

decrypt_pillar
New in version 2017.7.0.

Default: []

A list of paths to be recursively decrypted during pillar compilation.

decrypt_pillar:
- 'foo:bar': gpg
- 'lorem:ipsum:dolor'

decrypt_pillar_delimiter
New in version 2017.7.0.

Default: :

The delimiter used to distinguish nested data structures in the
decrypt_pillar option.

decrypt_pillar_delimiter: '|'
decrypt_pillar:
- 'foo|bar': gpg
- 'lorem|ipsum|dolor'

decrypt_pillar_default
New in version 2017.7.0.

Default: gpg

The default renderer used for decryption, if one is not specified for a
given pillar key in decrypt_pillar.

decrypt_pillar_default: my_custom_renderer

decrypt_pillar_renderers
New in version 2017.7.0.

Default: ['gpg']

List of renderers which are permitted to be used for pillar decryption.

decrypt_pillar_renderers:
- gpg
- my_custom_renderer

pillarenv
Default: None

Isolates the pillar environment on the minion side. This functions the
same as the environment setting, but for pillar instead of states.

pillarenv: dev

pillarenv_from_saltenv
New in version 2017.7.0.

Default: False

When set to True, the pillarenv value will assume the value of the ef-
fective saltenv when running states. This essentially makes salt '*'
state.sls mysls saltenv=dev equivalent to salt '*' state.sls mysls
saltenv=dev pillarenv=dev. If pillarenv is set, either in the minion
config file or via the CLI, it will override this option.

pillarenv_from_saltenv: True

pillar_raise_on_missing
New in version 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.

minion_pillar_cache
New in version 2016.3.0.

Default: False

The minion can locally cache rendered pillar data under
cachedir/pillar. This allows a temporarily disconnected minion to ac-
cess previously cached pillar data by invoking salt-call with the --lo-
cal and --pillar_root=:conf_minion:cachedir/pillar options. Before en-
abling this setting consider that the rendered pillar may contain secu-
rity sensitive data. Appropriate access restrictions should be in
place. By default the saved pillar data will be readable only by the
user account running salt. By default this feature is disabled, to en-
able set minion_pillar_cache to True.

minion_pillar_cache: False

file_recv_max_size
New in version 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

pass_to_ext_pillars
Specify a list of configuration keys whose values are to be passed to
external pillar functions.

Suboptions can be specified using the ':' notation (i.e. option:subop-
tion)

The values are merged and included in the extra_minion_data optional
parameter of the external pillar function. The extra_minion_data pa-
rameter is passed only to the external pillar functions that have it
explicitly specified in their definition.

If the config contains

opt1: value1
opt2:
subopt1: value2
subopt2: value3

pass_to_ext_pillars:
- opt1
- opt2: subopt1

the extra_minion_data parameter will be

{"opt1": "value1", "opt2": {"subopt1": "value2"}}

ssh_merge_pillar
New in version 2018.3.2.

Default: True

Merges the compiled pillar data with the pillar data already available
globally. This is useful when using salt-ssh or salt-call --local and
overriding the pillar data in a state file:

apply_showpillar:
module.run:
- name: state.apply
- mods:
- showpillar
- kwargs:
pillar:
test: "foo bar"

If set to True, the showpillar state will have access to the global
pillar data.

If set to False, only the overriding pillar data will be available to
the showpillar state.

Security Settings
open_mode
Default: False

Open mode can be used to clean out the PKI key received from the Salt
master, turn on open mode, restart the minion, then turn off open mode
and restart the minion to clean the keys.

open_mode: False

master_finger
Default: ''

Fingerprint of the master public key to validate the identity of your
Salt master before the initial key exchange. The master fingerprint can
be found as master.pub by running "salt-key -F master" on the Salt mas-
ter.

master_finger: 'ba:30:65:2a:d6:9e:20:4f:d8:b2:f3:a7:d4:65:11:13'

keysize
Default: 2048

The size of key that should be generated when creating new keys.

keysize: 2048

permissive_pki_access
Default: False

permissive_pki_access: False

verify_master_pubkey_sign
Default: False

Enables verification of the master-public-signature returned by the
master in auth-replies. Please see the tutorial on how to configure
this properly Multimaster-PKI with Failover Tutorial

New in version 2014.7.0.

verify_master_pubkey_sign: True

If this is set to True, master_sign_pubkey must be also set to True in
the master configuration file.

master_sign_key_name
Default: master_sign

The filename without the .pub suffix of the public key that should be
used for verifying the signature from the master. The file must be lo-
cated in the minion's pki directory.

New in version 2014.7.0.

master_sign_key_name: <filename_without_suffix>

autosign_grains
New in version 2018.3.0.

Default: not defined

The grains that should be sent to the master on authentication to de-
cide if the minion's key should be accepted automatically.

Please see the Autoaccept Minions from Grains documentation for more
information.

autosign_grains:
- uuid
- server_id

always_verify_signature
Default: False

If verify_master_pubkey_sign is enabled, the signature is only verified
if the public-key of the master changes. If the signature should always
be verified, this can be set to True.

New in version 2014.7.0.

always_verify_signature: True

cmd_blacklist_glob
Default: []

If cmd_blacklist_glob is enabled then any shell command called over re-
mote execution or via salt-call will be checked against the glob
matches found in the cmd_blacklist_glob list and any matched shell com-
mand will be blocked.

NOTE:
This blacklist is only applied to direct executions made by the salt
and salt-call commands. This does NOT blacklist commands called from
states or shell commands executed from other modules.

New in version 2016.11.0.

cmd_blacklist_glob:
- 'rm * '
- 'cat /etc/* '

cmd_whitelist_glob
Default: []

If cmd_whitelist_glob is enabled then any shell command called over re-
mote execution or via salt-call will be checked against the glob
matches found in the cmd_whitelist_glob list and any shell command NOT
found in the list will be blocked. If cmd_whitelist_glob is NOT SET,
then all shell commands are permitted.

NOTE:
This whitelist is only applied to direct executions made by the salt
and salt-call commands. This does NOT restrict commands called from
states or shell commands executed from other modules.

New in version 2016.11.0.

cmd_whitelist_glob:
- 'ls * '
- 'cat /etc/fstab'

ssl
New in version 2016.11.0.

Default: None

TLS/SSL connection options. This could be set to a dictionary contain-
ing arguments corresponding to python ssl.wrap_socket method. For de-
tails 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 PROTO-
COL_SSLv23.

ssl:
keyfile: <path_to_keyfile>
certfile: <path_to_certfile>
ssl_version: PROTOCOL_TLSv1_2

Reactor Settings
reactor
Default: []

Defines a salt reactor. See the Reactor documentation for more informa-
tion.

reactor: []

reactor_refresh_interval
Default: 60

The TTL for the cache of the reactor configuration.

reactor_refresh_interval: 60

reactor_worker_threads
Default: 10

The number of workers for the runner/wheel in the reactor.

reactor_worker_threads: 10

reactor_worker_hwm
Default: 10000

The queue size for workers in the reactor.

reactor_worker_hwm: 10000

Thread Settings
multiprocessing
Default: True

If multiprocessing is enabled when a minion receives a publication a
new process is spawned and the command is executed therein. Con-
versely, if multiprocessing is disabled the new publication will be run
executed in a thread.

multiprocessing: True

process_count_max
New in version 2018.3.0.

Default: -1

Limit the maximum amount of processes or threads created by salt-min-
ion. This is useful to avoid resource exhaustion in case the minion
receives more publications than it is able to handle, as it limits the
number of spawned processes or threads. -1 is the default and disables
the limit.

process_count_max: -1

Minion Logging Settings
log_file
Default: /var/log/salt/minion

The minion log can be sent to a regular file, local path name, or net-
work location. See also log_file.

Examples:

log_file: /var/log/salt/minion

log_file: file:///dev/log

log_file: udp://loghost:10514

log_level
Default: warning

The level of messages to send to the console. See also log_level.

log_level: warning

log_level_logfile
Default: warning

The level of messages to send to the log file. See also log_level_log-
file. When it is not set explicitly it will inherit the level set by
log_level option.

log_level_logfile: warning

log_datefmt
Default: %H:%M:%S

The date and time format used in console log messages. See also
log_datefmt.

log_datefmt: '%H:%M:%S'

log_datefmt_logfile
Default: %Y-%m-%d %H:%M:%S

The date and time format used in log file messages. See also
log_datefmt_logfile.

log_datefmt_logfile: '%Y-%m-%d %H:%M:%S'

log_fmt_console
Default: [%(levelname)-8s] %(message)s

The format of the console logging messages. See also log_fmt_console.

NOTE:
Log colors are enabled in log_fmt_console rather than the color con-
fig since the logging system is loaded before the minion config.

Console log colors are specified by these additional formatters:

%(colorlevel)s %(colorname)s %(colorprocess)s %(colormsg)s

log_fmt_console: '%(colorlevel)s %(colormsg)s'
log_fmt_console: '[%(levelname)-8s] %(message)s'

log_fmt_logfile
Default: %(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(mes-
sage)s

The format of the log file logging messages. See also log_fmt_logfile.

log_fmt_logfile: '%(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(message)s'

log_granular_levels
Default: {}

This can be used to control logging levels more specifically. See also
log_granular_levels.

log_rotate_max_bytes
Default: 0

log_rotate_backup_count
Default: 0

zmq_monitor
Default: False

To diagnose issues with minions disconnecting or missing returns, Ze-
roMQ supports the use of monitor sockets to log connection events. This
feature requires ZeroMQ 4.0 or higher.

To enable ZeroMQ monitor sockets, set 'zmq_monitor' to 'True' and log
at a debug level or higher.

A sample log event is as follows:

[DEBUG ] ZeroMQ event: {'endpoint': 'tcp://127.0.0.1:4505', 'event': 512,
'value': 27, 'description': 'EVENT_DISCONNECTED'}

All events logged will include the string ZeroMQ event. A connection
event should be logged as the minion starts up and initially connects
to the master. If not, check for debug log level and that the necessary
version of ZeroMQ is installed.

tcp_authentication_retries
Default: 5

The number of times to retry authenticating with the salt master when
it comes back online.

Zeromq does a lot to make sure when connections come back online that
they reauthenticate. The tcp transport should try to connect with a new
connection if the old one times out on reauthenticating.

-1 for infinite tries.

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

Include Configuration
Configuration can be loaded from multiple files. The order in which
this is done is:

1. The minion config file itself

2. The files matching the glob in default_include

3. The files matching the glob in include (if defined)

Each successive step overrides any values defined in the previous
steps. Therefore, any config options defined in one of the
default_include files would override the same value in the minion con-
fig file, and any options defined in include would override both.

default_include
Default: minion.d/*.conf

The minion can include configuration from other files. Per default the
minion will automatically include all config files from minion.d/*.conf
where minion.d is relative to the directory of the minion configuration
file.

NOTE:
Salt creates files in the minion.d directory for its own use. These
files are prefixed with an underscore. A common example of this is
the _schedule.conf file.

include
Default: not defined

The minion 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 di-
rectory 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 minion will log a warning message.

# Include files from a minion.d directory in the same
# directory as the minion config file
include: minion.d/*.conf

# Include a single extra file into the configuration
include: /etc/roles/webserver

# Include several files and the minion.d directory
include:
- extra_config
- minion.d/*
- /etc/roles/webserver

Keepalive Settings
tcp_keepalive
Default: True

The tcp keepalive interval to set on TCP ports. This setting can be
used to tune Salt connectivity issues in messy network environments
with misbehaving firewalls.

tcp_keepalive: True

tcp_keepalive_cnt
Default: -1

Sets the ZeroMQ TCP keepalive count. May be used to tune issues with
minion disconnects.

tcp_keepalive_cnt: -1

tcp_keepalive_idle
Default: 300

Sets ZeroMQ TCP keepalive idle. May be used to tune issues with minion
disconnects.

tcp_keepalive_idle: 300

tcp_keepalive_intvl
Default: -1

Sets ZeroMQ TCP keepalive interval. May be used to tune issues with
minion disconnects.

tcp_keepalive_intvl': -1

Frozen Build Update Settings
These options control how salt.modules.saltutil.update() works with
esky frozen apps. For more information look at
https://github.com/cloudmatrix/esky/.

update_url
Default: False (Update feature is disabled)

The url to use when looking for application updates. Esky depends on
directory listings to search for new versions. A webserver running on
your Master is a good starting point for most setups.

update_url: 'http://salt.example.com/minion-updates'

update_restart_services
Default: [] (service restarting on update is disabled)

A list of services to restart when the minion software is updated. This
would typically just be a list containing the minion's service name,
but you may have other services that need to go with it.

update_restart_services: ['salt-minion']

Windows Software Repo Settings
These settings apply to all minions, whether running in masterless or
master-minion mode.

winrepo_cache_expire_min
New in version 2016.11.0.

Default: 1800

If set to a nonzero integer, then passing refresh=True to functions in
the windows pkg module will not refresh the windows repo metadata if
the age of the metadata is less than this value. The exception to this
is pkg.refresh_db, which will always refresh the metadata, regardless
of age.

winrepo_cache_expire_min: 1800

winrepo_cache_expire_max
New in version 2016.11.0.

Default: 21600

If the windows repo metadata is older than this value, and the metadata
is needed by a function in the windows pkg module, the metadata will be
refreshed.

winrepo_cache_expire_max: 86400

winrepo_source_dir
Default: salt://win/repo-ng/

The source location for the winrepo sls files.

winrepo_source_dir: salt://win/repo-ng/

Standalone Minion Windows Software Repo Settings
The following settings are for configuring the Windows Software Reposi-
tory (winrepo) on a masterless minion. To run in masterless minion
mode, set the file_client to local or run salt-call with the --local
option

IMPORTANT:
These config options are only valid for minions running in master-
less mode

winrepo_dir
Changed in version 2015.8.0: Renamed from win_repo to winrepo_dir. This
option did not have a default value until this version.

Default: C:\salt\srv\salt\win\repo

Location on the minion file_roots where winrepo files are kept. This
is also where the winrepo_remotes are cloned to by winrepo.up-
date_git_repos.

winrepo_dir: 'D:\winrepo'

winrepo_dir_ng
New in version 2015.8.0: A new ng repo was added.

Default: C:\salt\srv\salt\win\repo-ng

Location on the minion file_roots where winrepo files are kept for
2018.8.0 and later minions. This is also where the winrepo_remotes are
cloned to by winrepo.update_git_repos.

winrepo_dir_ng: /usr/local/etc/salt/states/win/repo-ng

winrepo_cachefile
Changed in version 2015.8.0: Renamed from win_repo_cachefile to win-
repo_cachefile. Also, this option did not have a default value until
this version.

Default: winrepo.p

The name of the winrepo cache file. The file will be created at root of
the directory specified by winrepo_dir_ng.

winrepo_cachefile: winrepo.p

winrepo_remotes
Changed in version 2015.8.0: Renamed from win_gitrepos to winrepo_re-
motes. Also, this option did not have a default value until this ver-
sion.

New in version 2015.8.0.

Default: ['https://github.com/saltstack/salt-winrepo.git']

List of git repositories to checkout and include in the winrepo

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'

winrepo_remotes_ng
New in version 2015.8.0: A new ng 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_ng:
- '<commit_id> https://github.com/saltstack/salt-winrepo-ng.git'

Configuring the Salt Proxy Minion
The Salt system is amazingly simple and easy to configure. The two com-
ponents of the Salt system each have a respective configuration file.
The salt-master is configured via the master configuration file, and
the salt-proxy is configured via the proxy configuration file.

SEE ALSO:
example proxy minion configuration file

The Salt Minion configuration is very simple. Typically, the only value
that needs to be set is the master value so the proxy knows where to
locate its master.

By default, the salt-proxy configuration will be in /usr/lo-
cal/etc/salt/proxy. A notable exception is FreeBSD, where the configu-
ration will be in /usr/local/usr/local/etc/salt/proxy.

Proxy-specific Configuration Options
add_proxymodule_to_opts
New in version 2015.8.2.

Changed in version 2016.3.0.

Default: False

Add the proxymodule LazyLoader object to opts.

add_proxymodule_to_opts: True

proxy_merge_grains_in_module
New in version 2016.3.0.

Changed in version 2017.7.0.

Default: True

If a proxymodule has a function called grains, then call it during reg-
ular grains loading and merge the results with the proxy's grains dic-
tionary. Otherwise it is assumed that the module calls the grains
function in a custom way and returns the data elsewhere.

proxy_merge_grains_in_module: False

proxy_keep_alive
New in version 2017.7.0.

Default: True

Whether the connection with the remote device should be restarted when
dead. The proxy module must implement the alive function, otherwise the
connection is considered alive.

proxy_keep_alive: False

proxy_keep_alive_interval
New in version 2017.7.0.

Default: 1

The frequency of keepalive checks, in minutes. It requires the
proxy_keep_alive option to be enabled (and the proxy module to imple-
ment the alive function).

proxy_keep_alive_interval: 5

proxy_always_alive
New in version 2017.7.0.

Default: True

Whether the proxy should maintain the connection with the remote de-
vice. Similarly to proxy_keep_alive, this option is very specific to
the design of the proxy module. When proxy_always_alive is set to
False, the connection with the remote device is not maintained and has
to be closed after every command.

proxy_always_alive: False

proxy_merge_pillar_in_opts
New in version 2017.7.3.

Default: False.

Whether the pillar data to be merged into the proxy configuration op-
tions. As multiple proxies can run on the same server, we may need
different configuration options for each, while there's one single con-
figuration file. The solution is merging the pillar data of each proxy
minion into the opts.

proxy_merge_pillar_in_opts: True

proxy_deep_merge_pillar_in_opts
New in version 2017.7.3.

Default: False.

Deep merge of pillar data into configuration opts. This option is
evaluated only when proxy_merge_pillar_in_opts is enabled.

proxy_merge_pillar_in_opts_strategy
New in version 2017.7.3.

Default: smart.

The strategy used when merging pillar configuration into opts. This
option is evaluated only when proxy_merge_pillar_in_opts is enabled.

proxy_mines_pillar
New in version 2017.7.3.

Default: True.

Allow enabling mine details using pillar data. This evaluates the mine
configuration under the pillar, for the following regular minion op-
tions that are also equally available on the proxy minion: mine_inter-
val, and mine_functions.

Configuration file examples
o Example master configuration file

o Example minion configuration file

o Example proxy minion configuration file

Example master configuration file
##### Primary configuration settings #####
##########################################
# This configuration file is used to manage the behavior of the Salt Master.
# Values that are commented out but have an empty line after the comment are
# defaults that do not need to be set in the config. If there is no blank line
# after the comment then the value is presented as an example and is not the
# default.

# Per default, the master will automatically include all config files
# from master.d/*.conf (master.d is a directory in the same directory
# as the main master config file).
#default_include: master.d/*.conf

# The address of the interface to bind to:
#interface: 0.0.0.0

# 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: False

# The tcp port used by the publisher:
#publish_port: 4505

# The user under which the salt master will run. Salt will update all
# permissions to allow the specified user to run the master. The exception is
# the job cache, which must be deleted if this user is changed. If the
# modified files cause conflicts, set verify_env to False.
#user: root

# Tell the master to also use salt-ssh when running commands against minions.
#enable_ssh_minions: False

# The port used by the communication interface. The ret (return) port is the
# interface used for the file server, authentication, job returns, etc.
#ret_port: 4506

# Specify the location of the daemon process ID file:
#pidfile: /var/run/salt-master.pid

# The root directory prepended to these options: pki_dir, cachedir,
# sock_dir, log_file, autosign_file, autoreject_file, extension_modules,
# key_logfile, pidfile, autosign_grains_dir:
#root_dir: /

# The path to the master's configuration file.
#conf_file: /usr/local/etc/salt/master

# Directory used to store public key data:
#pki_dir: /usr/local/etc/salt/pki/master

# Key cache. Increases master speed for large numbers of accepted
# keys. Available options: 'sched'. (Updates on a fixed schedule.)
# Note that enabling this feature means that minions will not be
# available to target for up to the length of the maintanence loop
# which by default is 60s.
#key_cache: ''

# Directory to store job and cache data:
# This directory may contain sensitive data and should be protected accordingly.
#
#cachedir: /var/cache/salt/master

# 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", "utils", etc.
#extension_modules: /var/cache/salt/master/extmods

# Verify and set permissions on configuration directories at startup:
#verify_env: True

# Set the number of hours to keep old job information in the job cache:
#keep_jobs: 24

# The number of seconds to wait when the client is requesting information
# about running jobs.
#gather_job_timeout: 10

# Set the default timeout for the salt command and api. The default is 5
# seconds.
#timeout: 5

# 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.
#loop_interval: 60

# Set the default outputter used by the salt command. The default is "nested".
#output: nested

# To set a list of additional directories to search for salt outputters, set the
# outputter_dirs option.
#outputter_dirs: []

# 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: None

# Return minions that timeout when running commands like test.ping
#show_timeout: True

# Tell the client to display the jid when a job is published.
#show_jid: False

# By default, output is colored. To disable colored output, set the color value
# to False.
#color: True

# Do not strip off the colored output from nested results and state outputs
# (true by default).
# strip_colors: False

# To display a summary of the number of minions targeted, the number of
# minions returned, and the number of minions that did not return, set the
# cli_summary value to True. (False by default.)
#
#cli_summary: False

# Set the directory used to hold unix sockets:
#sock_dir: /var/run/salt/master

# The master can take a while to start up when lspci and/or dmidecode is used
# to populate the grains for the master. Enable if you want to see GPU hardware
# data for your master.
# enable_gpu_grains: False

# The master maintains a 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.
#job_cache: True

# Cache minion grains, pillar and mine data via the cache subsystem in the
# cachedir or a database.
#minion_data_cache: True

# Cache subsystem module to use for minion data cache.
#cache: localfs
# Enables a fast in-memory cache booster and sets the expiration time.
#memcache_expire_seconds: 0
# Set a memcache limit in items (bank + key) per cache storage (driver + driver_opts).
#memcache_max_items: 1024
# Each time a cache storage got full cleanup all the expired items not just the oldest one.
#memcache_full_cleanup: False
# Enable collecting the memcache stats and log it on `debug` log level.
#memcache_debug: False

# Store all returns in the given returner.
# Setting this option requires that any returner-specific configuration also
# be set. See various returners in salt/returners for details on required
# configuration values. (See also, event_return_queue, and event_return_queue_max_seconds below.)
#
#event_return: mysql

# 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

# In some cases enabling event return queueing can be very helpful, but the bus
# may not busy enough to flush the queue consistently. Setting this to a reasonable
# value (1-30 seconds) will cause the queue to be flushed when the oldest event is older
# than `event_return_queue_max_seconds` regardless of how many events are in the queue.
#event_return_queue_max_seconds: 0

# Only return events matching tags in a whitelist, supports glob matches.
#event_return_whitelist:
# - salt/master/a_tag
# - salt/run/*/ret

# Store all event returns **except** the tags in a blacklist, supports globs.
#event_return_blacklist:
# - salt/master/not_this_tag
# - salt/wheel/*/ret

# 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

# Windows platforms lack posix IPC and must rely on slower TCP based inter-
# process communications. Set ipc_mode to 'tcp' on such systems
#ipc_mode: ipc

# Overwrite the default tcp ports used by the minion when ipc_mode is set to 'tcp'
#tcp_master_pub_port: 4510
#tcp_master_pull_port: 4511

# By default, the master AES key rotates every 24 hours. The next command
# following a key rotation will trigger a key refresh from the minion which may
# result in minions which do not respond to the first command after a key refresh.
#
# To tell the master to ping all minions immediately after an AES key refresh, set
# ping_on_rotate to True. This should mitigate the issue where a minion does not
# appear to initially respond after a key is rotated.
#
# Note that ping_on_rotate may cause high load on the master immediately after
# the key rotation event as minions reconnect. Consider this carefully if this
# salt master is managing a large number of minions.
#
# If disabled, it is recommended to handle this event by listening for the
# 'aes_key_rotate' event with the 'key' tag and acting appropriately.
# ping_on_rotate: False

# By default, the master deletes its cache of minion data when the key for that
# minion is removed. To preserve the cache after key deletion, set
# 'preserve_minion_cache' to True.
#
# WARNING: This may have security implications if compromised minions auth with
# a previous deleted minion ID.
#preserve_minion_cache: False

# Allow or deny minions from requesting their own key revocation
#allow_minion_key_revoke: True

# 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: False

# 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 master configuration file lives in (this file). 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 a config file from some other path:
# include: /usr/local/etc/salt/extra_config
#
# Include config from several files and directories:
# include:
# - /usr/local/etc/salt/extra_config

##### Large-scale tuning settings #####
##########################################
# Max open files
#
# 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)
#
# By default this value will be the one of `ulimit -Hn`, ie, the hard limit for
# max open files.
#
# If you wish 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 your OS and/or distribution,
# a good way to find the limit is to search the internet. For example:
# raise max open files hard limit debian
#
#max_open_files: 100000

# The number of worker threads to start. These threads are used to manage
# return calls made from minions to the master. If the master seems to be
# running slowly, increase the number of threads. This setting can not be
# set lower than 3.
#worker_threads: 5

# Set the ZeroMQ high water marks
# http://api.zeromq.org/3-2:zmq-setsockopt

# The listen queue size / backlog
#zmq_backlog: 1000

# The publisher interface ZeroMQPubServerChannel
#pub_hwm: 1000

# The master may allocate memory per-event and not
# reclaim it.
# To set a high-water mark for memory allocation, use
# ipc_write_buffer to set a high-water mark for message
# buffering.
# Value: In bytes. Set to 'dynamic' to have Salt select
# a value for you. Default is disabled.
# ipc_write_buffer: 'dynamic'

# These two batch settings, batch_safe_limit and batch_safe_size, are used to
# automatically switch to a batch mode execution. If a command would have been
# sent to more than <batch_safe_limit> minions, then run the command in
# batches of <batch_safe_size>. If no batch_safe_size is specified, a default
# of 8 will be used. If no batch_safe_limit is specified, then no automatic
# batching will occur.
#batch_safe_limit: 100
#batch_safe_size: 8

# Master stats enables stats events to be fired from the master at close
# to the defined interval
#master_stats: False
#master_stats_event_iter: 60

##### Security settings #####
##########################################
# Enable passphrase protection of Master private key. Although a string value
# is acceptable; passwords should be stored in an external vaulting mechanism
# and retrieved via sdb. See https://docs.saltstack.com/en/latest/topics/sdb/.
# Passphrase protection is off by default but an example of an sdb profile and
# query is as follows.
# masterkeyring:
# driver: keyring
# service: system
#
# key_pass: sdb://masterkeyring/key_pass

# Enable passphrase protection of the Master signing_key. This only applies if
# master_sign_pubkey is set to True. This is disabled by default.
# master_sign_pubkey: True
# signing_key_pass: sdb://masterkeyring/signing_pass

# Enable "open mode", this mode still maintains encryption, but turns off
# authentication, this is only intended for highly secure environments or for
# the situation where your keys end up in a bad state. If you run in open mode
# you do so at your own risk!
#open_mode: False

# Enable auto_accept, this setting will automatically accept all incoming
# public keys from the minions. Note that this is insecure.
#auto_accept: False

# The size of key that should be generated when creating new keys.
#keysize: 2048

# Time in minutes that an 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.
# 0 equals no timeout
# autosign_timeout: 120

# If the autosign_file is specified, incoming keys specified in the
# autosign_file will be automatically accepted. This is insecure. Regular
# expressions as well as globing lines are supported. The file must be readonly
# except for the owner. Use permissive_pki_access to allow the group write access.
#autosign_file: /usr/local/etc/salt/autosign.conf

# Works like autosign_file, but instead allows you to specify minion IDs for
# which keys will automatically be rejected. Will override both membership in
# the autosign_file and the auto_accept setting.
#autoreject_file: /usr/local/etc/salt/autoreject.conf

# If the autosign_grains_dir is specified, incoming keys from minions with grain
# values matching those defined in files in this directory will be accepted
# automatically. This is insecure. Minions need to be configured to send the grains.
#autosign_grains_dir: /usr/local/etc/salt/autosign_grains

# Enable permissive access to the salt keys. This allows you to run the
# master or minion as root, but have a non-root group be given access to
# your pki_dir. To make the access explicit, root must belong to the group
# you've given access to. This is potentially quite insecure. If an autosign_file
# is specified, enabling permissive_pki_access will allow group access to that
# specific file.
#permissive_pki_access: False

# Allow users on the master access to execute specific commands on minions.
# This setting should be treated with care since it opens up execution
# capabilities to non root users. By default this capability is completely
# disabled.
#publisher_acl:
# larry:
# - test.ping
# - network.*
#
# Blacklist any of the following 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. This is completely disabled by default.
#
#
# Check the list of configured users in client ACL against users on the
# system and throw errors if they do not exist.
#client_acl_verify: True
#
#publisher_acl_blacklist:
# users:
# - root
# - '^(?!sudo_).*$' # all non sudo users
# modules:
# - cmd

# Enforce publisher_acl & publisher_acl_blacklist when users have sudo
# access to the salt command.
#
#sudo_acl: False

# 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.*
#
# Time (in seconds) for a newly generated token to live. Default: 12 hours
#token_expire: 43200
#
# 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
#
#token_expire_user_override: False

# Set to True to enable keeping the calculated user's auth list in the token
# file. This is disabled by default and the auth list is calculated or requested
# from the eauth driver each time.
#keep_acl_in_token: False

# Auth subsystem module to use to get authorized access list for a user. By default it's
# the same module used for external authentication.
#eauth_acl_module: django

# Allow minions to push files to the master. This is disabled by default, for
# security purposes.
#file_recv: False

# Set a hard-limit on the size of the files that can be pushed to the master.
# It will be interpreted as megabytes. Default: 100
#file_recv_max_size: 100

# Signature verification on messages published from the master.
# This causes the master to cryptographically sign all messages published to its event
# bus, and minions then verify that signature before acting on the message.
#
# This is False by default.
#
# Note that to facilitate interoperability with masters and minions that are different
# versions, if sign_pub_messages is True but a message is received by a minion with
# no signature, it will still be accepted, and a warning message will be logged.
# Conversely, if sign_pub_messages is False, but a minion receives a signed
# message it will be accepted, the signature will not be checked, and a warning message
# will be logged. This behavior went away in Salt 2014.1.0 and these two situations
# will cause minion to throw an exception and drop the message.
# sign_pub_messages: False

# Signature verification on messages published from minions
# This requires that minions cryptographically sign the messages they
# publish to the master. If minions are not signing, then log this information
# at loglevel 'INFO' and drop the message without acting on it.
# require_minion_sign_messages: False

# The below will drop messages when their signatures do not validate.
# Note that when this option is False but `require_minion_sign_messages` is True
# minions MUST sign their messages but the validity of their signatures
# is ignored.
# These two config options exist so a Salt infrastructure can be moved
# to signing minion messages gradually.
# drop_messages_signature_fail: False

# Use TLS/SSL encrypted connection between master and minion.
# Can be set to a dictionary containing keyword arguments corresponding to Python's
# 'ssl.wrap_socket' method.
# Default is None.
#ssl:
# keyfile: <path_to_keyfile>
# certfile: <path_to_certfile>
# ssl_version: PROTOCOL_TLSv1_2

##### Salt-SSH Configuration #####
##########################################
# Define the default salt-ssh roster module to use
#roster: flat

# Pass in an alternative location for the salt-ssh `flat` roster file
#roster_file: /usr/local/etc/salt/roster

# Define locations for `flat` roster files so they can be chosen when using Salt API.
# An administrator can place roster files into these locations. Then when
# calling Salt API, parameter 'roster_file' should contain a relative path to
# these locations. That is, "roster_file=/foo/roster" will be resolved as
# "/usr/local/etc/salt/roster.d/foo/roster" etc. This feature prevents passing insecure
# custom rosters through the Salt API.
#
#rosters:
# - /usr/local/etc/salt/roster.d
# - /opt/salt/some/more/rosters

# The ssh password to log in with.
#ssh_passwd: ''

#The target system's ssh port number.
#ssh_port: 22

# Comma-separated list of ports to scan.
#ssh_scan_ports: 22

# Scanning socket timeout for salt-ssh.
#ssh_scan_timeout: 0.01

# Boolean to run command via sudo.
#ssh_sudo: False

# Boolean to run ssh_pre_flight script defined in roster. By default
# the script will only run if the thin_dir does not exist on the targeted
# minion. This forces the script to run regardless of the thin dir existing
# or not.
#ssh_run_pre_flight: True

# Number of seconds to wait for a response when establishing an SSH connection.
#ssh_timeout: 60

# The user to log in as.
#ssh_user: root

# The log file of the salt-ssh command:
#ssh_log_file: /var/log/salt/ssh

# 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

# Set this to True to default to using ~/.ssh/id_rsa for salt-ssh
# authentication with minions
#ssh_use_home_key: False

# Set this to True to default salt-ssh to run with ``-o IdentitiesOnly=yes``.
# This option is intended for situations where the ssh-agent offers many
# different identities and allows ssh to ignore those identities and use the
# only one specified in options.
#ssh_identities_only: False

# List-only nodegroups for salt-ssh. Each group must be formed as either a
# comma-separated list, or a YAML list. This option is useful to group minions
# into easy-to-target groups when using salt-ssh. These groups can then be
# targeted with the normal -N argument to salt-ssh.
#ssh_list_nodegroups: {}

# salt-ssh has the ability to update the flat roster file if a minion is not
# found in the roster. Set this to True to enable it.
#ssh_update_roster: False

##### Master Module Management #####
##########################################
# Manage how master side modules are loaded.

# Add any additional locations to look for master runners:
#runner_dirs: []

# Add any additional locations to look for master utils:
#utils_dirs: []

# Enable Cython for master side modules:
#cython_enable: False

##### State System settings #####
##########################################
# 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 as defined in "File Server settings" below.
#state_top: top.sls

# The master_tops option replaces the external_nodes option by creating
# a plugable 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>
#
#master_tops: {}

# The renderer to use on the minions to render the state data
#renderer: jinja|yaml

# Default Jinja environment options for all templates except sls templates
#jinja_env:
# block_start_string: '{%'
# block_end_string: '%}'
# variable_start_string: '{{'
# variable_end_string: '}}'
# comment_start_string: '{#'
# comment_end_string: '#}'
# line_statement_prefix:
# line_comment_prefix:
# trim_blocks: False
# lstrip_blocks: False
# newline_sequence: '\n'
# keep_trailing_newline: False

# Jinja environment options for sls templates
#jinja_sls_env:
# block_start_string: '{%'
# block_end_string: '%}'
# variable_start_string: '{{'
# variable_end_string: '}}'
# comment_start_string: '{#'
# comment_end_string: '#}'
# line_statement_prefix:
# line_comment_prefix:
# trim_blocks: False
# lstrip_blocks: False
# newline_sequence: '\n'
# keep_trailing_newline: False

# The failhard option tells the minions to stop immediately after the first
# failure detected in the state execution, defaults to False
#failhard: False

# The state_verbose and state_output settings can be used to change the way
# state system data is printed to the display. By default all data is printed.
# The state_verbose setting can be set to True or False, when set to False
# all data that has a result of True and no changes will be suppressed.
#state_verbose: True

# The state_output setting controls which results will be output full multi line
# full, terse - each state will be full/terse
# mixed - only states with errors will be full
# changes - states with changes and errors will be full
# full_id, mixed_id, changes_id and terse_id are also allowed;
# when set, the state ID will be used as name in the output
#state_output: full

# The state_output_diff setting changes whether or not the output from
# successful states is returned. Useful when even the terse output of these
# states is cluttering the logs. Set it to True to ignore them.
#state_output_diff: 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: 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: False

##### File Server settings #####
##########################################
# 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:
# - /usr/local/etc/salt/states/
# dev:
# - /usr/local/etc/salt/states/dev/services
# - /usr/local/etc/salt/states/dev/states
# prod:
# - /usr/local/etc/salt/states/prod/services
# - /usr/local/etc/salt/states/prod/states
#
#file_roots:
# base:
# - /usr/local/etc/salt/states
#

# The master_roots setting configures a master-only copy of the file_roots dictionary,
# used by the state compiler.
#master_roots:
# base:
# - /usr/local/etc/salt/states-master

# When using multiple environments, each with their own top file, the
# default behaviour is an unordered merge. To prevent top files from
# being merged together and instead to only use the top file from the
# requested environment, set this value to 'same'.
#top_file_merging_strategy: merge

# To specify the order in which environments are merged, set the ordering
# in the env_order option. Given a conflict, the last matching value will
# win.
#env_order: ['base', 'dev', 'prod']

# If top_file_merging_strategy is set to 'same' and an environment does not
# contain a top file, the top file in the environment specified by default_top
# will be used instead.
#default_top: base

# The hash_type is the hash to use when discovering the hash of a file on
# the master server. The default is sha256, but md5, sha1, sha224, sha384 and
# sha512 are also supported.
#
# WARNING: While md5 and sha1 are also supported, do not use them due to the
# high chance of possible collisions and thus security breach.
#
# Prior to changing this value, the master should be stopped and all Salt
# caches should be cleared.
#hash_type: sha256

# The buffer size in the file server can be adjusted here:
#file_buffer_size: 1048576

# 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($|/)'

# 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'

# File Server Backend
#
# 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 uses the "file_roots" option.
#fileserver_backend:
# - roots
#
# To use multiple backends list them in the order they are searched:
#fileserver_backend:
# - git
# - roots
#
# Uncomment the line below if you do not want the file_server to follow
# symlinks when walking the filesystem tree. This is set to True
# by default. Currently this only applies to the default roots
# fileserver_backend.
#fileserver_followsymlinks: False
#
# Uncomment the line below if you do not want symlinks to be
# treated as the files they are pointing to. By default this is set to
# False. By uncommenting the line below, any detected symlink while listing
# files on the Master will not be returned to the Minion.
#fileserver_ignoresymlinks: True
#
# 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,
# enable the option below. This might be useful for installations where a file root
# has a very large number of files and performance is impacted. Default is False.
# fileserver_limit_traversal: False
#
# The fileserver can fire events off every time the fileserver is updated,
# these are disabled by default, but can be easily turned on by setting this
# flag to True
#fileserver_events: False

# Git File Server Backend Configuration
#
# Optional parameter used to specify the provider to be used for gitfs. Must be
# either pygit2 or gitpython. If unset, then both will be tried (in that
# order), and the first one with a compatible version installed will be the
# provider that is used.
#
#gitfs_provider: pygit2

# Along with gitfs_password, is used to authenticate to HTTPS remotes.
# gitfs_user: ''

# Along with gitfs_user, is used to authenticate to HTTPS remotes.
# This parameter is not required if the repository does not use authentication.
#gitfs_password: ''

# 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: False

# Along with gitfs_privkey (and optionally gitfs_passphrase), is used to
# authenticate to SSH remotes. This parameter (or its per-remote counterpart)
# is required for SSH remotes.
#gitfs_pubkey: ''

# Along with gitfs_pubkey (and optionally gitfs_passphrase), is used to
# authenticate to SSH remotes. This parameter (or its per-remote counterpart)
# is required for SSH remotes.
#gitfs_privkey: ''

# This parameter is optional, required only when the SSH key being used to
# authenticate is protected by a passphrase.
#gitfs_passphrase: ''

# 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.
# When using the git backend branches and tags are translated into salt
# environments.
# Note: file:// repos will be treated as a remote, so refs you want used must
# exist in that repo as *local* refs.
#gitfs_remotes:
# - git://github.com/saltstack/salt-states.git
# - file:///var/git/saltmaster
#
# The gitfs_ssl_verify option specifies whether to ignore ssl certificate
# errors when contacting the gitfs backend. You might want to set this to
# false if you're using a git backend that uses a self-signed certificate but
# keep in mind that setting this flag to anything other than the default of True
# is a security concern, you may want to try using the ssh transport.
#gitfs_ssl_verify: True
#
# The gitfs_root option gives the ability to serve files from a subdirectory
# within the repository. The path is defined relative to the root of the
# repository and defaults to the repository root.
#gitfs_root: somefolder/otherfolder
#
# The refspecs fetched by gitfs remotes
#gitfs_refspecs:
# - '+refs/heads/*:refs/remotes/origin/*'
# - '+refs/tags/*:refs/tags/*'
#
#
##### Pillar settings #####
##########################################
# Salt Pillars allow for the building of global data that can be made selectively
# available to different minions based on minion grain filtering. The Salt
# Pillar is laid out in the same fashion as the file server, with environments,
# a top file and sls files. However, pillar data does not need to be in the
# highstate format, and is generally just key/value pairs.
#pillar_roots:
# base:
# - /usr/local/etc/salt/pillar
#
#ext_pillar:
# - hiera: /etc/hiera.yaml
# - cmd_yaml: cat /usr/local/etc/salt/yaml

# A list of paths to be recursively decrypted during pillar compilation.
# Entries in this list can be formatted either as a simple string, or as a
# key/value pair, with the key being the pillar location, and the value being
# the renderer to use for pillar decryption. If the former is used, the
# renderer specified by decrypt_pillar_default will be used.
#decrypt_pillar:
# - 'foo:bar': gpg
# - 'lorem:ipsum:dolor'

# The delimiter used to distinguish nested data structures in the
# decrypt_pillar option.
#decrypt_pillar_delimiter: ':'

# The default renderer used for decryption, if one is not specified for a given
# pillar key in decrypt_pillar.
#decrypt_pillar_default: gpg

# List of renderers which are permitted to be used for pillar decryption.
#decrypt_pillar_renderers:
# - gpg

# The ext_pillar_first option allows for external pillar sources to populate
# before file system pillar. This allows for targeting file system pillar from
# ext_pillar.
#ext_pillar_first: False

# The external pillars permitted to be used on-demand using pillar.ext
#on_demand_ext_pillar:
# - libvirt
# - virtkey

# The pillar_gitfs_ssl_verify option specifies whether to ignore ssl certificate
# errors when contacting the pillar gitfs backend. You might want to set this to
# false if you're using a git backend that uses a self-signed certificate but
# keep in mind that setting this flag to anything other than the default of True
# is a security concern, you may want to try using the ssh transport.
#pillar_gitfs_ssl_verify: True

# The pillar_opts option adds the master configuration file data to a dict in
# the pillar called "master". This is used to set simple configurations in the
# master config file that can then be used on minions.
#pillar_opts: False

# The pillar_safe_render_error option prevents the master from passing pillar
# render errors to the minion. This is set on by default because the error could
# contain templating data which would give that minion information it shouldn't
# have, like a password! When set true the error message will only show:
# Rendering SLS 'my.sls' failed. Please see master log for details.
#pillar_safe_render_error: True

# The pillar_source_merging_strategy option allows you to configure merging strategy
# between different sources. It accepts five values: none, recurse, aggregate, overwrite,
# or smart. None will not do any merging at all. Recurse will merge recursively mapping of data.
# Aggregate instructs aggregation of elements between sources that use the #!yamlex renderer. Overwrite
# will overwrite elements according the order in which they are processed. This is
# behavior of the 2014.1 branch and earlier. Smart guesses the best strategy based
# on the "renderer" setting and is the default value.
#pillar_source_merging_strategy: smart

# Recursively merge lists by aggregating them instead of replacing them.
#pillar_merge_lists: False

# Set this option to True to force the pillarenv to be the same as the effective
# saltenv when running states. If pillarenv is specified this option will be
# ignored.
#pillarenv_from_saltenv: 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. Default is 'False'.
#pillar_raise_on_missing: False

# Git External Pillar (git_pillar) Configuration Options
#
# 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: pygit2

# 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.
#git_pillar_base: master

# If the branch is omitted from a git_pillar remote, then this branch will
# be used instead
#git_pillar_branch: master

# 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.
#git_pillar_env: ''

# Path relative to the root of the repository where the git_pillar top file
# and SLS files are located.
#git_pillar_root: ''

# Specifies whether or not to ignore SSL certificate errors when contacting
# the remote repository.
#git_pillar_ssl_verify: False

# 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.
#git_pillar_global_lock: True

# Git External Pillar Authentication Options
#
# Along with git_pillar_password, is used to authenticate to HTTPS remotes.
#git_pillar_user: ''

# Along with 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: ''

# By default, Salt will not authenticate to an HTTP (non-HTTPS) remote.
# This parameter enables authentication over HTTP.
#git_pillar_insecure_auth: False

# Along with git_pillar_privkey (and optionally git_pillar_passphrase),
# is used to authenticate to SSH remotes.
#git_pillar_pubkey: ''

# Along with git_pillar_pubkey (and optionally git_pillar_passphrase),
# is used to authenticate to SSH remotes.
#git_pillar_privkey: ''

# This parameter is optional, required only when the SSH key being used
# to authenticate is protected by a passphrase.
#git_pillar_passphrase: ''

# The refspecs fetched by git_pillar remotes
#git_pillar_refspecs:
# - '+refs/heads/*:refs/remotes/origin/*'
# - '+refs/tags/*:refs/tags/*'

# 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.
#
# Note: setting ``pillar_cache: True`` has no effect on targeting Minions with Pillars.
# See https://docs.saltstack.com/en/latest/topics/targeting/pillar.html
#pillar_cache: False

# 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.
#pillar_cache_ttl: 3600

# If and only if a master has set `pillar_cache: True`, one of several storage providers
# can be utilized.
#
# `disk`: 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. (Same 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 master can also cache GPG data 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 decrypted GPG data in a master cache have been addressed.
#
# When enabling this feature, be certain to read through the additional ``gpg_cache_*``
# configuration options to fully understand the tunable parameters and their implications.
#gpg_cache: False

# If and only if a master has set ``gpg_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.
#gpg_cache_ttl: 86400

# If and only if a master has set `gpg_cache: True`, one of several storage providers
# can be utilized. Available options are the same as ``pillar_cache_backend``.
#gpg_cache_backend: disk

###### Reactor Settings #####
###########################################
# Define a salt reactor. See https://docs.saltstack.com/en/latest/topics/reactor/
#reactor: []

#Set the TTL for the cache of the reactor configuration.
#reactor_refresh_interval: 60

#Configure the number of workers for the runner/wheel in the reactor.
#reactor_worker_threads: 10

#Define the queue size for workers in the reactor.
#reactor_worker_hwm: 10000

##### Syndic settings #####
##########################################
# The Salt syndic is used to pass commands through a master from a higher
# master. Using the syndic is simple. If this is a master that will have
# syndic servers(s) below it, then set the "order_masters" setting to True.
#
# If this is a master that will be running a syndic daemon for passthrough, then
# the "syndic_master" setting needs to be set to the location of the master server
# to receive commands from.

# Set the order_masters setting to True if this master will command lower
# masters' syndic interfaces.
#order_masters: False

# If this master will be running a salt syndic daemon, syndic_master tells
# this master where to receive commands from.
#syndic_master: masterofmasters

# This is the 'ret_port' of the MasterOfMaster:
#syndic_master_port: 4506

# PID file of the syndic daemon:
#syndic_pidfile: /var/run/salt-syndic.pid

# The log file of the salt-syndic daemon:
#syndic_log_file: /var/log/salt/syndic

# 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

# The number of seconds for the salt client to wait for additional syndics to
# check in with their lists of expected minions before giving up.
#syndic_wait: 5

##### Peer Publish settings #####
##########################################
# 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.

# 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!

# Minions can also be allowed to execute runners from the salt master.
# Since executing a runner from the minion could be considered a security risk,
# it needs to be enabled. This setting functions just like the peer setting
# except that it opens up runners instead of module functions.
#
# All peer runner support is turned off by default and must be enabled before
# using. This will enable all peer runners for all minions:
#peer_run:
# .*:
# - .*
#
# To enable just the manage.up runner for the minion foo.example.com:
#peer_run:
# foo.example.com:
# - manage.up
#
#
##### Mine settings #####
#####################################
# Restrict mine.get access from minions. By default any minion has a full access
# to get all mine data from master cache. In acl definion below, only pcre matches
# are allowed.
# mine_get:
# .*:
# - .*
#
# The example below enables minion foo.example.com to get 'network.interfaces' mine
# data only, minions web* to get all network.* and disk.* mine data and all other
# minions won't get any mine data.
# mine_get:
# foo.example.com:
# - network.interfaces
# web.*:
# - network.*
# - disk.*

##### Logging settings #####
##########################################
# The location of the master log file
# The master log can be sent to a regular file, local path name, or network
# location. Remote logging works best when configured to use rsyslogd(8) (e.g.:
# ``file:///dev/log``), with rsyslogd(8) configured for network logging. The URI
# format is: <file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility>
#log_file: /var/log/salt/master
#log_file: file:///dev/log
#log_file: udp://loghost:10514

#log_file: /var/log/salt/master
#key_logfile: /var/log/salt/key

# The level of messages to send to the console.
# One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'.
#
# The following log levels are considered INSECURE and may log sensitive data:
# ['garbage', 'trace', 'debug']
#
#log_level: warning

# The level of messages to send to the log file.
# One of 'garbage', 'trace', 'debug', 'info', 'warning', 'error', 'critical'.
# If using 'log_granular_levels' this must be set to the highest desired level.
#log_level_logfile: warning

# The date and time format used in log messages. Allowed date/time formatting
# can be seen here: http://docs.python.org/library/time.html#time.strftime
#log_datefmt: '%H:%M:%S'
#log_datefmt_logfile: '%Y-%m-%d %H:%M:%S'

# The format of the console logging messages. Allowed formatting options can
# be seen here: http://docs.python.org/library/logging.html#logrecord-attributes
#
# 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'
#
#log_fmt_logfile: '%(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(message)s'

# This can be used to control logging levels more specificically. This
# example sets the main salt library at the 'warning' level, but sets
# 'salt.modules' to log at the 'debug' level:
# log_granular_levels:
# 'salt': 'warning'
# 'salt.modules': 'debug'
#
#log_granular_levels: {}

##### Node Groups ######
##########################################
# Node groups allow for logical groupings of minion nodes. A group consists of
# a group name and a compound target. Nodgroups can reference other nodegroups
# with 'N@' classifier. Ensure that you do not have circular references.
#
#nodegroups:
# group1: 'L@foo.domain.com,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'

##### Range Cluster settings #####
##########################################
# 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

##### Windows Software Repo settings #####
###########################################
# Location of the repo on the master:
#winrepo_dir_ng: '/usr/local/etc/salt/states/win/repo-ng'
#
# List of git repositories to include with the local repo:
#winrepo_remotes_ng:
# - 'https://github.com/saltstack/salt-winrepo-ng.git'

##### Windows Software Repo settings - Pre 2015.8 #####
########################################################
# Legacy repo settings for pre-2015.8 Windows minions.
#
# Location of the repo on the master:
#winrepo_dir: '/usr/local/etc/salt/states/win/repo'
#
# Location of the master's repo cache file:
#winrepo_mastercachefile: '/usr/local/etc/salt/states/win/repo/winrepo.p'
#
# List of git repositories to include with the local repo:
#winrepo_remotes:
# - 'https://github.com/saltstack/salt-winrepo.git'

# The refspecs fetched by winrepo remotes
#winrepo_refspecs:
# - '+refs/heads/*:refs/remotes/origin/*'
# - '+refs/tags/*:refs/tags/*'
#

##### Returner settings ######
############################################
# Which returner(s) will be used for minion's result:
#return: mysql

###### Miscellaneous settings ######
############################################
# Default match type for filtering events tags: startswith, endswith, find, regex, fnmatch
#event_match_type: startswith

# Save runner returns to the job cache
#runner_returns: True

# Permanently include any available Python 3rd party modules into thin and minimal Salt
# when they are generated for Salt-SSH or other purposes.
# The modules should be named by the names they are actually imported inside the Python.
# The value of the parameters can be either one module or a comma separated list of them.
#thin_extra_mods: foo,bar
#min_extra_mods: foo,bar,baz

###### Keepalive settings ######
############################################
# Warning: Failure to set TCP keepalives on the salt-master can result in
# not detecting the loss of a minion when the connection is lost or when
# its host has been terminated without first closing the socket.
# Salt's Presence System depends on this connection status to know if a minion
# is "present".
# ZeroMQ now includes support for configuring SO_KEEPALIVE if supported by
# the OS. If connections between the minion and the master pass through
# a state tracking device such as a firewall or VPN gateway, there is
# the risk that it could tear down the connection the master and minion
# without informing either party that their connection has been taken away.
# Enabling TCP Keepalives prevents this from happening.

# Overall state of TCP Keepalives, enable (1 or True), disable (0 or False)
# or leave to the OS defaults (-1), on Linux, typically disabled. Default True, enabled.
#tcp_keepalive: True

# How long before the first keepalive should be sent in seconds. Default 300
# to send the first keepalive after 5 minutes, OS default (-1) is typically 7200 seconds
# on Linux see /proc/sys/net/ipv4/tcp_keepalive_time.
#tcp_keepalive_idle: 300

# How many lost probes are needed to consider the connection lost. Default -1
# to use OS defaults, typically 9 on Linux, see /proc/sys/net/ipv4/tcp_keepalive_probes.
#tcp_keepalive_cnt: -1

# How often, in seconds, to send keepalives after the first one. Default -1 to
# use OS defaults, typically 75 seconds on Linux, see
# /proc/sys/net/ipv4/tcp_keepalive_intvl.
#tcp_keepalive_intvl: -1

##### NetAPI settings #####
############################################
# Allow the raw_shell parameter to be used when calling Salt SSH client via API
#netapi_allow_raw_shell: True

Example minion configuration file
##### Primary configuration settings #####
##########################################
# This configuration file is used to manage the behavior of the Salt Minion.
# With the exception of the location of the Salt Master Server, values that are
# commented out but have an empty line after the comment are defaults that need
# not be set in the config. If there is no blank line after the comment, the
# value is presented as an example and is not the default.

# Per default the minion will automatically include all config files
# from minion.d/*.conf (minion.d is a directory in the same directory
# as the main minion config file).
#default_include: minion.d/*.conf

# Set the location of the salt master server. If the master server cannot be
# resolved, then the minion will fail to start.
#master: salt

# Set http proxy information for the minion when doing requests
#proxy_host:
#proxy_port:
#proxy_username:
#proxy_password:

# List of hosts to bypass HTTP proxy. This key does nothing unless proxy_host etc is
# configured, it does not support any kind of wildcards.
#no_proxy: []

# If multiple masters are specified in the 'master' setting, the default behavior
# is to always try to connect to them in the order they are listed. If random_master
# is set to True, the order will be randomized upon Minion startup instead. This can
# be helpful in distributing the load of many minions executing salt-call requests,
# for example, from a cron job. If only one master is listed, this setting is ignored
# and a warning will be logged.
#random_master: False

# NOTE: Deprecated in Salt 2019.2.0. Use 'random_master' instead.
#master_shuffle: False

# Minions can connect to multiple masters simultaneously (all masters
# are "hot"), or can be configured to failover if a master becomes
# unavailable. Multiple hot masters are configured by setting this
# value to "str". Failover masters can be requested by setting
# to "failover". MAKE SURE TO SET master_alive_interval if you are
# using failover.
# Setting master_type to 'disable' lets you have a running minion (with engines and
# beacons) without a master connection
# master_type: str

# Poll interval in seconds for checking if the master is still there. Only
# respected if master_type above is "failover". To disable the interval entirely,
# set the value to -1. (This may be necessary on machines which have high numbers
# of TCP connections, such as load balancers.)
# master_alive_interval: 30

# If the minion is in multi-master mode and the master_type configuration option
# is set to "failover", this setting can be set to "True" to force the minion
# to fail back to the first master in the list if the first master is back online.
#master_failback: False

# If the minion is in multi-master mode, the "master_type" configuration is set to
# "failover", and the "master_failback" option is enabled, the master failback
# interval can be set to ping the top master with this interval, in seconds.
#master_failback_interval: 0

# Set whether the minion should connect to the master via IPv6:
#ipv6: False

# Set the number of seconds to wait before attempting to resolve
# the master hostname if name resolution fails. Defaults to 30 seconds.
# Set to zero if the minion should shutdown and not retry.
# retry_dns: 30

# Set the number of times to attempt to resolve
# the master hostname if name resolution fails. Defaults to None,
# which will attempt the resolution indefinitely.
# retry_dns_count: 3

# Set the port used by the master reply and authentication server.
#master_port: 4506

# The user to run salt.
#user: root

# The user to run salt remote execution commands as via sudo. If this option is
# enabled then sudo will be used to change the active user executing the remote
# command. If enabled the user will need to be allowed access via the sudoers
# file for the user that the salt minion is configured to run as. The most
# common option would be to use the root user. If this option is set the user
# option should also be set to a non-root user. If migrating from a root minion
# to a non root minion the minion cache should be cleared and the minion pki
# directory will need to be changed to the ownership of the new user.
#sudo_user: root

# Specify the location of the daemon process ID file.
#pidfile: /var/run/salt-minion.pid

# The root directory prepended to these options: pki_dir, cachedir, log_file,
# sock_dir, pidfile.
#root_dir: /

# The path to the minion's configuration file.
#conf_file: /usr/local/etc/salt/minion

# The directory to store the pki information in
#pki_dir: /usr/local/etc/salt/pki/minion

# Explicitly declare the id for this minion to use, if left commented the id
# will be the hostname as returned by the python call: socket.getfqdn()
# Since salt uses detached ids it is possible to run multiple minions on the
# same machine but with different ids, this can be useful for salt compute
# clusters.
#id:

# Cache the minion id to a file when the minion's id is not statically defined
# in the minion config. Defaults to "True". This setting prevents potential
# problems when automatic minion id resolution changes, which can cause the
# minion to lose connection with the master. To turn off minion id caching,
# set this config to ``False``.
#minion_id_caching: True

# Convert minion id to lowercase when it is being generated. Helpful when some
# hosts get the minion id in uppercase. Cached ids will remain the same and
# not converted. For example, Windows minions often have uppercase minion
# names when they are set up but not always. To turn on, set this config to
# ``True``.
#minion_id_lowercase: False

# Append a domain to a hostname in the event that it does not exist. This is
# useful for systems where socket.getfqdn() does not actually result in a
# FQDN (for instance, Solaris).
#append_domain:

# Custom static grains for this minion can be specified here and used in SLS
# files just like all other grains. This example sets 4 custom grains, with
# the 'roles' grain having two values that can be matched against.
#grains:
# roles:
# - webserver
# - memcache
# deployment: datacenter4
# cabinet: 13
# cab_u: 14-15
#
# Where cache data goes.
# This data may contain sensitive data and should be protected accordingly.
#cachedir: /var/cache/salt/minion

# Append minion_id to these directories. Helps with
# multiple proxies and minions running on the same machine.
# Allowed elements in the list: pki_dir, cachedir, extension_modules
# Normally not needed unless running several proxies and/or minions on the same machine
# Defaults to ['cachedir'] for proxies, [] (empty list) for regular minions
#append_minionid_config_dirs:

# Verify and set permissions on configuration directories at startup.
#verify_env: True

# The minion can locally cache the return data from jobs sent to it, this
# can be a good way to keep track of jobs the minion has executed
# (on the minion side). By default this feature is disabled, to enable, set
# cache_jobs to True.
#cache_jobs: False

# Set the directory used to hold unix sockets.
#sock_dir: /var/run/salt/minion

# In order to calculate the fqdns grain, all the IP addresses from the minion
# are processed with underlying calls to `socket.gethostbyaddr` which can take
# 5 seconds to be released (after reaching `socket.timeout`) when there is no
# fqdn for that IP. These calls to `socket.gethostbyaddr` are processed
# asynchronously, however, it still adds 5 seconds every time grains are
# generated if an IP does not resolve. In Windows grains are regenerated each
# time a new process is spawned. Therefore, the default for Windows is `False`.
# All other OSes default to `True`
# enable_fqdns_grains: True

# The minion can take a while to start up when lspci and/or dmidecode is used
# to populate the grains for the minion. Set this to False if you do not need
# GPU hardware grains for your minion.
# enable_gpu_grains: True

# Set the default outputter used by the salt-call command. The default is
# "nested".
#output: nested

# To set a list of additional directories to search for salt outputters, set the
# outputter_dirs option.
#outputter_dirs: []

# By default output is colored. To disable colored output, set the color value
# to False.
#color: True

# Do not strip off the colored output from nested results and state outputs
# (true by default).
# strip_colors: False

# Backup files that are replaced by file.managed and file.recurse under
# 'cachedir'/file_backup relative to their original location and appended
# with a timestamp. The only valid setting is "minion". Disabled by default.
#
# Alternatively this can be specified for each file in state files:
# /etc/ssh/sshd_config:
# file.managed:
# - source: salt://ssh/sshd_config
# - backup: minion
#
#backup_mode: minion

# When waiting for a master to accept the minion's public key, salt will
# continuously attempt to reconnect until successful. This is the time, in
# seconds, between those reconnection attempts.
#acceptance_wait_time: 10

# If this is nonzero, the time between reconnection attempts will increase by
# acceptance_wait_time seconds per iteration, up to this maximum. If this is
# set to zero, the time between reconnection attempts will stay constant.
#acceptance_wait_time_max: 0

# If the master rejects the minion's public key, retry instead of exiting.
# Rejected keys will be handled the same as waiting on acceptance.
#rejected_retry: False

# When the master key changes, the minion will try to re-auth itself to receive
# the new master key. In larger environments this can cause a SYN flood on the
# master because all minions try to re-auth immediately. To prevent this and
# have a minion wait for a random amount of time, use this optional parameter.
# The wait-time will be a random number of seconds between 0 and the defined value.
#random_reauth_delay: 60

# To avoid overloading a master when many minions startup at once, a randomized
# delay may be set to tell the minions to wait before connecting to the master.
# This value is the number of seconds to choose from for a random number. For
# example, setting this value to 60 will choose a random number of seconds to delay
# on startup between zero seconds and sixty seconds. Setting to '0' will disable
# this feature.
#random_startup_delay: 0

# When waiting for a master to accept the minion's public key, salt will
# continuously attempt to reconnect until successful. This is the timeout value,
# in seconds, for each individual attempt. After this timeout expires, the minion
# will wait for acceptance_wait_time seconds before trying again. Unless your master
# is under unusually heavy load, this should be left at the default.
#auth_timeout: 60

# Number of consecutive SaltReqTimeoutError that are acceptable when trying to
# authenticate.
#auth_tries: 7

# The number of attempts to connect to a master before giving up.
# Set this to -1 for unlimited attempts. This allows for a master to have
# downtime and the minion to reconnect to it later when it comes back up.
# In 'failover' mode, it is the number of attempts for each set of masters.
# In this mode, it will cycle through the list of masters for each attempt.
#
# This is different than auth_tries because auth_tries attempts to
# retry auth attempts with a single master. auth_tries is under the
# assumption that you can connect to the master but not gain
# authorization from it. master_tries will still cycle through all
# the masters in a given try, so it is appropriate if you expect
# occasional downtime from the master(s).
#master_tries: 1

# If authentication fails due to SaltReqTimeoutError during a ping_interval,
# cause sub minion process to restart.
#auth_safemode: False

# Ping Master to ensure connection is alive (minutes).
#ping_interval: 0

# To auto recover minions if master changes IP address (DDNS)
# auth_tries: 10
# auth_safemode: False
# ping_interval: 2
#
# Minions won't know master is missing until a ping fails. After the ping fail,
# the minion will attempt authentication and likely fails out and cause a restart.
# When the minion restarts it will resolve the masters IP and attempt to reconnect.

# If you don't have any problems with syn-floods, don't bother with the
# three recon_* settings described below, just leave the defaults!
#
# The ZeroMQ pull-socket that binds to the masters publishing interface tries
# to reconnect immediately, if the socket is disconnected (for example if
# the master processes are restarted). In large setups this will have all
# minions reconnect immediately which might flood the master (the ZeroMQ-default
# is usually a 100ms delay). To prevent this, these three recon_* settings
# can be used.
# recon_default: the interval in milliseconds that the socket should wait before
# trying to reconnect to the master (1000ms = 1 second)
#
# recon_max: the maximum time a socket should wait. each interval the time to wait
# is calculated by doubling the previous time. if recon_max is reached,
# it starts again at recon_default. Short example:
#
# reconnect 1: the socket will wait 'recon_default' milliseconds
# reconnect 2: 'recon_default' * 2
# reconnect 3: ('recon_default' * 2) * 2
# reconnect 4: value from previous interval * 2
# reconnect 5: value from previous interval * 2
# reconnect x: if value >= recon_max, it starts again with recon_default
#
# recon_randomize: generate a random wait time on minion start. The wait time will
# be a random value between recon_default and recon_default +
# recon_max. Having all minions reconnect with the same recon_default
# and recon_max value kind of defeats the purpose of being able to
# change these settings. If all minions have the same values and your
# setup is quite large (several thousand minions), they will still
# flood the master. The desired behavior is to have timeframe within
# all minions try to reconnect.
#
# Example on how to use these settings. The goal: have all minions reconnect within a
# 60 second timeframe on a disconnect.
# recon_default: 1000
# recon_max: 59000
# recon_randomize: True
#
# Each minion will have a randomized reconnect value between 'recon_default'
# and 'recon_default + recon_max', which in this example means between 1000ms
# 60000ms (or between 1 and 60 seconds). The generated random-value will be
# doubled after each attempt to reconnect. Lets say the generated random
# value is 11 seconds (or 11000ms).
# reconnect 1: wait 11 seconds
# reconnect 2: wait 22 seconds
# reconnect 3: wait 33 seconds
# reconnect 4: wait 44 seconds
# reconnect 5: wait 55 seconds
# reconnect 6: wait time is bigger than 60 seconds (recon_default + recon_max)
# reconnect 7: wait 11 seconds
# reconnect 8: wait 22 seconds
# reconnect 9: wait 33 seconds
# reconnect x: etc.
#
# In a setup with ~6000 hosts these settings would average the reconnects
# to about 100 per second and all hosts would be reconnected within 60 seconds.
# recon_default: 100
# recon_max: 5000
# recon_randomize: False
#
#
# The loop_interval sets how long in seconds the minion will wait between
# evaluating the scheduler and running cleanup tasks. This defaults to 1
# second on the minion scheduler.
#loop_interval: 1

# Some installations choose to start all job returns in a cache or a returner
# and forgo sending the results back to a master. In this workflow, jobs
# are most often executed with --async from the Salt CLI and then results
# are evaluated by examining job caches on the minions or any configured returners.
# WARNING: Setting this to False will **disable** returns back to the master.
#pub_ret: True

# The grains can be merged, instead of overridden, using this option.
# This allows custom grains to defined different subvalues of a dictionary
# grain. By default this feature is disabled, to enable set grains_deep_merge
# to ``True``.
#grains_deep_merge: False

# The grains_refresh_every setting allows for a minion to periodically check
# its grains to see if they have changed and, if so, to inform the master
# of the new grains. This operation is moderately expensive, therefore
# care should be taken not to set this value too low.
#
# Note: This value is expressed in __minutes__!
#
# A value of 10 minutes is a reasonable default.
#
# If the value is set to zero, this check is disabled.
#grains_refresh_every: 1

# Cache grains on the minion. Default is False.
#grains_cache: False

# Cache rendered pillar data on the minion. Default is False.
# This may cause 'cachedir'/pillar to contain sensitive data that should be
# protected accordingly.
#minion_pillar_cache: False

# Grains cache expiration, in seconds. If the cache file is older than this
# number of seconds then the grains cache will be dumped and fully re-populated
# with fresh data. Defaults to 5 minutes. Will have no effect if 'grains_cache'
# is not enabled.
# grains_cache_expiration: 300

# Determines whether or not the salt minion should run scheduled mine updates.
# Defaults to "True". Set to "False" to disable the scheduled mine updates
# (this essentially just does not add the mine update function to the minion's
# scheduler).
#mine_enabled: True

# Determines whether or not scheduled mine updates should be accompanied by a job
# return for the job cache. Defaults to "False". Set to "True" to include job
# returns in the job cache for mine updates.
#mine_return_job: False

# Example functions that can be run via the mine facility
# NO mine functions are established by default.
# Note these can be defined in the minion's pillar as well.
#mine_functions:
# test.ping: []
# network.ip_addrs:
# interface: eth0
# cidr: '10.0.0.0/8'

# The number of minutes between mine updates.
#mine_interval: 60

# Windows platforms lack posix IPC and must rely on slower TCP based inter-
# process communications. ipc_mode is set to 'tcp' on such systems.
#ipc_mode: ipc

# Overwrite the default tcp ports used by the minion when ipc_mode is set to 'tcp'
#tcp_pub_port: 4510
#tcp_pull_port: 4511

# 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
# minion event bus. The value is expressed in bytes.
#max_event_size: 1048576

# When a minion starts up it sends a notification on the event bus with a tag
# that looks like this: `salt/minion/<minion_id>/start`. For historical reasons
# the minion also sends a similar event with an event tag like this:
# `minion_start`. This duplication can cause a lot of clutter on the event bus
# when there are many minions. Set `enable_legacy_startup_events: False` in the
# minion config to ensure only the `salt/minion/<minion_id>/start` events are
# sent. Beginning with the `Sodium` Salt release this option will default to
# `False`
#enable_legacy_startup_events: True

# To detect failed master(s) and fire events on connect/disconnect, set
# master_alive_interval to the number of seconds to poll the masters for
# connection events.
#
#master_alive_interval: 30

# The syndic minion can verify that it is talking to the correct master via the
# key fingerprint of the higher-level master with the "syndic_finger" config.
#syndic_finger: ''
#
#
#
##### Minion module management #####
##########################################
# Disable specific modules. This allows the admin to limit the level of
# access the master has to the minion. The default here is the empty list,
# below is an example of how this needs to be formatted in the config file
#disable_modules:
# - cmdmod
# - test
#disable_returners: []

# This is the reverse of disable_modules. The default, like disable_modules, is the empty list,
# but if this option is set to *anything* then *only* those modules will load.
# Note that this is a very large hammer and it can be quite difficult to keep the minion working
# the way you think it should since Salt uses many modules internally itself. At a bare minimum
# you need the following enabled or else the minion won't start.
#whitelist_modules:
# - cmdmod
# - test
# - config

# Modules can be loaded from arbitrary paths. This enables the easy deployment
# of third party modules. Modules for returners and minions can be loaded.
# Specify a list of extra directories to search for minion modules and
# returners. These paths must be fully qualified!
#module_dirs: []
#returner_dirs: []
#states_dirs: []
#render_dirs: []
#utils_dirs: []
#
# A module provider can be statically overwritten or extended for the minion
# via the providers option, in this case the default module will be
# overwritten by the specified module. In this example the pkg module will
# be provided by the yumpkg5 module instead of the system default.
#providers:
# pkg: yumpkg5
#
# Enable Cython modules searching and loading. (Default: False)
#cython_enable: False
#
# Specify a max size (in bytes) for modules on import. This feature is currently
# only supported on *nix operating systems and requires psutil.
# modules_max_memory: -1

##### State Management Settings #####
###########################################
# The default renderer to use in SLS files. This is configured as a
# pipe-delimited expression. For example, jinja|yaml will first run jinja
# templating on the SLS file, and then load the result as YAML. This syntax is
# documented in further depth at the following URL:
#
# https://docs.saltstack.com/en/latest/ref/renderers/#composing-renderers
#
# NOTE: The "shebang" prefix (e.g. "#!jinja|yaml") described in the
# documentation linked above is for use in an SLS file to override the default
# renderer, it should not be used when configuring the renderer here.
#
#renderer: jinja|yaml
#
# The failhard option tells the minions to stop immediately after the first
# failure detected in the state execution. Defaults to False.
#failhard: False
#
# Reload the modules prior to a highstate run.
#autoload_dynamic_modules: True
#
# clean_dynamic_modules keeps the dynamic modules on the minion in sync with
# the dynamic modules on the master, this means that if a dynamic module is
# not on the master it will be deleted from the minion. By default, this is
# enabled and can be disabled by changing this value to False.
#clean_dynamic_modules: True
#
# Renamed from ``environment`` to ``saltenv``. If ``environment`` is used,
# ``saltenv`` will take its value. If both are used, ``environment`` will be
# ignored and ``saltenv`` will be used.
# Normally the minion is not isolated to any single environment on the master
# when running states, but the environment can be isolated on the minion side
# by statically setting it. Remember that the recommended way to manage
# environments is to isolate via the top file.
#saltenv: None
#
# Isolates the pillar environment on the minion side. This functions the same
# as the environment setting, but for pillar instead of states.
#pillarenv: None
#
# Set this option to True to force the pillarenv to be the same as the
# effective saltenv when running states. Note that if pillarenv is specified,
# this option will be ignored.
#pillarenv_from_saltenv: 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. Default is 'False'.
#pillar_raise_on_missing: False
#
# If using the local file directory, then the state top file name needs to be
# defined, by default this is top.sls.
#state_top: top.sls
#
# Run states when the minion daemon starts. To enable, set startup_states to:
# 'highstate' -- Execute state.highstate
# 'sls' -- Read in the sls_list option and execute the named sls files
# 'top' -- Read top_file option and execute based on that file on the Master
#startup_states: ''
#
# List of states to run when the minion starts up if startup_states is 'sls':
#sls_list:
# - edit.vim
# - hyper
#
# List of grains to pass in start event when minion starts up:
#start_event_grains:
# - machine_id
# - uuid
#
# Top file to execute if startup_states is 'top':
#top_file: ''

# 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: False

# Disable requisites during state runs by specifying a single requisite
# or a list of requisites to disable.
#
# disabled_requisites: require_in
#
# disabled_requisites:
# - require
# - require_in

##### File Directory Settings #####
##########################################
# The Salt Minion can redirect all file server operations to a local directory,
# this allows for the same state tree that is on the master to be used if
# copied completely onto the minion. This is a literal copy of the settings on
# the master but used to reference a local directory on the minion.

# Set the file client. The client defaults to looking on the master server for
# files, but can be directed to look at the local file directory setting
# defined below by setting it to "local". Setting a local file_client runs the
# minion in masterless mode.
#file_client: remote

# The file directory works on environments passed to the minion, 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:
# - /usr/local/etc/salt/states/
# dev:
# - /usr/local/etc/salt/states/dev/services
# - /usr/local/etc/salt/states/dev/states
# prod:
# - /usr/local/etc/salt/states/prod/services
# - /usr/local/etc/salt/states/prod/states
#
#file_roots:
# base:
# - /usr/local/etc/salt/states

# Uncomment the line below if you do not want the file_server to follow
# symlinks when walking the filesystem tree. This is set to True
# by default. Currently this only applies to the default roots
# fileserver_backend.
#fileserver_followsymlinks: False
#
# Uncomment the line below if you do not want symlinks to be
# treated as the files they are pointing to. By default this is set to
# False. By uncommenting the line below, any detected symlink while listing
# files on the Master will not be returned to the Minion.
#fileserver_ignoresymlinks: True
#
# 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,
# enable the option below. This might be useful for installations where a file root
# has a very large number of files and performance is negatively impacted. Default
# is False.
#fileserver_limit_traversal: False

# The hash_type is the hash to use when discovering the hash of a file on
# the local fileserver. The default is sha256, but md5, sha1, sha224, sha384
# and sha512 are also supported.
#
# WARNING: While md5 and sha1 are also supported, do not use them due to the
# high chance of possible collisions and thus security breach.
#
# Warning: Prior to changing this value, the minion should be stopped and all
# Salt caches should be cleared.
#hash_type: sha256

# Set a hard-limit on the size of the files that can be pushed to the master.
# It will be interpreted as megabytes. Default: 100
#file_recv_max_size: 100
#
#
###### Security settings #####
###########################################
# Enable "open mode", this mode still maintains encryption, but turns off
# authentication, this is only intended for highly secure environments or for
# the situation where your keys end up in a bad state. If you run in open mode
# you do so at your own risk!
#open_mode: False

# The size of key that should be generated when creating new keys.
#keysize: 2048

# The state_output_profile setting changes whether profile information
# will be shown for each state run.
#state_output_profile: True

# Fingerprint of the master public key to validate the identity of your Salt master
# before the initial key exchange. The master fingerprint can be found by running
# "salt-key -f master.pub" on the Salt master.
#master_finger: ''

# Grains to be sent to the master on authentication to check if the minion's key
# will be accepted automatically. Needs to be configured on the master.
#autosign_grains:
# - uuid
# - server_id

###### Reactor Settings #####
###########################################
# Define a salt reactor. See https://docs.saltstack.com/en/latest/topics/reactor/
#reactor: []

#Set the TTL for the cache of the reactor configuration.
#reactor_refresh_interval: 60

#Configure the number of workers for the runner/wheel in the reactor.
#reactor_worker_threads: 10

#Define the queue size for workers in the reactor.
#reactor_worker_hwm: 10000

###### Thread settings #####
###########################################
# Disable multiprocessing support, by default when a minion receives a
# publication a new process is spawned and the command is executed therein.
#
# WARNING: Disabling multiprocessing may result in substantial slowdowns
# when processing large pillars. See https://github.com/saltstack/salt/issues/38758
# for a full explanation.
#multiprocessing: True

# Limit the maximum amount of processes or threads created by salt-minion.
# This is useful to avoid resource exhaustion in case the minion receives more
# publications than it is able to handle, as it limits the number of spawned
# processes or threads. -1 is the default and disables the limit.
#process_count_max: -1

##### Logging settings #####
##########################################
# The location of the minion log file
# The minion log can be sent to a regular file, local path name, or network
# location. Remote logging works best when configured to use rsyslogd(8) (e.g.:
# ``file:///dev/log``), with rsyslogd(8) configured for network logging. The URI
# format is: <file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility>
#log_file: /var/log/salt/minion
#log_file: file:///dev/log
#log_file: udp://loghost:10514
#
#log_file: /var/log/salt/minion
#key_logfile: /var/log/salt/key

# The level of messages to send to the console.
# One of 'garbage', 'trace', 'debug', 'info', 'warning', 'error', 'critical'.
#
# The following log levels are considered INSECURE and may log sensitive data:
# ['garbage', 'trace', 'debug']
#
# Default: 'warning'
#log_level: warning

# The level of messages to send to the log file.
# One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'.
# If using 'log_granular_levels' this must be set to the highest desired level.
# Default: 'warning'
#log_level_logfile:

# To diagnose issues with minions disconnecting or missing returns, ZeroMQ
# supports the use of monitor sockets to log connection events. This
# feature requires ZeroMQ 4.0 or higher.
#
# To enable ZeroMQ monitor sockets, set 'zmq_monitor' to 'True' and log at a
# debug level or higher.
#
# A sample log event is as follows:
#
# [DEBUG ] ZeroMQ event: {'endpoint': 'tcp://127.0.0.1:4505', 'event': 512,
# 'value': 27, 'description': 'EVENT_DISCONNECTED'}
#
# All events logged will include the string 'ZeroMQ event'. A connection event
# should be logged as the minion starts up and initially connects to the
# master. If not, check for debug log level and that the necessary version of
# ZeroMQ is installed.
#
#zmq_monitor: False

# Number of times to try to authenticate with the salt master when reconnecting
# to the master
#tcp_authentication_retries: 5

###### Module configuration #####
###########################################
# Salt allows for modules to be passed arbitrary configuration data, any data
# passed here in valid yaml format will be passed on to the salt minion modules
# for use. It is STRONGLY recommended that a naming convention be used in which
# the module name is followed by a . and then the value. Also, all top level
# data must be applied via the yaml dict construct, some examples:
#
# You can specify that all modules should run in test mode:
#test: True
#
# A simple value for the test module:
#test.foo: foo
#
# A list for the test module:
#test.bar: [baz,quo]
#
# A dict for the test module:
#test.baz: {spam: sausage, cheese: bread}
#
#
###### Update settings ######
###########################################
# Using the features in Esky, a salt minion can both run as a frozen app and
# be updated on the fly. These options control how the update process
# (saltutil.update()) behaves.
#
# The url for finding and downloading updates. Disabled by default.
#update_url: False
#
# The list of services to restart after a successful update. Empty by default.
#update_restart_services: []

###### Keepalive settings ######
############################################
# ZeroMQ now includes support for configuring SO_KEEPALIVE if supported by
# the OS. If connections between the minion and the master pass through
# a state tracking device such as a firewall or VPN gateway, there is
# the risk that it could tear down the connection the master and minion
# without informing either party that their connection has been taken away.
# Enabling TCP Keepalives prevents this from happening.

# Overall state of TCP Keepalives, enable (1 or True), disable (0 or False)
# or leave to the OS defaults (-1), on Linux, typically disabled. Default True, enabled.
#tcp_keepalive: True

# How many lost probes are needed to consider the connection lost. Default -1
# to use OS defaults, typically 9 on Linux, see /proc/sys/net/ipv4/tcp_keepalive_probes.
#tcp_keepalive_cnt: -1

# How often, in seconds, to send keepalives after the first one. Default -1 to
# use OS defaults, typically 75 seconds on Linux, see
# /proc/sys/net/ipv4/tcp_keepalive_intvl.
#tcp_keepalive_intvl: -1

###### Windows Software settings ######
############################################
# Location of the repository cache file on the master:
#win_repo_cachefile: 'salt://win/repo/winrepo.p'

###### Returner settings ######
############################################
# Default Minion returners. Can be a comma delimited string or a list:
#
#return: mysql
#
#return: mysql,slack,redis
#
#return:
# - mysql
# - hipchat
# - slack

Example proxy minion configuration file
##### Primary configuration settings #####
##########################################
# This configuration file is used to manage the behavior of all Salt Proxy
# Minions on this host.
# With the exception of the location of the Salt Master Server, values that are
# commented out but have an empty line after the comment are defaults that need
# not be set in the config. If there is no blank line after the comment, the
# value is presented as an example and is not the default.

# Backwards compatibility option for proxymodules created before 2015.8.2
# This setting will default to 'False' in the 2016.3.0 release
# Setting this to True adds proxymodules to the __opts__ dictionary.
# This breaks several Salt features (basically anything that serializes
# __opts__ over the wire) but retains backwards compatibility.
#add_proxymodule_to_opts: True

# Set the location of the salt master server. If the master server cannot be
# resolved, then the minion will fail to start.
#master: salt

# If a proxymodule has a function called 'grains', then call it during
# regular grains loading and merge the results with the proxy's grains
# dictionary. Otherwise it is assumed that the module calls the grains
# function in a custom way and returns the data elsewhere
#
# Default to False for 2016.3 and 2016.11. Switch to True for 2017.7.0.
# proxy_merge_grains_in_module: True

# If a proxymodule has a function called 'alive' returning a boolean
# flag reflecting the state of the connection with the remove device,
# when this option is set as True, a scheduled job on the proxy will
# try restarting the connection. The polling frequency depends on the
# next option, 'proxy_keep_alive_interval'. Added in 2017.7.0.
# proxy_keep_alive: True

# The polling interval (in minutes) to check if the underlying connection
# with the remote device is still alive. This option requires
# 'proxy_keep_alive' to be configured as True and the proxymodule to
# implement the 'alive' function. Added in 2017.7.0.
# proxy_keep_alive_interval: 1

# By default, any proxy opens the connection with the remote device when
# initialized. Some proxymodules allow through this option to open/close
# the session per command. This requires the proxymodule to have this
# capability. Please consult the documentation to see if the proxy type
# used can be that flexible. Added in 2017.7.0.
# proxy_always_alive: True

# If multiple masters are specified in the 'master' setting, the default behavior
# is to always try to connect to them in the order they are listed. If random_master is
# set to True, the order will be randomized instead. This can be helpful in distributing
# the load of many minions executing salt-call requests, for example, from a cron job.
# If only one master is listed, this setting is ignored and a warning will be logged.
#random_master: False

# Poll interval in seconds for checking if the master is still there. Only
# respected if master_type above is "failover".
# master_alive_interval: 30

# Set whether the minion should connect to the master via IPv6:
#ipv6: False

# Set the port used by the master reply and authentication server.
#master_port: 4506

# The user to run salt.
#user: root

# Setting sudo_user will cause salt to run all execution modules under an sudo
# to the user given in sudo_user. The user under which the salt minion process
# itself runs will still be that provided in the user config above, but all
# execution modules run by the minion will be rerouted through sudo.
#sudo_user: saltdev

# Specify the location of the daemon process ID file.
#pidfile: /var/run/salt-minion.pid

# The root directory prepended to these options: pki_dir, cachedir, log_file,
# sock_dir, pidfile.
#root_dir: /

# The directory to store the pki information in
#pki_dir: /usr/local/etc/salt/pki/minion

# Where cache data goes.
# This data may contain sensitive data and should be protected accordingly.
#cachedir: /var/cache/salt/minion

# Verify and set permissions on configuration directories at startup.
#verify_env: True

# Set the directory used to hold unix sockets.
#sock_dir: /var/run/salt/minion

# Set the default outputter used by the salt-call command. The default is
# "nested".
#output: nested
#
# By default output is colored. To disable colored output, set the color value
# to False.
#color: True

# Do not strip off the colored output from nested results and state outputs
# (true by default).
# strip_colors: False

# If the master rejects the minion's public key, retry instead of exiting.
# Rejected keys will be handled the same as waiting on acceptance.
#rejected_retry: False

# Number of consecutive SaltReqTimeoutError that are acceptable when trying to
# authenticate.
#auth_tries: 7

# If authentication fails due to SaltReqTimeoutError during a ping_interval,
# cause sub minion process to restart.
#auth_safemode: False

# Ping Master to ensure connection is alive (minutes).
#ping_interval: 0

# To auto recover minions if master changes IP address (DDNS)
# auth_tries: 10
# auth_safemode: False
# ping_interval: 90
#
# Minions won't know master is missing until a ping fails. After the ping fail,
# the minion will attempt authentication and likely fails out and cause a restart.
# When the minion restarts it will resolve the masters IP and attempt to reconnect.

# If you don't have any problems with syn-floods, don't bother with the
# three recon_* settings described below, just leave the defaults!
#
# The ZeroMQ pull-socket that binds to the masters publishing interface tries
# to reconnect immediately, if the socket is disconnected (for example if
# the master processes are restarted). In large setups this will have all
# minions reconnect immediately which might flood the master (the ZeroMQ-default
# is usually a 100ms delay). To prevent this, these three recon_* settings
# can be used.
# recon_default: the interval in milliseconds that the socket should wait before
# trying to reconnect to the master (1000ms = 1 second)
#
# recon_max: the maximum time a socket should wait. each interval the time to wait
# is calculated by doubling the previous time. if recon_max is reached,
# it starts again at recon_default. Short example:
#
# reconnect 1: the socket will wait 'recon_default' milliseconds
# reconnect 2: 'recon_default' * 2
# reconnect 3: ('recon_default' * 2) * 2
# reconnect 4: value from previous interval * 2
# reconnect 5: value from previous interval * 2
# reconnect x: if value >= recon_max, it starts again with recon_default
#
# recon_randomize: generate a random wait time on minion start. The wait time will
# be a random value between recon_default and recon_default +
# recon_max. Having all minions reconnect with the same recon_default
# and recon_max value kind of defeats the purpose of being able to
# change these settings. If all minions have the same values and your
# setup is quite large (several thousand minions), they will still
# flood the master. The desired behavior is to have timeframe within
# all minions try to reconnect.
#
# Example on how to use these settings. The goal: have all minions reconnect within a
# 60 second timeframe on a disconnect.
# recon_default: 1000
# recon_max: 59000
# recon_randomize: True
#
# Each minion will have a randomized reconnect value between 'recon_default'
# and 'recon_default + recon_max', which in this example means between 1000ms
# 60000ms (or between 1 and 60 seconds). The generated random-value will be
# doubled after each attempt to reconnect. Lets say the generated random
# value is 11 seconds (or 11000ms).
# reconnect 1: wait 11 seconds
# reconnect 2: wait 22 seconds
# reconnect 3: wait 33 seconds
# reconnect 4: wait 44 seconds
# reconnect 5: wait 55 seconds
# reconnect 6: wait time is bigger than 60 seconds (recon_default + recon_max)
# reconnect 7: wait 11 seconds
# reconnect 8: wait 22 seconds
# reconnect 9: wait 33 seconds
# reconnect x: etc.
#
# In a setup with ~6000 thousand hosts these settings would average the reconnects
# to about 100 per second and all hosts would be reconnected within 60 seconds.
# recon_default: 100
# recon_max: 5000
# recon_randomize: False
#
#
# The loop_interval sets how long in seconds the minion will wait between
# evaluating the scheduler and running cleanup tasks. This defaults to a
# sane 60 seconds, but if the minion scheduler needs to be evaluated more
# often lower this value
#loop_interval: 60

# Cache grains on the minion. Default is False.
#grains_cache: False

# Windows platforms lack posix IPC and must rely on slower TCP based inter-
# process communications. Set ipc_mode to 'tcp' on such systems
#ipc_mode: ipc

# Overwrite the default tcp ports used by the minion when in tcp mode
#tcp_pub_port: 4510
#tcp_pull_port: 4511

# To detect failed master(s) and fire events on connect/disconnect, set
# master_alive_interval to the number of seconds to poll the masters for
# connection events.
#
#master_alive_interval: 30

# The minion 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 (this file). Paths can make use
# of shell-style globbing. If no files are matched by a path passed to this
# option then the minion will log a warning message.
#
# Include a config file from some other path:
# include: /usr/local/etc/salt/extra_config
#
# Include config from several files and directories:
#include:
# - /usr/local/etc/salt/extra_config
# - /etc/roles/webserver
#
#
#
##### Minion module management #####
##########################################
# Disable specific modules. This allows the admin to limit the level of
# access the master has to the minion.
#disable_modules: [cmd,test]
#disable_returners: []
#
# Modules can be loaded from arbitrary paths. This enables the easy deployment
# of third party modules. Modules for returners and minions can be loaded.
# Specify a list of extra directories to search for minion modules and
# returners. These paths must be fully qualified!
#module_dirs: []
#returner_dirs: []
#states_dirs: []
#render_dirs: []
#utils_dirs: []
#
# A module provider can be statically overwritten or extended for the minion
# via the providers option, in this case the default module will be
# overwritten by the specified module. In this example the pkg module will
# be provided by the yumpkg5 module instead of the system default.
#providers:
# pkg: yumpkg5
#
# Enable Cython modules searching and loading. (Default: False)
#cython_enable: False
#
# Specify a max size (in bytes) for modules on import. This feature is currently
# only supported on *nix operating systems and requires psutil.
# modules_max_memory: -1

# 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,
# enable the option below. This might be useful for installations where a file root
# has a very large number of files and performance is negatively impacted. Default
# is False.
#fileserver_limit_traversal: False

# The hash_type is the hash to use when discovering the hash of a file in
# the local fileserver. The default is sha256 but sha224, sha384 and sha512
# are also supported.
#
# WARNING: While md5 and sha1 are also supported, do not use it due to the high chance
# of possible collisions and thus security breach.
#
# WARNING: While md5 is also supported, do not use it due to the high chance
# of possible collisions and thus security breach.
#
# Warning: Prior to changing this value, the minion should be stopped and all
# Salt caches should be cleared.
#hash_type: sha256

# The Salt pillar is searched for locally if file_client is set to local. If
# this is the case, and pillar data is defined, then the pillar_roots need to
# also be configured on the minion:
#pillar_roots:
# base:
# - /usr/local/etc/salt/pillar
#
#
###### Security settings #####
###########################################
# Enable "open mode", this mode still maintains encryption, but turns off
# authentication, this is only intended for highly secure environments or for
# the situation where your keys end up in a bad state. If you run in open mode
# you do so at your own risk!
#open_mode: False

# The state_output_profile setting changes whether profile information
# will be shown for each state run.
#state_output_profile: True

# Fingerprint of the master public key to validate the identity of your Salt master
# before the initial key exchange. The master fingerprint can be found by running
# "salt-key -F master" on the Salt master.
#master_finger: ''

# To diagnose issues with minions disconnecting or missing returns, ZeroMQ
# supports the use of monitor sockets # to log connection events. This
# feature requires ZeroMQ 4.0 or higher.
#
# To enable ZeroMQ monitor sockets, set 'zmq_monitor' to 'True' and log at a
# debug level or higher.
#
# A sample log event is as follows:
#
# [DEBUG ] ZeroMQ event: {'endpoint': 'tcp://127.0.0.1:4505', 'event': 512,
# 'value': 27, 'description': 'EVENT_DISCONNECTED'}
#
# All events logged will include the string 'ZeroMQ event'. A connection event
# should be logged on the as the minion starts up and initially connects to the
# master. If not, check for debug log level and that the necessary version of
# ZeroMQ is installed.
#
#zmq_monitor: False

# Overall state of TCP Keepalives, enable (1 or True), disable (0 or False)
# or leave to the OS defaults (-1), on Linux, typically disabled. Default True, enabled.
#tcp_keepalive: True

# How many lost probes are needed to consider the connection lost. Default -1
# to use OS defaults, typically 9 on Linux, see /proc/sys/net/ipv4/tcp_keepalive_probes.
#tcp_keepalive_cnt: -1

# How often, in seconds, to send keepalives after the first one. Default -1 to
# use OS defaults, typically 75 seconds on Linux, see
# /proc/sys/net/ipv4/tcp_keepalive_intvl.
#tcp_keepalive_intvl: -1

###### Windows Software settings ######
############################################
# Location of the repository cache file on the master:
#win_repo_cachefile: 'salt://win/repo/winrepo.p'

###### Returner settings ######
############################################
# Which returner(s) will be used for minion's result:
#return: mysql

Minion Blackout Configuration
New in version 2016.3.0.

Salt supports minion blackouts. When a minion is in blackout mode, all
remote execution commands are disabled. This allows production minions
to be put "on hold", eliminating the risk of an untimely configuration
change.

Minion blackouts are configured via a special pillar key, minion_black-
out. If this key is set to True, then the minion will reject all in-
coming commands, except for saltutil.refresh_pillar. (The exception is
important, so minions can be brought out of blackout mode)

Salt also supports an explicit whitelist of additional functions that
will be allowed during blackout. This is configured with the special
pillar key minion_blackout_whitelist, which is formed as a list:

minion_blackout_whitelist:
- test.version
- pillar.get

Access Control System
New in version 0.10.4.

Salt maintains a standard system used to open granular control to non
administrative users to execute Salt commands. The access control sys-
tem has been applied to all systems used to configure access to non ad-
ministrative control interfaces in Salt.

These interfaces include, the peer system, the external auth system and
the publisher acl system.

The access control system mandated a standard configuration syntax used
in all of the three aforementioned systems. While this adds functional-
ity to the configuration in 0.10.4, it does not negate the old configu-
ration.

Now specific functions can be opened up to specific minions from spe-
cific users in the case of external auth and publisher ACLs, and for
specific minions in the case of the peer system.

Publisher ACL system
The salt publisher ACL system is a means to allow system users other
than root to have access to execute select salt commands on minions
from the master.

NOTE:
publisher_acl is useful for allowing local system users to run Salt
commands without giving them root access. If you can log into the
Salt master directly, then publisher_acl allows you to use Salt
without root privileges. If the local system is configured to au-
thenticate against a remote system, like LDAP or Active Directory,
then publisher_acl will interact with the remote system transpar-
ently.

external_auth is useful for salt-api or for making your own scripts
that use Salt's Python API. It can be used at the CLI (with the -a
flag) but it is more cumbersome as there are more steps involved.
The only time it is useful at the CLI is when the local system is
not configured to authenticate against an external service but you
still want Salt to authenticate against an external service.

For more information and examples, see this Access Control System
section.

The publisher ACL system is configured in the master configuration file
via the publisher_acl configuration option. Under the publisher_acl
configuration option the users open to send commands are specified and
then a list of the minion functions which will be made available to
specified user. Both users and functions could be specified by exact
match, shell glob or regular expression. This configuration is much
like the external_auth configuration:

publisher_acl:
# Allow thatch to execute anything.
thatch:
- .*
# Allow fred to use test and pkg, but only on "web*" minions.
fred:
- web*:
- test.*
- pkg.*
# Allow admin and managers to use saltutil module functions
admin|manager_.*:
- saltutil.*
# Allow users to use only my_mod functions on "web*" minions with specific arguments.
user_.*:
- web*:
- 'my_mod.*':
args:
- 'a.*'
- 'b.*'
kwargs:
'kwa': 'kwa.*'
'kwb': 'kwb'

Permission Issues
Directories required for publisher_acl must be modified to be readable
by the users specified:

chmod 755 /var/cache/salt /var/cache/salt/master /var/cache/salt/master/jobs /var/run/salt /var/run/salt/master

NOTE:
In addition to the changes above you will also need to modify the
permissions of /var/log/salt and the existing log file to be
writable by the user(s) which will be running the commands. If you
do not wish to do this then you must disable logging or Salt will
generate errors as it cannot write to the logs as the system users.

If you are upgrading from earlier versions of salt you must also remove
any existing user keys and re-start the Salt master:

rm /var/cache/salt/.*key
service salt-master restart

Whitelist and Blacklist
Salt's authentication systems can be configured by specifying what is
allowed using a whitelist, or by specifying what is disallowed using a
blacklist. If you specify a whitelist, only specified operations are
allowed. If you specify a blacklist, all operations are allowed except
those that are blacklisted.

See publisher_acl and publisher_acl_blacklist.

External Authentication System
Salt's External Authentication System (eAuth) allows for Salt to pass
through command authorization to any external authentication system,
such as PAM or LDAP.

NOTE:
eAuth using the PAM external auth system requires salt-master to be
run as root as this system needs root access to check authentica-
tion.

For more information and examples, see this Access Control System
section.

External Authentication System Configuration
The external authentication system allows for specific users to be
granted access to execute specific functions on specific minions. Ac-
cess is configured in the master configuration file and uses the access
control system:

external_auth:
pam:
thatch:
- 'web*':
- test.*
- network.*
steve|admin.*:
- .*

The above configuration allows the user thatch to execute functions in
the test and network modules on the minions that match the web* target.
User steve and the users whose logins start with admin, are granted un-
restricted access to minion commands.

Salt respects the current PAM configuration in place, and uses the 'lo-
gin' service to authenticate.

NOTE:
The PAM module does not allow authenticating as root.

NOTE:
state.sls and state.highstate will return "Failed to authenticate!"
if the request timeout is reached. Use -t flag to increase the
timeout

To allow access to wheel modules or runner modules the following @ syn-
tax must be used:

external_auth:
pam:
thatch:
- '@wheel' # to allow access to all wheel modules
- '@runner' # to allow access to all runner modules
- '@jobs' # to allow access to the jobs runner and/or wheel module

NOTE:
The runner/wheel markup is different, since there are no minions to
scope the acl to.

NOTE:
Globs will not match wheel or runners! They must be explicitly al-
lowed with @wheel or @runner.

WARNING:
All users that have external authentication privileges are allowed
to run saltutil.findjob. Be aware that this could inadvertently ex-
pose some data such as minion IDs.

Matching syntax
The structure of the external_auth dictionary can take the following
shapes. User and function matches are exact matches, shell glob pat-
terns or regular expressions; minion matches are compound targets.

By user:

external_auth:
<eauth backend>:
<user or group%>:
- <regex to match function>

By user, by minion:

external_auth:
<eauth backend>:
<user or group%>:
<minion compound target>:
- <regex to match function>

By user, by runner/wheel:

external_auth:
<eauth backend>:
<user or group%>:
<@runner or @wheel>:
- <regex to match function>

By user, by runner+wheel module:

external_auth:
<eauth backend>:
<user or group%>:
<@module_name>:
- <regex to match function without module_name>

Groups
To apply permissions to a group of users in an external authentication
system, append a % to the ID:

external_auth:
pam:
admins%:
- '*':
- 'pkg.*'

Limiting by function arguments
Positional arguments or keyword arguments to functions can also be
whitelisted.

New in version 2016.3.0.

external_auth:
pam:
my_user:
- '*':
- 'my_mod.*':
args:
- 'a.*'
- 'b.*'
kwargs:
'kwa': 'kwa.*'
'kwb': 'kwb'
- '@runner':
- 'runner_mod.*':
args:
- 'a.*'
- 'b.*'
kwargs:
'kwa': 'kwa.*'
'kwb': 'kwb'

The rules:

1. The arguments values are matched as regexp.

2. If arguments restrictions are specified the only matched are al-
lowed.

3. If an argument isn't specified any value is allowed.

4. To skip an arg use "everything" regexp .*. I.e. if arg0 and arg2
should be limited but arg1 and other arguments could have any value
use:

args:
- 'value0'
- '.*'
- 'value2'

Usage
The external authentication system can then be used from the com-
mand-line by any user on the same system as the master with the -a op-
tion:

$ salt -a pam web\* test.version

The system will ask the user for the credentials required by the au-
thentication system and then publish the command.

Tokens
With external authentication alone, the authentication credentials will
be required with every call to Salt. This can be alleviated with Salt
tokens.

Tokens are short term authorizations and can be easily created by just
adding a -T option when authenticating:

$ salt -T -a pam web\* test.version

Now a token will be created that has an expiration of 12 hours (by de-
fault). This token is stored in a file named salt_token in the active
user's home directory.

Once the token is created, it is sent with all subsequent communica-
tions. User authentication does not need to be entered again until the
token expires.

Token expiration time can be set in the Salt master config file.

LDAP and Active Directory
NOTE:
LDAP usage requires that you have installed python-ldap.

Salt supports both user and group authentication for LDAP (and Active
Directory accessed via its LDAP interface)

OpenLDAP and similar systems
LDAP configuration happens in the Salt master configuration file.

Server configuration values and their defaults:

# Server to auth against
auth.ldap.server: localhost

# Port to connect via
auth.ldap.port: 389

# Use TLS when connecting
auth.ldap.tls: False

# Use STARTTLS when connecting
auth.ldap.starttls: False

# LDAP scope level, almost always 2
auth.ldap.scope: 2

# Server specified in URI format
auth.ldap.uri: '' # Overrides .ldap.server, .ldap.port, .ldap.tls above

# Verify server's TLS certificate
auth.ldap.no_verify: False

# Bind to LDAP anonymously to determine group membership
# Active Directory does not allow anonymous binds without special configuration
# In addition, if auth.ldap.anonymous is True, empty bind passwords are not permitted.
auth.ldap.anonymous: False

# FOR TESTING ONLY, this is a VERY insecure setting.
# If this is True, the LDAP bind password will be ignored and
# access will be determined by group membership alone with
# the group memberships being retrieved via anonymous bind
auth.ldap.auth_by_group_membership_only: False

# Require authenticating user to be part of this Organizational Unit
# This can be blank if your LDAP schema does not use this kind of OU
auth.ldap.groupou: 'Groups'

# Object Class for groups. An LDAP search will be done to find all groups of this
# class to which the authenticating user belongs.
auth.ldap.groupclass: 'posixGroup'

# Unique ID attribute name for the user
auth.ldap.accountattributename: 'memberUid'

# These are only for Active Directory
auth.ldap.activedirectory: False
auth.ldap.persontype: 'person'

auth.ldap.minion_stripdomains: []

# Redhat Identity Policy Audit
auth.ldap.freeipa: False

Authenticating to the LDAP Server
There are two phases to LDAP authentication. First, Salt authenticates
to search for a users' Distinguished Name and group membership. The
user it authenticates as in this phase is often a special LDAP system
user with read-only access to the LDAP directory. After Salt searches
the directory to determine the actual user's DN and groups, it re-au-
thenticates as the user running the Salt commands.

If you are already aware of the structure of your DNs and permissions
in your LDAP store are set such that users can look up their own group
memberships, then the first and second users can be the same. To tell
Salt this is the case, omit the auth.ldap.bindpw parameter. Note this
is not the same thing as using an anonymous bind. Most LDAP servers
will not permit anonymous bind, and as mentioned above, if
auth.ldap.anonymous is False you cannot use an empty password.

You can template the binddn like this:

auth.ldap.basedn: dc=saltstack,dc=com
auth.ldap.binddn: uid={{ username }},cn=users,cn=accounts,dc=saltstack,dc=com

Salt will use the password entered on the salt command line in place of
the bindpw.

To use two separate users, specify the LDAP lookup user in the binddn
directive, and include a bindpw like so

auth.ldap.binddn: uid=ldaplookup,cn=sysaccounts,cn=etc,dc=saltstack,dc=com
auth.ldap.bindpw: mypassword

As mentioned before, Salt uses a filter to find the DN associated with
a user. Salt substitutes the {{ username }} value for the username when
querying LDAP

auth.ldap.filter: uid={{ username }}

Determining Group Memberships (OpenLDAP / non-Active Directory)
For OpenLDAP, to determine group membership, one can specify an OU that
contains group data. This is prepended to the basedn to create a search
path. Then the results are filtered against auth.ldap.groupclass, de-
fault posixGroup, and the account's 'name' attribute, memberUid by de-
fault.

auth.ldap.groupou: Groups

Note that as of 2017.7, auth.ldap.groupclass can refer to either a
groupclass or an objectClass. For some LDAP servers (notably OpenLDAP
without the memberOf overlay enabled) to determine group membership we
need to know both the objectClass and the memberUid attributes. Usu-
ally for these servers you will want a auth.ldap.groupclass of posix-
Group and an auth.ldap.groupattribute of memberUid.

LDAP servers with the memberOf overlay will have entries similar to
auth.ldap.groupclass: person and auth.ldap.groupattribute: memberOf.

When using the ldap('DC=domain,DC=com') eauth operator, sometimes the
records returned from LDAP or Active Directory have fully-qualified do-
main names attached, while minion IDs instead are simple hostnames.
The parameter below allows the administrator to strip off a certain set
of domain names so the hostnames looked up in the directory service can
match the minion IDs.

auth.ldap.minion_stripdomains: ['.external.bigcorp.com', '.internal.bigcorp.com']

Determining Group Memberships (Active Directory)
Active Directory handles group membership differently, and does not
utilize the groupou configuration variable. AD needs the following op-
tions in the master config:

auth.ldap.activedirectory: True
auth.ldap.filter: sAMAccountName={{username}}
auth.ldap.accountattributename: sAMAccountName
auth.ldap.groupclass: group
auth.ldap.persontype: person

To determine group membership in AD, the username and password that is
entered when LDAP is requested as the eAuth mechanism on the command
line is used to bind to AD's LDAP interface. If this fails, then it
doesn't matter what groups the user belongs to, he or she is denied ac-
cess. Next, the distinguishedName of the user is looked up with the
following LDAP search:

(&(<value of auth.ldap.accountattributename>={{username}})
(objectClass=<value of auth.ldap.persontype>)
)

This should return a distinguishedName that we can use to filter for
group membership. Then the following LDAP query is executed:

(&(member=<distinguishedName from search above>)
(objectClass=<value of auth.ldap.groupclass>)
)

external_auth:
ldap:
test_ldap_user:
- '*':
- test.ping

To configure a LDAP group, append a % to the ID:

external_auth:
ldap:
test_ldap_group%:
- '*':
- test.echo

In addition, if there are a set of computers in the directory service
that should be part of the eAuth definition, they can be specified like
this:

external_auth:
ldap:
test_ldap_group%:
- ldap('DC=corp,DC=example,DC=com'):
- test.echo

The string inside ldap() above is any valid LDAP/AD tree limiter. OU=
in particular is permitted as long as it would return a list of com-
puter objects.

Peer Communication
Salt 0.9.0 introduced the capability for Salt minions to publish com-
mands. The intent of this feature is not for Salt minions to act as in-
dependent brokers one with another, but to allow Salt minions to pass
commands to each other.

In Salt 0.10.0 the ability to execute runners from the master was
added. This allows for the master to return collective data from run-
ners back to the minions via the peer interface.

The peer interface is configured through two options in the master con-
figuration file. For minions to send commands from the master the peer
configuration is used. To allow for minions to execute runners from the
master the peer_run configuration is used.

Since this presents a viable security risk by allowing minions access
to the master publisher the capability is turned off by default. The
minions can be allowed access to the master publisher on a per minion
basis based on regular expressions. Minions with specific ids can be
allowed access to certain Salt modules and functions.

Peer Configuration
The configuration is done under the peer setting in the Salt master
configuration file, here are a number of configuration possibilities.

The simplest approach is to enable all communication for all minions,
this is only recommended for very secure environments.

peer:
.*:
- .*

This configuration will allow minions with IDs ending in example.com
access to the test, ps, and pkg module functions.

peer:
.*example.com:
- test.*
- ps.*
- pkg.*

The configuration logic is simple, a regular expression is passed for
matching minion ids, and then a list of expressions matching minion
functions is associated with the named minion. For instance, this con-
figuration will also allow minions ending with foo.org access to the
publisher.

peer:
.*example.com:
- test.*
- ps.*
- pkg.*
.*foo.org:
- test.*
- ps.*
- pkg.*

NOTE:
Functions are matched using regular expressions.

Peer Runner Communication
Configuration to allow minions to execute runners from the master is
done via the peer_run option on the master. The peer_run configuration
follows the same logic as the peer option. The only difference is that
access is granted to runner modules.

To open up access to all minions to all runners:

peer_run:
.*:
- .*

This configuration will allow minions with IDs ending in example.com
access to the manage and jobs runner functions.

peer_run:
.*example.com:
- manage.*
- jobs.*

NOTE:
Functions are matched using regular expressions.

Using Peer Communication
The publish module was created to manage peer communication. The pub-
lish module comes with a number of functions to execute peer communica-
tion in different ways. Currently there are three functions in the pub-
lish module. These examples will show how to test the peer system via
the salt-call command.

To execute test.version on all minions:

# salt-call publish.publish \* test.version

To execute the manage.up runner:

# salt-call publish.runner manage.up

To match minions using other matchers, use tgt_type:

# salt-call publish.publish 'webserv* and not G@os:Ubuntu' test.version tgt_type='compound'

NOTE:
In pre-2017.7.0 releases, use expr_form instead of tgt_type.

When to Use Each Authentication System
publisher_acl is useful for allowing local system users to run Salt
commands without giving them root access. If you can log into the Salt
master directly, then publisher_acl allows you to use Salt without root
privileges. If the local system is configured to authenticate against a
remote system, like LDAP or Active Directory, then publisher_acl will
interact with the remote system transparently.

external_auth is useful for salt-api or for making your own scripts
that use Salt's Python API. It can be used at the CLI (with the -a
flag) but it is more cumbersome as there are more steps involved. The
only time it is useful at the CLI is when the local system is not con-
figured to authenticate against an external service but you still want
Salt to authenticate against an external service.

Examples
The access controls are manifested using matchers in these configura-
tions:

publisher_acl:
fred:
- web\*:
- pkg.list_pkgs
- test.*
- apache.*

In the above example, fred is able to send commands only to minions
which match the specified glob target. This can be expanded to include
other functions for other minions based on standard targets (all match-
ers are supported except the compound one).

external_auth:
pam:
dave:
- test.version
- mongo\*:
- network.*
- log\*:
- network.*
- pkg.*
- 'G@os:RedHat':
- kmod.*
steve:
- .*

The above allows for all minions to be hit by test.version by dave, and
adds a few functions that dave can execute on other minions. It also
allows steve unrestricted access to salt commands.

NOTE:
Functions are matched using regular expressions.

Job Management
New in version 0.9.7.

Since Salt executes jobs running on many systems, Salt needs to be able
to manage jobs running on many systems.

The Minion proc System
Salt Minions maintain a proc directory in the Salt cachedir. The proc
directory maintains files named after the executed job ID. These files
contain the information about the current running jobs on the minion
and allow for jobs to be looked up. This is located in the proc direc-
tory under the cachedir, with a default configuration it is under
/var/cache/salt/{master|minion}/proc.

Functions in the saltutil Module
Salt 0.9.7 introduced a few new functions to the saltutil module for
managing jobs. These functions are:

1. running Returns the data of all running jobs that are found in the
proc directory.

2. find_job Returns specific data about a certain job based on job id.

3. signal_job Allows for a given jid to be sent a signal.

4. term_job Sends a termination signal (SIGTERM, 15) to the process
controlling the specified job.

5. kill_job Sends a kill signal (SIGKILL, 9) to the process controlling
the specified job.

These functions make up the core of the back end used to manage jobs at
the minion level.

The jobs Runner
A convenience runner front end and reporting system has been added as
well. The jobs runner contains functions to make viewing data easier
and cleaner.

The jobs runner contains a number of functions...

active
The active function runs saltutil.running on all minions and formats
the return data about all running jobs in a much more usable and com-
pact format. The active function will also compare jobs that have re-
turned and jobs that are still running, making it easier to see what
systems have completed a job and what systems are still being waited
on.

# salt-run jobs.active

lookup_jid
When jobs are executed the return data is sent back to the master and
cached. By default it is cached for 24 hours, but this can be config-
ured via the keep_jobs option in the master configuration. Using the
lookup_jid runner will display the same return data that the initial
job invocation with the salt command would display.

# salt-run jobs.lookup_jid <job id number>

list_jobs
Before finding a historic job, it may be required to find the job id.
list_jobs will parse the cached execution data and display all of the
job data for jobs that have already, or partially returned.

# salt-run jobs.list_jobs

Scheduling Jobs
Salt's scheduling system allows incremental executions on minions or
the master. The schedule system exposes the execution of any execution
function on minions or any runner on the master.

Scheduling can be enabled by multiple methods:

o schedule option in either the master or minion config files. These
require the master or minion application to be restarted in order for
the schedule to be implemented.

o Minion pillar data. Schedule is implemented by refreshing the min-
ion's pillar data, for example by using saltutil.refresh_pillar.

o The schedule state or schedule module

NOTE:
The scheduler executes different functions on the master and min-
ions. When running on the master the functions reference runner
functions, when running on the minion the functions specify execu-
tion functions.

A scheduled run has no output on the minion unless the config is set to
info level or higher. Refer to minion-logging-settings.

States are executed on the minion, as all states are. You can pass po-
sitional arguments and provide a YAML dict of named arguments.

schedule:
job1:
function: state.sls
seconds: 3600
args:
- httpd
kwargs:
test: True

This will schedule the command: state.sls httpd test=True every 3600
seconds (every hour).

schedule:
job1:
function: state.sls
seconds: 3600
args:
- httpd
kwargs:
test: True
splay: 15

This will schedule the command: state.sls httpd test=True every 3600
seconds (every hour) splaying the time between 0 and 15 seconds.

schedule:
job1:
function: state.sls
seconds: 3600
args:
- httpd
kwargs:
test: True
splay:
start: 10
end: 15

This will schedule the command: state.sls httpd test=True every 3600
seconds (every hour) splaying the time between 10 and 15 seconds.

Schedule by Date and Time
New in version 2014.7.0.

Frequency of jobs can also be specified using date strings supported by
the Python dateutil library. This requires the Python dateutil library
to be installed.

schedule:
job1:
function: state.sls
args:
- httpd
kwargs:
test: True
when: 5:00pm

This will schedule the command: state.sls httpd test=True at 5:00 PM
minion localtime.

schedule:
job1:
function: state.sls
args:
- httpd
kwargs:
test: True
when:
- Monday 5:00pm
- Tuesday 3:00pm
- Wednesday 5:00pm
- Thursday 3:00pm
- Friday 5:00pm

This will schedule the command: state.sls httpd test=True at 5:00 PM on
Monday, Wednesday and Friday, and 3:00 PM on Tuesday and Thursday.

schedule:
job1:
function: state.sls
args:
- httpd
kwargs:
test: True
when:
- 'tea time'

whens:
tea time: 1:40pm
deployment time: Friday 5:00pm

The Salt scheduler also allows custom phrases to be used for the when
parameter. These whens can be stored as either pillar values or grain
values.

schedule:
job1:
function: state.sls
seconds: 3600
args:
- httpd
kwargs:
test: True
range:
start: 8:00am
end: 5:00pm

This will schedule the command: state.sls httpd test=True every 3600
seconds (every hour) between the hours of 8:00 AM and 5:00 PM. The
range parameter must be a dictionary with the date strings using the
dateutil format.

schedule:
job1:
function: state.sls
seconds: 3600
args:
- httpd
kwargs:
test: True
range:
invert: True
start: 8:00am
end: 5:00pm

Using the invert option for range, this will schedule the command
state.sls httpd test=True every 3600 seconds (every hour) until the
current time is between the hours of 8:00 AM and 5:00 PM. The range pa-
rameter must be a dictionary with the date strings using the dateutil
format.

schedule:
job1:
function: pkg.install
kwargs:
pkgs: [{'bar': '>1.2.3'}]
refresh: true
once: '2016-01-07T14:30:00'

This will schedule the function pkg.install to be executed once at the
specified time. The schedule entry job1 will not be removed after the
job completes, therefore use schedule.delete to manually remove it af-
terwards.

The default date format is ISO 8601 but can be overridden by also spec-
ifying the once_fmt option, like this:

schedule:
job1:
function: test.ping
once: 2015-04-22T20:21:00
once_fmt: '%Y-%m-%dT%H:%M:%S'

Maximum Parallel Jobs Running
New in version 2014.7.0.

The scheduler also supports ensuring that there are no more than N
copies of a particular routine running. Use this for jobs that may be
long-running and could step on each other or pile up in case of infra-
structure outage.

The default for maxrunning is 1.

schedule:
long_running_job:
function: big_file_transfer
jid_include: True
maxrunning: 1

Cron-like Schedule
New in version 2014.7.0.

schedule:
job1:
function: state.sls
cron: '*/15 * * * *'
args:
- httpd
kwargs:
test: True

The scheduler also supports scheduling jobs using a cron like format.
This requires the Python croniter library.

Job Data Return
New in version 2015.5.0.

By default, data about jobs runs from the Salt scheduler is returned to
the master. Setting the return_job parameter to False will prevent the
data from being sent back to the Salt master.

schedule:
job1:
function: scheduled_job_function
return_job: False

Job Metadata
New in version 2015.5.0.

It can be useful to include specific data to differentiate a job from
other jobs. Using the metadata parameter special values can be associ-
ated with a scheduled job. These values are not used in the execution
of the job, but can be used to search for specific jobs later if com-
bined with the return_job parameter. The metadata parameter must be
specified as a dictionary, othewise it will be ignored.

schedule:
job1:
function: scheduled_job_function
metadata:
foo: bar

Run on Start
New in version 2015.5.0.

By default, any job scheduled based on the startup time of the minion
will run the scheduled job when the minion starts up. Sometimes this is
not the desired situation. Using the run_on_start parameter set to
False will cause the scheduler to skip this first run and wait until
the next scheduled run:

schedule:
job1:
function: state.sls
seconds: 3600
run_on_start: False
args:
- httpd
kwargs:
test: True

Until and After
New in version 2015.8.0.

schedule:
job1:
function: state.sls
seconds: 15
until: '12/31/2015 11:59pm'
args:
- httpd
kwargs:
test: True

Using the until argument, the Salt scheduler allows you to specify an
end time for a scheduled job. If this argument is specified, jobs will
not run once the specified time has passed. Time should be specified in
a format supported by the dateutil library. This requires the Python
dateutil library to be installed.

New in version 2015.8.0.

schedule:
job1:
function: state.sls
seconds: 15
after: '12/31/2015 11:59pm'
args:
- httpd
kwargs:
test: True

Using the after argument, the Salt scheduler allows you to specify an
start time for a scheduled job. If this argument is specified, jobs
will not run until the specified time has passed. Time should be speci-
fied in a format supported by the dateutil library. This requires the
Python dateutil library to be installed.

Scheduling States
schedule:
log-loadavg:
function: cmd.run
seconds: 3660
args:
- 'logger -t salt < /proc/loadavg'
kwargs:
stateful: False
shell: /bin/sh

Scheduling Highstates
To set up a highstate to run on a minion every 60 minutes set this in
the minion config or pillar:

schedule:
highstate:
function: state.highstate
minutes: 60

Time intervals can be specified as seconds, minutes, hours, or days.

Scheduling Runners
Runner executions can also be specified on the master within the master
configuration file:

schedule:
run_my_orch:
function: state.orchestrate
hours: 6
splay: 600
args:
- orchestration.my_orch

The above configuration is analogous to running salt-run state.orch or-
chestration.my_orch every 6 hours.

Scheduler With Returner
The scheduler is also useful for tasks like gathering monitoring data
about a minion, this schedule option will gather status data and send
it to a MySQL returner database:

schedule:
uptime:
function: status.uptime
seconds: 60
returner: mysql
meminfo:
function: status.meminfo
minutes: 5
returner: mysql

Since specifying the returner repeatedly can be tiresome, the sched-
ule_returner option is available to specify one or a list of global re-
turners to be used by the minions when scheduling.

Managing the Job Cache
The Salt Master maintains a job cache of all job executions which can
be queried via the jobs runner. This job cache is called the Default
Job Cache.

Default Job Cache
A number of options are available when configuring the job cache. The
default caching system uses local storage on the Salt Master and can be
found in the job cache directory (on Linux systems this is typically
/var/cache/salt/master/jobs). The default caching system is suitable
for most deployments as it does not typically require any further con-
figuration or management.

The default job cache is a temporary cache and jobs will be stored for
24 hours. If the default cache needs to store jobs for a different pe-
riod the time can be easily adjusted by changing the keep_jobs parame-
ter in the Salt Master configuration file. The value passed in is mea-
sured via hours:

keep_jobs: 24

Reducing the Size of the Default Job Cache
The Default Job Cache can sometimes be a burden on larger deployments
(over 5000 minions). Disabling the job cache will make previously exe-
cuted jobs unavailable to the jobs system and is not generally recom-
mended. 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.

However, you can disable the job_cache by setting it to False in the
Salt Master configuration file. Setting this value to False means that
the Salt Master will no longer cache minion returns, but a JID direc-
tory and jid file for each job will still be created. This JID direc-
tory is necessary for checking for and preventing JID collisions.

The default location for the job cache is in the /var/cache/salt/mas-
ter/jobs/ directory.

Setting the job_cache to False in addition to setting the keep_jobs op-
tion to a smaller value, such as 1, in the Salt Master configuration
file will reduce the size of the Default Job Cache, and thus the burden
on the Salt Master.

NOTE:
Changing the keep_jobs option sets the number of hours to keep old
job information and defaults to 24 hours. Do not set this value to 0
when trying to make the cache cleaner run more frequently, as this
means the cache cleaner will never run.

Additional Job Cache Options
Many deployments may wish to use an external database to maintain a
long term register of executed jobs. Salt comes with two main mecha-
nisms to do this, the master job cache and the external job cache.

See Storing Job Results in an External System.

Storing Job Results in an External System
After a job executes, job results are returned to the Salt Master by
each Salt Minion. These results are stored in the Default Job Cache.

In addition to the Default Job Cache, Salt provides two additional
mechanisms to send job results to other systems (databases, local sys-
log, and others):

o External Job Cache

o Master Job Cache

The major difference between these two mechanism is from where results
are returned (from the Salt Master or Salt Minion). Configuring either
of these options will also make the Jobs Runner functions to automati-
cally query the remote stores for information.

External Job Cache - Minion-Side Returner
When an External Job Cache is configured, data is returned to the De-
fault Job Cache on the Salt Master like usual, and then results are
also sent to an External Job Cache using a Salt returner module running
on the Salt Minion. [image]

o Advantages: Data is stored without placing additional load on the
Salt Master.

o Disadvantages: Each Salt Minion connects to the external job cache,
which can result in a large number of connections. Also requires ad-
ditional configuration to get returner module settings on all Salt
Minions.

Master Job Cache - Master-Side Returner
New in version 2014.7.0.

Instead of configuring an External Job Cache on each Salt Minion, you
can configure the Master Job Cache to send job results from the Salt
Master instead. In this configuration, Salt Minions send data to the
Default Job Cache as usual, and then the Salt Master sends the data to
the external system using a Salt returner module running on the Salt
Master. [image]

o Advantages: A single connection is required to the external system.
This is preferred for databases and similar systems.

o Disadvantages: Places additional load on your Salt Master.

Configure an External or Master Job Cache
Step 1: Understand Salt Returners
Before you configure a job cache, it is essential to understand Salt
returner modules ("returners"). Returners are pluggable Salt Modules
that take the data returned by jobs, and then perform any necessary
steps to send the data to an external system. For example, a returner
might establish a connection, authenticate, and then format and trans-
fer data.

The Salt Returner system provides the core functionality used by the
External and Master Job Cache systems, and the same returners are used
by both systems.

Salt currently provides many different returners that let you connect
to a wide variety of systems. A complete list is available at all Salt
returners. Each returner is configured differently, so make sure you
read and follow the instructions linked from that page.

For example, the MySQL returner requires:

o A database created using provided schema (structure is available at
MySQL returner)

o A user created with privileges to the database

o Optional SSL configuration

A simpler returner, such as Slack or HipChat, requires:

o An API key/version

o The target channel/room

o The username that should be used to send the message

Step 2: Configure the Returner
After you understand the configuration and have the external system
ready, the configuration requirements must be declared.

External Job Cache
The returner configuration settings can be declared in the Salt Minion
configuration file, the Minion's pillar data, or the Minion's grains.

If external_job_cache configuration settings are specified in more than
one place, the options are retrieved in the following order. The first
configuration location that is found is the one that will be used.

o Minion configuration file

o Minion's grains

o Minion's pillar data

Master Job Cache
The returner configuration settings for the Master Job Cache should be
declared in the Salt Master's configuration file.

Configuration File Examples
MySQL requires:

mysql.host: 'salt'
mysql.user: 'salt'
mysql.pass: 'salt'
mysql.db: 'salt'
mysql.port: 3306

Slack requires:

slack.channel: 'channel'
slack.api_key: 'key'
slack.from_name: 'name'

After you have configured the returner and added settings to the con-
figuration file, you can enable the External or Master Job Cache.

Step 3: Enable the External or Master Job Cache
Configuration is a single line that specifies an already-configured re-
turner to use to send all job data to an external system.

External Job Cache
To enable a returner as the External Job Cache (Minion-side), add the
following line to the Salt Master configuration file:

ext_job_cache: <returner>

For example:

ext_job_cache: mysql

NOTE:
When configuring an External Job Cache (Minion-side), the returner
settings are added to the Minion configuration file, but the Exter-
nal Job Cache setting is configured in the Master configuration
file.

Master Job Cache
To enable a returner as a Master Job Cache (Master-side), add the fol-
lowing line to the Salt Master configuration file:

master_job_cache: <returner>

For example:

master_job_cache: mysql

Verify that the returner configuration settings are in the Master con-
figuration file, and be sure to restart the salt-master service after
you make configuration changes. (service salt-master restart).

Logging
The salt project tries to get the logging to work for you and help us
solve any issues you might find along the way.

If you want to get some more information on the nitty-gritty of salt's
logging system, please head over to the logging development document,
if all you're after is salt's logging configurations, please continue
reading.

Log Levels
The log levels are ordered numerically such that setting the log level
to a specific level will record all log statements at that level and
higher. For example, setting log_level: error will log statements at
error, critical, and quiet levels, although nothing should be logged at
quiet level.

Most of the logging levels are defined by default in Python's logging
library and can be found in the official Python documentation. Salt
uses some more levels in addition to the standard levels. All levels
available in salt are shown in the table below.

NOTE:
Python dependencies used by salt may define and use additional log-
ging levels. For example, the Python 2 version of the multiprocess-
ing standard Python library uses the levels subwarning, 25 and sub-
debug, 5.

+---------+---------------+---------------------+
|Level | Numeric value | Description |
+---------+---------------+---------------------+
|quiet | 1000 | Nothing should be |
| | | logged at this |
| | | level |
+---------+---------------+---------------------+
|critical | 50 | Critical errors |
+---------+---------------+---------------------+
|error | 40 | Errors |
+---------+---------------+---------------------+
|warning | 30 | Warnings |
+---------+---------------+---------------------+
|info | 20 | Normal log informa- |
| | | tion |
+---------+---------------+---------------------+
|profile | 15 | Profiling informa- |
| | | tion on salt per- |
| | | formance |
+---------+---------------+---------------------+

|debug | 10 | Information useful |
| | | for debugging both |
| | | salt implementa- |
| | | tions and salt code |
+---------+---------------+---------------------+
|trace | 5 | More detailed code |
| | | debugging informa- |
| | | tion |
+---------+---------------+---------------------+
|garbage | 1 | Even more debugging |
| | | information |
+---------+---------------+---------------------+
|all | 0 | Everything |
+---------+---------------+---------------------+

Available Configuration Settings
log_file
The log records can be sent to a regular file, local path name, or net-
work location. Remote logging works best when configured to use rsys-
logd(8) (e.g.: file:///dev/log), with rsyslogd(8) configured for net-
work logging. The format for remote addresses is:

<file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility>

Where log-facility is the symbolic name of a syslog facility as defined
in the SysLogHandler documentation. It defaults to LOG_USER.

Default: Dependent of the binary being executed, for example, for
salt-master, /var/log/salt/master.

Examples:

log_file: /var/log/salt/master

log_file: /var/log/salt/minion

log_file: file:///dev/log

log_file: file:///dev/log/LOG_DAEMON

log_file: udp://loghost:10514

log_level
Default: warning

The level of log record messages to send to the console. One of all,
garbage, trace, debug, profile, info, warning, error, critical, quiet.

log_level: warning

NOTE:
Add log_level: quiet in salt configuration file to completely dis-
able logging. In case of running salt in command line use
--log-level=quiet instead.

log_level_logfile
Default: info

The level of messages to send to the log file. One of all, garbage,
trace, debug, profile, info, warning, error, critical, quiet.

log_level_logfile: warning

log_datefmt
Default: %H:%M:%S

The date and time format used in console log messages. Allowed
date/time formatting matches those used in time.strftime().

log_datefmt: '%H:%M:%S'

log_datefmt_logfile
Default: %Y-%m-%d %H:%M:%S

The date and time format used in log file messages. Allowed date/time
formatting matches those used in time.strftime().

log_datefmt_logfile: '%Y-%m-%d %H:%M:%S'

log_fmt_console
Default: [%(levelname)-8s] %(message)s

The format of the console logging messages. All standard python logging
LogRecord attributes can be used. Salt also provides these custom Lo-
gRecord attributes to colorize console log output:

"%(colorlevel)s" # log level name colorized by level
"%(colorname)s" # colorized module name
"%(colorprocess)s" # colorized process number
"%(colormsg)s" # log message colorized by level

NOTE:
The %(colorlevel)s, %(colorname)s, and %(colorprocess) LogRecord at-
tributes also include padding and enclosing brackets, [ and ] to
match the default values of their collateral non-colorized LogRecord
attributes.

log_fmt_console: '[%(levelname)-8s] %(message)s'

log_fmt_logfile
Default: %(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(mes-
sage)s

The format of the log file logging messages. All standard python log-
ging LogRecord attributes can be used. Salt also provides these custom
LogRecord attributes that include padding and enclosing brackets [ and
]:

"%(bracketlevel)s" # equivalent to [%(levelname)-8s]
"%(bracketname)s" # equivalent to [%(name)-17s]
"%(bracketprocess)s" # equivalent to [%(process)5s]

log_fmt_logfile: '%(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(message)s'

log_granular_levels
Default: {}

This can be used to control logging levels more specifically, based on
log call name. The example sets the main salt library at the 'warning'
level, sets salt.modules to log at the debug level, and sets a custom
module to the all level:

log_granular_levels:
'salt': 'warning'
'salt.modules': 'debug'
'salt.loader.saltmaster.ext.module.custom_module': 'all'

log_fmt_jid
Default: [JID: %(jid)s]

The format of the JID when added to logging messages.

log_fmt_jid: '[JID: %(jid)s]'

External Logging Handlers
Besides the internal logging handlers used by salt, there are some ex-
ternal which can be used, see the external logging handlers document.

salt.log.handlers.fluent_mod
Fluent Logging Handler
New in version 2015.8.0.

This module provides some fluentd logging handlers.

Fluent Logging Handler
In the fluent configuration file:

<source>
type forward
bind localhost
port 24224
</source>

Then, to send logs via fluent in Logstash format, add the following to
the salt (master and/or minion) configuration file:

fluent_handler:
host: localhost
port: 24224

To send logs via fluent in the Graylog raw json format, add the follow-
ing to the salt (master and/or minion) configuration file:

fluent_handler:
host: localhost
port: 24224
payload_type: graylog
tags:
- salt_master.SALT

The above also illustrates the tags option, which allows one to set de-
scriptive (or useful) tags on records being sent. If not provided,
this defaults to the single tag: 'salt'. Also note that, via Graylog
"magic", the 'facility' of the logged message is set to 'SALT' (the
portion of the tag after the first period), while the tag itself will
be set to simply 'salt_master'. This is a feature, not a bug :)

Note: There is a third emitter, for the GELF format, but it is largely
untested, and I don't currently have a setup supporting this config, so
while it runs cleanly and outputs what LOOKS to be valid GELF, any
real-world feedback on its usefulness, and correctness, will be appre-
ciated.

Log Level
The fluent_handler configuration section accepts an additional setting
log_level. If not set, the logging level used will be the one defined
for log_level in the global configuration file section.

Inspiration

This work was inspired in fluent-logger-python

salt.log.handlers.log4mongo_mod
Log4Mongo Logging Handler
This module provides a logging handler for sending salt logs to MongoDB

Configuration
In the salt configuration file (e.g. /usr/local/etc/salt/{master,min-
ion}):

log4mongo_handler:
host: mongodb_host
port: 27017
database_name: logs
collection: salt_logs
username: logging
password: reindeerflotilla
write_concern: 0
log_level: warning

Log Level
If not set, the log_level will be set to the level defined in the
global configuration file setting.

Inspiration

This work was inspired by the Salt logging handlers for
LogStash and Sentry and by the log4mongo Python implementa-
tion.

salt.log.handlers.logstash_mod
Logstash Logging Handler
New in version 0.17.0.

This module provides some Logstash logging handlers.

UDP Logging Handler
For versions of Logstash before 1.2.0:

In the salt configuration file:

logstash_udp_handler:
host: 127.0.0.1
port: 9999
version: 0
msg_type: logstash

In the Logstash configuration file:

input {
udp {
type => "udp-type"
format => "json_event"
}
}

For version 1.2.0 of Logstash and newer:

In the salt configuration file:

logstash_udp_handler:
host: 127.0.0.1
port: 9999
version: 1
msg_type: logstash

In the Logstash configuration file:

input {
udp {
port => 9999
codec => json
}
}

Please read the UDP input configuration page for additional informa-
tion.

ZeroMQ Logging Handler
For versions of Logstash before 1.2.0:

In the salt configuration file:

logstash_zmq_handler:
address: tcp://127.0.0.1:2021
version: 0

In the Logstash configuration file:

input {
zeromq {
type => "zeromq-type"
mode => "server"
topology => "pubsub"
address => "tcp://0.0.0.0:2021"
charset => "UTF-8"
format => "json_event"
}
}

For version 1.2.0 of Logstash and newer:

In the salt configuration file:

logstash_zmq_handler:
address: tcp://127.0.0.1:2021
version: 1

In the Logstash configuration file:

input {
zeromq {
topology => "pubsub"
address => "tcp://0.0.0.0:2021"
codec => json
}
}

Please read the ZeroMQ input configuration page for additional informa-
tion.

Important Logstash Setting

One of the most important settings that you should not forget
on your Logstash configuration file regarding these logging
handlers is format. Both the UDP and ZeroMQ inputs need to
have format as json_event which is what we send over the
wire.

Log Level
Both the logstash_udp_handler and the logstash_zmq_handler configura-
tion sections accept an additional setting log_level. If not set, the
logging level used will be the one defined for log_level in the global
configuration file section.

HWM
The high water mark for the ZMQ socket setting. Only applicable for the
logstash_zmq_handler.

Inspiration

This work was inspired in pylogstash, python-logstash, canary
and the PyZMQ logging handler.

salt.log.handlers.sentry_mod
Sentry Logging Handler
New in version 0.17.0.

This module provides a Sentry logging handler. Sentry is an open source
error tracking platform that provides deep context about exceptions
that happen in production. Details about stack traces along with the
context variables available at the time of the exception are easily
browsable and filterable from the online interface. For more details
please see Sentry.

Note

The Raven library needs to be installed on the system for
this logging handler to be available.

Configuring the python Sentry client, Raven, should be done under the
sentry_handler configuration key. Additional context may be provided
for corresponding grain item(s). At the bare minimum, you need to de-
fine the DSN. As an example:

sentry_handler:
dsn: https://pub-key:secret-key@app.getsentry.com/app-id

More complex configurations can be achieved, for example:

sentry_handler:
servers:
- https://sentry.example.com
- http://192.168.1.1
project: app-id
public_key: deadbeefdeadbeefdeadbeefdeadbeef
secret_key: beefdeadbeefdeadbeefdeadbeefdead
context:
- os
- master
- saltversion
- cpuarch
- ec2.tags.environment

Note

The public_key and secret_key variables are not supported
with Sentry > 3.0. The DSN key should be used instead.

All the client configuration keys are supported, please see the Raven
client documentation.

The default logging level for the sentry handler is ERROR. If you wish
to define a different one, define log_level under the sentry_handler
configuration key:

sentry_handler:
dsn: https://pub-key:secret-key@app.getsentry.com/app-id
log_level: warning

The available log levels are those also available for the salt cli
tools and configuration; salt --help should give you the required in-
formation.

Threaded Transports
Raven's documents rightly suggest using its threaded transport for
critical applications. However, don't forget that if you start having
troubles with Salt after enabling the threaded transport, please try
switching to a non-threaded transport to see if that fixes your prob-
lem.

Salt File Server
Salt comes with a simple file server suitable for distributing files to
the Salt minions. The file server is a stateless ZeroMQ server that is
built into the Salt master.

The main intent of the Salt file server is to present files for use in
the Salt state system. With this said, the Salt file server can be used
for any general file transfer from the master to the minions.

File Server Backends
In Salt 0.12.0, the modular fileserver was introduced. This feature
added the ability for the Salt Master to integrate different file
server backends. File server backends allow the Salt file server to act
as a transparent bridge to external resources. A good example of this
is the git backend, which allows Salt to serve files sourced from one
or more git repositories, but there are several others as well. Click
here for a full list of Salt's fileserver backends.

Enabling a Fileserver Backend
Fileserver backends can be enabled with the fileserver_backend option.

fileserver_backend:
- git

See the documentation for each backend to find the correct value to add
to fileserver_backend in order to enable them.

Using Multiple Backends
If fileserver_backend is not defined in the Master config file, Salt
will use the roots backend, but the fileserver_backend option supports
multiple backends. When more than one backend is in use, the files from
the enabled backends are merged into a single virtual filesystem. When
a file is requested, the backends will be searched in order for that
file, and the first backend to match will be the one which returns the
file.

fileserver_backend:
- roots
- git

With this configuration, the environments and files defined in the
file_roots parameter will be searched first, and if the file is not
found then the git repositories defined in gitfs_remotes will be
searched.

Defining Environments
Just as the order of the values in fileserver_backend matters, so too
does the order in which different sources are defined within a file-
server environment. For example, given the below file_roots configura-
tion, if both /usr/local/etc/salt/states/dev/foo.txt and
/srv/salt/prod/foo.txt exist on the Master, then salt://foo.txt would
point to /usr/local/etc/salt/states/dev/foo.txt in the dev environment,
but it would point to /usr/local/etc/salt/states/prod/foo.txt in the
base environment.

file_roots:
base:
- /usr/local/etc/salt/states/prod
qa:
- /usr/local/etc/salt/states/qa
- /usr/local/etc/salt/states/prod
dev:
- /usr/local/etc/salt/states/dev
- /usr/local/etc/salt/states/qa
- /usr/local/etc/salt/states/prod

Similarly, when using the git backend, if both repositories defined be-
low have a hotfix23 branch/tag, and both of them also contain the file
bar.txt in the root of the repository at that branch/tag, then
salt://bar.txt in the hotfix23 environment would be served from the
first repository.

gitfs_remotes:
- https://mydomain.tld/repos/first.git
- https://mydomain.tld/repos/second.git

NOTE:
Environments map differently based on the fileserver backend. For
instance, the mappings are explicitly defined in roots backend,
while in the VCS backends (git, hg, svn) the environments are cre-
ated from branches/tags/bookmarks/etc. For the minion backend, the
files are all in a single environment, which is specified by the
minionfs_env option.

See the documentation for each backend for a more detailed explana-
tion of how environments are mapped.

Requesting Files from Specific Environments
The Salt fileserver supports multiple environments, allowing for SLS
files and other files to be isolated for better organization.

For the default backend (called roots), environments are defined using
the roots option. Other backends (such as gitfs) define environments
in their own ways. For a list of available fileserver backends, see
here.

Querystring Syntax
Any salt:// file URL can specify its fileserver environment using a
querystring syntax, like so:

salt://path/to/file?saltenv=foo

In Reactor configurations, this method must be used to pull files from
an environment other than base.

In States
Minions can be instructed which environment to use both globally, and
for a single state, and multiple methods for each are available:

Globally
A minion can be pinned to an environment using the environment option
in the minion config file.

Additionally, the environment can be set for a single call to the fol-
lowing functions:

o state.apply

o state.highstate

o state.sls

o state.top

NOTE:
When the saltenv parameter is used to trigger a highstate using ei-
ther state.apply or state.highstate, only states from that environ-
ment will be applied.

On a Per-State Basis
Within an individual state, there are two ways of specifying the envi-
ronment. The first is to add a saltenv argument to the state. This ex-
ample will pull the file from the config environment:

/etc/foo/bar.conf:
file.managed:
- source: salt://foo/bar.conf
- user: foo
- mode: 600
- saltenv: config

Another way of doing the same thing is to use the querystring syntax
described above:

/etc/foo/bar.conf:
file.managed:
- source: salt://foo/bar.conf?saltenv=config
- user: foo
- mode: 600

NOTE:
Specifying the environment using either of the above methods is only
necessary in cases where a state from one environment needs to ac-
cess files from another environment. If the SLS file containing this
state was in the config environment, then it would look in that en-
vironment by default.

File Server Configuration
The Salt file server is a high performance file server written in Ze-
roMQ. It manages large files quickly and with little overhead, and has
been optimized to handle small files in an extremely efficient manner.

The Salt file server is an environment aware file server. This means
that files can be allocated within many root directories and accessed
by specifying both the file path and the environment to search. The in-
dividual environments can span across multiple directory roots to cre-
ate overlays and to allow for files to be organized in many flexible
ways.

Environments
The Salt file server defaults to the mandatory base environment. This
environment MUST be defined and is used to download files when no envi-
ronment is specified.

Environments allow for files and sls data to be logically separated,
but environments are not isolated from each other. This allows for log-
ical isolation of environments by the engineer using Salt, but also al-
lows for information to be used in multiple environments.

Directory Overlay
The environment setting is a list of directories to publish files from.
These directories are searched in order to find the specified file and
the first file found is returned.

This means that directory data is prioritized based on the order in
which they are listed. In the case of this file_roots configuration:

file_roots:
base:
- /usr/local/etc/salt/states/base
- /usr/local/etc/salt/states/failover

If a file's URI is salt://httpd/httpd.conf, it will first search for
the file at /usr/local/etc/salt/states/base/httpd/httpd.conf. If the
file is found there it will be returned. If the file is not found
there, then /usr/local/etc/salt/states/failover/httpd/httpd.conf will
be used for the source.

This allows for directories to be overlaid and prioritized based on the
order they are defined in the configuration.

It is also possible to have file_roots which supports multiple environ-
ments:

file_roots:
base:
- /usr/local/etc/salt/states/base
dev:
- /usr/local/etc/salt/states/dev
- /usr/local/etc/salt/states/base
prod:
- /usr/local/etc/salt/states/prod
- /usr/local/etc/salt/states/base

This example ensures that each environment will check the associated
environment directory for files first. If a file is not found in the
appropriate directory, the system will default to using the base direc-
tory.

Local File Server
New in version 0.9.8.

The file server can be rerouted to run from the minion. This is primar-
ily to enable running Salt states without a Salt master. To use the lo-
cal file server interface, copy the file server data to the minion and
set the file_roots option on the minion to point to the directories
copied from the master. Once the minion file_roots option has been
set, change the file_client option to local to make sure that the local
file server interface is used.

The cp Module
The cp module is the home of minion side file server operations. The cp
module is used by the Salt state system, salt-cp, and can be used to
distribute files presented by the Salt file server.

Escaping Special Characters
The salt:// url format can potentially contain a query string, for ex-
ample salt://dir/file.txt?saltenv=base. You can prevent the file-
client/fileserver from interpreting ? as the initial token of a query
string by referencing the file with salt://| rather than salt://.

/etc/marathon/conf/?checkpoint:
file.managed:
- source: salt://|hw/config/?checkpoint
- makedirs: True

Environments
Since the file server is made to work with the Salt state system, it
supports environments. The environments are defined in the master con-
fig file and when referencing an environment the file specified will be
based on the root directory of the environment.

get_file
The cp.get_file function can be used on the minion to download a file
from the master, the syntax looks like this:

# salt '*' cp.get_file salt://vimrc /etc/vimrc

This will instruct all Salt minions to download the vimrc file and copy
it to /etc/vimrc

Template rendering can be enabled on both the source and destination
file names like so:

# salt '*' cp.get_file "salt://{{grains.os}}/vimrc" /etc/vimrc template=jinja

This example would instruct all Salt minions to download the vimrc from
a directory with the same name as their OS grain and copy it to
/etc/vimrc

For larger files, the cp.get_file module also supports gzip compres-
sion. Because gzip is CPU-intensive, this should only be used in sce-
narios where the compression ratio is very high (e.g. pretty-printed
JSON or YAML files).

To use compression, use the gzip named argument. Valid values are inte-
gers from 1 to 9, where 1 is the lightest compression and 9 the heavi-
est. In other words, 1 uses the least CPU on the master (and minion),
while 9 uses the most.

# salt '*' cp.get_file salt://vimrc /etc/vimrc gzip=5

Finally, note that by default cp.get_file does not create new destina-
tion directories if they do not exist. To change this, use the
makedirs argument:

# salt '*' cp.get_file salt://vimrc /etc/vim/vimrc makedirs=True

In this example, /etc/vim/ would be created if it didn't already exist.

get_dir
The cp.get_dir function can be used on the minion to download an entire
directory from the master. The syntax is very similar to get_file:

# salt '*' cp.get_dir salt://etc/apache2 /etc

cp.get_dir supports template rendering and gzip compression arguments
just like get_file:

# salt '*' cp.get_dir salt://etc/{{pillar.webserver}} /etc gzip=5 template=jinja

File Server Client Instance
A client instance is available which allows for modules and applica-
tions to be written which make use of the Salt file server.

The file server uses the same authentication and encryption used by the
rest of the Salt system for network communication.

fileclient Module
The salt/fileclient.py module is used to set up the communication from
the minion to the master. When creating a client instance using the
fileclient module, the minion configuration needs to be passed in. When
using the fileclient module from within a minion module the built in
__opts__ data can be passed:

import salt.minion
import salt.fileclient

def get_file(path, dest, saltenv="base"):
"""
Used to get a single file from the Salt master

CLI Example:
salt '*' cp.get_file salt://vimrc /etc/vimrc
"""
# Get the fileclient object
client = salt.fileclient.get_file_client(__opts__)
# Call get_file
return client.get_file(path, dest, False, saltenv)

Creating a fileclient instance outside of a minion module where the
__opts__ data is not available, it needs to be generated:

import salt.fileclient
import salt.config

def get_file(path, dest, saltenv="base"):
"""
Used to get a single file from the Salt master
"""
# Get the configuration data
opts = salt.config.minion_config("/usr/local/etc/salt/minion")
# Get the fileclient object
client = salt.fileclient.get_file_client(opts)
# Call get_file
return client.get_file(path, dest, False, saltenv)

Git Fileserver Backend Walkthrough
NOTE:
This walkthrough assumes basic knowledge of Salt. To get up to
speed, check out the Salt Walkthrough.

The gitfs backend allows Salt to serve files from git repositories. It
can be enabled by adding git to the fileserver_backend list, and con-
figuring one or more repositories in gitfs_remotes.

Branches and tags become Salt fileserver environments.

NOTE:
Branching and tagging can result in a lot of potentially-conflicting
top files, for this reason it may be useful to set top_file_merg-
ing_strategy to same in the minions' config files if the top files
are being managed in a GitFS repo.

Installing Dependencies
Both pygit2 and GitPython are supported Python interfaces to git. If
compatible versions of both are installed, pygit2 will be preferred. In
these cases, GitPython can be forced using the gitfs_provider parameter
in the master config file.

NOTE:
It is recommended to always run the most recent version of any the
below dependencies. Certain features of GitFS may not be available
without the most recent version of the chosen library.

pygit2
The minimum supported version of pygit2 is 0.20.3. Availability for
this version of pygit2 is still limited, though the SaltStack team is
working to get compatible versions available for as many platforms as
possible.

For the Fedora/EPEL versions which have a new enough version packaged,
the following command would be used to install pygit2:

# yum install python-pygit2

Provided a valid version is packaged for Debian/Ubuntu (which is not
currently the case), the package name would be the same, and the fol-
lowing command would be used to install it:

# apt-get install python-pygit2

If pygit2 is not packaged for the platform on which the Master is run-
ning, the pygit2 website has installation instructions here. Keep in
mind however that following these instructions will install libgit2 and
pygit2 without system packages. Additionally, keep in mind that SSH au-
thentication in pygit2 requires libssh2 (not libssh) development li-
braries to be present before libgit2 is built. On some Debian-based
distros pkg-config is also required to link libgit2 with libssh2.

NOTE:
If you are receiving the error "Unsupported URL Protocol" in the
Salt Master log when making a connection using SSH, review the lib-
ssh2 details listed above.

Additionally, version 0.21.0 of pygit2 introduced a dependency on
python-cffi, which in turn depends on newer releases of libffi. Upgrad-
ing libffi is not advisable as several other applications depend on it,
so on older LTS linux releases pygit2 0.20.3 and libgit2 0.20.0 is the
recommended combination.

WARNING:
pygit2 is actively developed and frequently makes non-backwards-com-
patible API changes, even in minor releases. It is not uncommon for
pygit2 upgrades to result in errors in Salt. Please take care when
upgrading pygit2, and pay close attention to the changelog, keeping
an eye out for API changes. Errors can be reported on the SaltStack
issue tracker.

RedHat Pygit2 Issues
The release of RedHat/CentOS 7.3 upgraded both python-cffi and
http-parser, both of which are dependencies for pygit2/libgit2. Both
pygit2 and libgit2 packages (which are from the EPEL repository) should
be upgraded to the most recent versions, at least to 0.24.2.

The below errors will show up in the master log if an incompatible
python-pygit2 package is installed:

2017-02-10 09:07:34,892 [salt.utils.gitfs ][ERROR ][11211] Import pygit2 failed: CompileError: command 'gcc' failed with exit status 1
2017-02-10 09:07:34,907 [salt.utils.gitfs ][ERROR ][11211] gitfs is configured but could not be loaded, are pygit2 and libgit2 installed?
2017-02-10 09:07:34,907 [salt.utils.gitfs ][CRITICAL][11211] No suitable gitfs provider module is installed.
2017-02-10 09:07:34,912 [salt.master ][CRITICAL][11211] Master failed pre flight checks, exiting

The below errors will show up in the master log if an incompatible
libgit2 package is installed:

2017-02-15 18:04:45,211 [salt.utils.gitfs ][ERROR ][6211] Error occurred fetching gitfs remote 'https://foo.com/bar.git': No Content-Type header in response

A restart of the salt-master daemon and gitfs cache directory clean up
may be required to allow http(s) repositories to continue to be
fetched.

GitPython
GitPython 0.3.0 or newer is required to use GitPython for gitfs. For
RHEL-based Linux distros, a compatible version is available in EPEL,
and can be easily installed on the master using yum:

# yum install GitPython

Ubuntu 14.04 LTS and Debian Wheezy (7.x) also have a compatible version
packaged:

# apt-get install python-git

GitPython requires the git CLI utility to work. If installed from a
system package, then git should already be installed, but if installed
via pip then it may still be necessary to install git separately. For
MacOS users, GitPython comes bundled in with the Salt installer, but
git must still be installed for it to work properly. Git can be in-
stalled in several ways, including by installing XCode.

WARNING:
GitPython advises against the use of its library for long-running
processes (such as a salt-master or salt-minion). Please see their
warning on potential leaks of system resources:
https://github.com/gitpython-developers/GitPython#leakage-of-system-resources.

WARNING:
Keep in mind that if GitPython has been previously installed on the
master using pip (even if it was subsequently uninstalled), then it
may still exist in the build cache (typically
/tmp/pip-build-root/GitPython) if the cache is not cleared after in-
stallation. The package in the build cache will override any re-
quirement specifiers, so if you try upgrading to version 0.3.2.RC1
by running pip install 'GitPython==0.3.2.RC1' then it will ignore
this and simply install the version from the cache directory.
Therefore, it may be necessary to delete the GitPython directory
from the build cache in order to ensure that the specified version
is installed.

WARNING:
GitPython 2.0.9 and newer is not compatible with Python 2.6. If in-
stalling GitPython using pip on a machine running Python 2.6, make
sure that a version earlier than 2.0.9 is installed. This can be
done on the CLI by running pip install 'GitPython<2.0.9', or in a
pip.installed state using the following SLS:

GitPython:
pip.installed:
- name: 'GitPython < 2.0.9'

Simple Configuration
To use the gitfs backend, only two configuration changes are required
on the master:

1. Include gitfs in the fileserver_backend list in the master config
file:

fileserver_backend:
- gitfs

NOTE:
git also works here. Prior to the 2018.3.0 release, only git
would work.

2. Specify one or more git://, https://, file://, or ssh:// URLs in
gitfs_remotes to configure which repositories to cache and search
for requested files:

gitfs_remotes:
- https://github.com/saltstack-formulas/salt-formula.git

SSH remotes can also be configured using scp-like syntax:

gitfs_remotes:
- git@github.com:user/repo.git
- ssh://user@domain.tld/path/to/repo.git

Information on how to authenticate to SSH remotes can be found here.

3. Restart the master to load the new configuration.

NOTE:
In a master/minion setup, files from a gitfs remote are cached once
by the master, so minions do not need direct access to the git
repository.

Multiple Remotes
The gitfs_remotes option accepts an ordered list of git remotes to
cache and search, in listed order, for requested files.

A simple scenario illustrates this cascading lookup behavior:

If the gitfs_remotes option specifies three remotes:

gitfs_remotes:
- git://github.com/example/first.git
- https://github.com/example/second.git
- file:///root/third

And each repository contains some files:

first.git:
top.sls
edit/vim.sls
edit/vimrc
nginx/init.sls

second.git:
edit/dev_vimrc
haproxy/init.sls

third:
haproxy/haproxy.conf
edit/dev_vimrc

Salt will attempt to lookup the requested file from each gitfs remote
repository in the order in which they are defined in the configuration.
The git://github.com/example/first.git remote will be searched first.
If the requested file is found, then it is served and no further
searching is executed. For example:

o A request for the file salt://haproxy/init.sls will be served from
the https://github.com/example/second.git git repo.

o A request for the file salt://haproxy/haproxy.conf will be served
from the file:///root/third repo.

NOTE:
This example is purposefully contrived to illustrate the behavior of
the gitfs backend. This example should not be read as a recommended
way to lay out files and git repos.

The file:// prefix denotes a git repository in a local directory.
However, it will still use the given file:// URL as a remote, rather
than copying the git repo to the salt cache. This means that any
refs you want accessible must exist as local refs in the specified
repo.

WARNING:
Salt versions prior to 2014.1.0 are not tolerant of changing the or-
der of remotes or modifying the URI of existing remotes. In those
versions, when modifying remotes it is a good idea to remove the
gitfs cache directory (/var/cache/salt/master/gitfs) before restart-
ing the salt-master service.

Per-remote Configuration Parameters
New in version 2014.7.0.

The following master config parameters are global (that is, they apply
to all configured gitfs remotes):

o gitfs_base

o gitfs_root

o gitfs_ssl_verify

o gitfs_mountpoint (new in 2014.7.0)

o gitfs_user (pygit2 only, new in 2014.7.0)

o gitfs_password (pygit2 only, new in 2014.7.0)

o gitfs_insecure_auth (pygit2 only, new in 2014.7.0)

o gitfs_pubkey (pygit2 only, new in 2014.7.0)

o gitfs_privkey (pygit2 only, new in 2014.7.0)

o gitfs_passphrase (pygit2 only, new in 2014.7.0)

o gitfs_refspecs (new in 2017.7.0)

o gitfs_disable_saltenv_mapping (new in 2018.3.0)

o gitfs_ref_types (new in 2018.3.0)

o gitfs_update_interval (new in 2018.3.0)

NOTE:
pygit2 only supports disabling SSL verification in versions 0.23.2
and newer.

These parameters can now be overridden on a per-remote basis. This al-
lows for a tremendous amount of customization. Here's some example us-
age:

gitfs_provider: pygit2
gitfs_base: develop

gitfs_remotes:
- https://foo.com/foo.git
- https://foo.com/bar.git:
- root: salt
- mountpoint: salt://bar
- base: salt-base
- ssl_verify: False
- update_interval: 120
- https://foo.com/bar.git:
- name: second_bar_repo
- root: other/salt
- mountpoint: salt://other/bar
- base: salt-base
- ref_types:
- branch
- http://foo.com/baz.git:
- root: salt/states
- user: joe
- password: mysupersecretpassword
- insecure_auth: True
- disable_saltenv_mapping: True
- saltenv:
- foo:
- ref: foo
- http://foo.com/quux.git:
- all_saltenvs: master

IMPORTANT:
There are two important distinctions which should be noted for
per-remote configuration:

1. The URL of a remote which has per-remote configuration must be
suffixed with a colon.

2. Per-remote configuration parameters are named like the global
versions, with the gitfs_ removed from the beginning. The excep-
tion being the name, saltenv, and all_saltenvs parameters, which
are only available to per-remote configurations.

The all_saltenvs parameter is new in the 2018.3.0 release.

In the example configuration above, the following is true:

1. The first and fourth gitfs remotes will use the develop branch/tag
as the base environment, while the second and third will use the
salt-base branch/tag as the base environment.

2. The first remote will serve all files in the repository. The second
remote will only serve files from the salt directory (and its subdi-
rectories). The third remote will only server files from the
other/salt directory (and its subdirectories), while the fourth re-
mote will only serve files from the salt/states directory (and its
subdirectories).

3. The third remote will only serve files from branches, and not from
tags or SHAs.

4. The fourth remote will only have two saltenvs available: base
(pointed at develop), and foo (pointed at foo).

5. The first and fourth remotes will have files located under the root
of the Salt fileserver namespace (salt://). The files from the sec-
ond remote will be located under salt://bar, while the files from
the third remote will be located under salt://other/bar.

6. The second and third remotes reference the same repository and
unique names need to be declared for duplicate gitfs remotes.

7. The fourth remote overrides the default behavior of not authenticat-
ing to insecure (non-HTTPS) remotes.

8. Because all_saltenvs is configured for the fifth remote, files from
the branch/tag master will appear in every fileserver environment.

NOTE:
The use of http:// (instead of https://) is permitted here only
because authentication is not being used. Otherwise, the inse-
cure_auth parameter must be used (as in the fourth remote) to
force Salt to authenticate to an http:// remote.

9. The first remote will wait 120 seconds between updates instead of
60.

Per-Saltenv Configuration Parameters
New in version 2016.11.0.

For more granular control, Salt allows the following three things to be
overridden for individual saltenvs within a given repo:

o The mountpoint

o The root

o The branch/tag to be used for a given saltenv

Here is an example:

gitfs_root: salt

gitfs_saltenv:
- dev:
- mountpoint: salt://gitfs-dev
- ref: develop

gitfs_remotes:
- https://foo.com/bar.git:
- saltenv:
- staging:
- ref: qa
- mountpoint: salt://bar-staging
- dev:
- ref: development
- https://foo.com/baz.git:
- saltenv:
- staging:
- mountpoint: salt://baz-staging

Given the above configuration, the following is true:

1. For all gitfs remotes, files for the dev saltenv will be located un-
der salt://gitfs-dev.

2. For the dev saltenv, files from the first remote will be sourced
from the development branch, while files from the second remote will
be sourced from the develop branch.

3. For the staging saltenv, files from the first remote will be located
under salt://bar-staging, while files from the second remote will be
located under salt://baz-staging.

4. For all gitfs remotes, and in all saltenvs, files will be served
from the salt directory (and its subdirectories).

Custom Refspecs
New in version 2017.7.0.

GitFS will by default fetch remote branches and tags. However, some-
times it can be useful to fetch custom refs (such as those created for
GitHub pull requests). To change the refspecs GitFS fetches, use the
gitfs_refspecs config option:

gitfs_refspecs:
- '+refs/heads/*:refs/remotes/origin/*'
- '+refs/tags/*:refs/tags/*'
- '+refs/pull/*/head:refs/remotes/origin/pr/*'
- '+refs/pull/*/merge:refs/remotes/origin/merge/*'

In the above example, in addition to fetching remote branches and tags,
GitHub's custom refs for pull requests and merged pull requests will
also be fetched. These special head refs represent the head of the
branch which is requesting to be merged, and the merge refs represent
the result of the base branch after the merge.

IMPORTANT:
When using custom refspecs, the destination of the fetched refs must
be under refs/remotes/origin/, preferably in a subdirectory like in
the example above. These custom refspecs will map as environment
names using their relative path underneath refs/remotes/origin/. For
example, assuming the configuration above, the head branch for pull
request 12345 would map to fileserver environment pr/12345 (slash
included).

Refspecs can be configured on a per-remote basis. For example, the be-
low configuration would only alter the default refspecs for the second
GitFS remote. The first remote would only fetch branches and tags (the
default).

gitfs_remotes:
- https://domain.tld/foo.git
- https://domain.tld/bar.git:
- refspecs:
- '+refs/heads/*:refs/remotes/origin/*'
- '+refs/tags/*:refs/tags/*'
- '+refs/pull/*/head:refs/remotes/origin/pr/*'
- '+refs/pull/*/merge:refs/remotes/origin/merge/*'

Global Remotes
New in version 2018.3.0: for all_saltenvs, 3001 for fallback

The all_saltenvs per-remote configuration parameter overrides the logic
Salt uses to map branches/tags to fileserver environments (i.e.
saltenvs). This allows a single branch/tag to appear in all GitFS
saltenvs.

NOTE:
all_saltenvs only works within GitFS. That is, files in a branch
configured using all_saltenvs will not show up in a fileserver envi-
ronment defined via some other fileserver backend (e.g.
file_roots).

The fallback global or per-remote configuration can also be used.

This is very useful in particular when working with salt formulas.
Prior to the addition of this feature, it was necessary to push a
branch/tag to the remote repo for each saltenv in which that formula
was to be used. If the formula needed to be updated, this update would
need to be reflected in all of the other branches/tags. This is both
inconvenient and not scalable.

With all_saltenvs, it is now possible to define your formula once, in a
single branch.

gitfs_remotes:
- http://foo.com/quux.git:
- all_saltenvs: anything

If you want to also test working branches of the formula repository,
use fallback:

gitfs_remotes:
- http://foo.com/quux.git:
- fallback: anything

Update Intervals
Prior to the 2018.3.0 release, GitFS would update its fileserver back-
ends as part of a dedicated "maintenance" process, in which various
routine maintenance tasks were performed. This tied the update interval
to the loop_interval config option, and also forced all fileservers to
update at the same interval.

Now it is possible to make GitFS update at its own interval, using
gitfs_update_interval:

gitfs_update_interval: 180

gitfs_remotes:
- https://foo.com/foo.git
- https://foo.com/bar.git:
- update_interval: 120

Using the above configuration, the first remote would update every
three minutes, while the second remote would update every two minutes.

Configuration Order of Precedence
The order of precedence for GitFS configuration is as follows (each
level overrides all levels below it):

1. Per-saltenv configuration (defined under a per-remote saltenv param)

gitfs_remotes:
- https://foo.com/bar.git:
- saltenv:
- dev:
- mountpoint: salt://bar

2. Global per-saltenv configuration (defined in gitfs_saltenv)

gitfs_saltenv:
- dev:
- mountpoint: salt://bar

3. Per-remote configuration parameter

gitfs_remotes:
- https://foo.com/bar.git:
- mountpoint: salt://bar

4. Global configuration parameter

gitfs_mountpoint: salt://bar

NOTE:
The one exception to the above is when all_saltenvs is used. This
value overrides all logic for mapping branches/tags to fileserver
environments. So, even if gitfs_saltenv is used to globally override
the mapping for a given saltenv, all_saltenvs would take precedence
for any remote which uses it.

It's important to note however that any root and mountpoint values
configured in gitfs_saltenv (or per-saltenv configuration) would be
unaffected by this.

Serving from a Subdirectory
The gitfs_root parameter allows files to be served from a subdirectory
within the repository. This allows for only part of a repository to be
exposed to the Salt fileserver.

Assume the below layout:

.gitignore
README.txt
foo/
foo/bar/
foo/bar/one.txt
foo/bar/two.txt
foo/bar/three.txt
foo/baz/
foo/baz/top.sls
foo/baz/edit/vim.sls
foo/baz/edit/vimrc
foo/baz/nginx/init.sls

The below configuration would serve only the files under foo/baz, ig-
noring the other files in the repository:

gitfs_remotes:
- git://mydomain.com/stuff.git

gitfs_root: foo/baz

The root can also be configured on a per-remote basis.

Mountpoints
New in version 2014.7.0.

The gitfs_mountpoint parameter will prepend the specified path to the
files served from gitfs. This allows an existing repository to be used,
rather than needing to reorganize a repository or design it around the
layout of the Salt fileserver.

Before the addition of this feature, if a file being served up via
gitfs was deeply nested within the root directory (for example,
salt://webapps/foo/files/foo.conf, it would be necessary to ensure that
the file was properly located in the remote repository, and that all of
the parent directories were present (for example, the directories we-
bapps/foo/files/ would need to exist at the root of the repository).

The below example would allow for a file foo.conf at the root of the
repository to be served up from the Salt fileserver path salt://we-
bapps/foo/files/foo.conf.

gitfs_remotes:
- https://mydomain.com/stuff.git

gitfs_mountpoint: salt://webapps/foo/files

Mountpoints can also be configured on a per-remote basis.

Using gitfs in Masterless Mode
Since 2014.7.0, gitfs can be used in masterless mode. To do so, simply
add the gitfs configuration parameters (and set fileserver_backend) in
the _minion_ config file instead of the master config file.

Using gitfs Alongside Other Backends
Sometimes it may make sense to use multiple backends; for instance, if
sls files are stored in git but larger files are stored directly on the
master.

The cascading lookup logic used for multiple remotes is also used with
multiple backends. If the fileserver_backend option contains multiple
backends:

fileserver_backend:
- roots
- git

Then the roots backend (the default backend of files in /usr/lo-
cal/etc/salt/states) will be searched first for the requested file;
then, if it is not found on the master, each configured git remote will
be searched.

NOTE:
This can be used together with file_roots accepting __env__ as a
catch-all environment, since 2018.3.5 and 2019.2.1:

file_roots:
base:
- /usr/local/etc/salt/states
__env__:
- /usr/local/etc/salt/states

Branches, Environments, and Top Files
When using the GitFS backend, branches, and tags will be mapped to en-
vironments using the branch/tag name as an identifier.

There is one exception to this rule: the master branch is implicitly
mapped to the base environment.

So, for a typical base, qa, dev setup, the following branches could be
used:

master
qa
dev

top.sls files from different branches will be merged into one at run-
time. Since this can lead to overly complex configurations, the recom-
mended setup is to have a separate repository, containing only the
top.sls file with just one single master branch.

To map a branch other than master as the base environment, use the
gitfs_base parameter.

gitfs_base: salt-base

The base can also be configured on a per-remote basis.

Environment Whitelist/Blacklist
New in version 2014.7.0.

The gitfs_saltenv_whitelist and gitfs_saltenv_blacklist parameters al-
low for greater control over which branches/tags are exposed as file-
server environments. Exact matches, globs, and regular expressions are
supported, and are evaluated in that order. If using a regular expres-
sion, ^ and $ must be omitted, and the expression must match the entire
branch/tag.

gitfs_saltenv_whitelist:
- base
- v1.*
- 'mybranch\d+'

NOTE:
v1.*, in this example, will match as both a glob and a regular ex-
pression (though it will have been matched as a glob, since globs
are evaluated before regular expressions).

The behavior of the blacklist/whitelist will differ depending on which
combination of the two options is used:

o If only gitfs_saltenv_whitelist is used, then only branches/tags
which match the whitelist will be available as environments

o If only gitfs_saltenv_blacklist is used, then the branches/tags which
match the blacklist will not be available as environments

o If both are used, then the branches/tags which match the whitelist,
but do not match the blacklist, will be available as environments.

Authentication
pygit2
New in version 2014.7.0.

Both HTTPS and SSH authentication are supported as of version 0.20.3,
which is the earliest version of pygit2 supported by Salt for gitfs.

NOTE:
The examples below make use of per-remote configuration parameters,
a feature new to Salt 2014.7.0. More information on these can be
found here.

HTTPS
For HTTPS repositories which require authentication, the username and
password can be provided like so:

gitfs_remotes:
- https://domain.tld/myrepo.git:
- user: git
- password: mypassword

If the repository is served over HTTP instead of HTTPS, then Salt will
by default refuse to authenticate to it. This behavior can be overrid-
den by adding an insecure_auth parameter:

gitfs_remotes:
- http://domain.tld/insecure_repo.git:
- user: git
- password: mypassword
- insecure_auth: True

SSH
SSH repositories can be configured using the ssh:// protocol designa-
tion, or using scp-like syntax. So, the following two configurations
are equivalent:

o ssh://git@github.com/user/repo.git

o git@github.com:user/repo.git

Both gitfs_pubkey and gitfs_privkey (or their per-remote counterparts)
must be configured in order to authenticate to SSH-based repos. If the
private key is protected with a passphrase, it can be configured using
gitfs_passphrase (or simply passphrase if being configured per-remote).
For example:

gitfs_remotes:
- git@github.com:user/repo.git:
- pubkey: /root/.ssh/id_rsa.pub
- privkey: /root/.ssh/id_rsa
- passphrase: myawesomepassphrase

Finally, the SSH host key must be added to the known_hosts file.

NOTE:
There is a known issue with public-key SSH authentication to Micro-
soft Visual Studio (VSTS) with pygit2. This is due to a bug or lack
of support for VSTS in older libssh2 releases. Known working re-
leases include libssh2 1.7.0 and later, and known incompatible re-
leases include 1.5.0 and older. At the time of this writing, 1.6.0
has not been tested.

Since upgrading libssh2 would require rebuilding many other packages
(curl, etc.), followed by a rebuild of libgit2 and a reinstall of
pygit2, an easier workaround for systems with older libssh2 is to
use GitPython with a passphraseless key for authentication.

GitPython
HTTPS
For HTTPS repositories which require authentication, the username and
password can be configured in one of two ways. The first way is to in-
clude them in the URL using the format https://<user>:<password>@<url>,
like so:

gitfs_remotes:
- https://git:mypassword@domain.tld/myrepo.git

The other way would be to configure the authentication in ~/.netrc:

machine domain.tld
login git
password mypassword

If the repository is served over HTTP instead of HTTPS, then Salt will
by default refuse to authenticate to it. This behavior can be overrid-
den by adding an insecure_auth parameter:

gitfs_remotes:
- http://git:mypassword@domain.tld/insecure_repo.git:
- insecure_auth: True

SSH
Only passphrase-less SSH public key authentication is supported using
GitPython. The auth parameters (pubkey, privkey, etc.) shown in the py-
git2 authentication examples above do not work with GitPython.

gitfs_remotes:
- ssh://git@github.com/example/salt-states.git

Since GitPython wraps the git CLI, the private key must be located in
~/.ssh/id_rsa for the user under which the Master is running, and
should have permissions of 0600. Also, in the absence of a user in the
repo URL, GitPython will (just as SSH does) attempt to login as the
current user (in other words, the user under which the Master is run-
ning, usually root).

If a key needs to be used, then ~/.ssh/config can be configured to use
the desired key. Information on how to do this can be found by viewing
the manpage for ssh_config. Here's an example entry which can be added
to the ~/.ssh/config to use an alternate key for gitfs:

Host github.com
IdentityFile /root/.ssh/id_rsa_gitfs

The Host parameter should be a hostname (or hostname glob) that matches
the domain name of the git repository.

It is also necessary to add the SSH host key to the known_hosts file.
The exception to this would be if strict host key checking is disabled,
which can be done by adding StrictHostKeyChecking no to the entry in
~/.ssh/config

Host github.com
IdentityFile /root/.ssh/id_rsa_gitfs
StrictHostKeyChecking no

However, this is generally regarded as insecure, and is not recom-
mended.

Adding the SSH Host Key to the known_hosts File
To use SSH authentication, it is necessary to have the remote reposi-
tory's SSH host key in the ~/.ssh/known_hosts file. If the master is
also a minion, this can be done using the ssh.set_known_host function:

# salt mymaster ssh.set_known_host user=root hostname=github.com
mymaster:
----------
new:
----------
enc:
ssh-rsa
fingerprint:
16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48
hostname:
|1|OiefWWqOD4kwO3BhoIGa0loR5AA=|BIXVtmcTbPER+68HvXmceodDcfI=
key:
AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
old:
None
status:
updated

If not, then the easiest way to add the key is to su to the user (usu-
ally root) under which the salt-master runs and attempt to login to the
server via SSH:

$ su -
Password:
# ssh github.com
The authenticity of host 'github.com (192.30.252.128)' can't be established.
RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'github.com,192.30.252.128' (RSA) to the list of known hosts.
Permission denied (publickey).

It doesn't matter if the login was successful, as answering yes will
write the fingerprint to the known_hosts file.

Verifying the Fingerprint
To verify that the correct fingerprint was added, it is a good idea to
look it up. One way to do this is to use nmap:

$ nmap -p 22 github.com --script ssh-hostkey

Starting Nmap 5.51 ( http://nmap.org ) at 2014-08-18 17:47 CDT
Nmap scan report for github.com (192.30.252.129)
Host is up (0.17s latency).
Not shown: 996 filtered ports
PORT STATE SERVICE
22/tcp open ssh
| ssh-hostkey: 1024 ad:1c:08:a4:40:e3:6f:9c:f5:66:26:5d:4b:33:5d:8c (DSA)
|_2048 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48 (RSA)
80/tcp open http
443/tcp open https
9418/tcp open git

Nmap done: 1 IP address (1 host up) scanned in 28.78 seconds

Another way is to check one's own known_hosts file, using this
one-liner:

$ ssh-keygen -l -f /dev/stdin <<<`ssh-keyscan github.com 2>/dev/null` | awk '{print $2}'
16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48

WARNING:
AWS tracks usage of nmap and may flag it as abuse. On AWS hosts, the
ssh-keygen method is recommended for host key verification.

NOTE:
As of OpenSSH 6.8 the SSH fingerprint is now shown as a base64-en-
coded SHA256 checksum of the host key. So, instead of the finger-
print looking like 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48,
it would look like SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCAR-
LviKw6E5SY8.

Refreshing gitfs Upon Push
By default, Salt updates the remote fileserver backends every 60 sec-
onds. However, if it is desirable to refresh quicker than that, the
Reactor System can be used to signal the master to update the file-
server on each push, provided that the git server is also a Salt min-
ion. There are three steps to this process:

1. On the master, create a file /srv/reactor/update_fileserver.sls,
with the following contents:

update_fileserver:
runner.fileserver.update

2. Add the following reactor configuration to the master config file:

reactor:
- 'salt/fileserver/gitfs/update':
- /srv/reactor/update_fileserver.sls

3. On the git server, add a post-receive hook

a. If the user executing git push is the same as the minion user,
use the following hook:

#!/usr/bin/env sh
salt-call event.fire_master update salt/fileserver/gitfs/update

b. To enable other git users to run the hook after a push, use sudo
in the hook script:

#!/usr/bin/env sh
sudo -u root salt-call event.fire_master update salt/fileserver/gitfs/update

4. If using sudo in the git hook (above), the policy must be changed to
permit all users to fire the event. Add the following policy to the
sudoers file on the git server.

Cmnd_Alias SALT_GIT_HOOK = /bin/salt-call event.fire_master update salt/fileserver/gitfs/update
Defaults!SALT_GIT_HOOK !requiretty
ALL ALL=(root) NOPASSWD: SALT_GIT_HOOK

The update argument right after event.fire_master in this example can
really be anything, as it represents the data being passed in the
event, and the passed data is ignored by this reactor.

Similarly, the tag name salt/fileserver/gitfs/update can be replaced by
anything, so long as the usage is consistent.

The root user name in the hook script and sudo policy should be changed
to match the user under which the minion is running.

Using Git as an External Pillar Source
The git external pillar (a.k.a. git_pillar) has been rewritten for the
2015.8.0 release. This rewrite brings with it pygit2 support (allowing
for access to authenticated repositories), as well as more granular
support for per-remote configuration. This configuration schema is de-
tailed here.

Why aren't my custom modules/states/etc. syncing to my Minions?
In versions 0.16.3 and older, when using the git fileserver backend,
certain versions of GitPython may generate errors when fetching, which
Salt fails to catch. While not fatal to the fetch process, these inter-
rupt the fileserver update that takes place before custom types are
synced, and thus interrupt the sync itself. Try disabling the git file-
server backend in the master config, restarting the master, and at-
tempting the sync again.

This issue is worked around in Salt 0.16.4 and newer.

MinionFS Backend Walkthrough
New in version 2014.1.0.

NOTE:
This walkthrough assumes basic knowledge of Salt and cp.push. To get
up to speed, check out the Salt Walkthrough.

Sometimes it is desirable to deploy a file located on one minion to one
or more other minions. This is supported in Salt, and can be accom-
plished in two parts:

1. Minion support for pushing files to the master (using cp.push)

2. The minionfs fileserver backend

This walkthrough will show how to use both of these features.

Enabling File Push
To set the master to accept files pushed from minions, the file_recv
option in the master config file must be set to True (the default is
False).

file_recv: True

NOTE:
This change requires a restart of the salt-master service.

Pushing Files
Once this has been done, files can be pushed to the master using the
cp.push function:

salt 'minion-id' cp.push /path/to/the/file

This command will store the file in a subdirectory named minions under
the master's cachedir. On most masters, this path will be
/var/cache/salt/master/minions. Within this directory will be one di-
rectory for each minion which has pushed a file to the master, and un-
derneath that the full path to the file on the minion. So, for example,
if a minion with an ID of dev1 pushed a file /var/log/myapp.log to the
master, it would be saved to /var/cache/salt/master/min-
ions/dev1/var/log/myapp.log.

Serving Pushed Files Using MinionFS
While it is certainly possible to add /var/cache/salt/master/minions to
the master's file_roots and serve these files, it may only be desirable
to expose files pushed from certain minions. Adding
/var/cache/salt/master/minions/<minion-id> for each minion that needs
to be exposed can be cumbersome and prone to errors.

Enter minionfs. This fileserver backend will make files pushed using
cp.push available to the Salt fileserver, and provides an easy mecha-
nism to restrict which minions' pushed files are made available.

Simple Configuration
To use the minionfs backend, add minionfs to the list of backends in
the fileserver_backend configuration option on the master:

file_recv: True

fileserver_backend:
- roots
- minionfs

NOTE:
minion also works here. Prior to the 2018.3.0 release, only minion
would work.

Also, as described earlier, file_recv: True is needed to enable the
master to receive files pushed from minions. As always, changes to
the master configuration require a restart of the salt-master ser-
vice.

Files made available via minionfs are by default located at
salt://<minion-id>/path/to/file. Think back to the earlier example, in
which dev1 pushed a file /var/log/myapp.log to the master. With min-
ionfs enabled, this file would be addressable in Salt at
salt://dev1/var/log/myapp.log.

If many minions have pushed to the master, this will result in many di-
rectories in the root of the Salt fileserver. For this reason, it is
recommended to use the minionfs_mountpoint config option to organize
these files underneath a subdirectory:

minionfs_mountpoint: salt://minionfs

Using the above mountpoint, the file in the example would be located at
salt://minionfs/dev1/var/log/myapp.log.

Restricting Certain Minions' Files from Being Available Via MinionFS
A whitelist and blacklist can be used to restrict the minions whose
pushed files are available via minionfs. These lists can be managed us-
ing the minionfs_whitelist and minionfs_blacklist config options. Click
the links for both of them for a detailed explanation of how to use
them.

A more complex configuration example, which uses both a whitelist and
blacklist, can be found below:

file_recv: True

fileserver_backend:
- roots
- minionfs

minionfs_mountpoint: salt://minionfs

minionfs_whitelist:
- host04
- web*
- 'mail\d+\.domain\.tld'

minionfs_blacklist:
- web21

Potential Concerns
o There is no access control in place to restrict which minions have
access to files served up by minionfs. All minions will have access
to these files.

o Unless the minionfs_whitelist and/or minionfs_blacklist config op-
tions are used, all minions which push files to the master will have
their files made available via minionfs.

Salt Package Manager
The Salt Package Manager, or SPM, enables Salt formulas to be packaged
to simplify distribution to Salt masters. The design of SPM was influ-
enced by other existing packaging systems including RPM, Yum, and Pac-
man. [image]

NOTE:
The previous diagram shows each SPM component as a different system,
but this is not required. You can build packages and host the SPM
repo on a single Salt master if you'd like.

Packaging System

The packaging system is used to package the state, pillar, file tem-
plates, and other files used by your formula into a single file. After
a formula package is created, it is copied to the Repository System
where it is made available to Salt masters.

See Building SPM Packages

Repo System

The Repo system stores the SPM package and metadata files and makes
them available to Salt masters via http(s), ftp, or file URLs. SPM
repositories can be hosted on a Salt Master, a Salt Minion, or on an-
other system.

See Distributing SPM Packages

Salt Master

SPM provides Salt master settings that let you configure the URL of one
or more SPM repos. You can then quickly install packages that contain
entire formulas to your Salt masters using SPM.

See Installing SPM Packages

Contents

Building SPM Packages
The first step when using Salt Package Manager is to build packages for
each of of the formulas that you want to distribute. Packages can be
built on any system where you can install Salt.

Package Build Overview
To build a package, all state, pillar, jinja, and file templates used
by your formula are assembled into a folder on the build system. These
files can be cloned from a Git repository, such as those found at the
saltstack-formulas organization on GitHub, or copied directly to the
folder.

The following diagram demonstrates a typical formula layout on the
build system: [image]

In this example, all formula files are placed in a myapp-formula
folder. This is the folder that is targeted by the spm build command
when this package is built.

Within this folder, pillar data is placed in a pillar.example file at
the root, and all state, jinja, and template files are placed within a
subfolder that is named after the application being packaged. State
files are typically contained within a subfolder, similar to how state
files are organized in the state tree. Any non-pillar files in your
package that are not contained in a subfolder are placed at the root of
the spm state tree.

Additionally, a FORMULA file is created and placed in the root of the
folder. This file contains package metadata that is used by SPM.

Package Installation Overview
When building packages, it is useful to know where files are installed
on the Salt master. During installation, all files except pillar.exam-
ple and FORMULA are copied directly to the spm state tree on the Salt
master (located at \srv\spm\salt).

If a pillar.example file is present in the root, it is renamed to <for-
mula name>.sls.orig and placed in the pillar_path. [image]

NOTE:
Even though the pillar data file is copied to the pillar root, you
still need to manually assign this pillar data to systems using the
pillar top file. This file can also be duplicated and renamed so the
.orig version is left intact in case you need to restore it later.

Building an SPM Formula Package
1. Assemble formula files in a folder on the build system.

2. Create a FORMULA file and place it in the root of the package
folder.

3. Run spm build <folder name>. The package is built and placed in the
/srv/spm_build folder.

spm build /path/to/salt-packages-source/myapp-formula

4. Copy the .spm file to a folder on the repository system.

Types of Packages
SPM supports different types of packages. The function of each package
is denoted by its name. For instance, packages which end in -formula
are considered to be Salt States (the most common type of formula).
Packages which end in -conf contain configuration which is to be placed
in the /usr/local/etc/salt/ directory. Packages which do not contain
one of these names are treated as if they have a -formula name.

formula
By default, most files from this type of package live in the
/srv/spm/salt/ directory. The exception is the pillar.example file,
which will be renamed to <package_name>.sls and placed in the pillar
directory (/srv/spm/pillar/ by default).

reactor
By default, files from this type of package live in the /srv/spm/reac-
tor/ directory.

conf
The files in this type of package are configuration files for Salt,
which normally live in the /usr/local/etc/salt/ directory. Configura-
tion files for packages other than Salt can and should be handled with
a Salt State (using a formula type of package).

Technical Information
Packages are built using BZ2-compressed tarballs. By default, the pack-
age database is stored using the sqlite3 driver (see Loader Modules be-
low).

Support for these are built into Python, and so no external dependen-
cies are needed.

All other files belonging to SPM use YAML, for portability and ease of
use and maintainability.

SPM-Specific Loader Modules
SPM was designed to behave like traditional package managers, which ap-
ply files to the filesystem and store package metadata in a local data-
base. However, because modern infrastructures often extend beyond those
use cases, certain parts of SPM have been broken out into their own set
of modules.

Package Database
By default, the package database is stored using the sqlite3 module.
This module was chosen because support for SQLite3 is built into Python
itself.

Please see the SPM Development Guide for information on creating new
modules for package database management.

Package Files
By default, package files are installed using the local module. This
module applies files to the local filesystem, on the machine that the
package is installed on.

Please see the SPM Development Guide for information on creating new
modules for package file management.

Distributing SPM Packages
SPM packages can be distributed to Salt masters over HTTP(S), FTP, or
through the file system. The SPM repo can be hosted on any system where
you can install Salt. Salt is installed so you can run the spm cre-
ate_repo command when you update or add a package to the repo. SPM re-
pos do not require the salt-master, salt-minion, or any other process
running on the system.

NOTE:
If you are hosting the SPM repo on a system where you can not or do
not want to install Salt, you can run the spm create_repo command on
the build system and then copy the packages and the generated
SPM-METADATA file to the repo. You can also install SPM files di-
rectly on a Salt master, bypassing the repository completely.

Setting up a Package Repository
After packages are built, the generated SPM files are placed in the
srv/spm_build folder.

Where you place the built SPM files on your repository server depends
on how you plan to make them available to your Salt masters.

You can share the srv/spm_build folder on the network, or copy the
files to your FTP or Web server.

Adding a Package to the repository
New packages are added by simply copying the SPM file to the repo
folder, and then generating repo metadata.

Generate Repo Metadata
Each time you update or add an SPM package to your repository, issue an
spm create_repo command:

spm create_repo /srv/spm_build

SPM generates the repository metadata for all of the packages in that
directory and places it in an SPM-METADATA file at the folder root.
This command is used even if repository metadata already exists in that
directory.

Installing SPM Packages
SPM packages are installed to your Salt master, where they are avail-
able to Salt minions using all of Salt's package management functions.

Configuring Remote Repositories
Before SPM can use a repository, two things need to happen. First, the
Salt master needs to know where the repository is through a configura-
tion process. Then it needs to pull down the repository metadata.

Repository Configuration Files
Repositories are configured by adding each of them to the /usr/lo-
cal/etc/salt/spm.repos.d/spm.repo file on each Salt master. This file
contains the name of the repository, and the link to the repository:

my_repo:
url: https://spm.example.com/

For HTTP/HTTPS Basic authorization you can define credentials:

my_repo:
url: https://spm.example.com/
username: user
password: pass

Beware of unauthorized access to this file, please set at least 0640
permissions for this configuration file:

The URL can use http, https, ftp, or file.

my_repo:
url: file:///srv/spm_build

Updating Local Repository Metadata
After the repository is configured on the Salt master, repository meta-
data is downloaded using the spm update_repo command:

spm update_repo

NOTE:
A file for each repo is placed in /var/cache/salt/spm on the Salt
master after you run the update_repo command. If you add a reposi-
tory and it does not seem to be showing up, check this path to ver-
ify that the repository was found.

Update File Roots
SPM packages are installed to the srv/spm/salt folder on your Salt mas-
ter. This path needs to be added to the file roots on your Salt master
manually.

file_roots:
base:
1. /usr/local/etc/salt/states
2. /srv/spm/salt

Restart the salt-master service after updating the file_roots setting.

Installing Packages
To install a package, use the spm install command:

spm install apache

WARNING:
Currently, SPM does not check to see if files are already in place
before installing them. That means that existing files will be over-
written without warning.

Installing directly from an SPM file
You can also install SPM packages using a local SPM file using the spm
local install command:

spm local install /srv/spm/apache-201506-1.spm

An SPM repository is not required when using spm local install.

Pillars
If an installed package includes Pillar data, be sure to target the in-
stalled pillar to the necessary systems using the pillar Top file.

Removing Packages
Packages may be removed after they are installed using the spm remove
command.

spm remove apache

If files have been modified, they will not be removed. Empty directo-
ries will also be removed.

SPM Configuration
There are a number of options that are specific to SPM. They may be
configured in the master configuration file, or in SPM's own spm con-
figuration file (normally located at /usr/local/etc/salt/spm). If con-
figured in both places, the spm file takes precedence. In general,
these values will not need to be changed from the defaults.

spm_logfile
Default: /var/log/salt/spm

Where SPM logs messages.

spm_repos_config
Default: /usr/local/etc/salt/spm.repos

SPM repositories are configured with this file. There is also a direc-
tory which corresponds to it, which ends in .d. For instance, if the
filename is /usr/local/etc/salt/spm.repos, the directory will be
/etc/salt/spm.repos.d/.

spm_cache_dir
Default: /var/cache/salt/spm

When SPM updates package repository metadata and downloads packaged,
they will be placed in this directory. The package database, normally
called packages.db, also lives in this directory.

spm_db
Default: /var/cache/salt/spm/packages.db

The location and name of the package database. This database stores the
names of all of the SPM packages installed on the system, the files
that belong to them, and the metadata for those files.

spm_build_dir
Default: /srv/spm_build

When packages are built, they will be placed in this directory.

spm_build_exclude
Default: ['.git']

When SPM builds a package, it normally adds all files in the formula
directory to the package. Files listed here will be excluded from that
package. This option requires a list to be specified.

spm_build_exclude:
- .git
- .svn

Types of Packages
SPM supports different types of formula packages. The function of each
package is denoted by its name. For instance, packages which end in
-formula are considered to be Salt States (the most common type of for-
mula). Packages which end in -conf contain configuration which is to be
placed in the /usr/local/etc/salt/ directory. Packages which do not
contain one of these names are treated as if they have a -formula name.

reactor
By default, files from this type of package live in the /srv/spm/reac-
tor/ directory.

FORMULA File
In addition to the formula itself, a FORMULA file must exist which de-
scribes the package. An example of this file is:

name: apache
os: RedHat, Debian, Ubuntu, SUSE, FreeBSD
os_family: RedHat, Debian, Suse, FreeBSD
version: 201506
release: 2
summary: Formula for installing Apache
description: Formula for installing Apache

Required Fields
This file must contain at least the following fields:

name
The name of the package, as it will appear in the package filename, in
the repository metadata, and the package database. Even if the source
formula has -formula in its name, this name should probably not include
that. For instance, when packaging the apache-formula, the name should
be set to apache.

os
The value of the os grain that this formula supports. This is used to
help users know which operating systems can support this package.

os_family
The value of the os_family grain that this formula supports. This is
used to help users know which operating system families can support
this package.

version
The version of the package. While it is up to the organization that
manages this package, it is suggested that this version is specified in
a YYYYMM format. For instance, if this version was released in June
2015, the package version should be 201506. If multiple releases are
made in a month, the release field should be used.

minimum_version
Minimum recommended version of Salt to use this formula. Not currently
enforced.

release
This field refers primarily to a release of a version, but also to mul-
tiple versions within a month. In general, if a version has been made
public, and immediate updates need to be made to it, this field should
also be updated.

summary
A one-line description of the package.

description
A more detailed description of the package which can contain more than
one line.

Optional Fields
The following fields may also be present.

top_level_dir
This field is optional, but highly recommended. If it is not specified,
the package name will be used.

Formula repositories typically do not store .sls files in the root of
the repository; instead they are stored in a subdirectory. For in-
stance, an apache-formula repository would contain a directory called
apache, which would contain an init.sls, plus a number of other related
files. In this instance, the top_level_dir should be set to apache.

Files outside the top_level_dir, such as README.rst, FORMULA, and LI-
CENSE will not be installed. The exceptions to this rule are files that
are already treated specially, such as pillar.example and _modules/.

dependencies
A comma-separated list of packages that must be installed along with
this package. When this package is installed, SPM will attempt to dis-
cover and install these packages as well. If it is unable to, then it
will refuse to install this package.

This is useful for creating packages which tie together other packages.
For instance, a package called wordpress-mariadb-apache would depend
upon wordpress, mariadb, and apache.

optional
A comma-separated list of packages which are related to this package,
but are neither required nor necessarily recommended. This list is dis-
played in an informational message when the package is installed to
SPM.

recommended
A comma-separated list of optional packages that are recommended to be
installed with the package. This list is displayed in an informational
message when the package is installed to SPM.

files
A files section can be added, to specify a list of files to add to the
SPM. Such a section might look like:

files:
- _pillar
- FORMULA
- _runners
- d|mymodule/index.rst
- r|README.rst

When files are specified, then only those files will be added to the
SPM, regardless of what other files exist in the directory. They will
also be added in the order specified, which is useful if you have a
need to lay down files in a specific order.

As can be seen in the example above, you may also tag files as being a
specific type. This is done by pre-pending a filename with its type,
followed by a pipe (|) character. The above example contains a document
file and a readme. The available file types are:

o c: config file

o d: documentation file

o g: ghost file (i.e. the file contents are not included in the package
payload)

o l: license file

o r: readme file

o s: SLS file

o m: Salt module

The first 5 of these types (c, d, g, l, r) will be placed in
/usr/share/salt/spm/ by default. This can be changed by setting an
spm_share_dir value in your /usr/local/etc/salt/spm configuration file.

The last two types (s and m) are currently ignored, but they are re-
served for future use.

Pre and Post States
It is possible to run Salt states before and after installing a package
by using pre and post states. The following sections may be declared in
a FORMULA:

o pre_local_state

o pre_tgt_state

o post_local_state

o post_tgt_state

Sections with pre in their name are evaluated before a package is in-
stalled and sections with post are evaluated after a package is in-
stalled. local states are evaluated before tgt states.

Each of these sections needs to be evaluated as text, rather than as
YAML. Consider the following block:

pre_local_state: >
echo test > /tmp/spmtest:
cmd:
- run

Note that this declaration uses > after pre_local_state. This is a YAML
marker that marks the next multi-line block as text, including new-
lines. It is important to use this marker whenever declaring pre or
post states, so that the text following it can be evaluated properly.

local States
local states are evaluated locally; this is analogous to issuing a
state run using a salt-call --local command. These commands will be is-
sued on the local machine running the spm command, whether that machine
is a master or a minion.

local states do not require any special arguments, but they must still
use the > marker to denote that the state is evaluated as text, not a
data structure.

pre_local_state: >
echo test > /tmp/spmtest:
cmd:
- run

tgt States
tgt states are issued against a remote target. This is analogous to is-
suing a state using the salt command. As such it requires that the ma-
chine that the spm command is running on is a master.

Because tgt states require that a target be specified, their code
blocks are a little different. Consider the following state:

pre_tgt_state:
tgt: '*'
data: >
echo test > /tmp/spmtest:
cmd:
- run

With tgt states, the state data is placed under a data section, inside
the *_tgt_state code block. The target is of course specified as a tgt
and you may also optionally specify a tgt_type (the default is glob).

You still need to use the > marker, but this time it follows the data
line, rather than the *_tgt_state line.

Templating States
The reason that state data must be evaluated as text rather than a data
structure is because that state data is first processed through the
rendering engine, as it would be with a standard state run.

This means that you can use Jinja or any other supported renderer in-
side of Salt. All formula variables are available to the renderer, so
you can reference FORMULA data inside your state if you need to:

pre_tgt_state:
tgt: '*'
data: >
echo {{ name }} > /tmp/spmtest:
cmd:
- run

You may also declare your own variables inside the FORMULA. If SPM
doesn't recognize them then it will ignore them, so there are no re-
strictions on variable names, outside of avoiding reserved words.

By default the renderer is set to jinja|yaml. You may change this by
changing the renderer setting in the FORMULA itself.

Building a Package
Once a FORMULA file has been created, it is placed into the root of the
formula that is to be turned into a package. The spm build command is
used to turn that formula into a package:

spm build /path/to/saltstack-formulas/apache-formula

The resulting file will be placed in the build directory. By default
this directory is located at /srv/spm/.

Loader Modules
When an execution module is placed in <file_roots>/_modules/ on the
master, it will automatically be synced to minions, the next time a
sync operation takes place. Other modules are also propagated this way:
state modules can be placed in _states/, and so on.

When SPM detects a file in a package which resides in one of these di-
rectories, that directory will be placed in <file_roots> instead of in
the formula directory with the rest of the files.

Removing Packages
Packages may be removed once they are installed using the spm remove
command.