About Salt¶

Built on Python, Salt is an event-driven automation tool and framework to deploy, configure, and manage complex IT systems. Use Salt to automate common infrastructure administration tasks and ensure that all the components of your infrastructure are operating in a consistent desired state.

Salt has many possible uses, including configuration management, which involves:

Salt is ideal for configuration management because it is pluggable, customizable, and plays well with many existing technologies. Salt enables you to deploy and manage applications that use any tech stack running on nearly any operating system, including different types of network devices such as switches and routers from a variety of vendors.

In addition to configuration management Salt can also:

About our sponsors¶

Salt powers VMware's vRealize Automation SaltStack Config, and can be found under the hood of products from Juniper, Cisco, Cloudflare, Nutanix, SUSE, and Tieto, to name a few.

The original sponsor of our community, SaltStack, was acquired by VMware in 2020. The Salt Project remains an open source ecosystem that VMware supports and contributes to. VMware ensures the code integrity and quality of the Salt modules by acting as the official sponsor and manager of the Salt project. Many of the core Salt Project contributors are also VMware employees. This team carefully reviews and enhances the Salt modules to ensure speed, quality, and security.

Download and install Salt¶

Salt is tested and packaged to run on CentOS, Debian, RHEL, Ubuntu, MacOS, Windows, and more. Download Salt and get started now. See supported operating systems for more information.

To download and install Salt, see: * The Salt install guide * Salt Project repository

Technical support¶

Report bugs or problems using Salt by opening an issue: https://github.com/saltstack/salt/issues

To join our community forum where you can exchange ideas, best practices, discuss technical support questions, and talk to project maintainers, join our Slack workspace: Salt Project Community Slack

Salt Project documentation¶

Installation instructions, tutorials, in-depth API and module documentation:

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.

Join our community¶

Salt is built by the Salt Project community, which includes more than 3,000 contributors working in roles just like yours. This well-known and trusted community works together to improve the underlying technology and extend Salt by creating a variety of execution and state modules to accomplish the most common tasks or solve the most important problems that people in your role are likely to face.

If you want to help extend Salt or solve a problem with Salt, you can join our community and contribute today.

Please be sure to review our Code of Conduct. Also, check out some of our community resources including:

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, Jimmy Chunga 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

The 30 second summary¶

Salt is:

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:

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.

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:

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:

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:

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:

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:

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

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:

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.

Environment setup¶

To hack on Salt or the docs you're going to need to set up your development environment. If you already have a workflow that you're comfortable with, you can use that, but otherwise this is an opinionated guide for setting up your dev environment. Follow these steps and you'll end out with a functioning dev environment and be able to submit your first PR.

This guide assumes at least a passing familiarity with Git, a common version control tool used across many open source projects, and is necessary for contributing to Salt. For an introduction to Git, watch Salt Docs Clinic - Git For the True Beginner. Because of its widespread use, there are many resources for learning more about Git. One popular resource is the free online book Learn Git in a Month of Lunches.

pyenv, Virtual Environments, and you¶

We recommend pyenv, since it allows installing multiple different Python versions, which is important for testing Salt across all the versions of Python that we support.

On Linux¶

Install pyenv:

git clone https://github.com/pyenv/pyenv.git ~/.pyenv
export PATH="$HOME/.pyenv/bin:$PATH"
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

On Mac¶

Install pyenv using brew:

brew update
brew install pyenv
brew install pyenv-virtualenv

----

Now add pyenv to your .bashrc:

echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
pyenv init 2>> ~/.bashrc
pyenv virtualenv-init 2>> ~/.bashrc

For other shells, see the pyenv instructions.

Go ahead and restart your shell. Now you should be able to install a new version of Python:

pyenv install 3.7.0

If that fails, don't panic! You're probably just missing some build dependencies. Check out pyenv common build problems.

Now that you've got your version of Python installed, you can create a new virtual environment with this command:

pyenv virtualenv 3.7.0 salt

Then activate it:

pyenv activate salt

Sweet! Now you're ready to clone Salt so you can start hacking away! If you get stuck at any point, check out the resources at the beginning of this guide. IRC and Slack are particularly helpful places to go.

Get the source!¶

Salt uses the fork and clone workflow for Git contributions. See Using the Fork-and-Branch Git Workflow for how to implement it. But if you just want to hurry and get started you can go ahead and follow these steps:

