Ubuntu Manpage: salt - Salt Documentation

NAME

       salt - Salt Documentation

SALT PROJECT

· Latest Salt Documentation

· Open an issue (bug report, feature request, etc.)

Salt is the world’s fastest, most intelligent and scalable automation engine.

About Salt
Built on python, Salt uses simple and human-readable YAML combined with event-driven
automation to deploy and configure complex IT systems. In addition to leveling-up vRealize
Automation SaltStack Config, Salt can be found under the hood of products from Juniper,
Cisco, Cloudflare, Nutanix, SUSE, and Tieto, to name a few.

About SaltStack
SaltStack was acquired by VMware in 2020. Salt Project remains an open source ecosystem
that VMware supports and contributes to.

Download Salt
Salt is tested and packaged to run on CentOS, Debian, RHEL, Ubuntu, MacOS, Windows, and
more. Download Salt and get started now.

· https://repo.saltproject.io/

· Installation Instructions

Salt Project Documentation
Installation instructions, getting started guides, in-depth API documentation, and
contributing to Salt.

· Getting Started with Salt

· Latest Salt Documentation

· Salt’s Contributor Guide

Security Advisories
Keep an eye on the Salt Project Security Announcements landing page. Salt Project
recommends subscribing to the Salt Project Security RSS feed to receive notification when
new information is available regarding security announcements.

Other channels to receive security announcements include the Salt Community mailing list
and the Salt Project Community Slack.

Responsibly Reporting Security Vulnerabilities
When reporting security vulnerabilities for Salt or other SaltStack projects, refer to the
SECURITY.md file found in this repository.

Engage the Salt Project and The Community
Please be sure to review our Code of Conduct. Also, check out some of our community
resources including:

· Salt Project Community Wiki

· Salt Project Community Slack

· Salt Project: IRC on LiberaChat

· Salt Project YouTube channel

· Salt Project Twitch channel

There are lots of ways to get involved in our community. Every month, there are around a
dozen opportunities to meet with other contributors and the Salt Core team and collaborate
in real time. The best way to keep track is by subscribing to the Salt Project Community
Events Calendar on the main https://saltproject.io website.

If you have additional questions, email us at saltproject@vmware.com or reach out directly
to the Community Manager, Janae Andrus via Slack. We’d be glad to have you join our
community!

License
Salt is licensed under the Apache 2.0 license. Please see the LICENSE file for the full
text of the Apache license, followed by a full summary of the licensing used by external
modules.

A complete list of attributions and dependencies can be found here: salt/DEPENDENCIES.md

INTRODUCTION TO SALT

We’re not just talking about NaCl.

The 30 second summary
Salt is:

· A configuration management system. Salt is capable of maintaining remote nodes in
defined states. For example, it can ensure that specific packages are installed and that
specific services are running.

· A distributed remote execution system used to execute commands and query data on remote
nodes. Salt can query and execute commands either 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 maintain, 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
centers. 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:

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

· use a secure and encrypted protocol

· use the smallest and fastest network payloads possible

· provide a simple programming interface

Salt also introduces more granular controls to the realm of remote execution, 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
encryption 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 executions can be sent back to the master
server, or to any arbitrary program. 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 target 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 deliciousness 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 mailing list is hosted by Google Groups. It
is open to new members.

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

IRC
The #salt IRC channel is hosted on the popular LiberaChat network. You can use the
LiberaChat 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 Enhancement 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:

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

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

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

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

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

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

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

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

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

SALT SYSTEM ARCHITECTURE

Overview
This page provides a high-level overview of the Salt system architecture and its different
components.

What is Salt?
Salt is a Python-based open-source remote execution framework used for:

· Configuration management

· Automation

· Provisioning

· Orchestration

The Salt system architecture
The following diagram shows the primary components of the basic Salt architecture: [image]

The following sections describe some of the core components of the Salt architecture.

Salt Masters and Salt Minions
Salt uses the master-client model in which a master issues commands to a client and the
client executes the command. In the Salt ecosystem, the Salt Master is a server that is
running the salt-master service. It issues commands to one or more Salt Minions, which are
servers that are running the salt-minion service and that are registered with that
particular Salt Master.

Another way to describe Salt is as a publisher-subscriber model. The master publishes jobs
that need to be executed and Salt Minions subscribe to those jobs. When a specific job
applies to that minion, it will execute the job.

When a minion finishes executing a job, it sends job return data back to the master. Salt
has two ports used by default for the minions to communicate with their master(s). These
ports work in concert to receive and deliver data to the Message Bus. Salt’s message bus
is ZeroMQ, which creates an asynchronous network topology to provide the fastest
communication possible.

Targets and grains
The master indicates which minions should execute the job by defining a target. A target
is the group of minions, across one or many masters, that a job's Salt command applies to.

NOTE:
A master can also be managed like a minion and can be a target if it is running the
salt-minion service.

The following is an example of one of the many kinds of commands that a master might issue
to a minion. This command indicates that all minions should install the Vim application:

salt -v '*' pkg.install vim

In this case the glob '*' is the target, which indicates that all minions should execute
this command. Many other targeting options are available, including targeting a specific
minion by its ID or targeting minions by their shared traits or characteristics (called
grains in Salt).

Salt comes with an interface to derive information about the underlying system. This is
called the grains interface, because it presents Salt with grains of information. Grains
are collected for the operating system, domain name, IP address, kernel, OS type, memory,
and many other system properties. You can also create your own custom grain data.

Grain data is relatively static. However, grain data is refreshed when system information
changes (such as network settings) or when a new value is assigned to a custom grain.

Open event system (event bus)
The event system is used for inter-process communication between the Salt Master and Salt
Minions. In the event system:

· Events are seen by both the master and minions.

· Events can be monitored and evaluated by both.

The event bus lays the groundwork for orchestration and real-time monitoring.

All minions see jobs and results by subscribing to events published on the event system.
Salt uses a pluggable event system with two layers:

· ZeroMQ (0MQ) - The current default socket-level library providing a flexible transport
layer.

· Tornado - Full TCP-based transport layer event system.

One of the greatest strengths of Salt is the speed of execution. The event system’s
communication bus is more efficient than running a higher-level web service (http). The
remote execution system is the component that all components are built upon, allowing for
decentralized remote execution to spread load across resources.

Salt states
In addition to remote execution, Salt provides another method for configuring minions by
declaring which state a minion should be in, otherwise referred to as Salt states. Salt
states make configuration management possible. You can use Salt states to deploy and
manage infrastructure with simple YAML files. Using states, you can automate recursive
and predictable tasks by queueing jobs for Salt to implement without needing user input.
You can also add more complex conditional logic to state files with Jinja.

To illustrate the subtle differences between remote execution and configuration
management, take the command referenced in the previous section about Targets and grains
in which Salt installed the application Vim on all minions:

┌─────────────────────────┬──────────────────────────┬──────────────────────────┐
│Methodology │ Implementation │ Result │
├─────────────────────────┼──────────────────────────┼──────────────────────────┤
│Remote execution │ │ │
│ │ · Run salt -v '*' │ · Remotely │
│ │ pkg.install vim │ installs Vim on │
│ │ from the │ the targeted │
│ │ terminal │ minions │
├─────────────────────────┼──────────────────────────┼──────────────────────────┤
│Configuration management │ │ │
│ │ · Write a YAML │ · Ensures that │
│ │ state file that │ Vim is always │
│ │ checks whether │ installed on │
│ │ Vim is │ the targeted │
│ │ installed │ minions │
│ │ │ │
│ │ · This state file │ · Salt analyzes │
│ │ is then applied │ the state file │
│ │ to the targeted │ and determines │
│ │ minions │ what actions │
│ │ │ need to be │
│ │ │ taken to ensure │
│ │ │ the minion │
│ │ │ complies with │
│ │ │ the state │
│ │ │ declarations │
│ │ │ │
│ │ │ · If Vim is not │
│ │ │ installed, it │
│ │ │ automates the │
│ │ │ processes to │
│ │ │ install Vim on │
│ │ │ the targeted │
│ │ │ minions │
└─────────────────────────┴──────────────────────────┴──────────────────────────┘

The state file that verifies Vim is installed might look like the following example:

# File:/srv/salt/vim_install.sls

install_vim_now:
pkg.installed:
- pkgs:
- vim

To apply this state to a minion, you would use the state.apply module, such as in the
following example:

salt '*' state.apply vim_install

This command applies the vim_install state to all minions.

Formulas are collections of states that work in harmony to configure a minion or
application. For example, one state might trigger another state.

The Top file
It is not practical to manually run each state individually targeting specific minions
each time. Some environments have hundreds of state files targeting thousands of minions.

Salt offers two features to help with this scaling problem:

· The top.sls file - Maps Salt states to their applicable minions.

· Highstate execution - Runs all Salt states outlined in top.sls in a single execution.

The top file maps which states should be applied to different minions in certain
environments. The following is an example of a simple top file:

# File: /srv/salt/top.sls

base:
'*':
- all_server_setup

'01webserver':
- web_server_setup

In this example, base refers to the Salt environment, which is the default. You can
specify more than one environment as needed, such as prod, dev, QA, etc.

Groups of minions are specified under the environment, and states are listed for each set
of minions. This top file indicates that a state called all_server_setup should be applied
to all minions '*' and the state called web_server_setup should be applied to the
01webserver minion.

To run the Salt command, you would use the state.highstate function:

salt \* state.highstate

This command applies the top file to the targeted minions.

Salt pillar
Salt’s pillar feature takes data defined on the Salt Master and distributes it to minions
as needed. Pillar is primarily used to store secrets or other highly sensitive data, such
as account credentials, cryptographic keys, or passwords. Pillar is also useful for
storing non-secret data that you don't want to place directly in your state files, such as
configuration data.

Salt pillar brings data into the cluster from the opposite direction as grains. While
grains are data generated from the minion, the pillar is data generated from the master.

Pillars are organized similarly to states in a Pillar state tree, where top.sls acts to
coordinate pillar data to environments and minions privy to the data. Information
transferred using pillar has a dictionary generated for the targeted minion and encrypted
with that minion’s key for secure data transfer. Pillar data is encrypted on a per-minion
basis, which makes it useful for storing sensitive data specific to a particular minion.

Beacons and reactors
The beacon system is a monitoring tool that can listen for a variety of system processes
on Salt Minions. Beacons can trigger reactors which can then help implement a change or
troubleshoot an issue. For example, if a service’s response times out, the reactor system
can restart the service.

Beacons are used for a variety of purposes, including:

· Automated reporting

· Error log delivery

· Microservice monitoring

· User shell activity

· Resource monitoring

When coupled with reactors, beacons can create automated pre-written responses to
infrastructure and application issues. Reactors expand Salt with automated responses using
pre-written remediation states.

Reactors can be applied in a variety of scenarios:

· Infrastructure scaling

· Notifying administrators

· Restarting failed applications

· Automatic rollback

When both beacons and reactors are used together , you can create unique states customized
to your specific needs.

Salt runners and orchestration
Salt runners are convenience applications executed with the salt-run command. Salt runners
work similarly to Salt execution modules. However, they execute on the Salt Master instead
of the Salt Minions. A Salt runner can be a simple client call or a complex application.

Salt provides the ability to orchestrate system administrative tasks throughout the
enterprise. Orchestration makes it possible to coordinate the activities of multiple
machines from a central place. It has the added advantage of being able to control the
sequence of when certain configuration events occur. Orchestration states execute on the
master using the state runner module.

INSTALLATION

This section contains instructions to install Salt. If you are setting up your environment
for the first time, you should install a Salt master on a dedicated management server or
VM, and then install a Salt minion on each system that you want to manage using Salt. For
now you don't need to worry about your architecture, you can easily add components and
modify your configuration later without needing to reinstall anything.

The general installation process is as follows:

1. Install a Salt master using the instructions for your platform or by running the Salt
bootstrap script. If you use the bootstrap script, be sure to include the -M option to
install the Salt master.

2. Make sure that your Salt minions can find the Salt master.

3. Install the Salt minion on each system that you want to manage.

4. Accept the Salt minion keys after the Salt minion connects.

After this, you should be able to run a simple command and receive salt version returns
from all connected Salt minions.

salt '*' test.version

Quick Install
On most distributions, you can set up a Salt Minion with the Salt bootstrap.

Platform-specific Installation Instructions
These guides go into detail how to install Salt on a given platform.

Arch Linux
Installation
Salt (stable) is currently available via the Arch Linux Official repositories. There are
currently -git packages available in the Arch User repositories (AUR) as well.

Stable Release
Install Salt stable releases from the Arch Linux Official repositories as follows:

pacman -S salt

Tracking develop
To install the bleeding edge version of Salt (may include bugs!), use the -git package.
Installing the -git package as follows:

wget https://aur.archlinux.org/packages/sa/salt-git/salt-git.tar.gz
tar xf salt-git.tar.gz
cd salt-git/
makepkg -is

NOTE:
yaourt

If a tool such as Yaourt is used, the dependencies will be gathered and built
automatically.

The command to install salt using the yaourt tool is:

yaourt salt-git

Post-installation tasks
systemd

Activate the Salt Master and/or Minion via systemctl as follows:

systemctl enable salt-master.service
systemctl enable salt-minion.service

Start the Master

Once you've completed all of these steps you're ready to start your Salt Master. You
should be able to start your Salt Master now using the command seen here:

systemctl start salt-master

Now go to the Configuring Salt page.

Debian GNU/Linux / Raspbian
Debian GNU/Linux distribution and some derivatives such as Raspbian already have included
Salt packages to their repositories. However, current stable Debian release contains old
outdated Salt releases. It is recommended to use SaltStack repository for Debian as
described below.

Installation from official Debian and Raspbian repositories is described here.

Installation from the Official SaltStack Repository
Packages for Debian 10 (Buster) and Debian 9 (Stretch) are available in the Official
SaltStack repository.

Instructions are at https://repo.saltproject.io/#debian.

NOTE:
Archived builds from unsupported branches:

· Archive 1

· Archive 2

If looking to use archives, the same directions from the Debian install directions can
be used by replacing the URL paths with the appropriate archive location. The
repository configuration endpoint also needs to be adjusted to point to the archives.
Here is an example sed command:

# Salt repo configurations are found in the /etc/apt/sources.list.d/salt.list directory
sed -i 's/repo.saltproject.io/archive.repo.saltproject.io/g' /etc/apt/sources.list.d/salt.list

WARNING:
Regular security support for Debian 8 ended on June 30th 2018. As a result, 3000.3 and
2019.2.5 will be the last Salt releases for which Debian 8 packages are created. Debian
8 also reached LTS EOL on June 30 2020.

Regular security support for Debian 7 ended on April 25th 2016. As a result, 2016.3.1
and 2015.8.10 will be the last Salt releases for which Debian 7 packages are created.
Debian 7 also reached LTS EOL on May 31 2018.

Installation from the Debian / Raspbian Official Repository
The Debian distributions contain mostly old Salt packages built by the Debian Salt Team.
You can install Salt components directly from Debian but it is recommended to use the
instructions above for the packages from the official Salt repository.

On Jessie there is an option to install Salt minion from Stretch with python-tornado
dependency from jessie-backports repositories.

To install fresh release of Salt minion on Jessie:

1. Add jessie-backports and stretch repositories:

Debian:

echo 'deb http://httpredir.debian.org/debian jessie-backports main' >> /etc/apt/sources.list
echo 'deb http://httpredir.debian.org/debian stretch main' >> /etc/apt/sources.list

Raspbian:

echo 'deb http://archive.raspbian.org/raspbian/ stretch main' >> /etc/apt/sources.list

2. Make Jessie a default release:

echo 'APT::Default-Release "jessie";' > /etc/apt/apt.conf.d/10apt

3. Install Salt dependencies:

Debian:

apt-get update
apt-get install python-zmq python-systemd/jessie-backports python-tornado/jessie-backports salt-common/stretch

Raspbian:

apt-get update
apt-get install python-zmq python-tornado/stretch salt-common/stretch

4. Install Salt minion package from Latest Debian Release:

apt-get install salt-minion/stretch

Install Packages
Install the Salt master, minion or other packages from the repository with the apt-get
command. These examples each install one of Salt components, but more than one package
name may be given at a time:

· apt-get install salt-api

· apt-get install salt-cloud

· apt-get install salt-master

· apt-get install salt-minion

· apt-get install salt-ssh

· apt-get install salt-syndic

Post-installation tasks
Now, go to the Configuring Salt page.

Arista EOS Salt minion installation guide
The Salt minion for Arista EOS is distributed as a SWIX extension and can be installed
directly on the switch. The EOS network operating system is based on old Fedora
distributions and the installation of the salt-minion requires backports. This SWIX
extension contains the necessary backports, together with the Salt basecode.

NOTE:
This SWIX extension has been tested on Arista DCS-7280SE-68-R, running EOS 4.17.5M and
vEOS 4.18.3F.

Important Notes
This package is in beta, make sure to test it carefully before running it in production.

If confirmed working correctly, please report and add a note on this page with the
platform model and EOS version.

If you want to uninstall this package, please refer to the uninstalling section.

Installation from the Official SaltStack Repository
Download the swix package and save it to flash.

veos#copy https://salt-eos.netops.life/salt-eos-latest.swix flash:
veos#copy https://salt-eos.netops.life/startup.sh flash:

Install the Extension
Copy the Salt package to extension

veos#copy flash:salt-eos-latest.swix extension:

Install the SWIX

veos#extension salt-eos-latest.swix force

Verify the installation

veos#show extensions | include salt-eos
salt-eos-2017-07-19.swix 1.0.11/1.fc25 A, F 27

Change the Salt master IP address or FQDN, by edit the variable (SALT_MASTER)

veos#bash vi /mnt/flash/startup.sh

Make sure you enable the eAPI with unix-socket

veos(config)#management api http-commands
protocol unix-socket
no shutdown

Post-installation tasks
Generate Keys and host record and start Salt minion

veos#bash
#sudo /mnt/flash/startup.sh

salt-minion should be running

Copy the installed extensions to boot-extensions

veos#copy installed-extensions boot-extensions

Apply event-handler to let EOS start salt-minion during boot-up