Clones are so shallow. Well, this one is anyway:

git clone --depth=1 --origin salt https://github.com/saltstack/salt.git

This creates a shallow clone of Salt, which should be fast. Most of the time that's all you'll need, and you can start building out other commits as you go. If you really want all 108,300+ commits you can just run git fetch --unshallow. Then go make a sandwich because it's gonna be a while.

You're also going to want to head over to GitHub and create your own fork of Salt. Once you've got that set up you can add it as a remote:

git remote add yourname <YOUR SALT REMOTE>

If you use your name to refer to your fork, and salt to refer to the official Salt repo you'll never get upstream or origin confused.

NOTE:

Set up pre-commit and nox¶

Here at Salt we use pre-commit and nox to make it easier for contributors to get quick feedback, for quality control, and to increase the chance that your merge request will get reviewed and merged. Nox enables us to run multiple different test configurations, as well as other common tasks. You can think of it as Make with superpowers. Pre-commit does what it sounds like: it configures some Git pre-commit hooks to run black for formatting, isort for keeping our imports sorted, and pylint to catch issues like unused imports, among others. You can easily install them in your virtualenv with:

python -m pip install pre-commit nox
pre-commit install

WARNING:

Now before each commit, it will ensure that your code at least looks right before you open a pull request. And with that step, it's time to start hacking on Salt!

Set up imagemagick¶

One last prerequisite is to have imagemagick installed, as it is required by Sphinx for generating the HTML documentation.

# On Mac, via homebrew
brew install imagemagick

# Example Linux installation: Debian-based
sudo apt install imagemagick

Salt issues¶

Create your own¶

Perhaps you've come to this guide because you found a problem in Salt, and you've diagnosed the cause. Maybe you need some help figuring out the problem. In any case, creating quality bug reports is a great way to contribute to Salt even if you lack the skills, time, or inclination to fix it yourself. If that's the case, head on over to Salt's issue tracker on GitHub.

Creating a good report can take a little bit of time - but every minute you invest in making it easier for others to reproduce and understand your issue is time well spent. The faster someone can understand your issue, the faster it will be able to get fixed correctly.

The thing that every issue needs goes by many names, but one at least as good as any other is MCVE - Minimum Complete Verifiable Example.

In a nutshell:

Slow is smooth, and smooth is fast - it may feel like you're taking a long time to create your issue if you're creating a proper MCVE, but a MCVE eliminates back and forth required to reproduce/verify the issue so someone can actually create a fix.

Pick an issue¶

If you don't already have an issue in mind, you can search for help wanted issues. If you also search for good first issue then you should be able to find some issues that are good for getting started contributing to Salt. Documentation issues are also good starter issues. When you find an issue that catches your eye (or one of your own), it's a good idea to comment on the issue and mention that you're working on it. Good communication is key to collaboration - so if you don't have time to complete work on the issue, just leaving some information about when you expect to pick things up again is a great idea!

Hacking away¶

Salt, tests, documentation, and you¶

Before approving code contributions, Salt requires:

Documentation fixes just require correct documentation.

What if I don't write tests or docs?¶

If you aren't into writing documentation or tests, we still welcome your contributions! But your PR will be labeled Needs Testcase and Help Wanted until someone can get to write the tests/documentation. Of course, if you have a desire but just lack the skill we are more than happy to collaborate and help out! There's the documentation working group and the testing working group. We also regularly stream our test clinic live on Twitch every Tuesday afternoon and Thursday morning, Central Time. If you'd like specific help with tests, bring them to the clinic. If no community members need help, you can also just watch tests written in real time.

Documentation¶

Salt uses both docstrings, as well as normal reStructuredText files in the salt/doc folder for documentation. Sphinx is used to generate the documentation, and does require imagemagick. See Set up imagemagick for more information.

Before submitting a documentation PR, it helps to first build the Salt docs locally on your machine and preview them. Local previews helps you:

To set up your local environment to preview the core Salt and module documentation:

sudo apt-get update
sudo apt-get install -y enchant-2 git gcc imagemagick make zlib1g-dev libc-dev libffi-dev g++ libxml2 libxml2-dev libxslt-dev libcurl4-openssl-dev libssl-dev libgnutls28-dev xz-utils inkscape

rm -rf .nox

pyenv install 3.7.15
pyenv virtualenv 3.7.15 salt-docs
echo 'salt-docs' > .python-version

pyenv exec pip install -U pip setuptools wheel

pyenv exec pip install nox

Since we use nox, you can build your docs and view them in your browser with this one-liner:

python -m nox -e 'docs-html(compress=False, clean=False)'; cd doc/_build/html; python -m webbrowser http://localhost:8000/contents.html; python -m http.server

The first time you build the docs, it will take a while because there are a lot of modules. Maybe you should go grab some dessert if you already finished that sandwich. But once nox and Sphinx are done building the docs, python should launch your default browser with the URL http://localhost:8000/contents.html. Now you can navigate to your docs and ensure your changes exist. If you make changes, you can simply run this:

cd -; python -m nox -e 'docs-html(compress=False, clean=False)'; cd doc/_build/html; python -m http.server

And then refresh your browser to get your updated docs. This one should be quite a bit faster since Sphinx won't need to rebuild everything.

Alternatively, you could build the docs on your local machine and then preview the build output. To build the docs locally:

pyenv exec nox -e 'docs-html(compress=False, clean=True)'

The output from this command will put the preview files in: doc > _build > html.

If your change is a docs-only change, you can go ahead and commit/push your code and open a PR. You can indicate that it's a docs-only change by adding [Documentation] to the title of your PR. Otherwise, you'll want to write some tests and code.

Running development Salt¶

Note: If you run into any issues in this section, check the Troubleshooting section.

If you're going to hack on the Salt codebase you're going to want to be able to run Salt locally. The first thing you need to do is install Salt as an editable pip install:

python -m pip install -e .

This will let you make changes to Salt without having to re-install it.

After all of the dependencies and Salt are installed, it's time to set up the config for development. Typically Salt runs as root, but you can specify which user to run as. To configure that, just copy the master and minion configs. We have .gitignore setup to ignore the local/ directory, so we can put all of our personal files there.

mkdir -p local/etc/salt/

Create a master config file as local/etc/salt/master:

cat <<EOF >local/etc/salt/master
user: $(whoami)
root_dir: $PWD/local/
publish_port: 55505
ret_port: 55506
EOF

And a minion config as local/etc/salt/minion:

cat <<EOF >local/etc/salt/minion
user: $(whoami)
root_dir: $PWD/local/
master: localhost
id: saltdev
master_port: 55506
EOF

Now you can start your Salt master and minion, specifying the config dir.

salt-master --config-dir=local/etc/salt/ --log-level=debug --daemon
salt-minion --config-dir=local/etc/salt/ --log-level=debug --daemon

Now you should be able to accept the minion key:

salt-key -c local/etc/salt -Ay

And check that your master/minion are communicating:

salt -c local/etc/salt \* test.version

Rather than running test.version from your master, you can run it from the minion instead:

salt-call -c local/etc/salt test.version

Note that you're running salt-call instead of salt, and you're not specifying the minion (\*), but if you're running the dev version then you still will need to pass in the config dir. Now that you've got Salt running, you can hack away on the Salt codebase!

If you need to restart Salt for some reason, if you've made changes and they don't appear to be reflected, this is one option:

kill -INT $(pgrep salt-master)
kill -INT $(pgrep salt-minion)

If you'd rather not use kill, you can have a couple of terminals open with your salt virtualenv activated and omit the --daemon argument. Salt will run in the foreground, so you can just use ctrl+c to quit.

Test first? Test last? Test meaningfully!¶

You can write tests first or tests last, as long as your tests are meaningful and complete! Typically the best tests for Salt are going to be unit tests. Testing is a whole topic on its own, But you may also want to write functional or integration tests. You'll find those in the salt/tests directory.

When you're thinking about tests to write, the most important thing to keep in mind is, “What, exactly, am I testing?” When a test fails, you should know:

If you can't answer those questions then you might need to refactor your tests.

When you're running tests locally, you should make sure that if you remove your code changes your tests are failing. If your tests aren't failing when you haven't yet made changes, then it's possible that you're testing the wrong thing.

But whether you adhere to TDD/BDD, or you write your code first and your tests last, ensure that your tests are meaningful.

Running tests¶

As previously mentioned, we use nox, and that's how we run our tests. You should have it installed by this point but if not you can install it with this:

python -m pip install nox

Now you can run your tests:

python -m nox -e "test-3(coverage=False)" -- tests/unit/cli/test_batch.py

It's a good idea to install espeak or use say on Mac if you're running some long-running tests. You can do something like this:

python -m nox -e "test-3(coverage=False)" -- tests/unit/cli/test_batch.py; espeak "Tests done, woohoo!"

That way you don't have to keep monitoring the actual test run.

python -m nox -e "test-3(coverage=False)" -- --core-tests

You can enable or disable test groups locally by passing their respected flag:

In Your PR, you can enable or disable test groups by setting a label. All fast, slow, and core tests specified in the change file will always run.

Changelog and commit!¶

When you write your commit message you should use imperative style. Do this:

Don't do this:

But that advice is backwards for the changelog. We follow the keepachangelog approach for our changelog, and use towncrier to generate it for each release. As a contributor, all that means is that you need to add a file to the salt/changelog directory, using the <issue #>.<type> format. For instanch, if you fixed issue 123, you would do:

echo "Made sys.doc inform when no minions return" > changelog/123.fixed

And that's all that would go into your file. When it comes to your commit message, it's usually a good idea to add other information, such as

This will also help you out, because when you go to create the PR it will automatically insert the body of your commit messages.

Pull request time!¶

Once you've done all your dev work and tested locally, you should check out our PR guidelines. After you read that page, it's time to open a new PR. Fill out the PR template - you should have updated or created any necessary docs, and written tests if you're providing a code change. When you submit your PR, we have a suite of tests that will run across different platforms to help ensure that no known bugs were introduced.

Now what?¶

You've made your changes, added documentation, opened your PR, and have passing tests… now what? When can you expect your code to be merged?

When you open your PR, a reviewer will get automatically assigned. If your PR is submitted during the week you should be able to expect some kind of communication within that business day. If your tests are passing and we're not in a code freeze, ideally your code will be merged that week or month. If you haven't heard from your assigned reviewer, ping them on GitHub, irc, or Community Slack.

It's likely that your reviewer will leave some comments that need addressing - it may be a style change, or you forgot a changelog entry, or need to update the docs. Maybe it's something more fundamental - perhaps you encountered the rare case where your PR has a much larger scope than initially assumed.

Whatever the case, simply make the requested changes (or discuss why the requests are incorrect), and push up your new commits. If your PR is open for a significant period of time it may be worth rebasing your changes on the most recent changes to Salt. If you need help, the previously linked Git resources will be valuable.

But if, for whatever reason, you're not interested in driving your PR to completion then just note that in your PR. Something like, “I'm not interested in writing docs/tests, I just wanted to provide this fix - someone else will need to complete this PR.” If you do that then we'll add a “Help Wanted” label and someone will be able to pick up the PR, make the required changes, and it can eventually get merged in.

In any case, now that you have a PR open, congrats! You're a Salt developer! You rock!

Troubleshooting¶

zmq.core.error.ZMQError¶

Once the minion starts, you may see an error like the following:

::

This means that the path to the socket the minion is using is too long. This is a system limitation, so the only workaround is to reduce the length of this path. This can be done in a couple different ways:

NOTE: The socket path is limited to 107 characters on Solaris and Linux, and 103 characters on BSD-based systems.

No permissions to access ...¶

If you forget to pass your config path to any of the salt* commands, you might see

No permissions to access "/var/log/salt/master", are you running as the
correct user?

Just pass -c local/etc/salt (or whatever you named it)

File descriptor limit¶

You might need to raise your file descriptor limit. You can check it with:

ulimit -n

If the value is less than 3072, you should increase it with:

ulimit -n 3072
# For c-shell:
limit descriptors 3072

Pygit2 or other dependency install fails¶

You may see some failure messages when installing requirements. You can directly access your nox environment and possibly install pygit (or other dependency) that way. When you run nox, you'll see a message like this:

nox > Re-using existing virtual environment at .nox/pytest-parametrized-3-crypto-none-transport-zeromq-coverage-false.

For this, you would be able to install with:

.nox/pytest-parametrized-3-crypto-none-transport-zeromq-coverage-false/bin/python -m pip install pygit2

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:

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:

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:

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:

conf_file¶

Default: /etc/salt/master

The path to the master's configuration file.

conf_file: /etc/salt/master

pki_dir¶

Default: <LIB_STATE_DIR>/pki/master