veos(config)#event-handler boot-up-script
trigger on-boot
action bash sudo /mnt/flash/startup.sh

For more specific installation details of the salt-minion, please refer to Configuring
Salt.

Uninstalling
If you decide to uninstall this package, the following steps are recommended for safety:

1. Remove the extension from boot-extensions

veos#bash rm /mnt/flash/boot-extensions

2. Remove the extension from extensions folder

veos#bash rm /mnt/flash/.extensions/salt-eos-latest.swix

2. Remove boot-up script

veos(config)#no event-handler boot-up-script

Additional Information
This SWIX extension contains the following RPM packages:

libsodium-1.0.11-1.fc25.i686.rpm
libstdc++-6.2.1-2.fc25.i686.rpm
openpgm-5.2.122-6.fc24.i686.rpm
python-Jinja2-2.8-0.i686.rpm
python-PyYAML-3.12-0.i686.rpm
python-babel-0.9.6-5.fc18.noarch.rpm
python-backports-1.0-3.fc18.i686.rpm
python-backports-ssl_match_hostname-3.4.0.2-1.fc18.noarch.rpm
python-backports_abc-0.5-0.i686.rpm
python-certifi-2016.9.26-0.i686.rpm
python-chardet-2.0.1-5.fc18.noarch.rpm
python-crypto-1.4.1-1.noarch.rpm
python-crypto-2.6.1-1.fc18.i686.rpm
python-futures-3.1.1-1.noarch.rpm
python-jtextfsm-0.3.1-0.noarch.rpm
python-kitchen-1.1.1-2.fc18.noarch.rpm
python-markupsafe-0.18-1.fc18.i686.rpm
python-msgpack-python-0.4.8-0.i686.rpm
python-napalm-base-0.24.3-1.noarch.rpm
python-napalm-eos-0.6.0-1.noarch.rpm
python-netaddr-0.7.18-0.noarch.rpm
python-pyeapi-0.7.0-0.noarch.rpm
python-salt-2017.7.0_1414_g2fb986f-1.noarch.rpm
python-singledispatch-3.4.0.3-0.i686.rpm
python-six-1.10.0-0.i686.rpm
python-tornado-4.4.2-0.i686.rpm
python-urllib3-1.5-7.fc18.noarch.rpm
python2-zmq-15.3.0-2.fc25.i686.rpm
zeromq-4.1.4-5.fc25.i686.rpm

Fedora
Beginning with version 0.9.4, Salt has been available in the primary Fedora repositories
and EPEL. It is installable using yum or dnf, depending on your version of Fedora.

NOTE:
Released versions of Salt starting with 2015.5.2 through 2016.3.2 do not have Fedora
packages available though EPEL. To install a version of Salt within this release array,
please use SaltStack's Bootstrap Script and use the git method of installing Salt using
the version's associated release tag.

Release 2016.3.3 and onward will have packaged versions available via EPEL.

WARNING: Fedora 19 comes with systemd 204. Systemd has known bugs fixed in later
revisions that prevent the salt-master from starting reliably or opening the network
connections that it needs to. It's not likely that a salt-master will start or run
reliably on any distribution that uses systemd version 204 or earlier. Running
salt-minions should be OK.

Installation
Salt can be installed using yum and is available in the standard Fedora repositories.

Stable Release
Salt is packaged separately for the minion and the master. It is necessary only to install
the appropriate package for the role the machine will play. Typically, there will be one
master and multiple minions.

yum install salt-master
yum install salt-minion

Installing from updates-testing
When a new Salt release is packaged, it is first admitted into the updates-testing
repository, before being moved to the stable repo.

To install from updates-testing, use the enablerepo argument for yum:

yum --enablerepo=updates-testing install salt-master
yum --enablerepo=updates-testing install salt-minion

Installation Using pip
Since Salt is on PyPI, it can be installed using pip, though most users prefer to install
using a package manager.

Installing from pip has a few additional requirements:

· Install the group 'Development Tools', dnf groupinstall 'Development Tools'

· Install the 'zeromq-devel' package if it fails on linking against that afterwards as
well.

A pip install does not make the init scripts or the /etc/salt directory, and you will need
to provide your own systemd service unit.

Installation from pip:

pip install salt

WARNING:
If installing from pip (or from source using setup.py install), be advised that the
yum-utils package is needed for Salt to manage packages. Also, if the Python
dependencies are not already installed, then you will need additional libraries/tools
installed to build some of them. More information on this can be found here.

Post-installation tasks
Master

To have the Master start automatically at boot time:

systemctl enable salt-master.service

To start the Master:

systemctl start salt-master.service

Minion

To have the Minion start automatically at boot time:

systemctl enable salt-minion.service

To start the Minion:

systemctl start salt-minion.service

Now go to the Configuring Salt page.

FreeBSD
Installation
Salt is available in the FreeBSD ports tree at sysutils/py-salt.

FreeBSD binary repo
Install Salt on FreeBSD via the official package repository. Salt is packaged with
whichever Python version is currently the default on FreeBSD.

Python 3.8 is currently default, install from packages like this:

pkg install py38-salt

FreeBSD ports
Installation from ports:

cd /usr/ports/sysutils/py-salt
make install

Python 3.7 can be used by setting default Python version to 3.7:

echo "DEFAULT_VERSIONS+= python=3.7" >> /etc/make.conf

Post-installation tasks
rc.conf

Activate the Salt Master in /etc/rc.conf:

sysrc salt_master_enable="YES"

Start the Master

Start the Salt Master as follows:

service salt_master start

rc.conf

Activate the Salt Minion in /etc/rc.conf:

sysrc salt_minion_enable="YES"

Start the Minion

Start the Salt Minion as follows:

service salt_minion start

Now go to the Configuring Salt page.

Gentoo
Salt can be easily installed on Gentoo via Portage:

emerge app-admin/salt

Post-installation tasks
Now go to the Configuring Salt page.

Cisco Nexus Salt Minion Installation and Configuration Guide
This document describes the Salt Minion installation and configuration on Cisco Nexus
switches. These instructions detail the process for managing the Nexus switches using a
Proxy Minion or Native Minion on platforms that have GuestShell support.

Table of Contents
· Cisco Nexus Salt Minion Installation and Configuration Guide

· Pre-Install Tasks

· STEP 1: Verify Platform and Software Version Support

· STEP 2: Choose Salt Minion Type

· STEP 3: Network Connectivity

· Salt Proxy Minion Configuration

· Proxy Minion Pillar Data

· GuestShell Salt Minion Installation

· STEP 1a: Enable the Guestshell on low footprint N3ks

· STEP 1b: Enable the Guestshell

· STEP 2: Set Up Guestshell Network

· STEP 3: Install SaltStack Minion

· STEP 4: Configure SaltStack Minion

· GuestShell Salt Minion Persistence

· References

Pre-Install Tasks
STEP 1: Verify Platform and Software Version Support
The following platforms and software versions have been certified to work with this
version of Salt.

Platform / Software Minimum Requirements
┌────────────────┬──────────────────┬──────────────────┬──────────────────┬───────────────┐
│Supported │ Minimum NX-OS │ SSH Proxy Minion │ NX-API Proxy │ GuestShell │
│Platforms │ Version │ │ Minion │ Minion │
├────────────────┼──────────────────┼──────────────────┼──────────────────┼───────────────┤
│Cisco Nexus N3k │ 7.0(3)I2(5) and │ Supported │ Supported │ Supported │
│ │ later │ │ │ │
├────────────────┼──────────────────┼──────────────────┼──────────────────┼───────────────┤
│Cisco Nexus N9k │ 7.0(3)I2(5) and │ Supported │ Supported │ Supported │
│ │ later │ │ │ │
├────────────────┼──────────────────┼──────────────────┼──────────────────┼───────────────┤
│Cisco Nexus N6k │ 7.3(0)N1(1) and │ Supported │ Not Supported │ Not Supported │
│ │ later │ │ │ │
├────────────────┼──────────────────┼──────────────────┼──────────────────┼───────────────┤
│Cisco Nexus N7k │ 7.3(0)D1(1) and │ Supported │ Supported │ Not Supported │
│ │ later │ │ │ │
└────────────────┴──────────────────┴──────────────────┴──────────────────┴───────────────┘

Platform Models
┌─────────┬──────────────────────────────────┐
│Platform │ Description │
├─────────┼──────────────────────────────────┤
│N3k │ Support includes N30xx, N31xx, │
│ │ N32xx and N35xx models │
├─────────┼──────────────────────────────────┤
│N6k │ Support includes all N6xxx │
│ │ models │
└─────────┴──────────────────────────────────┘

│N7k │ Support includes all N7xxx │
│ │ models │
├─────────┼──────────────────────────────────┤
│N9k │ Support includes all N9xxx │
│ │ models │
└─────────┴──────────────────────────────────┘

STEP 2: Choose Salt Minion Type
Using the tables above, select the Salt Minion type.

Choices:

· SSH Proxy Minion (See Salt Proxy Minion Configuration Section)

· NX-API Proxy Minion (See Salt Proxy Minion Configuration Section)

GuestShell Native Minion (See GuestShell Salt Minion Installation Section)

· Some platforms support a native minion installed directly on the NX-OS
device inside the GuestShell

· The GuestShell is a secure Linux container environment running CentOS

STEP 3: Network Connectivity
Ensure that IP reachability exists between the NX-OS Salt Minion device and the SaltStack
Master.

Note: The management interface exists in a separate VRF context and requires additional
configuration as shown.

Example: Nexus CLI Configuration for connectivity via management interface

config term
vrf context management
ip name-server 10.0.0.202
ip domain-name mycompany.com
ip route 0.0.0.0/0 10.0.0.1

interface mgmt0
vrf member management
ip address 10.0.0.99/24

ntp server 10.0.0.201 use-vrf management
end

Salt Proxy Minion Configuration
Here is a sample Proxy Minion directory structure

saltmaster:/srv/pillar$tree
.
├── n3k-proxy.sls
├── n7k-proxy.sls
└── top.sls

This displays a top sls file and two proxy minion sls files for a Nexus 3k and Nexus 7k
device.

Sample contents for the top.sls file.

saltmaster:/srv/pillar$cat top.sls
base:
n3k-proxy:
- n3k-proxy
n7k-proxy:
- n7k-proxy

Proxy Minion Pillar Data
Here is a sample Proxy Minion pillar data file.

All of the data for both ssh and nxapi proxy minion types can be stored in the same pillar
data file. To choose ssh or nxapi, simply set the connection: parameter accordingly.

saltmaster:/srv/pillar$cat n7k-proxy.sls
proxy:
proxytype: nxos

# Specify ssh or nxapi connection type (default is ssh)
#connection: ssh
connection: nxapi

# Parameters Common to both SSH and NX-API
host: n7k.example.com
username: admin
password: password

# SSH Parameters
prompt_name: n7k
ssh_args: '-o PubkeyAuthentication=no'
key_accept: True

# NX-API Parameters
transport: https
port: 443
verify: False

# Option to prevent auto-save after each configuration command.
# Setting this to True will improve performance when using
# nxos execution module functions to configure the device.
no_save_config: True

· For the most current nxos proxy minion configuration options, See salt.proxy.nxos

· For the most current list of nxos execution module functions, See salt.modules.nxos

GuestShell Salt Minion Installation
This section is only required when running the SaltStack Minion from the guestshell.

STEP 1a: Enable the Guestshell on low footprint N3ks
NOTE: Skip down to STEP 1b if the target system is not a low footprint N3k.

Nexus 3xxx switches with 4 GB RAM and 1.6 GB bootflash are advised to use compacted images
to reduce the storage resources consumed by the image. As part of the compaction process,
the guestshell.ova is removed from the system image. To make use of the guestshell on
these systems, the guestshell.ova may be downloaded and used to install the guestshell.

Guestshell OVA Download Link

Starting in release 9.2(1) and onward, the .ova file can be copied to the volatile:
directory which frees up more space on bootflash:.

Copy the guestshell.ova file to volatile: if supported, otherwise copy it to bootflash:

n3xxx# copy scp://admin@1.2.3.4/guestshell.ova volatile: vrf management
guestshell.ova 100% 55MB 10.9MB/s 00:05
Copy complete, now saving to disk (please wait)...
Copy complete.

Use the guestshell enable command to install and enable guestshell.

n3xxx# guestshell enable package volatile:guestshell.ova

STEP 1b: Enable the Guestshell
The guestshell container environment is enabled by default on most platforms; however, the
default disk and memory resources allotted to guestshell are typically too small to
support SaltStack Minion requirements. The resource limits may be increased with the NX-OS
CLI guestshell resize commands as shown below.

Resource Requirements
┌─────────┬─────────────┐
│Resource │ Recommended │
├─────────┼─────────────┤
│Disk │ 1000 MB │
├─────────┼─────────────┤
│Memory │ 350 MB │
└─────────┴─────────────┘

show guestshell detail displays the current resource limits:

n3k# show guestshell detail
Virtual service guestshell+ detail
State : Activated
...
Resource reservation
Disk : 150 MB
Memory : 128 MB

guestshell resize rootfs sets disk size limits while guestshell resize memory sets memory
limits. The resize commands do not take effect until after the guestshell container is
(re)started by guestshell reboot or guestshell enable.

Example. Allocate resources for guestshell by setting new limits to 1000MB disk and 350MB
memory.

n3k# guestshell resize rootfs 1000
n3k# guestshell resize memory 350

n3k# guestshell reboot
Are you sure you want to reboot the guest shell? (y/n) [n] y

STEP 2: Set Up Guestshell Network
The guestshell is an independent CentOS container that does not inherit settings from
NX-OS.

· Use guestshell to enter the guestshell environment, then become root.

· Optional: Use chvrf to specify a vrf namespace; e.g. sudo chvrf management

n3k# guestshell

[guestshell@guestshell ~]$ sudo su - # Optional: sudo chvrf management
[root@guestshell guestshell]#

OPTIONAL: Add DNS Configuration

[root@guestshell guestshell]# cat >> /etc/resolv.conf << EOF
nameserver 10.0.0.202
domain mycompany.com
EOF

OPTIONAL: Define proxy server variables if needed to allow network access to SaltStack
package repositories

export http_proxy=http://proxy.yourdomain.com:<port>
export https_proxy=https://proxy.yourdomain.com:<port>

STEP 3: Install SaltStack Minion
Install the python3 and python3-pip packages.
[root@guestshell guestshell]# yum install python3 python3-pip

OPTIONAL: Upgrade the pip installer
[root@guestshell guestshell]# pip3 install --upgrade pip

Install the certifi python package.
[root@guestshell guestshell]# pip3 install certifi

The most current information on installing the SaltStack Minion in a CentOS 7 environment
can be found here

Information from the install guide is provided here for convenience.

Run the following commands to install the SaltStack repository and key:

[root@guestshell guestshell]# rpm --import https://repo.saltproject.io/py3/redhat/7/x86_64/latest/SALTSTACK-GPG-KEY.pub
[root@guestshell guestshell]# curl -fsSL https://repo.saltproject.io/py3/redhat/7/x86_64/latest.repo | tee /etc/yum.repos.d/salt.repo

Run the following command to force yum to revalidate the cache for each repository.
[root@guestshell guestshell]# yum clean expire-cache

Install the Salt Minion.
[root@guestshell guestshell]# yum install salt-minion

STEP 4: Configure SaltStack Minion
Make the following changes to the /etc/salt/minion configuration file in the NX-OS
GuestShell.

Change the master: directive to point to the SaltStack Master.

- #master: salt
+ master: saltmaster.example.com

Change the id: directive to easily identify the minion running in the GuestShell.

Example:

- #id: salt
+ id: n3k-guestshell-minion

Start the Minion in the Guestshell and accept the key on the SaltStack Master.
[root@guestshell ~]# systemctl start salt-minion

saltmaster: salt-key -L
Accepted Keys:
Denied Keys:
Unaccepted Keys:
n3k-guestshell-minion
Rejected Keys:

saltmaster: salt-key -A
The following keys are going to be accepted:
Unaccepted Keys:
n3k-guestshell-minion
Proceed? [n/Y] Y
Key for minion n3k-guestshell-minion accepted.

Ping the SaltStack Minion running in the Guestshell.

saltmaster: salt n3k-guestshell-minion nxos.ping
n3k-guestshell-minion:
True

GuestShell Salt Minion Persistence
This section documents SaltStack Minion persistence in the guestshell after system
restarts and high availability switchovers.

The guestshell container does not automatically sync filesystem changes from the active
processor to the standby processor. This means that SaltStack Minion installation files
and related file changes will not be present on the standby until they are manually synced
with the following NX-OS exec command:

guestshell sync

The guestshell environment uses systemd for service management. The SaltStack Minion
provides a generic systemd script when installed, but a slight modification as shown below
is needed for nodes that run Salt in the management (or other vrf) namespace:

--- /usr/lib/systemd/system/salt-minion.service.old
+++ /usr/lib/systemd/system/salt-minion.service
[Unit]
Description=The Salt Minion
Documentation=man:salt-minion(1) file:///usr/share/doc/salt/html/contents.html
https://docs.saltproject.io/en/latest/contents.html
After=network.target salt-master.service

[Service]
KillMode=process
Type=notify
NotifyAccess=all
LimitNOFILE=8192

- ExecStart=/usr/bin/salt-minion
+ ExecStart=/bin/nsenter --net=/var/run/netns/management -- /usr/bin/salt-minion

[Install]
WantedBy=multi-user.target

Change the pidfile: directive to point to the /run tmpfs location in the GuestShell.

- #pidfile: /var/run/salt-minion.pid
+ pidfile: /run/salt-minion.pid

Next, enable the SaltStack Minion systemd service (the enable command adds it to systemd
for autostarting on the next boot) and optionally start it now:

systemctl enable salt-minion
systemctl start salt-minion

References
Nexus Document References
┌───────────────┬──────────────────────────────────┐
│References │ Description │
├───────────────┼──────────────────────────────────┤
│GuestShell_N9k │ N9k Guestshell Programmability │
│ │ Guide │
├───────────────┼──────────────────────────────────┤
│GuestShell_N3k │ N3k Guestshell Programmability │
│ │ Guide │
└───────────────┴──────────────────────────────────┘