The directory to store the pki authentication keys.

<LIB_STATE_DIR> is the pre-configured variable state directory set during installation via --salt-lib-state-dir. It defaults to /etc/salt. Systems following the Filesystem Hierarchy Standard (FHS) might set it to /var/lib/salt.

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 where custom modules are synced to. 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.

Note, any directories or files not found in the module_dirs location will be removed from the extension_modules path.

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

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.

Deprecated since version 3006: Replaced by keep_jobs_seconds

keep_jobs: 24

keep_jobs_seconds¶

Default: 86400

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

keep_jobs_seconds: 86400

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.

maintenance_interval¶

New in version 3006.0.

Default: 3600

Defines how often to restart the master's Maintenance process.

maintenance_interval: 9600

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:

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:

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

ipc_write_buffer¶

Default: 0

The maximum size of a message sent via the IPC transport module can be limited dynamically or by sharing an integer value lower than the total memory size. When the value dynamic is set, salt will use 2.5% of the total memory as ipc_write_buffer value (rounded to an integer). A value of 0 disables this option.

ipc_write_buffer: 10485760

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.

Note: keep_acl_in_token will be forced to True when using external authentication for REST API (rest is present under external_auth). This is because the REST API does not store the password, and can therefore not retroactively fetch the ACL, so the ACL must be stored in the token.

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:

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.

Standards for busy environments:

NOTE:

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:

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

Default: False

The state_output_pct setting changes whether success and failure information as a percent of total actions will be shown for each state run.

state_output_pct: False

state_compress_ids¶

Default: False

The state_compress_ids setting aggregates information about states which have multiple "names" under the same state ID in the highstate output.

state_compress_ids: False

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

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

runner_returns: False

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:

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

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:

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¶

Changed in version 3005.

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

Taking dynamic environments one step further, __env__ can also be used in the file_roots filesystem path as of version 3005. It will be replaced with the actual saltenv and searched for states and data to provide to the minion. Note this substitution ONLY occurs for the __env__ environment. For instance, this configuration:

file_roots:


  __env__:


    - /srv/__env__/salt

is equivalent to this static configuration:

file_roots:


  dev:


    - /srv/dev/salt


  test:


    - /srv/test/salt


  prod:


    - /srv/prod/salt

NOTE:

roots_update_interval¶

New in version 2018.3.0.

Default: 60

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

NOTE:

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:

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:

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:

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:

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:

NOTE:

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:

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:

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:

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:

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:

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:

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:

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.

hgfs_branch_method: mixed

NOTE:

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:

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: []

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

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

If used in conjunction with 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:

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:

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: []

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

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

If used in conjunction with 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:

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:

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

fileserver_interval¶

New in version 3006.0.

Default: 3600

Defines how often to restart the master's FilesServerUpdate process.

fileserver_interval: 9600

Pillar Configuration¶

pillar_roots¶

Changed in version 3005.

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

Taking dynamic environments one step further, __env__ can also be used in the pillar_roots filesystem path as of version 3005. It will be replaced with the actual pillarenv and searched for Pillar data to provide to the minion. Note this substitution ONLY occurs for the __env__ environment. For instance, this configuration:

pillar_roots:


  __env__:


    - /srv/__env__/pillar

is equivalent to this static configuration:

pillar_roots:


  dev:


    - /srv/dev/pillar


  test:


    - /srv/test/pillar


  prod:


    - /srv/prod/pillar

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:

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

gpg_decrypt_must_succeed¶

New in version 3005.

Default: False

If this is True and the ciphertext could not be decrypted, then an error is raised.

Sending the ciphertext through basically is never desired, for example if a state is setting a database password from pillar and gpg rendering fails, then the state will update the password to the ciphertext, which by definition is not encrypted.

WARNING:

gpg_decrypt_must_succeed: False

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:

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

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:

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:

ext_pillar:


  - git:


    - master https://mygitserver/pillar1.git


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


      - root: pillar

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:

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:

foo: 42
bar:


    element1: True

bar:


    element2: True
baz: quux

foo: 42
bar:


    element1: True


    element2: True
baz: quux

foo: 42
bar: !aggregate {


  element1: True
}
baz: !aggregate quux

bar: !aggregate {


  element2: True
}
baz: !aggregate quux2

foo: 42
bar:


  element1: True


  element2: True
baz:


  - quux


  - quux2

A:


  first_key: blah


  second_key: blah

A:


  third_key: blah


  fourth_key: blah

A:


  third_key: blah


  fourth_key: blah

NOTE:

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:

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:

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

netapi_enable_clients¶

New in version 3006.0.

Default: []

Used by salt-api to enable access to the listed clients. Unless a client is addded to this list, requests will be rejected before authentication is attempted or processing of the low state occurs.

This can be used to only expose the required functionality via salt-api.

Configuration with all possible clients enabled:

netapi_enable_clients:


  - local


  - local_async


  - local_batch


  - local_subset


  - runner


  - runner_async


  - ssh


  - wheel


  - wheel_async

NOTE:

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

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:

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:

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'

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

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¶

Common Directories¶

Roots¶

file_roots

pillar_roots

Win Repo Settings¶

Configuring the Salt Minion¶

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:

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

By default, the salt-minion configuration will be in /etc/salt/minion. A notable exception is FreeBSD, where the configuration will be in /usr/local/etc/salt/minion.

Minion Primary Configuration¶

master¶

Default: salt

The hostname or IP address of the master. See ipv6 for IPv6 connections to the master.

Default: salt

master: salt

master:port Syntax¶

New in version 2015.8.0.

The master config option can also be set to use the master's IP in conjunction with a port number by default.

master: localhost:1234

For IPv6 formatting with a port, remember to add brackets around the IP address before adding the port and enclose the line in single quotes to make it a string:

master: '[2001:db8:85a3:8d3:1319:8a2e:370:7348]:1234'

NOTE:

List of Masters Syntax¶

The option can also be set to a list of masters, enabling multi-master mode.

master:


  - address1


  - address2

Changed in version 2014.7.0: The master can be dynamically configured. The master value can be set to an module function which will be executed and will assume that the returning value is the ip or hostname of the desired master. If a function is being specified, then the master_type option must be set to func, to tell the minion that the value is a function to be run and not a fully-qualified domain name.

master: module.function
master_type: func

In addition, instead of using multi-master mode, the minion can be configured to use the list of master addresses as a failover list, trying the first address, then the second, etc. until the minion successfully connects. To enable this behavior, set master_type to failover:

master:


  - address1


  - address2
master_type: failover

color¶

Default: True

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

ipv6¶

Default: None

Whether the master should be connected over IPv6. By default salt minion will try to automatically detect IPv6 connectivity to master.

ipv6: True

master_uri_format¶

New in version 2015.8.0.

Specify the format in which the master address will be evaluated. Valid options are default or ip_only. If ip_only is specified, then the master address will not be split into IP and PORT, so be sure that only an IP (or domain name) is set in the master configuration setting.

master_uri_format: ip_only

master_tops_first¶

New in version 2018.3.0.

Default: False

SLS targets defined using the Master Tops system are normally executed after any matches defined in the Top File. Set this option to True to have the minion execute the Master Tops states first.

master_tops_first: True

master_type¶

New in version 2014.7.0.

Default: str

The type of the master variable. Can be str, failover, func or disable.

master_type: str

If this option is str (default), multiple hot masters are configured. Minions can connect to multiple masters simultaneously (all master are "hot").

master_type: failover

If this option is set to failover, master must be a list of master addresses. The minion will then try each master in the order specified in the list until it successfully connects. master_alive_interval must also be set, this determines how often the minion will verify the presence of the master.

master_type: func

If the master needs to be dynamically assigned by executing a function instead of reading in the static master value, set this to func. This can be used to manage the minion's master setting from an execution module. By simply changing the algorithm in the module to return a new master ip/fqdn, restart the minion and it will connect to the new master.

As of version 2016.11.0 this option can be set to disable and the minion will never attempt to talk to the master. This is useful for running a masterless minion daemon.

master_type: disable

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

max_event_size: 1048576

enable_legacy_startup_events¶

New in version 2019.2.0.

Default: True

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

enable_legacy_startup_events: True

master_failback¶

New in version 2016.3.0.

Default: False

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

master_failback: False

master_failback_interval¶

New in version 2016.3.0.

Default: 0

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

master_failback_interval: 0

master_alive_interval¶

Default: 0

Configures how often, in seconds, the minion will verify that the current master is alive and responding. The minion will try to establish a connection to the next master in the list if it finds the existing one is dead.