OpenBSD
Salt was added to the OpenBSD ports tree on Aug 10th 2013. It has been tested on OpenBSD
5.5 onwards.

Salt is dependent on the following additional ports. These will be installed as
dependencies of the sysutils/salt port:

devel/py3-progressbar
net/py3-msgpack
net/py3-zmq
security/py3-Cryptodome
security/py3-M2Crypto
sysutils/py3-distro
textproc/py3-MarkupSafe
textproc/py3-yaml
www/py3-jinja2
www/py3-requests

Installation
To install Salt from the OpenBSD package repo, use the command:

pkg_add salt

Post-installation tasks
Master

To have the Master start automatically at boot time:

rcctl enable salt_master

To start the Master:

rcctl start salt_master

Minion

To have the Minion start automatically at boot time:

rcctl enable salt_minion

To start the Minion:

rcctl start salt_minion

Now go to the Configuring Salt page.

macOS
Installation from the Official SaltStack Repository
Latest stable build from the selected branch:

The output of md5 <salt pkg> should match the contents of the corresponding md5 file.

NOTE:

· Earlier builds from supported branches

· Archived builds from unsupported branches

Installation from Homebrew
brew install saltstack

It should be noted that Homebrew explicitly discourages the use of sudo:
Homebrew is designed to work without using sudo. You can decide to use it but we
strongly recommend not to do so. If you have used sudo and run into a bug then it is
likely to be the cause. Please don’t file a bug report unless you can reproduce it
after reinstalling Homebrew from scratch without using sudo

Installation from MacPorts
Macports isolates its dependencies from the OS, and installs salt in /opt/local by
default, with config files under /opt/local/etc/salt. For best results, add /opt/local/bin
to your PATH.

sudo port install salt

Variants allow selection of python version used to run salt, defaulting to python27, but
also supporting python34, python35, and python36. To install salt with Python 3.6, use the
python36 variant, for example:

sudo port install salt @python36

Startup items (for master, minion, and rest-cherrypy API gateway, respectively) are
installed by subport targets. These will register launchd LaunchDaemons as
org.macports.salt-minion, for example, to trigger automatic startup of the salt-minion
through launchd. LaunchDaemons for salt can be started and stopped without reboot using
the macprots load and unload commands.

sudo port install salt-master salt-minion salt-api
sudo port load salt-master salt-minion salt-api

Installation from Pip
When only using the macOS system's pip, install this way:

sudo pip install salt

Salt-Master Customizations
NOTE:
Salt master on macOS is not tested or supported by SaltStack. See SaltStack Platform
Support for more information.

To run salt-master on macOS, sudo add this configuration option to the /etc/salt/master
file:

max_open_files: 8192

On versions previous to macOS 10.10 (Yosemite), increase the root user maxfiles limit:

sudo launchctl limit maxfiles 4096 8192

NOTE:
On macOS 10.10 (Yosemite) and higher, maxfiles should not be adjusted. The default
limits are sufficient in all but the most extreme scenarios. Overriding these values
with the setting below will cause system instability!

Now the salt-master should run without errors:

sudo salt-master --log-level=all

Post-installation tasks
Now go to the Configuring Salt page.

RHEL / CentOS / Scientific Linux / Amazon Linux / Oracle Linux
Salt should work properly with all mainstream derivatives of Red Hat Enterprise Linux,
including CentOS, Scientific Linux, Oracle Linux, and Amazon Linux. Report any bugs or
issues on the issue tracker.

Installation from the Official Salt Project Repository
Packages for Redhat, CentOS, and Amazon Linux are available in the Salt Project
Repository.

· Red Hat / CentOS

· Amazon Linux

NOTE:
Archived builds from unsupported branches:

Red Hat / CentOS

· Archive 1

· Archive 2

If looking to use archives, the same directions from the RHEL/CentOS install directions
can be used by replacing the URL paths with the appropriate archive location. The
repository configuration endpoint also needs to be adjusted to point to the archives.
Here is an example sed command:

# Salt repo configurations are found in the /etc/yum.repos.d/ directory
sed -i 's/repo.saltproject.io/archive.repo.saltproject.io/g' /etc/yum.repos.d/salt*.repo

Amazon Linux

· Archive 1

· Archive 2

If looking to use archives, the same directions from the Amazon install directions can
be used by replacing the URL paths with the appropriate archive location. The
repository configuration endpoint also needs to be adjusted to point to the archives.
Here is an example sed command:

# Salt repo configurations are found in the /etc/yum.repos.d/ directory
sed -i 's/repo.saltproject.io/archive.repo.saltproject.io/g' /etc/yum.repos.d/salt*.repo

NOTE:
As of 2015.8.0, EPEL repository is no longer required for installing on RHEL systems.
Salt Project repository provides all needed dependencies.

WARNING:
If installing on Red Hat Enterprise Linux 7 with disabled (not subscribed on) 'RHEL
Server Releases' or 'RHEL Server Optional Channel' repositories, append CentOS 7 GPG
key URL to Salt Project yum repository configuration to install required base packages:

[saltstack-repo]
name=Salt repo for Red Hat Enterprise Linux $releasever
baseurl=https://repo.saltproject.io/py3/redhat/$releasever/$basearch/latest
enabled=1
gpgcheck=1
gpgkey=https://repo.saltproject.io/py3/redhat/$releasever/$basearch/latest/SALTSTACK-GPG-KEY.pub
https://repo.saltproject.io/py3/redhat/$releasever/$basearch/latest/base/RPM-GPG-KEY-CentOS-7

NOTE:
systemd and systemd-python are required by Salt, but are not installed by the Red Hat 7
@base installation or by the Salt installation. These dependencies might need to be
installed before Salt.

Installation Using pip
Since Salt is on PyPI, it can be installed using pip, though most users prefer to install
using RPM packages (which can be installed by following the directions in the Salt
Repository).

Installing from pip has a few additional requirements:

· Install the group 'Development Tools', yum groupinstall 'Development Tools'

· Install the 'zeromq-devel' package if it fails on linking against that afterwards as
well.

A pip install does not make the init scripts or the /etc/salt directory, and you will need
to provide your own systemd service unit.

Installation from pip:

pip install salt

ZeroMQ 4
We recommend using ZeroMQ 4 where available. Salt Project provides ZeroMQ 4.3.1 and pyzmq
17.0.0 in the Salt Repository.

If this repository is added before Salt is installed, then installing either salt-master
or salt-minion will automatically pull in ZeroMQ 4.3.1, and additional steps to upgrade
ZeroMQ and pyzmq are unnecessary.

Package Management
Salt's interface to yum makes heavy use of the repoquery utility, from the yum-utils
package. If salt has been installed using pip, or a host is being managed using salt-ssh,
then as of version 2014.7.0 yum-utils will be installed automatically to satisfy this
dependency.

Post-installation tasks
Master
To have the Master start automatically at boot time:

RHEL/CentOS 7 and 8

systemctl enable salt-master.service

To start the Master:

RHEL/CentOS 7 and 8

systemctl start salt-master.service

Minion
To have the Minion start automatically at boot time:

RHEL/CentOS 7 and 8

systemctl enable salt-minion.service

To start the Minion:

RHEL/CentOS 7 and 8

systemctl start salt-minion.service

Now go to the Configuring Salt page.

Solaris
Salt is known to work on Solaris but community packages are unmaintained.

It is possible to install Salt on Solaris by using setuptools.

For example, to install the develop version of salt:

git clone https://github.com/saltstack/salt
cd salt
sudo python setup.py install --force

NOTE:
SaltStack does offer commercial support for Solaris which includes packages. Packages
can be found on the Downloads page of the Enterprise Installation Guide and are
downloadable with a SaltStack Enterprise account.

Ubuntu
Installation from the Official SaltStack Repository
Packages for Ubuntu 20.04 (Focal), Ubuntu 18.04 (Bionic), and Ubuntu 16 (Xenial) are
available in the SaltStack repository.

Instructions are at https://repo.saltproject.io/#ubuntu.

NOTE:
Archived builds from unsupported branches:

· Archive 1

· Archive 2

If looking to use archives, the same directions from the Ubuntu install directions can
be used by replacing the URL paths with the appropriate archive location. The
repository configuration endpoint also needs to be adjusted to point to the archives.
Here is an example sed command:

# Salt repo configurations are found in the /etc/apt/sources.list.d/salt.list directory
sed -i 's/repo.saltproject.io/archive.repo.saltproject.io/g' /etc/apt/sources.list.d/salt.list

· apt-get install salt-api

· apt-get install salt-cloud

· apt-get install salt-master

· apt-get install salt-minion

· apt-get install salt-ssh

· apt-get install salt-syndic

Post-installation tasks
Now go to the Configuring Salt page.

Windows
Salt has full support for running the Salt minion on Windows. You must connect Windows
Salt minions to a Salt master on a supported operating system to control your Salt
Minions.

Many of the standard Salt modules have been ported to work on Windows and many of the Salt
States currently work on Windows as well.

Installation from the Official SaltStack Repository
Latest stable build from the selected branch:

The output of md5sum <salt minion exe> should match the contents of the corresponding md5
file.

There are installers available for Python 3. Starting with Salt 3001, only Python 3 builds
of the Windows Salt Minion will be built. Python 2 builds exist for earlier Salt Minion
versions.

NOTE:

· Earlier builds from supported branches

Archived builds from unsupported branches:

· Archive 1

· Archive 2

NOTE:
The installation executable installs dependencies that the Salt minion requires.

The 64bit and 32bit installers have been tested on Windows 8.1, Windows Server 2012 R2,
Windows 10, Windows Server 2016, and Windows Server 2019. 32bit installers have only been
tested on 64bit systems. Please file a bug report on our GitHub repo if issues for other
platforms are found.

The installer will detect previous installations of Salt and ask if you would like to
remove them. Clicking OK will remove the Salt binaries and related files but leave any
existing config, cache, and PKI information.

Salt Minion Installation
If the system is missing the appropriate version of the Visual C++ Redistributable
(vcredist) the user will be prompted to install it. Click OK to install the vcredist.
Click Cancel to abort the installation without making modifications to the system.

If Salt is already installed on the system the user will be prompted to remove the
previous installation. Click OK to uninstall Salt without removing the configuration, PKI
information, or cached files. Click Cancel to abort the installation before making any
modifications to the system.

After the Welcome and the License Agreement, the installer asks for two bits of
information to configure the minion; the master hostname and the minion name. The
installer will update the minion config with these options.

If the installer finds an existing minion config file, these fields will be populated with
values from the existing config, but they will be grayed out. There will also be a
checkbox to use the existing config. If you continue, the existing config will be used. If
the checkbox is unchecked, default values are displayed and can be changed. If you
continue, the existing config file in c:\salt\conf will be removed along with the
c:\salt\conf\minion.d directory. The values entered will be used with the default config.

The final page allows you to start the minion service and optionally change its startup
type. By default, the minion is set to Automatic. You can change the minion start type to
Automatic (Delayed Start) by checking the 'Delayed Start' checkbox.

NOTE:
Highstates that require a reboot may fail after reboot because salt continues the
highstate before Windows has finished the booting process. This can be fixed by
changing the startup type to 'Automatic (Delayed Start)'. The drawback is that it may
increase the time it takes for the 'salt-minion' service to actually start.

The salt-minion service will appear in the Windows Service Manager and can be managed
there or from the command line like any other Windows service.

sc start salt-minion
net start salt-minion

Installation Prerequisites
Most Salt functionality should work just fine right out of the box. A few Salt modules
rely on PowerShell. The minimum version of PowerShell required for Salt is version 3. If
you intend to work with DSC then Powershell version 5 is the minimum.

Silent Installer Options
The installer can be run silently by providing the /S option at the command line. The
installer also accepts the following options for configuring the Salt Minion silently:

┌──────────────────────┬──────────────────────────────────┐
│Option │ Description │
├──────────────────────┼──────────────────────────────────┤
│/master= │ A string value to set the IP │
│ │ address or hostname of the │
│ │ master. Default value is 'salt'. │
│ │ You can pass a single master or │
│ │ a comma-separated list of │
│ │ masters. Setting the master │
│ │ will cause the installer to use │
│ │ the default config or a custom │
│ │ config if defined. │
├──────────────────────┼──────────────────────────────────┤
│/minion-name= │ A string value to set the minion │
│ │ name. Default value is │
│ │ 'hostname'. Setting the minion │
│ │ name causes the installer to use │
│ │ the default config or a custom │
│ │ config if defined. │
├──────────────────────┼──────────────────────────────────┤
│/start-minion= │ Either a 1 or 0. '1' will start │
│ │ the salt-minion service, '0' │
│ │ will not. Default is to start │
│ │ the service after installation. │
├──────────────────────┼──────────────────────────────────┤
│/start-minion-delayed │ Set the minion start type to │
│ │ Automatic (Delayed Start). │
├──────────────────────┼──────────────────────────────────┤
│/default-config │ Overwrite the existing config if │
│ │ present with the default config │
│ │ for salt. Default is to use the │
│ │ existing config if present. If │
│ │ /master and/or /minion-name is │
│ │ passed, those values will be │
│ │ used to update the new default │
│ │ config. │
└──────────────────────┴──────────────────────────────────┘

│/custom-config= │ A string value specifying the │
│ │ name of a custom config file in │
│ │ the same path as the installer │
│ │ or the full path to a custom │
│ │ config file. If /master and/or │
│ │ /minion-name is passed, those │
│ │ values will be used to update │
│ │ the new custom config. │
├──────────────────────┼──────────────────────────────────┤
│/S │ Runs the installation silently. │
│ │ Uses the above settings or the │
│ │ defaults. │
├──────────────────────┼──────────────────────────────────┤
│/? │ Displays command line help. │
└──────────────────────┴──────────────────────────────────┘

NOTE:
/start-service has been deprecated but will continue to function as expected for the
time being.

NOTE:
/default-config and /custom-config= will backup an existing config if found. A
timestamp and a .bak extension will be added. That includes the minion file and the
minion.d directory.

Here are some examples of using the silent installer:

# Install the Salt Minion
# Configure the minion and start the service

Salt-Minion-3001-Py3-AMD64-Setup.exe /S /master=yoursaltmaster /minion-name=yourminionname

# Install the Salt Minion
# Configure the minion but don't start the minion service

Salt-Minion-3001-Py3-AMD64-Setup.exe /S /master=yoursaltmaster /minion-name=yourminionname /start-minion=0

# Install the Salt Minion
# Configure the minion using a custom config and configuring multimaster

Salt-Minion-3001-Py3-AMD64-Setup.exe /S /custom-config=windows_minion /master=prod_master1,prod_master2

Running the Salt Minion on Windows as an Unprivileged User
Notes:

· These instructions were tested with Windows Server 2008 R2

· They are generalizable to any version of Windows that supports a salt-minion

Create the Unprivileged User that the Salt Minion will Run As
1. Click Start > Control Panel > User Accounts.

2. Click Add or remove user accounts.

3. Click Create new account.

4. Enter salt-user (or a name of your preference) in the New account name field.

5. Select the Standard user radio button.

6. Click the Create Account button.

7. Click on the newly created user account.

8. Click the Create a password link.

9. In the New password and Confirm new password fields, provide a password (e.g
"SuperSecretMinionPassword4Me!").

10. In the Type a password hint field, provide appropriate text (e.g. "My Salt Password").

11. Click the Create password button.

12. Close the Change an Account window.

Add the New User to the Access Control List for the Salt Folder
1. In a File Explorer window, browse to the path where Salt is installed (the default path
is C:\Salt).

2. Right-click on the Salt folder and select Properties.

3. Click on the Security tab.

4. Click the Edit button.

5. Click the Add button.

6. Type the name of your designated Salt user and click the OK button.

7. Check the box to Allow the Modify permission.

8. Click the OK button.

9. Click the OK button to close the Salt Properties window.

Update the Windows Service User for the salt-minion Service
1. Click Start > Administrative Tools > Services.

2. In the Services list, right-click on salt-minion and select Properties.

3. Click the Log On tab.

4. Click the This account radio button.

5. Provide the account credentials created in section A.

6. Click the OK button.

7. Click the OK button to the prompt confirming that the user has been granted the Log On
As A Service right.

8. Click the OK button to the prompt confirming that The new logon name will not take
effect until you stop and restart the service.

9. Right-Click on salt-minion and select Stop.

10. Right-Click on salt-minion and select Start.

Building and Developing on Windows
This document will explain how to set up a development environment for Salt on Windows.
The development environment allows you to work with the source code to customize or fix
bugs. It will also allow you to build your own installation.

There are several scripts to automate creating a Windows installer as well as setting up
an environment that facilitates developing and troubleshooting Salt code. They are located
in the pkg\windows directory in the Salt repo (here).

Scripts:
┌────────────────┬──────────────────────────────────┐
│Script │ Description │
├────────────────┼──────────────────────────────────┤
│build_env_2.ps1 │ A PowerShell script that sets up │
│ │ a Python 2 build environment │
├────────────────┼──────────────────────────────────┤
│build_env_3.ps1 │ A PowerShell script that sets up │
│ │ a Python 3 build environment │
└────────────────┴──────────────────────────────────┘

│build_pkg.bat │ A batch file that builds a │
│ │ Windows installer based on the │
│ │ contents of the C:\Python27 │
│ │ directory │
├────────────────┼──────────────────────────────────┤
│build.bat │ A batch file that fully │
│ │ automates the building of the │
│ │ Windows installer using the │
│ │ above two scripts │
└────────────────┴──────────────────────────────────┘

NOTE:
The build.bat and build_pkg.bat scripts both accept a parameter to specify the version
of Salt that will be displayed in the Windows installer. If no version is passed, the
version will be determined using git.

Both scripts also accept an additional parameter to specify the version of Python to
use. The default is 2.

Prerequisite Software
The only prerequisite is Git for Windows.

Create a Build Environment
1. Working Directory
Create a Salt-Dev directory on the root of C:. This will be our working directory.
Navigate to Salt-Dev and clone the Salt repo from GitHub.

Open a command line and type:

cd \
md Salt-Dev
cd Salt-Dev
git clone https://github.com/saltstack/salt

Go into the salt directory and checkout the version of salt to work with (2016.3 or
higher).

cd salt
git checkout 2017.7.2

2. Setup the Python Environment
Navigate to the pkg\windows directory and execute the build_env.ps1 PowerShell script.

cd pkg\windows
powershell -file build_env_2.ps1

NOTE:
You can also do this from Explorer by navigating to the pkg\windows directory, right
clicking the build_env_2.ps1 powershell script and selecting Run with PowerShell

This will download and install Python 2 with all the dependencies needed to develop and
build Salt.

NOTE:
If you get an error or the script fails to run you may need to change the execution
policy. Open a powershell window and type the following command:

Set-ExecutionPolicy RemoteSigned

3. Salt in Editable Mode
Editable mode allows you to more easily modify and test the source code. For more
information see the Pip documentation.

Navigate to the root of the salt directory and install Salt in editable mode with pip

cd \Salt-Dev\salt
pip install -e .

NOTE:
The . is important

NOTE:
If pip is not recognized, you may need to restart your shell to get the updated path

NOTE:
If pip is still not recognized make sure that the Python Scripts folder is in the
System %PATH%. (C:\Python2\Scripts)

4. Setup Salt Configuration
Salt requires a minion configuration file and a few other directories. The default config
file is named minion located in C:\salt\conf. The easiest way to set this up is to copy
the contents of the salt\pkg\windows\buildenv directory to C:\salt.

cd \
md salt
xcopy /s /e \Salt-Dev\salt\pkg\windows\buildenv\* \salt\

Now go into the C:\salt\conf directory and edit the minion config file named minion (no
extension). You need to configure the master and id parameters in this file. Edit the
following lines:

master: <ip or name of your master>
id: <name of your minion>

Create a Windows Installer
To create a Windows installer, follow steps 1 and 2 from Create a Build Environment above.
Then proceed to 3 below:

3. Install Salt
To create the installer for Window we install Salt using Python instead of pip. Navigate
to the root salt directory and install Salt.

cd \Salt-Dev\salt
python setup.py install

4. Create the Windows Installer
Navigate to the pkg\windows directory and run the build_pkg.bat with the build version
(2017.7.2) and the Python version as parameters.

cd pkg\windows
build_pkg.bat 2017.7.2 2
^^^^^^^^ ^
| |
# build version -- |
# python version ------

NOTE:
If no version is passed, the build_pkg.bat will guess the version number using git. If
the python version is not passed, the default is 2.

Creating a Windows Installer: Alternate Method (Easier)
Clone the Salt repo from GitHub into the directory of your choice. We're going to use
Salt-Dev.

cd \
md Salt-Dev
cd Salt-Dev
git clone https://github.com/saltstack/salt

Go into the salt directory and checkout the version of Salt you want to build.

cd salt
git checkout 2017.7.2

Then navigate to pkg\windows and run the build.bat script with the version you're
building.

cd pkg\windows
build.bat 2017.7.2 3
^^^^^^^^ ^
| |
# build version |
# python version --

This will install everything needed to build a Windows installer for Salt using Python 3.
The binary will be in the salt\pkg\windows\installer directory.