master_alive_interval: 30

master_shuffle¶

New in version 2014.7.0.

Deprecated since version 2019.2.0.

Default: False

WARNING:

master_shuffle: True

random_master¶

New in version 2014.7.0.

Changed in version 2019.2.0: The master_failback option can be used in conjunction with random_master to force the minion to fail back to the first master in the list if the first master is back online. Note that master_type must be set to failover in order for the master_failback setting to work.

Default: False

If master is a list of addresses, shuffle them before trying to connect to distribute the minions over all available masters. This uses Python's random.shuffle method.

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

random_master: True

NOTE:

retry_dns¶

Default: 30

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

retry_dns: 30

retry_dns_count¶

New in version 2018.3.4.

Default: None

Set the number of attempts to perform when resolving the master hostname if name resolution fails. By default the minion will retry indefinitely.

retry_dns_count: 3

master_port¶

Default: 4506

The port of the master ret server, this needs to coincide with the ret_port option on the Salt master.

master_port: 4506

publish_port¶

Default: 4505

The port of the master publish server, this needs to coincide with the publish_port option on the Salt master.

publish_port: 4505

source_interface_name¶

New in version 2018.3.0.

The name of the interface to use when establishing the connection to the Master.

NOTE:

NOTE:

NOTE:

WARNING:

Configuration example:

source_interface_name: bond0.1234

source_address¶

New in version 2018.3.0.

The source IP address or the domain name to be used when connecting the Minion to the Master. See ipv6 for IPv6 connections to the Master.

WARNING:

Configuration example:

source_address: if-bond0-1234.sjc.us-west.internal

source_ret_port¶

New in version 2018.3.0.

The source port to be used when connecting the Minion to the Master ret server.

WARNING:

Configuration example:

source_ret_port: 49017

source_publish_port¶

New in version 2018.3.0.

The source port to be used when connecting the Minion to the Master publish server.

WARNING:

Configuration example:

source_publish_port: 49018

user¶

Default: root

The user to run the Salt processes

user: root

sudo_user¶

Default: ''

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

sudo_user: root

pidfile¶

Default: /var/run/salt-minion.pid

The location of the daemon's process ID file

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

root_dir¶

Default: /

This directory is prepended to the following options: pki_dir, cachedir, log_file, sock_dir, and pidfile.

root_dir: /

conf_file¶

Default: /etc/salt/minion

The path to the minion's configuration file.

conf_file: /etc/salt/minion

pki_dir¶

Default: <LIB_STATE_DIR>/pki/minion

The directory used to store the minion's public and private keys.

<LIB_STATE_DIR> is the pre-configured variable state directory set during installation via --salt-lib-state-dir. It defaults to /etc/salt. Systems following the Filesystem Hierarchy Standard (FHS) might set it to /var/lib/salt.

pki_dir: /etc/salt/pki/minion

id¶

Default: the system's hostname

SEE ALSO:

Explicitly declare the id for this minion to use. Since Salt uses detached ids it is possible to run multiple minions on the same machine but with different ids.

id: foo.bar.com

minion_id_caching¶

New in version 0.17.2.

Default: True

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

For more information, please see Issue #7558 and Pull Request #8488.

minion_id_caching: True

append_domain¶

Default: None

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

append_domain: foo.org

minion_id_remove_domain¶

New in version 3000.

Default: False

Remove a domain when the minion id is generated as a fully qualified domain name (either by the user provided id_function, or by Salt). This is useful when the minions shall be named like hostnames. Can be a single domain (to prevent name clashes), or True, to remove all domains.

For more information, please see issue 49212 and PR 49378.

minion_id_remove_domain: foo.org

minion_id_lowercase¶

Default: False

Convert minion id to lowercase when it is being generated. Helpful when some hosts get the minion id in uppercase. Cached ids will remain the same and not converted.

minion_id_lowercase: True

cachedir¶

Default: /var/cache/salt/minion

The location for minion cache data.

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

cachedir: /var/cache/salt/minion

color_theme¶

Default: ""

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

color_theme: /etc/salt/color_theme

append_minionid_config_dirs¶

Default: [] (the empty list) for regular minions, ['cachedir'] for proxy minions.

Append minion_id to these configuration directories. Helps with multiple proxies and minions running on the same machine. Allowed elements in the list: pki_dir, cachedir, extension_modules. Normally not needed unless running several proxies and/or minions on the same machine.