Testing the Salt minion
1. Create the directory C:\salt (if it doesn't exist already)

Copy the example conf and var directories from
pkg\windows\buildenv into C:\salt

3. Edit C:\salt\conf\minion

master: ipaddress or hostname of your salt-master

4. Start the salt-minion

cd C:\Python27\Scripts
python salt-minion -l debug

5. On the salt-master accept the new minion's key

sudo salt-key -A

This accepts all unaccepted keys. If you're concerned about security just accept the
key for this specific minion.

6. Test that your minion is responding
On the salt-master run:

sudo salt '*' test.version

You should get the following response: {'your minion hostname': True}

Packages Management Under Windows 2003
Windows Server 2003 and Windows XP have both reached End of Support. Though Salt is not
officially supported on operating systems that are EoL, some functionality may continue to
work.

On Windows Server 2003, you need to install optional component "WMI Windows Installer
Provider" to get a full list of installed packages. If you don't have this, salt-minion
can't report some installed software.

SUSE
Installation from the Official SaltStack Repository
The SaltStack Repository has packages available for the following platforms:

· SLES 11 SP4

· SLES 12 / SLES 12 SP1 through SP4

· SLES 15

· openSUSE Leap 15.0, 15.1, 42.2, 42.3

· openSUSE Tumbleweed

Instructions are at https://repo.saltproject.io/#suse.

Installation from the SUSE Repository
Since openSUSE 13.2, Salt has been available in the primary repositories. With the
release of SUSE manager 3 a new repository setup has been created. The new repo will by
systemsmanagement:saltstack, which is the source for newer stable packages. For backward
compatibility a linkpackage will be created to the old devel:language:python repo. All
development of suse packages will be done in systemsmanagement:saltstack:testing. This
will ensure that salt will be in mainline suse repo's, a stable release repo and a testing
repo for further enhancements.

Installation
Salt can be installed using zypper and is available in the standard openSUSE/SLES
repositories.

zypper install salt-master
zypper install salt-minion

Post-installation tasks openSUSE
Master

To have the Master start automatically at boot time:

systemctl enable salt-master.service

To start the Master:

systemctl start salt-master.service

Minion

To have the Minion start automatically at boot time:

systemctl enable salt-minion.service

To start the Minion:

systemctl start salt-minion.service

Post-installation tasks SLES
Master

To have the Master start automatically at boot time:

chkconfig salt-master on

To start the Master:

rcsalt-master start

Minion

To have the Minion start automatically at boot time:

chkconfig salt-minion on

To start the Minion:

rcsalt-minion start

Unstable Release
openSUSE
For openSUSE Leap or Tumbleweed systems, run the following as root:

zypper install salt salt-minion salt-master

SUSE Linux Enterprise
For SLES 15 and above run the following as root:

zypper install salt salt-minion salt-master

Now go to the Configuring Salt page.

Initial Configuration
Configuring Salt
Salt configuration is very simple. The default configuration for the master will work for
most installations and the only requirement for setting up a minion is to set the location
of the master in the minion configuration file.

The configuration files will be installed to /etc/salt and are named after the respective
components, /etc/salt/master, and /etc/salt/minion.

Master Configuration
By default the Salt master listens on ports 4505 and 4506 on all interfaces (0.0.0.0). To
bind Salt to a specific IP, redefine the "interface" directive in the master configuration
file, typically /etc/salt/master, as follows:

- #interface: 0.0.0.0
+ interface: 10.0.0.1

After updating the configuration file, restart the Salt master. See the master
configuration reference for more details about other configurable options.

Minion Configuration
Although there are many Salt Minion configuration options, configuring a Salt Minion is
very simple. By default a Salt Minion will try to connect to the DNS name "salt"; if the
Minion is able to resolve that name correctly, no configuration is needed.

If the DNS name "salt" does not resolve to point to the correct location of the Master,
redefine the "master" directive in the minion configuration file, typically
/etc/salt/minion, as follows:

- #master: salt
+ master: 10.0.0.1

After updating the configuration file, restart the Salt minion. See the minion
configuration reference for more details about other configurable options.

Proxy Minion Configuration
A proxy minion emulates the behaviour of a regular minion and inherits their options.

Similarly, the configuration file is /etc/salt/proxy and the proxy tries to connect to the
DNS name "salt".

In addition to the regular minion options, there are several proxy-specific - see the
proxy minion configuration reference.

Running Salt
1. Start the master in the foreground (to daemonize the process, pass the -d flag):

salt-master

2. Start the minion in the foreground (to daemonize the process, pass the -d flag):

salt-minion

Having trouble?

The simplest way to troubleshoot Salt is to run the master and minion in the
foreground with log level set to debug:

salt-master --log-level=debug

For information on salt's logging system please see the logging document.

Run as an unprivileged (non-root) user

To run Salt as another user, set the user parameter in the master config file.

Additionally, ownership, and permissions need to be set such that the desired
user can read from and write to the following directories (and their
subdirectories, where applicable):

· /etc/salt

· /var/cache/salt

· /var/log/salt

· /var/run/salt

More information about running salt as a non-privileged user can be found here.

There is also a full troubleshooting guide available.

Key Identity
Salt provides commands to validate the identity of your Salt master and Salt minions
before the initial key exchange. Validating key identity helps avoid inadvertently
connecting to the wrong Salt master, and helps prevent a potential MiTM attack when
establishing the initial connection.

Master Key Fingerprint
Print the master key fingerprint by running the following command on the Salt master:

salt-key -F master

Copy the master.pub fingerprint from the Local Keys section, and then set this value as
the master_finger in the minion configuration file. Save the configuration file and then
restart the Salt minion.

Minion Key Fingerprint
Run the following command on each Salt minion to view the minion key fingerprint:

salt-call --local key.finger

Compare this value to the value that is displayed when you run the salt-key --finger
<MINION_ID> command on the Salt master.

Key Management
Salt uses AES encryption for all communication between the Master and the Minion. This
ensures that the commands sent to the Minions cannot be tampered with, and that
communication between Master and Minion is authenticated through trusted, accepted keys.

Before commands can be sent to a Minion, its key must be accepted on the Master. Run the
salt-key command to list the keys known to the Salt Master:

[root@master ~]# salt-key -L
Unaccepted Keys:
alpha
bravo
charlie
delta
Accepted Keys:

This example shows that the Salt Master is aware of four Minions, but none of the keys has
been accepted. To accept the keys and allow the Minions to be controlled by the Master,
again use the salt-key command:

[root@master ~]# salt-key -A
[root@master ~]# salt-key -L
Unaccepted Keys:
Accepted Keys:
alpha
bravo
charlie
delta

The salt-key command allows for signing keys individually or in bulk. The example above,
using -A bulk-accepts all pending keys. To accept keys individually use the lowercase of
the same option, -a keyname.

CONFIGURING SALT

This section explains how to configure user access, view and store job results, secure and
troubleshoot, and how to perform many other administrative tasks.

Configuring the Salt Master
The Salt system is amazingly simple and easy to configure, the two components of the Salt
system each have a respective configuration file. The salt-master is configured via the
master configuration file, and the salt-minion is configured via the minion configuration
file.

SEE ALSO:
Example master configuration file.

The configuration file for the salt-master is located at /etc/salt/master by default.
Atomic included configuration files can be placed in /etc/salt/master.d/*.conf. Warning:
files with other suffixes than .conf will not be included. A notable exception is FreeBSD,
where the configuration file is located at /usr/local/etc/salt. The available options are
as follows:

Primary Master Configuration
interface
Default: 0.0.0.0 (all interfaces)

The local interface to bind to, must be an IP address.

interface: 192.168.0.1

ipv6
Default: False

Whether the master should listen for IPv6 connections. If this is set to True, the
interface option must be adjusted too (for example: interface: '::')

ipv6: True

publish_port
Default: 4505

The network port to set up the publication interface.

publish_port: 4505

master_id
Default: None

The id to be passed in the publish job to minions. This is used for MultiSyndics to return
the job to the requesting master.

NOTE:
This must be the same string as the syndic is configured with.

master_id: MasterOfMaster

user
Default: root

The user to run the Salt processes

user: root

enable_ssh_minions
Default: False

Tell the master to also use salt-ssh when running commands against minions.

enable_ssh_minions: True

NOTE:
Cross-minion communication is still not possible. The Salt mine and publish.publish do
not work between minion types.

ret_port
Default: 4506

The port used by the return server, this is the server used by Salt to receive execution
returns and command executions.

ret_port: 4506

pidfile
Default: /var/run/salt-master.pid

Specify the location of the master pidfile.

pidfile: /var/run/salt-master.pid

root_dir
Default: /

The system root directory to operate from, change this to make Salt run from an
alternative root.

root_dir: /

NOTE:
This directory is prepended to the following options: pki_dir, cachedir, sock_dir,
log_file, autosign_file, autoreject_file, pidfile, autosign_grains_dir.

conf_file
Default: /etc/salt/master

The path to the master's configuration file.

conf_file: /etc/salt/master

pki_dir
Default: <STATE_DIR>/pki/master

The directory to store the pki authentication keys.

pki_dir: /etc/salt/pki/master

extension_modules
Changed in version 2016.3.0: The default location for this directory has been moved. Prior
to this version, the location was a directory named extmods in the Salt cachedir (on most
platforms, /var/cache/salt/extmods). It has been moved into the master cachedir (on most
platforms, /var/cache/salt/master/extmods).

Directory for custom modules. This directory can contain subdirectories for each of Salt's
module types such as runners, output, wheel, modules, states, returners, engines, utils,
etc. This path is appended to root_dir.

extension_modules: /root/salt_extmods

extmod_whitelist/extmod_blacklist
New in version 2017.7.0.

By using this dictionary, the modules that are synced to the master'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 modules of a specific type, whitelist an empty list.

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

extmod_blacklist:
modules:
- specific_module

Valid options:

· modules

· states

· grains

· renderers

· returners

· output

· proxy

· runners

· wheel

· engines

· queues

· pillar

· utils

· sdb

· cache

· clouds

· tops

· roster

· tokens

module_dirs
Default: []

Like extension_modules, but a list of extra directories to search for Salt modules.

module_dirs:
- /var/cache/salt/minion/extmods

cachedir
Default: /var/cache/salt/master

The location used to store cache information, particularly the job information for
executed salt commands.

This directory may contain sensitive data and should be protected accordingly.

cachedir: /var/cache/salt/master

verify_env
Default: True

Verify and set permissions on configuration directories at startup.

verify_env: True

keep_jobs
Default: 24

Set the number of hours to keep old job information. Note that setting this option to 0
disables the cache cleaner.

keep_jobs: 24

gather_job_timeout
New in version 2014.7.0.

Default: 10

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

gather_job_timeout: 10

timeout
Default: 5

Set the default timeout for the salt command and api.

loop_interval
Default: 60

The loop_interval option controls the seconds for the master's maintenance process check
cycle. This process updates file server backends, cleans the job cache and executes the
scheduler.

output
Default: nested

Set the default outputter used by the salt command.

outputter_dirs
Default: []

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

outputter_dirs: []

output_file
Default: None

Set the default output file used by the salt command. Default is to output to the CLI and
not to a file. Functions the same way as the "--out-file" CLI option, only sets this to a
single file for all salt commands.

output_file: /path/output/file

show_timeout
Default: True

Tell the client to show minions that have timed out.

show_timeout: True

show_jid
Default: False

Tell the client to display the jid when a job is published.

show_jid: False

color
Default: True

By default output is colored, to disable colored output set the color value to False.

color: False

color_theme
Default: ""

Specifies a path to the color theme to use for colored command line output.

color_theme: /etc/salt/color_theme

cli_summary
Default: False

When set to True, displays a summary of the number of minions targeted, the number of
minions returned, and the number of minions that did not return.

cli_summary: False

sock_dir
Default: /var/run/salt/master

Set the location to use for creating Unix sockets for master process communication.

sock_dir: /var/run/salt/master

enable_gpu_grains
Default: False

Enable GPU hardware data for your master. Be aware that the master can take a while to
start up when lspci and/or dmidecode is used to populate the grains for the master.

enable_gpu_grains: True

skip_grains
Default: False

MasterMinions should omit grains. A MasterMinion is "a minion function object for generic
use on the master" that omit pillar. A RunnerClient creates a MasterMinion omitting states
and renderer. Setting to True can improve master performance.

skip_grains: True

job_cache
Default: True

The master maintains a temporary job cache. While this is a great addition, it can be a
burden on the master for larger deployments (over 5000 minions). Disabling the job cache
will make previously executed jobs unavailable to the jobs system and is not generally
recommended. Normally it is wise to make sure the master has access to a faster IO system
or a tmpfs is mounted to the jobs dir.

job_cache: True

NOTE:
Setting the job_cache to False will not cache minion returns, but the JID directory for
each job is still created. The creation of the JID directories is necessary because
Salt uses those directories to check for JID collisions. By setting this option to
False, the job cache directory, which is /var/cache/salt/master/jobs/ by default, will
be smaller, but the JID directories will still be present.

Note that the keep_jobs option can be set to a lower value, such as 1, to limit the
number of hours jobs are stored in the job cache. (The default is 24 hours.)

Please see the Managing the Job Cache documentation for more information.

minion_data_cache
Default: True

The minion data cache is a cache of information about the minions stored on the master,
this information is primarily the pillar, grains and mine data. The data is cached via the
cache subsystem in the Master cachedir under the name of the minion or in a supported
database. The data is used to predetermine what minions are expected to reply from
executions.

minion_data_cache: True

cache
Default: localfs

Cache subsystem module to use for minion data cache.

cache: consul

memcache_expire_seconds
Default: 0

Memcache is an additional cache layer that keeps a limited amount of data fetched from the
minion data cache for a limited period of time in memory that makes cache operations
faster. It doesn't make much sense for the localfs cache driver but helps for more complex
drivers like consul.

This option sets the memcache items expiration time. By default is set to 0 that disables
the memcache.

memcache_expire_seconds: 30

memcache_max_items
Default: 1024

Set memcache limit in items that are bank-key pairs. I.e the list of minion_0/data,
minion_0/mine, minion_1/data contains 3 items. This value depends on the count of minions
usually targeted in your environment. The best one could be found by analyzing the cache
log with memcache_debug enabled.

memcache_max_items: 1024

memcache_full_cleanup
Default: False

If cache storage got full, i.e. the items count exceeds the memcache_max_items value,
memcache cleans up its storage. If this option set to False memcache removes the only one
oldest value from its storage. If this set set to True memcache removes all the expired
items and also removes the oldest one if there are no expired items.

memcache_full_cleanup: True

memcache_debug
Default: False

Enable collecting the memcache stats and log it on debug log level. If enabled memcache
collect information about how many fetch calls has been done and how many of them has been
hit by memcache. Also it outputs the rate value that is the result of division of the
first two values. This should help to choose right values for the expiration time and the
cache size.

memcache_debug: True

ext_job_cache
Default: ''

Used to specify a default returner for all minions. When this option is set, the specified
returner needs to be properly configured and the minions will always default to sending
returns to this returner. This will also disable the local job cache on the master.

ext_job_cache: redis

event_return
New in version 2015.5.0.

Default: ''

Specify the returner(s) to use to log events. Each returner may have installation and
configuration requirements. Read the returner's documentation.

NOTE:
Not all returners support event returns. Verify that a returner has an event_return()
function before configuring this option with a returner.

event_return:
- syslog
- splunk

event_return_queue
New in version 2015.5.0.

Default: 0

On busy systems, enabling event_returns can cause a considerable load on the storage
system for returners. Events can be queued on the master and stored in a batched fashion
using a single transaction for multiple events. By default, events are not queued.

event_return_queue: 0

event_return_whitelist
New in version 2015.5.0.

Default: []

Only return events matching tags in a whitelist.

Changed in version 2016.11.0: Supports glob matching patterns.

event_return_whitelist:
- salt/master/a_tag
- salt/run/*/ret

event_return_blacklist
New in version 2015.5.0.

Default: []

Store all event returns _except_ the tags in a blacklist.

Changed in version 2016.11.0: Supports glob matching patterns.

event_return_blacklist:
- salt/master/not_this_tag
- salt/wheel/*/ret

max_event_size
New in version 2014.7.0.

Default: 1048576

Passing very large events can cause the minion to consume large amounts of memory. This
value tunes the maximum size of a message allowed onto the master event bus. The value is
expressed in bytes.

max_event_size: 1048576

master_job_cache
New in version 2014.7.0.

Default: local_cache

Specify the returner to use for the job cache. The job cache will only be interacted with
from the salt master and therefore does not need to be accessible from the minions.

master_job_cache: redis

job_cache_store_endtime
New in version 2015.8.0.

Default: False

Specify whether the Salt Master should store end times for jobs as returns come in.

job_cache_store_endtime: False

enforce_mine_cache
Default: False

By-default when disabling the minion_data_cache mine will stop working since it is based
on cached data, by enabling this option we explicitly enabling only the cache for the mine
system.

enforce_mine_cache: False

max_minions
Default: 0

The maximum number of minion connections allowed by the master. Use this to accommodate
the number of minions per master if you have different types of hardware serving your
minions. The default of 0 means unlimited connections. Please note that this can slow
down the authentication process a bit in large setups.

max_minions: 100

con_cache
Default: False

If max_minions is used in large installations, the master might experience high-load
situations because of having to check the number of connected minions for every
authentication. This cache provides the minion-ids of all connected minions to all
MWorker-processes and greatly improves the performance of max_minions.

con_cache: True

presence_events
Default: False

Causes the master to periodically look for actively connected minions. Presence events
are fired on the event bus on a regular interval with a list of connected minions, as well
as events with lists of newly connected or disconnected minions. This is a master-only
operation that does not send executions to minions.

presence_events: False

detect_remote_minions
Default: False

When checking the minions connected to a master, also include the master's connections to
minions on the port specified in the setting remote_minions_port. This is particularly
useful when checking if the master is connected to any Heist-Salt minions. If this setting
is set to True, the master will check all connections on port 22 by default unless a user
also configures a different port with the setting remote_minions_port.

Changing this setting will check the remote minions the master is connected to when using
presence events, the manage runner, and any other parts of the code that call the
connected_ids method to check the status of connected minions.

detect_remote_minions: True

remote_minions_port
Default: 22

The port to use when checking for remote minions when detect_remote_minions is set to
True.

remote_minions_port: 2222

ping_on_rotate
New in version 2014.7.0.

Default: False

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 enabling this 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

transport
Default: zeromq

Changes the underlying transport layer. ZeroMQ is the recommended transport while
additional transport layers are under development. Supported values are zeromq and tcp
(experimental). This setting has a significant impact on performance and should not be
changed unless you know what you are doing!

transport: zeromq

transport_opts
Default: {}

(experimental) Starts multiple transports and overrides options for each transport with
the provided dictionary This setting has a significant impact on performance and should
not be changed unless you know what you are doing! The following example shows how to
start a TCP transport alongside a ZMQ transport.

transport_opts:
tcp:
publish_port: 4605
ret_port: 4606
zeromq: []

master_stats
Default: False

Turning on the master stats enables runtime throughput and statistics events to be fired
from the master event bus. These events will report on what functions have been run on the
master and how long these runs have, on average, taken over a given period of time.

master_stats_event_iter
Default: 60

The time in seconds to fire master_stats events. This will only fire in conjunction with
receiving a request to the master, idle masters will not fire these events.

sock_pool_size
Default: 1

To avoid blocking waiting while writing a data to a socket, we support socket pool for
Salt applications. For example, a job with a large number of target host list can cause
long period blocking waiting. The option is used by ZMQ and TCP transports, and the other
transport methods don't need the socket pool by definition. Most of Salt tools, including
CLI, are enough to use a single bucket of socket pool. On the other hands, it is highly
recommended to set the size of socket pool larger than 1 for other Salt applications,
especially Salt API, which must write data to socket concurrently.

sock_pool_size: 15

ipc_mode
Default: ipc

The ipc strategy. (i.e., sockets versus tcp, etc.) Windows platforms lack POSIX IPC and
must rely on TCP based inter-process communications. ipc_mode is set to tcp by default on
Windows.

ipc_mode: ipc

tcp_master_pub_port
Default: 4512

The TCP port on which events for the master should be published if ipc_mode is TCP.

tcp_master_pub_port: 4512

tcp_master_pull_port
Default: 4513

The TCP port on which events for the master should be pulled if ipc_mode is TCP.

tcp_master_pull_port: 4513

tcp_master_publish_pull
Default: 4514

The TCP port on which events for the master should be pulled fom and then republished onto
the event bus on the master.

tcp_master_publish_pull: 4514

tcp_master_workers
Default: 4515

The TCP port for mworkers to connect to on the master.

tcp_master_workers: 4515

auth_events
New in version 2017.7.3.

Default: True

Determines whether the master will fire authentication events. Authentication events are
fired when a minion performs an authentication check with the master.

auth_events: True

minion_data_cache_events
New in version 2017.7.3.

Default: True

Determines whether the master will fire minion data cache events. Minion data cache
events are fired when a minion requests a minion data cache refresh.

minion_data_cache_events: True

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

use_yamlloader_old
New in version 2019.2.1.

Default: False

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

use_yamlloader_old: False

req_server_niceness
New in version 3001.

Default: None

Process priority level of the ReqServer subprocess of the master. Supported on POSIX
platforms only.

req_server_niceness: 9

pub_server_niceness
New in version 3001.

Default: None

Process priority level of the PubServer subprocess of the master. Supported on POSIX
platforms only.

pub_server_niceness: 9

fileserver_update_niceness
New in version 3001.

Default: None

Process priority level of the FileServerUpdate subprocess of the master. Supported on
POSIX platforms only.

fileserver_update_niceness: 9

maintenance_niceness
New in version 3001.

Default: None

Process priority level of the Maintenance subprocess of the master. Supported on POSIX
platforms only.

maintenance_niceness: 9

mworker_niceness
New in version 3001.

Default: None

Process priority level of the MWorker subprocess of the master. Supported on POSIX
platforms only.

mworker_niceness: 9

mworker_queue_niceness
New in version 3001.

default: None

process priority level of the MWorkerQueue subprocess of the master. supported on POSIX
platforms only.

mworker_queue_niceness: 9

event_return_niceness
New in version 3001.

default: None

process priority level of the EventReturn subprocess of the master. supported on POSIX
platforms only.

event_return_niceness: 9

event_publisher_niceness
New in version 3001.

default: none

process priority level of the EventPublisher subprocess of the master. supported on POSIX
platforms only.

event_publisher_niceness: 9

reactor_niceness
New in version 3001.

default: None

process priority level of the Reactor subprocess of the master. supported on POSIX
platforms only.

reactor_niceness: 9

Salt-SSH Configuration
roster
Default: flat

Define the default salt-ssh roster module to use

roster: cache

roster_defaults
New in version 2017.7.0.

Default settings which will be inherited by all rosters.

roster_defaults:
user: daniel
sudo: True
priv: /root/.ssh/id_rsa
tty: True

roster_file
Default: /etc/salt/roster

Pass in an alternative location for the salt-ssh flat roster file.

roster_file: /root/roster

rosters
Default: None

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,
the roster_file parameter should contain a relative path to these locations. That is,
roster_file=/foo/roster will be resolved as /etc/salt/roster.d/foo/roster etc. This
feature prevents passing insecure custom rosters through the Salt API.

rosters:
- /etc/salt/roster.d
- /opt/salt/some/more/rosters

ssh_passwd
Default: ''

The ssh password to log in with.

ssh_passwd: ''

ssh_priv_passwd
Default: ''

Passphrase for ssh private key file.

ssh_priv_passwd: ''

ssh_port
Default: 22

The target system's ssh port number.

ssh_port: 22

ssh_scan_ports
Default: 22

Comma-separated list of ports to scan.

ssh_scan_ports: 22

ssh_scan_timeout
Default: 0.01

Scanning socket timeout for salt-ssh.

ssh_scan_timeout: 0.01

ssh_sudo
Default: False

Boolean to run command via sudo.

ssh_sudo: False

ssh_timeout
Default: 60

Number of seconds to wait for a response when establishing an SSH connection.

ssh_timeout: 60

ssh_user
Default: root

The user to log in as.

ssh_user: root

ssh_log_file
New in version 2016.3.5.

Default: /var/log/salt/ssh

Specify the log file of the salt-ssh command.

ssh_log_file: /var/log/salt/ssh

ssh_minion_opts
Default: None

Pass in minion option overrides that will be inserted into the SHIM for salt-ssh calls.
The local minion config is not used for salt-ssh. Can be overridden on a per-minion basis
in the roster (minion_opts)

ssh_minion_opts:
gpg_keydir: /root/gpg

ssh_use_home_key
Default: False

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

ssh_use_home_key: False

ssh_identities_only
Default: 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

ssh_list_nodegroups
Default: {}

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:
groupA: minion1,minion2
groupB: minion1,minion3

Default: False

Run the ssh_pre_flight script defined in the salt-ssh roster. By default the script will
only run when the thin dir does not exist on the targeted minion. This will force the
script to run and not check if the thin dir exists first.

thin_extra_mods
Default: None

List of additional modules, needed to be included into the Salt Thin. Pass a list of
importable Python modules that are typically located in the site-packages Python directory
so they will be also always included into the Salt Thin, once generated.

min_extra_mods
Default: None

Identical as thin_extra_mods, only applied to the Salt Minimal.

Master Security Settings
open_mode
Default: False

Open mode is a dangerous security feature. One problem encountered with pki authentication
systems is that keys can become "mixed up" and authentication begins to fail. Open mode
turns off authentication and tells the master to accept all authentication. This will
clean up the pki keys received from the minions. Open mode should not be turned on for
general use. Open mode should only be used for a short period of time to clean up pki
keys. To turn on open mode set this value to True.

open_mode: False

auto_accept
Default: False

Enable auto_accept. This setting will automatically accept all incoming public keys from
minions.

auto_accept: False

keysize
Default: 2048

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

keysize: 2048

autosign_timeout
New in version 2014.7.0.

Default: 120

Time in minutes that a incoming public key with a matching name found in
pki_dir/minion_autosign/keyid is automatically accepted. Expired autosign keys are removed
when the master checks the minion_autosign directory. This method to auto accept minions
can be safer than an autosign_file because the keyid record can expire and is limited to
being an exact name match. This should still be considered a less than secure option, due
to the fact that trust is based on just the requesting minion id.

autosign_file
Default: not defined

If the autosign_file is specified incoming keys specified in the autosign_file will be
automatically accepted. Matches will be searched for first by string comparison, then by
globbing, then by full-string regex matching. This should still be considered a less than
secure option, due to the fact that trust is based on just the requesting minion id.

Changed in version 2018.3.0: For security reasons the file must be readonly except for its
owner. If permissive_pki_access is True the owning group can also have write access, but
if Salt is running as root it must be a member of that group. A less strict requirement
also existed in previous version.

autoreject_file
New in version 2014.1.0.

Default: not defined

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.

autosign_grains_dir
New in version 2018.3.0.

Default: not defined

If the autosign_grains_dir is specified, incoming keys from minions with grain values that
match those defined in files in the autosign_grains_dir will be accepted automatically.
Grain values that should be accepted automatically can be defined by creating a file named
like the corresponding grain in the autosign_grains_dir and writing the values into that
file, one value per line. Lines starting with a # will be ignored. Minion must be
configured to send the corresponding grains on authentication. This should still be
considered a less than secure option, due to the fact that trust is based on just the
requesting minion.

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

autosign_grains_dir: /etc/salt/autosign_grains

permissive_pki_access
Default: False

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

publisher_acl
Default: {}

Enable user accounts on the master to execute specific modules. These modules can be
expressed as regular expressions.

publisher_acl:
fred:
- test.ping
- pkg.*

publisher_acl_blacklist
Default: {}

Blacklist users or modules

This example would blacklist all non sudo users, including root from running any commands.
It would also blacklist any use of the "cmd" module.

This is completely disabled by default.

publisher_acl_blacklist:
users:
- root
- '^(?!sudo_).*$' # all non sudo users
modules:
- cmd.*
- test.echo

sudo_acl
Default: False

Enforce publisher_acl and publisher_acl_blacklist when users have sudo access to the salt
command.

sudo_acl: False

external_auth
Default: {}

The external auth system uses the Salt auth modules to authenticate and validate users to
access areas of the Salt system.

external_auth:
pam:
fred:
- test.*

token_expire
Default: 43200

Time (in seconds) for a newly generated token to live.

Default: 12 hours

token_expire: 43200

token_expire_user_override
Default: False

Allow eauth users to specify the expiry time of the tokens they generate.

A boolean applies to all users or a dictionary of whitelisted eauth backends and usernames
may be given:

token_expire_user_override:
pam:
- fred
- tom
ldap:
- gary

keep_acl_in_token
Default: 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

eauth_acl_module
Default: ''

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

file_recv
Default: False

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

file_recv: 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

master_sign_pubkey
Default: False

Sign the master auth-replies with a cryptographic signature of the master's public key.
Please see the tutorial how to use these settings in the Multimaster-PKI with Failover
Tutorial

master_sign_pubkey: True

master_sign_key_name
Default: master_sign

The customizable name of the signing-key-pair without suffix.

master_sign_key_name: <filename_without_suffix>

master_pubkey_signature
Default: master_pubkey_signature

The name of the file in the master's pki-directory that holds the pre-calculated signature
of the master's public-key.

master_pubkey_signature: <filename>

master_use_pubkey_signature
Default: False

Instead of computing the signature for each auth-reply, use a pre-calculated signature.
The master_pubkey_signature must also be set for this.

master_use_pubkey_signature: True

rotate_aes_key
Default: True

Rotate the salt-masters AES-key when a minion-public is deleted with salt-key. This is a
very important security-setting. Disabling it will enable deleted minions to still listen
in on the messages published by the salt-master. Do not disable this unless it is
absolutely clear what this does.

rotate_aes_key: True

publish_session
Default: 86400

The number of seconds between AES key rotations on the master.

publish_session: Default: 86400

ssl
New in version 2016.11.0.

Default: None

TLS/SSL connection options. This could be set to a dictionary containing arguments
corresponding to python ssl.wrap_socket method. For details see Tornado and Python
documentation.

Note: to set enum arguments values like cert_reqs and ssl_version use constant names
without ssl module prefix: CERT_REQUIRED or PROTOCOL_SSLv23.

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

preserve_minion_cache
Default: 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_minion_key_revoke
Default: True

Controls whether a minion can request its own key revocation. When True the master will
honor the minion's request and revoke its key. When False, the master will drop the
request and the minion's key will remain accepted.

allow_minion_key_revoke: False

optimization_order
Default: [0, 1, 2]

In cases where Salt is distributed without .py files, this option determines 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

Master Large Scale Tuning Settings
max_open_files
Default: 100000

Each minion connecting to the master uses AT LEAST one file descriptor, the master
subscription connection. If enough minions connect you might start seeing on the
console(and then salt-master crashes):

Too many open files (tcp_listener.cpp:335)
Aborted (core dumped)

max_open_files: 100000

By default this value will be the one of ulimit -Hn, i.e., the hard limit for max open
files.

To set a different value than the default one, uncomment, and configure this setting.
Remember that this value CANNOT be higher than the hard limit. Raising the hard limit
depends on the OS and/or distribution, a good way to find the limit is to search the
internet for something like this:

raise max open files hard limit debian

worker_threads
Default: 5

The number of threads to start for receiving commands and replies from minions. If
minions are stalling on replies because you have many minions, raise the worker_threads
value.

Worker threads should not be put below 3 when using the peer system, but can drop down to
1 worker otherwise.

NOTE:
When the master daemon starts, it is expected behaviour to see multiple salt-master
processes, even if 'worker_threads' is set to '1'. At a minimum, a controlling process
will start along with a Publisher, an EventPublisher, and a number of MWorker processes
will be started. The number of MWorker processes is tuneable by the 'worker_threads'
configuration value while the others are not.

worker_threads: 5

pub_hwm
Default: 1000

The zeromq high water mark on the publisher interface.

pub_hwm: 1000

zmq_backlog
Default: 1000

The listen queue size of the ZeroMQ backlog.

zmq_backlog: 1000

Master Module Management
runner_dirs
Default: []

Set additional directories to search for runner modules.

runner_dirs:
- /var/lib/salt/runners

utils_dirs
New in version 2018.3.0.

Default: []

Set additional directories to search for util modules.

utils_dirs:
- /var/lib/salt/utils

cython_enable
Default: False

Set to true to enable Cython modules (.pyx files) to be compiled on the fly on the Salt
master.

cython_enable: False

Master State System Settings
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. The value of "state_top" is also used for the pillar top file

state_top: top.sls

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

NOTE:
Using this value does not change the merging strategy. For instance, if
top_file_merging_strategy is set to merge, and state_top_saltenv is set to foo, then
any sections for environments other than foo in the top file for the foo environment
will be ignored. With state_top_saltenv set to base, all states from all environments
in the base top file will be applied, while all other top files are ignored. The only
way to set state_top_saltenv to something other than base and not have the other
environments in the targeted top file ignored, would be to set
top_file_merging_strategy to merge_all.

state_top_saltenv: dev

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

Default: merge

When no specific fileserver environment (a.k.a. saltenv) has been specified for a
highstate, all environments' top files are inspected. This config option determines how
the SLS targets in those top files are handled.

When set to merge, the base environment's top file is evaluated first, followed by the
other environments' top files. The first target expression (e.g. '*') for a given
environment is kept, and when the same target expression is used in a different top file
evaluated later, it is ignored. Because base is evaluated first, it is authoritative. For
example, if there is a target for '*' for the foo environment in both the base and foo
environment's top files, the one in the foo environment would be ignored. The environments
will be evaluated in no specific order (aside from base coming first). For greater control
over the order in which the environments are evaluated, use env_order. Note that, aside
from the base environment's top file, any sections in top files that do not match that top
file's environment will be ignored. So, for example, a section for the qa environment
would be ignored if it appears in the dev environment's top file. To keep use cases like
this from being ignored, use the merge_all strategy.

When set to same, then for each environment, only that environment's top file is
processed, with the others being ignored. For example, only the dev environment's top file
will be processed for the dev environment, and any SLS targets defined for dev in the base
environment's (or any other environment's) top file will be ignored. If an environment
does not have a top file, then the top file from the default_top config parameter will be
used as a fallback.

When set to merge_all, then all states in all environments in all top files will be
applied. The order in which individual SLS files will be executed will depend on the order
in which the top files were evaluated, and the environments will be evaluated in no
specific order. For greater control over the order in which the environments are
evaluated, use env_order.

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

master_tops
Default: {}

The master_tops option replaces the external_nodes option by creating a pluggable system
for the generation of external top data. The external_nodes option is deprecated by the
master_tops option. To gain the capabilities of the classic external_nodes system, use
the following configuration:

master_tops:
ext_nodes: <Shell command which returns yaml>

renderer
Default: jinja|yaml

The renderer to use on the minions to render the state data.

renderer: jinja|json

userdata_template
New in version 2016.11.4.

Default: None

The renderer to use for templating userdata files in salt-cloud, if the userdata_template
is not set in the cloud profile. If no value is set in the cloud profile or master config
file, no templating will be performed.

userdata_template: jinja

jinja_env
New in version 2018.3.0.

Default: {}

jinja_env overrides the default Jinja environment options for all templates except sls
templates. To set the options for sls templates use jinja_sls_env.

NOTE:
The Jinja2 Environment documentation is the official source for the default values.
Not all the options listed in the jinja documentation can be overridden using jinja_env
or jinja_sls_env.

The default options are:

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

Default: {}

jinja_sls_env sets the Jinja environment options for sls templates. The defaults and
accepted options are exactly the same as they are for jinja_env.

The default options are:

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

Example using line statements and line comments to increase ease of use:

If your configuration options are

jinja_sls_env:
line_statement_prefix: '%'
line_comment_prefix: '##'

With these options jinja will interpret anything after a % at the start of a line
(ignoreing whitespace) as a jinja statement and will interpret anything after a ## as a
comment.

This allows the following more convenient syntax to be used:

## (this comment will not stay once rendered)
# (this comment remains in the rendered template)
## ensure all the formula services are running
% for service in formula_services:
enable_service_{{ service }}:
service.running:
name: {{ service }}
% endfor

The following less convenient but equivalent syntax would have to be used if you had not
set the line_statement and line_comment options:

{# (this comment will not stay once rendered) #}
# (this comment remains in the rendered template)
{# ensure all the formula services are running #}
{% for service in formula_services %}
enable_service_{{ service }}:
service.running:
name: {{ service }}
{% endfor %}

jinja_trim_blocks
Deprecated since version 2018.3.0: Replaced by jinja_env and jinja_sls_env

New in version 2014.1.0.

Default: False

If this is set to True, the first newline after a Jinja block is removed (block, not
variable tag!). Defaults to False and corresponds to the Jinja environment init variable
trim_blocks.

jinja_trim_blocks: False

jinja_lstrip_blocks
Deprecated since version 2018.3.0: Replaced by jinja_env and jinja_sls_env

New in version 2014.1.0.

Default: False

If this is set to True, leading spaces and tabs are stripped from the start of a line to a
block. Defaults to False and corresponds to the Jinja environment init variable
lstrip_blocks.

jinja_lstrip_blocks: False

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

state_verbose
Default: True

Controls the verbosity of state runs. By default, the results of all states are returned,
but setting this value to False will cause salt to only display output for states that
failed or states that have changes.

state_verbose: False

state_output
Default: full

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

state_output_diff
Default: False

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

state_output_profile
Default: True

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

state_output_profile: True

state_aggregate
Default: False

Automatically aggregate all states that have support for mod_aggregate by setting to True.

state_aggregate: True

Or pass a list of state module names to automatically aggregate just those types.

state_aggregate:
- pkg

state_events
Default: False

Send progress events as each function in a state run completes execution by setting to
True. Progress events are in the format salt/job/<JID>/prog/<MID>/<RUN NUM>.

state_events: True

yaml_utf8
Default: False

Enable extra routines for YAML renderer used states containing UTF characters.

yaml_utf8: False

runner_returns
Default: False

If set to True, runner jobs will be saved to job cache (defined by master_job_cache).

runner_returns: True

Master File Server Settings
fileserver_backend
Default: ['roots']

Salt supports a modular fileserver backend system, this system allows the salt master to
link directly to third party systems to gather and manage the files available to minions.
Multiple backends can be configured and will be searched for the requested file in the
order in which they are defined here. The default setting only enables the standard
backend roots, which is configured using the file_roots option.

Example:

fileserver_backend:
- roots
- gitfs

NOTE:
For masterless Salt, this parameter must be specified in the minion config file.

fileserver_followsymlinks
New in version 2014.1.0.

Default: True

By default, the file_server follows symlinks when walking the filesystem tree. Currently
this only applies to the default roots fileserver_backend.

fileserver_followsymlinks: True

fileserver_ignoresymlinks
New in version 2014.1.0.

Default: False

If you do not want symlinks to be treated as the files they are pointing to, set
fileserver_ignoresymlinks to True. By default this is set to False. When set to True, any
detected symlink while listing files on the Master will not be returned to the Minion.

fileserver_ignoresymlinks: False

fileserver_limit_traversal
New in version 2014.1.0.

Deprecated since version 2018.3.4: This option is now ignored. Firstly, it only traversed
file_roots, which means it did not work for the other fileserver backends. Secondly, since
this option was added we have added caching to the code that traverses the file_roots (and
gitfs, etc.), which greatly reduces the amount of traversal that is done.

Default: False

By default, the Salt fileserver recurses fully into all defined environments to attempt to
find files. To limit this behavior so that the fileserver only traverses directories with
SLS files and special Salt directories like _modules, set fileserver_limit_traversal to
True. This might be useful for installations where a file root has a very large number of
files and performance is impacted.

fileserver_limit_traversal: False

fileserver_list_cache_time
New in version 2014.1.0.

Changed in version 2016.11.0: The default was changed from 30 seconds to 20.

Default: 20

Salt caches the list of files/symlinks/directories for each fileserver backend and
environment as they are requested, to guard against a performance bottleneck at scale when
many minions all ask the fileserver which files are available simultaneously. This
configuration parameter allows for the max age of that cache to be altered.

Set this value to 0 to disable use of this cache altogether, but keep in mind that this
may increase the CPU load on the master when running a highstate on a large number of
minions.

NOTE:
Rather than altering this configuration parameter, it may be advisable to use the
fileserver.clear_file_list_cache runner to clear these caches.

fileserver_list_cache_time: 5

fileserver_verify_config
New in version 2017.7.0.

Default: True

By default, as the master starts it performs some sanity checks on the configured
fileserver backends. If any of these sanity checks fail (such as when an invalid
configuration is used), the master daemon will abort.

To skip these sanity checks, set this option to False.

fileserver_verify_config: False

hash_type
Default: sha256

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.

hash_type: sha256

file_buffer_size
Default: 1048576

The buffer size in the file server in bytes.

file_buffer_size: 1048576

file_ignore_regex
Default: ''

A regular expression (or a list of expressions) that will be matched against the file path
before syncing the modules and states to the minions. This includes files affected by the
file.recurse state. For example, if you manage your custom modules and states in
subversion and don't want all the '.svn' folders and content synced to your minions, you
could set this to '/.svn($|/)'. By default nothing is ignored.

file_ignore_regex:
- '/\.svn($|/)'
- '/\.git($|/)'

file_ignore_glob
Default ''

A file glob (or list of file globs) that will be matched against the file path before
syncing the modules and states to the minions. This is similar to file_ignore_regex above,
but works on globs instead of regex. By default nothing is ignored.

file_ignore_glob:
- '\*.pyc'
- '\*/somefolder/\*.bak'
- '\*.swp'

NOTE:
Vim's .swp files are a common cause of Unicode errors in file.recurse states which use
templating. Unless there is a good reason to distribute them via the fileserver, it is
good practice to include '\*.swp' in the file_ignore_glob.

master_roots
Default: ''

A master-only copy of the file_roots dictionary, used by the state compiler.

Example:

master_roots:
base:
- /srv/salt-master

roots: Master's Local File Server
file_roots
Default:

base:
- /srv/salt

Salt runs a lightweight file server written in ZeroMQ to deliver files to minions. This
file server is built into the master daemon and does not require a dedicated port.

The file server works on environments passed to the master. Each environment can have
multiple root directories. The subdirectories in the multiple file roots cannot match,
otherwise the downloaded files will not be able to be reliably ensured. A base environment
is required to house the top file.

As of 2018.3.5 and 2019.2.1, it is possible to have __env__ as a catch-all environment.

Example:

file_roots:
base:
- /srv/salt
dev:
- /srv/salt/dev/services
- /srv/salt/dev/states
prod:
- /srv/salt/prod/services
- /srv/salt/prod/states
__env__:
- /srv/salt/default

NOTE:
For masterless Salt, this parameter must be specified in the minion config file.

roots_update_interval
New in version 2018.3.0.

Default: 60

This option defines the update interval (in seconds) for file_roots.

NOTE:
Since file_roots consists of files local to the minion, the update process for this
fileserver backend just reaps the cache for this backend.

roots_update_interval: 120

gitfs: Git Remote File Server Backend
gitfs_remotes
Default: []

When using the git fileserver backend at least one git remote needs to be defined. The
user running the salt master will need read access to the repo.

The repos will be searched in order to find the file requested by a client and the first
repo to have the file will return it. Branches and tags are translated into salt
environments.

gitfs_remotes:
- git://github.com/saltstack/salt-states.git
- file:///var/git/saltmaster

NOTE:
file:// repos will be treated as a remote and copied into the master's gitfs cache, so
only the local refs for those repos will be exposed as fileserver environments.

As of 2014.7.0, it is possible to have per-repo versions of several of the gitfs
configuration parameters. For more information, see the GitFS Walkthrough.

gitfs_provider
New in version 2014.7.0.

Optional parameter used to specify the provider to be used for gitfs. More information can
be found in the GitFS Walkthrough.

Must be either pygit2 or gitpython. If unset, then each will be tried in that same order,
and the first one with a compatible version installed will be the provider that is used.

gitfs_provider: gitpython

gitfs_ssl_verify
Default: True

Specifies whether or not to ignore SSL certificate errors when fetching from the
repositories configured in gitfs_remotes. The False setting is useful if you're using a
git repo that uses a self-signed certificate. However, keep in mind that setting this to
anything other True is a considered insecure, and using an SSH-based transport (if
available) may be a better option.

gitfs_ssl_verify: False

NOTE:
pygit2 only supports disabling SSL verification in versions 0.23.2 and newer.

Changed in version 2015.8.0: This option can now be configured on individual repositories
as well. See here for more info.

Changed in version 2016.11.0: The default config value changed from False to True.

gitfs_mountpoint
New in version 2014.7.0.

Default: ''

Specifies a path on the salt fileserver which will be prepended to all files served by
gitfs. This option can be used in conjunction with gitfs_root. It can also be configured
for an individual repository, see here for more info.

gitfs_mountpoint: salt://foo/bar

NOTE:
The salt:// protocol designation can be left off (in other words, foo/bar and
salt://foo/bar are equivalent). Assuming a file baz.sh in the root of a gitfs remote,
and the above example mountpoint, this file would be served up via
salt://foo/bar/baz.sh.

gitfs_root
Default: ''

Relative path to a subdirectory within the repository from which Salt should begin to
serve files. This is useful when there are files in the repository that should not be
available to the Salt fileserver. Can be used in conjunction with gitfs_mountpoint. If
used, then from Salt's perspective the directories above the one specified will be ignored
and the relative path will (for the purposes of gitfs) be considered as the root of the
repo.

gitfs_root: somefolder/otherfolder

Changed in version 2014.7.0: This option can now be configured on individual repositories
as well. See here for more info.

gitfs_base
Default: master

Defines which branch/tag should be used as the base environment.

gitfs_base: salt

Changed in version 2014.7.0: This option can now be configured on individual repositories
as well. See here for more info.

gitfs_saltenv
New in version 2016.11.0.

Default: []

Global settings for per-saltenv configuration parameters. Though per-saltenv configuration
parameters are typically one-off changes specific to a single gitfs remote, and thus more
often configured on a per-remote basis, this parameter can be used to specify per-saltenv
changes which should apply to all remotes. For example, the below configuration will map
the develop branch to the dev saltenv for all gitfs remotes.

gitfs_saltenv:
- dev:
- ref: develop

gitfs_disable_saltenv_mapping
New in version 2018.3.0.

Default: False

When set to True, all saltenv mapping logic is disregarded (aside from which branch/tag is
mapped to the base saltenv). To use any other environments, they must then be defined
using per-saltenv configuration parameters.

gitfs_disable_saltenv_mapping: True

NOTE:
This is is a global configuration option, see here for examples of configuring it for
individual repositories.

gitfs_ref_types
New in version 2018.3.0.

Default: ['branch', 'tag', 'sha']

This option defines what types of refs are mapped to fileserver environments (i.e.
saltenvs). It also sets the order of preference when there are ambiguously-named refs
(i.e. when a branch and tag both have the same name). The below example disables mapping
of both tags and SHAs, so that only branches are mapped as saltenvs:

gitfs_ref_types:
- branch

NOTE:
This is is a global configuration option, see here for examples of configuring it for
individual repositories.

NOTE:
sha is special in that it will not show up when listing saltenvs (e.g. with the
fileserver.envs runner), but works within states and with cp.cache_file to retrieve a
file from a specific git SHA.

gitfs_saltenv_whitelist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from gitfs_env_whitelist to gitfs_saltenv_whitelist

Default: []

Used to restrict which environments are made available. Can speed up state runs if the
repos in gitfs_remotes contain many branches/tags. More information can be found in the
GitFS Walkthrough.

gitfs_saltenv_whitelist:
- base
- v1.*
- 'mybranch\d+'

gitfs_saltenv_blacklist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from gitfs_env_blacklist to gitfs_saltenv_blacklist

Default: []

Used to restrict which environments are made available. Can speed up state runs if the
repos in gitfs_remotes contain many branches/tags. More information can be found in the
GitFS Walkthrough.

gitfs_saltenv_blacklist:
- base
- v1.*
- 'mybranch\d+'

gitfs_global_lock
New in version 2015.8.9.

Default: True

When set to False, if there is an update lock for a gitfs remote and the pid written to it
is not running on the master, the lock file will be automatically cleared and a new lock
will be obtained. When set to True, Salt will simply log a warning when there is an update
lock present.

On single-master deployments, disabling this option can help automatically deal with
instances where the master was shutdown/restarted during the middle of a gitfs update,
leaving a update lock in place.

However, on multi-master deployments with the gitfs cachedir shared via GlusterFS, nfs, or
another network filesystem, it is strongly recommended not to disable this option as doing
so will cause lock files to be removed if they were created by a different master.

# Disable global lock
gitfs_global_lock: False

gitfs_update_interval
New in version 2018.3.0.

Default: 60

This option defines the default update interval (in seconds) for gitfs remotes. The
update interval can also be set for a single repository via a per-remote config option

gitfs_update_interval: 120

GitFS Authentication Options
These parameters only currently apply to the pygit2 gitfs provider. Examples of how to use
these can be found in the GitFS Walkthrough.

gitfs_user
New in version 2014.7.0.

Default: ''

Along with gitfs_password, is used to authenticate to HTTPS remotes.

gitfs_user: git

NOTE:
This is is a global configuration option, see here for examples of configuring it for
individual repositories.

gitfs_password
New in version 2014.7.0.

Default: ''

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: mypassword

NOTE:
This is is a global configuration option, see here for examples of configuring it for
individual repositories.

gitfs_insecure_auth
New in version 2014.7.0.

Default: False

By default, Salt will not authenticate to an HTTP (non-HTTPS) remote. This parameter
enables authentication over HTTP. Enable this at your own risk.

gitfs_insecure_auth: True

NOTE:
This is is a global configuration option, see here for examples of configuring it for
individual repositories.

gitfs_pubkey
New in version 2014.7.0.

Default: ''

Along with gitfs_privkey (and optionally gitfs_passphrase), is used to authenticate to SSH
remotes. Required for SSH remotes.

gitfs_pubkey: /path/to/key.pub

NOTE:
This is is a global configuration option, see here for examples of configuring it for
individual repositories.

gitfs_privkey
New in version 2014.7.0.

Default: ''

Along with gitfs_pubkey (and optionally gitfs_passphrase), is used to authenticate to SSH
remotes. Required for SSH remotes.

gitfs_privkey: /path/to/key

NOTE:
This is is a global configuration option, see here for examples of configuring it for
individual repositories.

gitfs_passphrase
New in version 2014.7.0.

Default: ''

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

gitfs_passphrase: mypassphrase

NOTE:
This is is a global configuration option, see here for examples of configuring it for
individual repositories.

gitfs_refspecs
New in version 2017.7.0.

Default: ['+refs/heads/*:refs/remotes/origin/*', '+refs/tags/*:refs/tags/*']

When fetching from remote repositories, by default Salt will fetch branches and tags. This
parameter can be used to override the default and specify alternate refspecs to be
fetched. More information on how this feature works can be found in the GitFS Walkthrough.

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/*'

hgfs: Mercurial Remote File Server Backend
hgfs_remotes
New in version 0.17.0.

Default: []

When using the hg fileserver backend at least one mercurial remote needs to be defined.
The user running the salt master will need read access to the repo.

The repos will be searched in order to find the file requested by a client and the first
repo to have the file will return it. Branches and/or bookmarks are translated into salt
environments, as defined by the hgfs_branch_method parameter.

hgfs_remotes:
- https://username@bitbucket.org/username/reponame

NOTE:
As of 2014.7.0, it is possible to have per-repo versions of the hgfs_root,
hgfs_mountpoint, hgfs_base, and hgfs_branch_method parameters. For example:

hgfs_remotes:
- https://username@bitbucket.org/username/repo1
- base: saltstates
- https://username@bitbucket.org/username/repo2:
- root: salt
- mountpoint: salt://foo/bar/baz
- https://username@bitbucket.org/username/repo3:
- root: salt/states
- branch_method: mixed

hgfs_branch_method
New in version 0.17.0.

Default: branches

Defines the objects that will be used as fileserver environments.

· branches - Only branches and tags will be used

· bookmarks - Only bookmarks and tags will be used

· mixed - Branches, bookmarks, and tags will be used

hgfs_branch_method: mixed

NOTE:
Starting in version 2014.1.0, the value of the hgfs_base parameter defines which branch
is used as the base environment, allowing for a base environment to be used with an
hgfs_branch_method of bookmarks.

Prior to this release, the default branch will be used as the base environment.

hgfs_mountpoint
New in version 2014.7.0.

Default: ''

Specifies a path on the salt fileserver which will be prepended to all files served by
hgfs. This option can be used in conjunction with hgfs_root. It can also be configured on
a per-remote basis, see here for more info.

hgfs_mountpoint: salt://foo/bar

NOTE:
The salt:// protocol designation can be left off (in other words, foo/bar and
salt://foo/bar are equivalent). Assuming a file baz.sh in the root of an hgfs remote,
this file would be served up via salt://foo/bar/baz.sh.

hgfs_root
New in version 0.17.0.

Default: ''

Relative path to a subdirectory within the repository from which Salt should begin to
serve files. This is useful when there are files in the repository that should not be
available to the Salt fileserver. Can be used in conjunction with hgfs_mountpoint. If
used, then from Salt's perspective the directories above the one specified will be ignored
and the relative path will (for the purposes of hgfs) be considered as the root of the
repo.

hgfs_root: somefolder/otherfolder

Changed in version 2014.7.0: Ability to specify hgfs roots on a per-remote basis was
added. See here for more info.

hgfs_base
New in version 2014.1.0.

Default: default

Defines which branch should be used as the base environment. Change this if
hgfs_branch_method is set to bookmarks to specify which bookmark should be used as the
base environment.

hgfs_base: salt

hgfs_saltenv_whitelist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from hgfs_env_whitelist to hgfs_saltenv_whitelist

Default: []

Used to restrict which environments are made available. Can speed up state runs if your
hgfs remotes contain many branches/bookmarks/tags. Full names, globs, and regular
expressions are supported. If using a regular expression, the expression must match the
entire minion ID.

If used, only branches/bookmarks/tags which match one of the specified expressions will be
exposed as fileserver environments.

If used in conjunction with hgfs_saltenv_blacklist, then the subset of
branches/bookmarks/tags which match the whitelist but do not match the blacklist will be
exposed as fileserver environments.

hgfs_saltenv_whitelist:
- base
- v1.*
- 'mybranch\d+'

hgfs_saltenv_blacklist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from hgfs_env_blacklist to hgfs_saltenv_blacklist

Default: []

If used, branches/bookmarks/tags which match one of the specified expressions will not be
exposed as fileserver environments.

If used in conjunction with hgfs_saltenv_whitelist, then the subset of
branches/bookmarks/tags which match the whitelist but do not match the blacklist will be
exposed as fileserver environments.

hgfs_saltenv_blacklist:
- base
- v1.*
- 'mybranch\d+'

hgfs_update_interval
New in version 2018.3.0.

Default: 60

This option defines the update interval (in seconds) for hgfs_remotes.

hgfs_update_interval: 120

svnfs: Subversion Remote File Server Backend
svnfs_remotes
New in version 0.17.0.

Default: []

When using the svn fileserver backend at least one subversion remote needs to be defined.
The user running the salt master will need read access to the repo.

The repos will be searched in order to find the file requested by a client and the first
repo to have the file will return it. The trunk, branches, and tags become environments,
with the trunk being the base environment.

svnfs_remotes:
- svn://foo.com/svn/myproject

NOTE:
As of 2014.7.0, it is possible to have per-repo versions of the following configuration
parameters:

· svnfs_root

· svnfs_mountpoint

· svnfs_trunk

· svnfs_branches

· svnfs_tags

For example:

svnfs_remotes:
- svn://foo.com/svn/project1
- svn://foo.com/svn/project2:
- root: salt
- mountpoint: salt://foo/bar/baz
- svn//foo.com/svn/project3:
- root: salt/states
- branches: branch
- tags: tag

svnfs_mountpoint
New in version 2014.7.0.

Default: ''

Specifies a path on the salt fileserver which will be prepended to all files served by
hgfs. This option can be used in conjunction with svnfs_root. It can also be configured on
a per-remote basis, see here for more info.

svnfs_mountpoint: salt://foo/bar

NOTE:
The salt:// protocol designation can be left off (in other words, foo/bar and
salt://foo/bar are equivalent). Assuming a file baz.sh in the root of an svnfs remote,
this file would be served up via salt://foo/bar/baz.sh.

svnfs_root
New in version 0.17.0.

Default: ''

Relative path to a subdirectory within the repository from which Salt should begin to
serve files. This is useful when there are files in the repository that should not be
available to the Salt fileserver. Can be used in conjunction with svnfs_mountpoint. If
used, then from Salt's perspective the directories above the one specified will be ignored
and the relative path will (for the purposes of svnfs) be considered as the root of the
repo.

svnfs_root: somefolder/otherfolder

Changed in version 2014.7.0: Ability to specify svnfs roots on a per-remote basis was
added. See here for more info.

svnfs_trunk
New in version 2014.7.0.

Default: trunk

Path relative to the root of the repository where the trunk is located. Can also be
configured on a per-remote basis, see here for more info.

svnfs_trunk: trunk

svnfs_branches
New in version 2014.7.0.

Default: branches

Path relative to the root of the repository where the branches are located. Can also be
configured on a per-remote basis, see here for more info.

svnfs_branches: branches

svnfs_tags
New in version 2014.7.0.

Default: tags

Path relative to the root of the repository where the tags are located. Can also be
configured on a per-remote basis, see here for more info.

svnfs_tags: tags

svnfs_saltenv_whitelist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from svnfs_env_whitelist to svnfs_saltenv_whitelist

Default: []

Used to restrict which environments are made available. Can speed up state runs if your
svnfs remotes contain many branches/tags. Full names, globs, and regular expressions are
supported. If using a regular expression, the expression must match the entire minion ID.

If used, only branches/tags which match one of the specified expressions will be exposed
as fileserver environments.

If used in conjunction with svnfs_saltenv_blacklist, then the subset of branches/tags
which match the whitelist but do not match the blacklist will be exposed as fileserver
environments.

svnfs_saltenv_whitelist:
- base
- v1.*
- 'mybranch\d+'

svnfs_saltenv_blacklist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from svnfs_env_blacklist to svnfs_saltenv_blacklist

Default: []

If used, branches/tags which match one of the specified expressions will not be exposed as
fileserver environments.

If used in conjunction with svnfs_saltenv_whitelist, then the subset of branches/tags
which match the whitelist but do not match the blacklist will be exposed as fileserver
environments.

svnfs_saltenv_blacklist:
- base
- v1.*
- 'mybranch\d+'

svnfs_update_interval
New in version 2018.3.0.

Default: 60

This option defines the update interval (in seconds) for svnfs_remotes.

svnfs_update_interval: 120

minionfs: MinionFS Remote File Server Backend
minionfs_env
New in version 2014.7.0.

Default: base

Environment from which MinionFS files are made available.

minionfs_env: minionfs

minionfs_mountpoint
New in version 2014.7.0.

Default: ''

Specifies a path on the salt fileserver from which minionfs files are served.

minionfs_mountpoint: salt://foo/bar

NOTE:
The salt:// protocol designation can be left off (in other words, foo/bar and
salt://foo/bar are equivalent).

minionfs_whitelist
New in version 2014.7.0.

Default: []

Used to restrict which minions' pushed files are exposed via minionfs. If using a regular
expression, the expression must match the entire minion ID.

If used, only the pushed files from minions which match one of the specified expressions
will be exposed.

If used in conjunction with minionfs_blacklist, then the subset of hosts which match the
whitelist but do not match the blacklist will be exposed.

minionfs_whitelist:
- server01
- dev*
- 'mail\d+.mydomain.tld'

minionfs_blacklist
New in version 2014.7.0.

Default: []

Used to restrict which minions' pushed files are exposed via minionfs. If using a regular
expression, the expression must match the entire minion ID.

If used, only the pushed files from minions which match one of the specified expressions
will not be exposed.

If used in conjunction with minionfs_whitelist, then the subset of hosts which match the
whitelist but do not match the blacklist will be exposed.

minionfs_blacklist:
- server01
- dev*
- 'mail\d+.mydomain.tld'

minionfs_update_interval
New in version 2018.3.0.

Default: 60

This option defines the update interval (in seconds) for MinionFS.

NOTE:
Since MinionFS consists of files local to the master, the update process for this
fileserver backend just reaps the cache for this backend.

minionfs_update_interval: 120

azurefs: Azure File Server Backend
New in version 2015.8.0.

See the azurefs documentation for usage examples.

azurefs_update_interval
New in version 2018.3.0.

Default: 60

This option defines the update interval (in seconds) for azurefs.

azurefs_update_interval: 120

s3fs: S3 File Server Backend
New in version 0.16.0.

See the s3fs documentation for usage examples.

s3fs_update_interval
New in version 2018.3.0.

Default: 60

This option defines the update interval (in seconds) for s3fs.

s3fs_update_interval: 120

Pillar Configuration
pillar_roots
Default:

base:
- /srv/pillar

Set the environments and directories used to hold pillar sls data. This configuration is
the same as file_roots:

As of 2017.7.5 and 2018.3.1, it is possible to have __env__ as a catch-all environment.

Example:

pillar_roots:
base:
- /srv/pillar
dev:
- /srv/pillar/dev
prod:
- /srv/pillar/prod
__env__:
- /srv/pillar/others

on_demand_ext_pillar
New in version 2016.3.6,2016.11.3,2017.7.0.

Default: ['libvirt', 'virtkey']

The external pillars permitted to be used on-demand using pillar.ext.

on_demand_ext_pillar:
- libvirt
- virtkey
- git

WARNING:
This will allow minions to request specific pillar data via pillar.ext, and may be
considered a security risk. However, pillar data generated in this way will not affect
the in-memory pillar data, so this risk is limited to instances in which
states/modules/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'

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_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

pillar_opts
Default: False

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

Note that setting this option to True means the master config file will be included in all
minion's pillars. While this makes global configuration of services and systems easy, it
may not be desired if sensitive data is stored in the master configuration.

pillar_opts: False

pillar_safe_render_error
Default: True

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

ext_pillar
The ext_pillar option allows for any number of external pillar interfaces to be called
when populating pillar data. The configuration is based on ext_pillar functions. The
available ext_pillar functions can be found herein:

https://github.com/saltstack/salt/blob/master/salt/pillar

By default, the ext_pillar interface is not configured to run.

Default: []

ext_pillar:
- hiera: /etc/hiera.yaml
- cmd_yaml: cat /etc/salt/yaml
- reclass:
inventory_base_uri: /etc/reclass

There are additional details at salt-pillars

ext_pillar_first
New in version 2015.5.0.

Default: False

This option allows for external pillar sources to be evaluated before pillar_roots.
External pillar data is evaluated separately from pillar_roots pillar data, and then both
sets of pillar data are merged into a single pillar dictionary, so the value of this
config option will have an impact on which key "wins" when there is one of the same name
in both the external pillar data and pillar_roots pillar data. By setting this option to
True, ext_pillar keys will be overridden by pillar_roots, while leaving it as False will
allow ext_pillar keys to override those from pillar_roots.

NOTE:
For a while, this config option did not work as specified above, because of a bug in
Pillar compilation. This bug has been resolved in version 2016.3.4 and later.

ext_pillar_first: False

pillarenv_from_saltenv
Default: False

When set to True, the pillarenv value will assume the value of the effective saltenv when
running states. This essentially makes salt-run pillar.show_pillar saltenv=dev equivalent
to salt-run pillar.show_pillar saltenv=dev pillarenv=dev. If pillarenv is set on the CLI,
it will override this option.

pillarenv_from_saltenv: True

NOTE:
For salt remote execution commands this option should be set in the Minion
configuration instead.

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.

Git External Pillar (git_pillar) Configuration Options
git_pillar_provider
New in version 2015.8.0.

Specify the provider to be used for git_pillar. Must be either pygit2 or gitpython. If
unset, then both will be tried in that same order, and the first one with a compatible
version installed will be the provider that is used.

git_pillar_provider: gitpython

git_pillar_base
New in version 2015.8.0.

Default: master

If the desired branch matches this value, and the environment is omitted from the
git_pillar configuration, then the environment for that git_pillar remote will be base.
For example, in the configuration below, the foo branch/tag would be assigned to the base
environment, while bar would be mapped to the bar environment.

git_pillar_base: foo

ext_pillar:
- git:
- foo https://mygitserver/git-pillar.git
- bar https://mygitserver/git-pillar.git

git_pillar_branch
New in version 2015.8.0.

Default: master

If the branch is omitted from a git_pillar remote, then this branch will be used instead.
For example, in the configuration below, the first two remotes would use the pillardata
branch/tag, while the third would use the foo branch/tag.

git_pillar_branch: pillardata

ext_pillar:
- git:
- https://mygitserver/pillar1.git
- https://mygitserver/pillar2.git:
- root: pillar
- foo https://mygitserver/pillar3.git

git_pillar_env
New in version 2015.8.0.

Default: '' (unset)

Environment to use for git_pillar remotes. This is normally derived from the branch/tag
(or from a per-remote env parameter), but if set this will override the process of
deriving the env from the branch/tag name. For example, in the configuration below the foo
branch would be assigned to the base environment, while the bar branch would need to
explicitly have bar configured as its environment to keep it from also being mapped to the
base environment.

git_pillar_env: base

ext_pillar:
- git:
- foo https://mygitserver/git-pillar.git
- bar https://mygitserver/git-pillar.git:
- env: bar

For this reason, this option is recommended to be left unset, unless the use case calls
for all (or almost all) of the git_pillar remotes to use the same environment irrespective
of the branch/tag being used.

git_pillar_root
New in version 2015.8.0.

Default: ''

Path relative to the root of the repository where the git_pillar top file and SLS files
are located. In the below configuration, the pillar top file and SLS files would be looked
for in a subdirectory called pillar.

git_pillar_root: pillar

ext_pillar:
- git:
- master https://mygitserver/pillar1.git
- master https://mygitserver/pillar2.git

NOTE:
This is a global option. If only one or two repos need to have their files sourced from
a subdirectory, then git_pillar_root can be omitted and the root can be specified on a
per-remote basis, like so:

ext_pillar:
- git:
- master https://mygitserver/pillar1.git
- master https://mygitserver/pillar2.git:
- root: pillar

In this example, for the first remote the top file and SLS files would be looked for in
the root of the repository, while in the second remote the pillar data would be
retrieved from the pillar subdirectory.

git_pillar_ssl_verify
New in version 2015.8.0.

Changed in version 2016.11.0.

Default: False

Specifies whether or not to ignore SSL certificate errors when contacting the remote
repository. The False setting is useful if you're using a git repo that uses a self-signed
certificate. However, keep in mind that setting this to anything other True is a
considered insecure, and using an SSH-based transport (if available) may be a better
option.

In the 2016.11.0 release, the default config value changed from False to True.

git_pillar_ssl_verify: True

NOTE:
pygit2 only supports disabling SSL verification in versions 0.23.2 and newer.

git_pillar_global_lock
New in version 2015.8.9.

Default: True

When set to False, if there is an update/checkout lock for a git_pillar remote and the pid
written to it is not running on the master, the lock file will be automatically cleared
and a new lock will be obtained. When set to True, Salt will simply log a warning when
there is an lock present.

On single-master deployments, disabling this option can help automatically deal with
instances where the master was shutdown/restarted during the middle of a git_pillar
update/checkout, leaving a lock in place.

However, on multi-master deployments with the git_pillar cachedir shared via GlusterFS,
nfs, or another network filesystem, it is strongly recommended not to disable this option
as doing so will cause lock files to be removed if they were created by a different
master.

# Disable global lock
git_pillar_global_lock: False

git_pillar_includes
New in version 2017.7.0.

Default: True

Normally, when processing git_pillar remotes, if more than one repo under the same git
section in the ext_pillar configuration refers to the same pillar environment, then each
repo in a given environment will have access to the other repos' files to be referenced in
their top files. However, it may be desirable to disable this behavior. If so, set this
value to False.

For a more detailed examination of how includes work, see this explanation from the
git_pillar documentation.

git_pillar_includes: False

git_pillar_update_interval
New in version 3000.

Default: 60

This option defines the default update interval (in seconds) for git_pillar remotes. The
update is handled within the global loop, hence git_pillar_update_interval should be a
multiple of loop_interval.

git_pillar_update_interval: 120

Git External Pillar Authentication Options
These parameters only currently apply to the pygit2 git_pillar_provider. Authentication
works the same as it does in gitfs, as outlined in the GitFS Walkthrough, though the
global configuration options are named differently to reflect that they are for git_pillar
instead of gitfs.

git_pillar_user
New in version 2015.8.0.

Default: ''

Along with git_pillar_password, is used to authenticate to HTTPS remotes.

git_pillar_user: git

git_pillar_password
New in version 2015.8.0.

Default: ''

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: mypassword

git_pillar_insecure_auth
New in version 2015.8.0.

Default: False

By default, Salt will not authenticate to an HTTP (non-HTTPS) remote. This parameter
enables authentication over HTTP. Enable this at your own risk.

git_pillar_insecure_auth: True

git_pillar_pubkey
New in version 2015.8.0.

Default: ''

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

git_pillar_pubkey: /path/to/key.pub

git_pillar_privkey
New in version 2015.8.0.

Default: ''

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

git_pillar_privkey: /path/to/key

git_pillar_passphrase
New in version 2015.8.0.

Default: ''

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

git_pillar_passphrase: mypassphrase

git_pillar_refspecs
New in version 2017.7.0.

Default: ['+refs/heads/*:refs/remotes/origin/*', '+refs/tags/*:refs/tags/*']

When fetching from remote repositories, by default Salt will fetch branches and tags. This
parameter can be used to override the default and specify alternate refspecs to be
fetched. This parameter works similarly to its GitFS counterpart, in that it can be
configured both globally and for individual remotes.

git_pillar_refspecs:
- '+refs/heads/*:refs/remotes/origin/*'
- '+refs/tags/*:refs/tags/*'
- '+refs/pull/*/head:refs/remotes/origin/pr/*'
- '+refs/pull/*/merge:refs/remotes/origin/merge/*'

git_pillar_verify_config
New in version 2017.7.0.

Default: True

By default, as the master starts it performs some sanity checks on the configured
git_pillar repositories. If any of these sanity checks fail (such as when an invalid
configuration is used), the master daemon will abort.

To skip these sanity checks, set this option to False.

git_pillar_verify_config: False

Pillar Merging Options
pillar_source_merging_strategy
New in version 2014.7.0.

Default: smart

The pillar_source_merging_strategy option allows you to configure merging strategy between
different sources. It accepts 5 values:

· none:

It will not do any merging at all and only parse the pillar data from the passed
environment and 'base' if no environment was specified.

New in version 2016.3.4.

· recurse:

It will recursively merge data. For example, theses 2 sources:

foo: 42
bar:
element1: True

bar:
element2: True
baz: quux

will be merged as:

foo: 42
bar:
element1: True
element2: True
baz: quux

· aggregate:

instructs aggregation of elements between sources that use the #!yamlex renderer.

For example, these two documents:

foo: 42
bar: !aggregate {
element1: True
}
baz: !aggregate quux

bar: !aggregate {
element2: True
}
baz: !aggregate quux2

will be merged as:

foo: 42
bar:
element1: True
element2: True
baz:
- quux
- quux2

NOTE:
This requires that the render pipeline defined in the renderer master configuration
ends in yamlex.

· overwrite:

Will use the behaviour of the 2014.1 branch and earlier.

Overwrites elements according the order in which they are processed.

First pillar processed:

A:
first_key: blah
second_key: blah

Second pillar processed:

A:
third_key: blah
fourth_key: blah

will be merged as:

A:
third_key: blah
fourth_key: blah

· smart (default):

Guesses the best strategy based on the "renderer" setting.

NOTE:
In order for yamlex based features such as !aggregate to work as expected across
documents using the default smart merge strategy, the renderer config option must be
set to jinja|yamlex or similar.

pillar_merge_lists
New in version 2015.8.0.

Default: False

Recursively merge lists by aggregating them instead of replacing them.

pillar_merge_lists: False

pillar_includes_override_sls
New in version 2017.7.6,2018.3.1.

Default: False

Prior to version 2017.7.3, keys from pillar includes would be merged on top of the pillar
SLS. Since 2017.7.3, the includes are merged together and then the pillar SLS is merged on
top of that.

Set this option to True to return to the old behavior.

pillar_includes_override_sls: True

Pillar Cache Options
pillar_cache
New in version 2015.8.8.

Default: False

A master can cache pillars locally to bypass the expense of having to render them for each
minion on every request. This feature should only be enabled in cases where pillar
rendering time is known to be unsatisfactory and any attendant security concerns about
storing pillars in a master cache have been addressed.

When enabling this feature, be certain to read through the additional pillar_cache_*
configuration options to fully understand the tunable parameters and their implications.

pillar_cache: False

NOTE:
Setting pillar_cache: True has no effect on targeting minions with pillar.

pillar_cache_ttl
New in version 2015.8.8.

Default: 3600

If and only if a master has set pillar_cache: True, the cache TTL controls the amount of
time, in seconds, before the cache is considered invalid by a master and a fresh pillar is
recompiled and stored.

pillar_cache_backend
New in version 2015.8.8.

Default: disk

If an only if a master has set pillar_cache: True, one of several storage providers can be
utilized:

· disk (default):

The default storage backend. This caches rendered pillars to the master cache. Rendered
pillars are serialized and deserialized as msgpack structures for speed. Note that
pillars are stored UNENCRYPTED. Ensure that the master cache has permissions set
appropriately (sane defaults are provided).

· memory [EXPERIMENTAL]:

An optional backend for pillar caches which uses a pure-Python in-memory data structure
for maximal performance. There are several caveats, however. First, because each master
worker contains its own in-memory cache, there is no guarantee of cache consistency
between minion requests. This works best in situations where the pillar rarely if ever
changes. Secondly, and perhaps more importantly, this means that unencrypted pillars
will be accessible to any process which can examine the memory of the salt-master! This
may represent a substantial security risk.

pillar_cache_backend: disk

Master Reactor Settings
reactor
Default: []

Defines a salt reactor. See the Reactor documentation for more information.

reactor:
- 'salt/minion/*/start':
- salt://reactor/startup_tasks.sls

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

Salt-API Master Settings
There are some settings for salt-api that can be configured on the Salt Master.

api_logfile
Default: /var/log/salt/api

The logfile location for salt-api.

api_logfile: /var/log/salt/api

api_pidfile
Default: /var/run/salt-api.pid

If this master will be running salt-api, specify the pidfile of the salt-api daemon.

api_pidfile: /var/run/salt-api.pid

rest_timeout
Default: 300

Used by salt-api for the master requests timeout.

rest_timeout: 300

Syndic Server Settings
A Salt syndic is a Salt master used to pass commands from a higher Salt master to minions
below the syndic. Using the syndic is simple. If this is a master that will have syndic
servers(s) below it, set the order_masters setting to True.

If this is a master that will be running a syndic daemon for passthrough the syndic_master
setting needs to be set to the location of the master server.

Do not forget that, in other words, it means that it shares with the local minion its ID
and PKI directory.

order_masters
Default: False

Extra data needs to be sent with publications if the master is controlling a lower level
master via a syndic minion. If this is the case the order_masters value must be set to
True

order_masters: False

syndic_master
Changed in version 2016.3.5,2016.11.1: Set default higher level master address.

Default: masterofmasters

If this master will be running the salt-syndic to connect to a higher level master,
specify the higher level master with this configuration value.

syndic_master: masterofmasters

You can optionally connect a syndic to multiple higher level masters by setting the
syndic_master value to a list:

syndic_master:
- masterofmasters1
- masterofmasters2

Each higher level master must be set up in a multi-master configuration.

syndic_master_port
Default: 4506

If this master will be running the salt-syndic to connect to a higher level master,
specify the higher level master port with this configuration value.

syndic_master_port: 4506

syndic_pidfile
Default: /var/run/salt-syndic.pid

If this master will be running the salt-syndic to connect to a higher level master,
specify the pidfile of the syndic daemon.

syndic_pidfile: /var/run/syndic.pid

syndic_log_file
Default: /var/log/salt/syndic

If this master will be running the salt-syndic to connect to a higher level master,
specify the log file of the syndic daemon.

syndic_log_file: /var/log/salt-syndic.log

syndic_failover
New in version 2016.3.0.

Default: random

The behaviour of the multi-syndic when connection to a master of masters failed. Can
specify random (default) or ordered. If set to random, masters will be iterated in random
order. If ordered is specified, the configured order will be used.

syndic_failover: random

syndic_wait
Default: 5

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

syndic_forward_all_events
New in version 2017.7.0.

Default: False

Option on multi-syndic or single when connected to multiple masters to be able to send
events to all connected masters.

syndic_forward_all_events: False

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.

peer
Default: {}

The configuration uses regular expressions to match minions and then a list of regular
expressions to match functions. The following will allow the minion authenticated as
foo.example.com to execute functions from the test and pkg modules.

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

This will allow all minions to execute all commands:

peer:
.*:
- .*

This is not recommended, since it would allow anyone who gets root on any single minion to
instantly have root on all of the minions!

By adding an additional layer you can limit the target hosts in addition to the accessible
commands:

peer:
foo.example.com:
'db*':
- test.*
- pkg.*

peer_run
Default: {}

The peer_run option is used to open up runners on the master to access from the minions.
The peer_run configuration matches the format of the peer configuration.

The following example would allow foo.example.com to execute the manage.up runner:

peer_run:
foo.example.com:
- manage.up

Master Logging Settings
log_file
Default: /var/log/salt/master

The master log can be sent to a regular file, local path name, or network location. See
also log_file.

Examples:

log_file: /var/log/salt/master

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_logfile. 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 config since the
logging system is loaded before the master config.

Console log colors are specified by these additional formatters:

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

Since it is desirable to include the surrounding brackets, '[' and ']', in the coloring
of the messages, these color formatters also include padding as well. Color LogRecord
attributes are only available for console logging.

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

log_fmt_logfile
Default: %(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(message)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

The maximum number of bytes a single log file may contain before it is rotated. A value
of 0 disables this feature. Currently only supported on Windows. On other platforms, use
an external tool such as 'logrotate' to manage log files. log_rotate_max_bytes

log_rotate_backup_count
Default: 0

The number of backup files to keep when rotating log files. Only used if
log_rotate_max_bytes is greater than 0. Currently only supported on Windows. On other
platforms, use an external tool such as 'logrotate' to manage log files.
log_rotate_backup_count

Node Groups
nodegroups
Default: {}

Node groups allow for logical groupings of minion nodes. A group consists of a group name
and a compound target.

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'

More information on using nodegroups can be found here.

Range Cluster Settings
range_server
Default: 'range:80'

The range server (and optional port) that serves your cluster information
https://github.com/ytoolshed/range/wiki/%22yamlfile%22-module-file-spec

range_server: range:80

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

1. The master 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 master config file, and any options defined in include would override both.

default_include
Default: master.d/*.conf

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

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

include
Default: not defined

The master can include configuration from other files. To enable this, pass a list of
paths to this option. The paths can be either relative or absolute; if relative, they are
considered to be relative to the directory the main minion configuration file lives in.
Paths can make use of shell-style globbing. If no files are matched by a path passed to
this option then the master will log a warning message.

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

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

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

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

Windows Software Repo Settings
winrepo_provider
New in version 2015.8.0.

Specify the provider to be used for winrepo. Must be either pygit2 or gitpython. If unset,
then both will be tried in that same order, and the first one with a compatible version
installed will be the provider that is used.

winrepo_provider: gitpython

winrepo_dir
Changed in version 2015.8.0: Renamed from win_repo to winrepo_dir.

Default: /srv/salt/win/repo

Location on the master where the winrepo_remotes are checked out for pre-2015.8.0 minions.
2015.8.0 and later minions use winrepo_remotes_ng instead.

winrepo_dir: /srv/salt/win/repo

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

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

Location on the master where the winrepo_remotes_ng are checked out for 2015.8.0 and later
minions.

winrepo_dir_ng: /srv/salt/win/repo-ng

winrepo_cachefile
Changed in version 2015.8.0: Renamed from win_repo_mastercachefile to winrepo_cachefile

NOTE:
2015.8.0 and later minions do not use this setting since the cachefile is now generated
by the minion.

Default: winrepo.p

Path relative to winrepo_dir where the winrepo cache should be created.

winrepo_cachefile: winrepo.p

winrepo_remotes
Changed in version 2015.8.0: Renamed from win_gitrepos to winrepo_remotes.

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

List of git repositories to checkout and include in the winrepo for pre-2015.8.0 minions.
2015.8.0 and later minions use winrepo_remotes_ng instead.

winrepo_remotes:
- https://github.com/saltstack/salt-winrepo.git

To specify a specific revision of the repository, prepend a commit ID to the URL of the
repository:

winrepo_remotes:
- '<commit_id> https://github.com/saltstack/salt-winrepo.git'

Replace <commit_id> with the SHA1 hash of a commit ID. Specifying a commit ID is useful in
that it allows one to revert back to a previous version in the event that an error is
introduced in the latest revision of the repo.

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'

winrepo_branch
New in version 2015.8.0.

Default: master

If the branch is omitted from a winrepo remote, then this branch will be used instead. For
example, in the configuration below, the first two remotes would use the winrepo
branch/tag, while the third would use the foo branch/tag.

winrepo_branch: winrepo

winrepo_remotes:
- https://mygitserver/winrepo1.git
- https://mygitserver/winrepo2.git:
- foo https://mygitserver/winrepo3.git

winrepo_ssl_verify
New in version 2015.8.0.

Changed in version 2016.11.0.

Default: False

Specifies whether or not to ignore SSL certificate errors when contacting the remote
repository. The False setting is useful if you're using a git repo that uses a
self-signed certificate. However, keep in mind that setting this to anything other True is
a considered insecure, and using an SSH-based transport (if available) may be a better
option.

In the 2016.11.0 release, the default config value changed from False to True.

winrepo_ssl_verify: True

Winrepo Authentication Options
These parameters only currently apply to the pygit2 winrepo_provider. Authentication works
the same as it does in gitfs, as outlined in the GitFS Walkthrough, though the global
configuration options are named differently to reflect that they are for winrepo instead
of gitfs.

winrepo_user
New in version 2015.8.0.

Default: ''

Along with winrepo_password, is used to authenticate to HTTPS remotes.

winrepo_user: git

winrepo_password
New in version 2015.8.0.

Default: ''

Along with winrepo_user, is used to authenticate to HTTPS remotes. This parameter is not
required if the repository does not use authentication.

winrepo_password: mypassword

winrepo_insecure_auth
New in version 2015.8.0.

Default: False

By default, Salt will not authenticate to an HTTP (non-HTTPS) remote. This parameter
enables authentication over HTTP. Enable this at your own risk.

winrepo_insecure_auth: True

winrepo_pubkey
New in version 2015.8.0.

Default: ''

Along with winrepo_privkey (and optionally winrepo_passphrase), is used to authenticate to
SSH remotes.

winrepo_pubkey: /path/to/key.pub

winrepo_privkey
New in version 2015.8.0.

Default: ''

Along with winrepo_pubkey (and optionally winrepo_passphrase), is used to authenticate to
SSH remotes.

winrepo_privkey: /path/to/key

winrepo_passphrase
New in version 2015.8.0.

Default: ''

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

winrepo_passphrase: mypassphrase

winrepo_refspecs
New in version 2017.7.0.

Default: ['+refs/heads/*:refs/remotes/origin/*', '+refs/tags/*:refs/tags/*']

When fetching from remote repositories, by default Salt will fetch branches and tags. This
parameter can be used to override the default and specify alternate refspecs to be
fetched. This parameter works similarly to its GitFS counterpart, in that it can be
configured both globally and for individual remotes.

winrepo_refspecs:
- '+refs/heads/*:refs/remotes/origin/*'
- '+refs/tags/*:refs/tags/*'
- '+refs/pull/*/head:refs/remotes/origin/pr/*'
- '+refs/pull/*/merge:refs/remotes/origin/merge/*'

Configure Master on Windows
The master on Windows requires no additional configuration. You can modify the master
configuration by creating/editing the master config file located at c:\salt\conf\master.
The same configuration options available on Linux are available in Windows, as long as
they apply. For example, SSH options wouldn't apply in Windows. The main differences are
the file paths. If you are familiar with common salt paths, the following table may be
useful:

┌────────────┬───────┬───────────────┐
│linux Paths │ │ Windows Paths │
├────────────┼───────┼───────────────┤
│/etc/salt │ <---> │ c:\salt\conf │
├────────────┼───────┼───────────────┤
│/ │ <---> │ c:\salt │
└────────────┴───────┴───────────────┘

So, for example, the master config file in Linux is /etc/salt/master. In Windows the
master config file is c:\salt\conf\master. The Linux path /etc/salt becomes c:\salt\conf
in Windows.

Common File Locations
┌───────────────────────────────┬─────────────────────────────────┐
│Linux Paths │ Windows Paths │
├───────────────────────────────┼─────────────────────────────────┤
│conf_file: /etc/salt/master │ conf_file: c:\salt\conf\master │
├───────────────────────────────┼─────────────────────────────────┤
│log_file: /var/log/salt/master │ log_file: │
│ │ c:\salt\var\log\salt\master │
├───────────────────────────────┼─────────────────────────────────┤
│pidfile: │ pidfile: │
│/var/run/salt-master.pid │ c:\salt\var\run\salt-master.pid │
└───────────────────────────────┴─────────────────────────────────┘

Common Directories
───────────────────────────────────────────────────────────────────────────
Linux Paths Windows Paths
───────────────────────────────────────────────────────────────────────────
cachedir: /var/cache/salt/master cachedir:
c:\salt\var\cache\salt\master
───────────────────────────────────────────────────────────────────────────
extension_modules: c:\salt\var\cache\salt\master\extmods
/var/cache/salt/master/extmods
───────────────────────────────────────────────────────────────────────────
pki_dir: /etc/salt/pki/master pki_dir: c:\salt\conf\pki\master
───────────────────────────────────────────────────────────────────────────
root_dir: / root_dir: c:\salt
───────────────────────────────────────────────────────────────────────────
sock_dir: /var/run/salt/master sock_dir: c:\salt\var\run\salt\master
┌─────────────────────────────────┬───────────────────────────────────────┐
│ │ │
Roots │ │ │
Binary file (standard input) matches