append_minionid_config_dirs:


  - pki_dir


  - cachedir

verify_env¶

Default: True

Verify and set permissions on configuration directories at startup.

verify_env: True

NOTE:

cache_jobs¶

Default: False

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

cache_jobs: False

grains¶

Default: (empty)

SEE ALSO:

Statically assigns grains to the minion.

grains:


  roles:


    - webserver


    - memcache


  deployment: datacenter4


  cabinet: 13


  cab_u: 14-15

grains_blacklist¶

Default: []

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

NOTE:

New in version 3000.

grains_blacklist:


  - cpu_flags


  - zmq*


  - ipv[46]

grains_cache¶

Default: False

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

grains_cache: False

grains_cache_expiration¶

Default: 300

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

grains_cache_expiration: 300

grains_deep_merge¶

New in version 2016.3.0.

Default: False

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

grains_deep_merge: False

For example, with these custom grains functions:

def custom1_k1():


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


    return {"custom1": {"k2": "v2"}}

Without grains_deep_merge, the result would be:

custom1:


  k1: v1

With grains_deep_merge, the result will be:

custom1:


  k1: v1


  k2: v2

grains_refresh_every¶

Default: 0

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

Note: This value is expressed in minutes.

A value of 10 minutes is a reasonable default.

grains_refresh_every: 0

grains_refresh_pre_exec¶

New in version 3005.

Default: False

The grains_refresh_pre_exec setting allows for a minion to check its grains prior to the execution of any operation to see if they have changed and, if so, to inform the master of the new grains. This operation is moderately expensive, therefore care should be taken before enabling this behavior.

grains_refresh_pre_exec: True

metadata_server_grains¶

New in version 2017.7.0.

Default: False

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

metadata_server_grains: True

fibre_channel_grains¶

Default: False

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

fibre_channel_grains: True

iscsi_grains¶

Default: False

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

iscsi_grains: True

nvme_grains¶

Default: False

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

nvme_grains: True

mine_enabled¶

New in version 2015.8.10.

Default: True

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

mine_enabled: True

mine_return_job¶

New in version 2015.8.10.

Default: False

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

mine_return_job: False

mine_functions¶

Default: Empty

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

mine_functions:


  test.ping: []


  network.ip_addrs:


    interface: eth0


    cidr: '10.0.0.0/8'

mine_interval¶

Default: 60

The number of minutes between mine updates.

mine_interval: 60

sock_dir¶

Default: /var/run/salt/minion

The directory where Unix sockets will be kept.

sock_dir: /var/run/salt/minion

enable_fqdns_grains¶

Default: True

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

enable_fqdns_grains: False

enable_gpu_grains¶

Default: True

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

enable_gpu_grains: False

outputter_dirs¶

Default: []

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

outputter_dirs: []

backup_mode¶

Default: ''

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

backup_mode: minion

acceptance_wait_time¶

Default: 10

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

acceptance_wait_time: 10

acceptance_wait_time_max¶

Default: 0

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

acceptance_wait_time_max: 0

rejected_retry¶

Default: False

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

rejected_retry: False

random_reauth_delay¶

Default: 10

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

random_reauth_delay: 60

master_tries¶

New in version 2016.3.0.

Default: 1

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

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

master_tries: 1

auth_tries¶

New in version 2014.7.0.

Default: 7

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

auth_tries: 7

auth_timeout¶

New in version 2014.7.0.

Default: 5

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

NOTE:

auth_timeout: 5

auth_safemode¶

New in version 2014.7.0.

Default: False

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

auth_safemode: False

ping_interval¶

Default: 0

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

ping_interval: 0

random_startup_delay¶

Default: 0

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

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

random_startup_delay: 5

recon_default¶

Default: 1000

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

recon_default: 1000

recon_max¶

Default: 10000

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

recon_max: 10000

recon_randomize¶

Default: True

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

recon_randomize: True

loop_interval¶

Default: 1

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

loop_interval: 1

pub_ret¶

Default: True

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

pub_ret: True

return_retry_timer¶

Default: 5

The default timeout for a minion return attempt.

return_retry_timer: 5

return_retry_timer_max¶

Default: 10

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

return_retry_timer_max: 10

return_retry_tries¶

Default: 3

The maximum number of retries for a minion return attempt.