NAME¶

salt - Salt Documentation

INSTALLATION¶

This section contains instructions to install Salt. If you are setting up your environment for the first time, you should install a Salt master on a dedicated management server or VM, and then install a Salt minion on each system that you want to manage using Salt. For now you don't need to worry about your architecture, you can easily add components and modify your configuration later without needing to reinstall anything. The general installation process is as follows:
After this, you should be able to run a simple command and receive returns from all connected Salt minions.

Quick Install¶

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

Platform-specific Installation Instructions¶

These guides go into detail how to install Salt on a given platform.

Arch Linux¶

Installation¶

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

Stable Release¶

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

Tracking develop¶

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

Post-installation tasks¶

systemd Activate the Salt Master and/or Minion via systemctl as follows:
Start the Master Once you've completed all of these steps you're ready to start your Salt Master. You should be able to start your Salt Master now using the command seen here:
Now go to the Configuring Salt page.

Debian GNU/Linux / Raspbian¶

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

Installation from the Official SaltStack Repository¶

Packages for Debian 8 (Jessie) and Debian 7 (Wheezy) are available in the Official SaltStack repository. Instructions are at https://repo.saltstack.com/#debian. NOTE:

Installation from the Debian / Raspbian Official Repository¶

Stretch (Testing) and Sid (Unstable) distributions are already contain mostly up-to-date Salt packages built by Debian Salt Team. You can install Salt components directly from Debian. On Jessie (Stable) there is an option to install Salt minion from Stretch with python-tornado dependency from jessie-backports repositories. To install fresh release of Salt minion on Jessie:

Install Packages¶

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

Post-installation tasks¶

Now, go to the Configuring Salt page.

Fedora¶

Beginning with version 0.9.4, Salt has been available in the primary Fedora repositories and EPEL. It is installable using yum or dnf, depending on your version of Fedora. NOTE:
WARNING: Fedora 19 comes with systemd 204. Systemd has known bugs fixed in later revisions that prevent the salt-master from starting reliably or opening the network connections that it needs to. It's not likely that a salt-master will start or run reliably on any distribution that uses systemd version 204 or earlier. Running salt-minions should be OK.

Installation¶

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

Stable Release¶

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

Installing from updates-testing¶

When a new Salt release is packaged, it is first admitted into the updates-testing repository, before being moved to the stable repo. To install from updates-testing, use the enablerepo argument for yum:

Installation Using pip¶

Since Salt is on PyPI, it can be installed using pip, though most users prefer to install using a package manager. Installing from pip has a few additional requirements:
A pip install does not make the init scripts or the /etc/salt directory, and you will need to provide your own systemd service unit. Installation from pip:
WARNING:

Post-installation tasks¶

Master To have the Master start automatically at boot time:
To start the Master:
Minion To have the Minion start automatically at boot time:
To start the Minion:
Now go to the Configuring Salt page.

FreeBSD¶

Installation¶

Salt is available in binary package form from both the FreeBSD pkgng repository or directly from SaltStack. The instructions below outline installation via both methods:

FreeBSD repo¶

The FreeBSD pkgng repository is preconfigured on systems 10.x and above. No configuration is needed to pull from these repositories.
These packages are usually available within a few days of upstream release.

SaltStack repo¶

SaltStack also hosts internal binary builds of the Salt package, available from https://repo.saltstack.com/freebsd/. To make use of this repository, add the following file to your system: /usr/local/etc/pkg/repos/saltstack.conf:
You should now be able to install Salt from this new repository:
These packages are usually available earlier than upstream FreeBSD. Also available are release candidates and development releases. Use these pre-release packages with caution.

Post-installation tasks¶

Master Copy the sample configuration file:
rc.conf Activate the Salt Master in /etc/rc.conf:
Start the Master Start the Salt Master as follows:
Minion Copy the sample configuration file:
rc.conf Activate the Salt Minion in /etc/rc.conf:
Start the Minion Start the Salt Minion as follows:
Now go to the Configuring Salt page.

Gentoo¶

Salt can be easily installed on Gentoo via Portage:

Post-installation tasks¶

Now go to the Configuring Salt page.

OpenBSD¶

Salt was added to the OpenBSD ports tree on Aug 10th 2013. It has been tested on OpenBSD 5.5 onwards. Salt is dependent on the following additional ports. These will be installed as dependencies of the sysutils/salt port:

Installation¶

To install Salt from the OpenBSD pkg repo, use the command:

Post-installation tasks¶

Master To have the Master start automatically at boot time:
To start the Master:
Minion To have the Minion start automatically at boot time:
To start the Minion:
Now go to the Configuring Salt page.

macOS¶

Installation from the Official SaltStack Repository¶

Latest stable build from the selected branch: The output of md5 <salt pkg> should match the contents of the corresponding md5 file. Earlier builds from supported branches Archived builds from unsupported branches

Installation from Homebrew¶

It should be noted that Homebrew explicitly discourages the use of sudo:

Installation from MacPorts¶

Installation from Pip¶

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

Salt-Master Customizations¶

NOTE:
To run salt-master on macOS, sudo add this configuration option to the /etc/salt/master file:
On versions previous to macOS 10.10 (Yosemite), increase the root user maxfiles limit:
NOTE:
Now the salt-master should run without errors:

Post-installation tasks¶

Now go to the Configuring Salt page.

RHEL / CentOS / Scientific Linux / Amazon Linux / Oracle Linux¶

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

Installation from the Official SaltStack Repository¶

Packages for Redhat, CentOS, and Amazon Linux are available in the SaltStack Repository.
NOTE:
WARNING:
NOTE:

Installation from the Community-Maintained Repository¶

Beginning with version 0.9.4, Salt has been available in EPEL. For RHEL/CentOS 5, Fedora COPR is a single community repository that provides Salt packages due to the removal from EPEL5. NOTE:

RHEL/CentOS 6 and 7, Scientific Linux, etc.¶

WARNING:

Enabling EPEL¶

If the EPEL repository is not installed on your system, you can download the RPM for RHEL/CentOS 6 or for RHEL/CentOS 7 and install it using the following command:
Replace epel-release-X-Y.rpm with the appropriate filename.

Installing Stable Release¶

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

Installing from epel-testing¶

When a new Salt release is packaged, it is first admitted into the epel-testing repository, before being moved to the stable EPEL repository. To install from epel-testing, use the enablerepo argument for yum:

Installation Using pip¶

Since Salt is on PyPI, it can be installed using pip, though most users prefer to install using RPM packages (which can be installed from EPEL). Installing from pip has a few additional requirements:
A pip install does not make the init scripts or the /etc/salt directory, and you will need to provide your own systemd service unit. Installation from pip:
WARNING:

ZeroMQ 4¶

We recommend using ZeroMQ 4 where available. SaltStack provides ZeroMQ 4.0.5 and pyzmq 14.5.0 in the SaltStack Repository as well as a separate zeromq4 COPR repository. If this repository is added before Salt is installed, then installing either salt-master or salt-minion will automatically pull in ZeroMQ 4.0.5, and additional steps to upgrade ZeroMQ and pyzmq are unnecessary. WARNING:
NOTE:

Package Management¶

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

Post-installation tasks¶

Master¶

To have the Master start automatically at boot time: RHEL/CentOS 5 and 6
RHEL/CentOS 7
To start the Master: RHEL/CentOS 5 and 6
RHEL/CentOS 7

Minion¶

To have the Minion start automatically at boot time: RHEL/CentOS 5 and 6
RHEL/CentOS 7
To start the Minion: RHEL/CentOS 5 and 6
RHEL/CentOS 7
Now go to the Configuring Salt page.

Solaris¶

Salt was added to the OpenCSW package repository in September of 2012 by Romeo Theriault < romeot@hawaii.edu> at version 0.10.2 of Salt. It has mainly been tested on Solaris 10 (sparc), though it is built for and has been tested minimally on Solaris 10 (x86), Solaris 9 (sparc/x86) and 11 (sparc/x86). (Please let me know if you're using it on these platforms!) Most of the testing has also just focused on the minion, though it has verified that the master starts up successfully on Solaris 10. Comments and patches for better support on these platforms is very welcome. As of version 0.10.4, Solaris is well supported under salt, with all of the following working well:
Salt is dependent on the following additional packages. These will automatically be installed as dependencies of the py_salt package:

Installation¶

To install Salt from the OpenCSW package repository you first need to install pkgutil assuming you don't already have it installed: On Solaris 10:
On Solaris 9:
Once pkgutil is installed you'll need to edit it's config file /etc/opt/csw/pkgutil.conf to point it at the unstable catalog:
OK, time to install salt.

Minion Configuration¶

Now that salt is installed you can find it's configuration files in /etc/opt/csw/salt/. You'll want to edit the minion config file to set the name of your salt master server:
If you would like to use pkgutil as the default package provider for your Solaris minions, you can do so using the providers option in the minion config file. You can now start the salt minion like so: On Solaris 10:
On Solaris 9:
You should now be able to log onto the salt master and check to see if the salt-minion key is awaiting acceptance:
Accept the key:
Run a simple test against the minion:

Troubleshooting¶

Logs are in /var/log/salt

Ubuntu¶

Installation from the Official SaltStack Repository¶

Packages for Ubuntu 16 (Xenial), Ubuntu 14 (Trusty), and Ubuntu 12 (Precise) are available in the SaltStack repository. Instructions are at https://repo.saltstack.com/#ubuntu.

Install Packages¶

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

Post-installation tasks¶

Now go to the Configuring Salt page.

Windows¶

Salt has full support for running the Salt minion on Windows. You must connect Windows Salt minions to a Salt master on a supported operating system to control your Salt Minions. Many of the standard Salt modules have been ported to work on Windows and many of the Salt States currently work on Windows as well.

Installation from the Official SaltStack Repository¶

Latest stable build from the selected branch: The output of md5sum <salt minion exe> should match the contents of the corresponding md5 file. Earlier builds from supported branches Archived builds from unsupported branches NOTE:
The 64bit installer has been tested on Windows 7 64bit and Windows Server 2008R2 64bit. The 32bit installer has been tested on Windows 2008 Server 32bit. Please file a bug report on our GitHub repo if issues for other platforms are found. The installer will detect previous installations of Salt and ask if you would like to remove them. Clicking OK will remove the Salt binaries and related files but leave any existing config, cache, and PKI information. The installer asks for two additional bits of information to configure the minion; the master hostname and the minion name. The installer will update the minion config with these options. The final page allows you to select which services to start. The salt-minion service will appear in the Windows Service Manager and can be started and stopped there or with the command line program sc like any other Windows service.
If the minion won't start, try installing the Microsoft Visual C++ 2008 x64 SP1 redistributable. Allow all Windows updates to run salt-minion smoothly.

Installation Prerequisites¶

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

Silent Installer Options¶

The installer can be run silently by providing the /S option at the command line. The installer also accepts the following options for configuring the Salt Minion silently:
NOTE:
Here are some examples of using the silent installer:

Running the Salt Minion on Windows as an Unprivileged User¶

Notes:

Create the Unprivileged User that the Salt Minion will Run As¶

Add the New User to the Access Control List for the Salt Folder¶

Update the Windows Service User for the salt-minion Service¶

Building and Developing on Windows¶

This document will explain how to set up a development environment for Salt on Windows. The development environment allows you to work with the source code to customize or fix bugs. It will also allow you to build your own installation. There are several scripts to automate creating a Windows installer as well as setting up an environment that facilitates developing and troubleshooting Salt code. They are located in the pkg\windows directory in the Salt repo (here).

Scripts:¶

Script	Description
build_env.ps1	A PowerShell script that sets up the build environment
build_pkg.bat	A batch file that builds a Windows installer based on the contents of the C:\Python27 directory
build.bat	A batch file that fully automates the building of the Windows installer using the above two scripts

NOTE:

Prerequisite Software¶

The only prerequisite is Git for Windows.

Create a Build Environment¶

1. Working Directory¶

Create a Salt-Dev directory on the root of C:. This will be our working directory. Navigate to Salt-Dev and clone the Salt repo from GitHub. Open a command line and type:
Go into the salt directory and checkout the version of salt to work with (2016.3 or higher).

2. Setup the Python Environment¶

Navigate to the pkg\windows directory and execute the build_env.ps1 PowerShell script.
NOTE:
This will download and install Python with all the dependencies needed to develop and build Salt. NOTE:

3. Salt in Editable Mode¶

Editable mode allows you to more easily modify and test the source code. For more information see the Pip documentation. Navigate to the root of the salt directory and install Salt in editable mode with pip
NOTE:
NOTE:

4. Setup Salt Configuration¶

Salt requires a minion configuration file and a few other directories. The default config file is named minion located in C:\salt\conf. The easiest way to set this up is to copy the contents of the salt\pkg\windows\buildenv directory to C:\salt.
Now go into the C:\salt\conf directory and edit the file name minion (no extension). You need to configure the master and id parameters in this file. Edit the following lines:

Create a Windows Installer¶

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

3. Install Salt¶

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

4. Create the Windows Installer¶

Navigate to the pkg\windows directory and run the build_pkg.bat with the build version (2016.3) script.
NOTE:

Creating a Windows Installer: Alternate Method (Easier)¶

Clone the Salt repo from GitHub into the directory of your choice. We're going to use Salt-Dev.
Go into the salt directory and checkout the version of Salt you want to build.
Then navigate to pkg\windows and run the build.bat script with the version you're building.
This will install everything needed to build a Windows installer for Salt. The binary will be in the salt\pkg\windows\installer directory.

Testing the Salt minion¶

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

Packages Management Under Windows 2003¶

Windows Server 2003 and Windows XP have both reached End of Support. Though Salt is not officially supported on operating systems that are EoL, some functionality may continue to work. On Windows Server 2003, you need to install optional component "WMI Windows Installer Provider" to get a full list of installed packages. If you don't have this, salt-minion can't report some installed software.

SUSE¶

Installation from the Official SaltStack Repository¶

Packages for SUSE 12 SP1, SUSE 12, SUSE 11, openSUSE 13 and openSUSE Leap 42.1 are available in the SaltStack Repository. Instructions are at https://repo.saltstack.com/#suse.

Installation from the SUSE Repository¶

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

Installation¶

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

Stable Release¶

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

Post-installation tasks openSUSE¶

Master To have the Master start automatically at boot time:
To start the Master:
Minion To have the Minion start automatically at boot time:
To start the Minion:

Post-installation tasks SLES¶

Master To have the Master start automatically at boot time:
To start the Master:
Minion To have the Minion start automatically at boot time:
To start the Minion:

Unstable Release¶

openSUSE¶

For openSUSE Tumbleweed run the following as root:
For openSUSE 42.1 Leap run the following as root:
For openSUSE 13.2 run the following as root:

SUSE Linux Enterprise¶

For SLE 12 run the following as root:
For SLE 11 SP4 run the following as root:
Now go to the Configuring Salt page.

Initial Configuration¶

Configuring Salt¶

Salt configuration is very simple. The default configuration for the master will work for most installations and the only requirement for setting up a minion is to set the location of the master in the minion configuration file. The configuration files will be installed to /etc/salt and are named after the respective components, /etc/salt/master, and /etc/salt/minion.

Master Configuration¶

By default the Salt master listens on ports 4505 and 4506 on all interfaces (0.0.0.0). To bind Salt to a specific IP, redefine the "interface" directive in the master configuration file, typically /etc/salt/master, as follows:
After updating the configuration file, restart the Salt master. See the master configuration reference for more details about other configurable options.

Minion Configuration¶

Although there are many Salt Minion configuration options, configuring a Salt Minion is very simple. By default a Salt Minion will try to connect to the DNS name "salt"; if the Minion is able to resolve that name correctly, no configuration is needed. If the DNS name "salt" does not resolve to point to the correct location of the Master, redefine the "master" directive in the minion configuration file, typically /etc/salt/minion, as follows:
After updating the configuration file, restart the Salt minion. See the minion configuration reference for more details about other configurable options.

Running Salt¶

There is also a full troubleshooting guide available.

Key Identity¶

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

Master Key Fingerprint¶

Print the master key fingerprint by running the following command on the Salt master:
Copy the master.pub fingerprint from the Local Keys section, and then set this value as the master_finger in the minion configuration file. Save the configuration file and then restart the Salt minion.

Minion Key Fingerprint¶

Run the following command on each Salt minion to view the minion key fingerprint:
Compare this value to the value that is displayed when you run the salt-key --finger <MINION_ID> command on the Salt master.

Key Management¶

Salt uses AES encryption for all communication between the Master and the Minion. This ensures that the commands sent to the Minions cannot be tampered with, and that communication between Master and Minion is authenticated through trusted, accepted keys. Before commands can be sent to a Minion, its key must be accepted on the Master. Run the salt-key command to list the keys known to the Salt Master:
This example shows that the Salt Master is aware of four Minions, but none of the keys has been accepted. To accept the keys and allow the Minions to be controlled by the Master, again use the salt-key command:
The salt-key command allows for signing keys individually or in bulk. The example above, using -A bulk-accepts all pending keys. To accept keys individually use the lowercase of the same option, -a keyname. SEE ALSO:

Sending Commands¶

Communication between the Master and a Minion may be verified by running the test.ping command:
Communication between the Master and all Minions may be tested in a similar way:
Each of the Minions should send a True response as shown above.

What's Next?¶

Understanding targeting is important. From there, depending on the way you wish to use Salt, you should also proceed to learn about Remote Execution and Configuration Management.

Additional Installation Guides¶

Salt Bootstrap¶

The Salt Bootstrap script allows for a user to install the Salt Minion or Master on a variety of system distributions and versions. This shell script known as bootstrap-salt.sh runs through a series of checks to determine the operating system type and version. It then installs the Salt binaries using the appropriate methods. The Salt Bootstrap script installs the minimum number of packages required to run Salt. This means that in the event you run the bootstrap to install via package, Git will not be installed. Installing the minimum number of packages helps ensure the script stays as lightweight as possible, assuming the user will install any other required packages after the Salt binaries are present on the system. The script source is available on GitHub: https://github.com/saltstack/salt-bootstrap

Supported Operating Systems¶

NOTE:

Debian and derivatives¶

Red Hat family¶

SUSE family¶

Ubuntu and derivatives¶

Other Linux distro¶

UNIX systems¶

BSD:
SunOS:

Example Usage¶

If you're looking for the one-liner to install Salt, please scroll to the bottom and use the instructions for Installing via an Insecure One-Liner NOTE:
The Salt Bootstrap script has a wide variety of options that can be passed as well as several ways of obtaining the bootstrap script itself. NOTE:

Install using curl¶

Using curl to install latest development version from GitHub:
If you want to install a specific release version (based on the Git tags):
To install a specific branch from a Git fork:
If all you want is to install a salt-master using latest Git:
If your host has Internet access only via HTTP proxy:

Install using wget¶

Using wget to install your distribution's stable packages:
Downloading the script from develop branch:
Installing a specific version from git using wget:
NOTE:

Install using Python¶

If you already have Python installed, python 2.6, then it's as easy as:
All Python versions should support the following in-line code:

Install using fetch¶

On a FreeBSD base system you usually don't have either of the above binaries available. You do have fetch available though:
If you have any SSL issues install ca_root_nssp:
And either copy the certificates to the place where fetch can find them:
Or link them to the right place:

Installing via an Insecure One-Liner¶

The following examples illustrate how to install Salt via a one-liner. NOTE:
Any of the example above which use two-lines can be made to run in a single-line configuration with minor modifications. For example, using curl to install your distribution's stable packages:
Using wget to install your distribution's stable packages:
Installing the latest develop branch of Salt:

Command Line Options¶

Here's a summary of the command line options:

Opening the Firewall up for Salt¶

The Salt master communicates with the minions using an AES-encrypted ZeroMQ connection. These communications are done over TCP ports 4505 and 4506, which need to be accessible on the master only. This document outlines suggested firewall rules for allowing these incoming connections to the master. NOTE:

Fedora 18 and beyond / RHEL 7 / CentOS 7¶

Starting with Fedora 18 FirewallD is the tool that is used to dynamically manage the firewall rules on a host. It has support for IPv4/6 settings and the separation of runtime and permanent configurations. To interact with FirewallD use the command line client firewall-cmd. firewall-cmd example:
Please choose the desired zone according to your setup. Don't forget to reload after you made your changes.

RHEL 6 / CentOS 6¶

The lokkit command packaged with some Linux distributions makes opening iptables firewall ports very simple via the command line. Just be careful to not lock out access to the server by neglecting to open the ssh port. lokkit example:
The system-config-firewall-tui command provides a text-based interface to modifying the firewall. system-config-firewall-tui:

openSUSE¶

Salt installs firewall rules in /etc/sysconfig/SuSEfirewall2.d/services/salt. Enable with:
If you have an older package of Salt where the above configuration file is not included, the SuSEfirewall2 command makes opening iptables firewall ports very simple via the command line. SuSEfirewall example:
The firewall module in YaST2 provides a text-based interface to modifying the firewall. YaST2:

iptables¶

Different Linux distributions store their iptables (also known as netfilter) rules in different places, which makes it difficult to standardize firewall documentation. Included are some of the more common locations, but your mileage may vary. Fedora / RHEL / CentOS:
Arch Linux:
Debian Follow these instructions: https://wiki.debian.org/iptables Once you've found your firewall rules, you'll need to add the two lines below to allow traffic on tcp/4505 and tcp/4506:
Ubuntu Salt installs firewall rules in /etc/ufw/applications.d/salt.ufw. Enable with:

pf.conf¶

The BSD-family of operating systems uses packet filter (pf). The following example describes the additions to pf.conf needed to access the Salt master.
Once these additions have been made to the pf.conf the rules will need to be reloaded. This can be done using the pfctl command.

Whitelist communication to Master¶

There are situations where you want to selectively allow Minion traffic from specific hosts or networks into your Salt Master. The first scenario which comes to mind is to prevent unwanted traffic to your Master out of security concerns, but another scenario is to handle Minion upgrades when there are backwards incompatible changes between the installed Salt versions in your environment. Here is an example Linux iptables ruleset to be set on the Master:
NOTE:

Preseed Minion with Accepted Key¶

In some situations, it is not convenient to wait for a minion to start before accepting its key on the master. For instance, you may want the minion to bootstrap itself as soon as it comes online. You may also want to to let your developers provision new development machines on the fly. SEE ALSO:
There is a general four step process to do this:

Pick a name for the key, such as the minion's id.

It is necessary that the public key file has the same name as your minion id. This is how Salt matches minions with their keys. Also note that the pki folder could be in a different location, depending on your OS or if specified in the master config file.
There is no single method to get the keypair to your minion. The difficulty is finding a distribution method which is secure. For Amazon EC2 only, an AWS best practice is to use IAM Roles to pass credentials. (See blog post, http://blogs.aws.amazon.com/security/post/Tx610S2MLVZWEA/Using-IAM-roles-to-distribute-non-AWS-credentials-to-your-EC2-instances )

You will want to place the minion keys before starting the salt-minion daemon:
Once in place, you should be able to start salt-minion and run salt-call state.apply or any other salt commands that require master authentication.

The macOS (Maverick) Developer Step By Step Guide To Salt Installation¶

This document provides a step-by-step guide to installing a Salt cluster consisting of one master, and one minion running on a local VM hosted on macOS. NOTE:

The 5 Cent Salt Intro¶

Since you're here you've probably already heard about Salt, so you already know Salt lets you configure and run commands on hordes of servers easily. Here's a brief overview of a Salt cluster:
NOTE:

[1]

Salt also works with "masterless" configuration where a minion is autonomous (in which case salt can be seen as a local configuration tool), or in "multiple master" configuration. See the documentation for more on that.

Before Digging In, The Architecture Of The Salt Cluster¶

Salt Master¶

The "Salt master" server is going to be the Mac OS machine, directly. Commands will be run from a terminal app, so Salt will need to be installed on the Mac. This is going to be more convenient for toying around with configuration files.

Salt Minion¶

We'll only have one "Salt minion" server. It is going to be running on a Virtual Machine running on the Mac, using VirtualBox. It will run an Ubuntu distribution.

Step 1 - Configuring The Salt Master On Your Mac¶

official documentation Because Salt has a lot of dependencies that are not built in macOS, we will use Homebrew to install Salt. Homebrew is a package manager for Mac, it's great, use it (for this tutorial at least!). Some people spend a lot of time installing libs by hand to better understand dependencies, and then realize how useful a package manager is once they're configuring a brand new machine and have to do it all over again. It also lets you uninstall things easily. NOTE:
TIP:

Install Homebrew¶

Install Homebrew here http://brew.sh/ Or just type
Now type the following commands in your terminal (you may want to type brew doctor after each to make sure everything's fine):
NOTE:

Install Salt¶

You should now have everything ready to launch this command:
NOTE:
Now type python in a terminal then, import salt. There should be no errors. Now exit the Python terminal using exit().

Create The Master Configuration¶

If the default /etc/salt/master configuration file was not created, copy-paste it from here: http://docs.saltstack.com/ref/configuration/examples.html#configuration-examples-master NOTE:
Salt Master configuration changes. The Salt master needs a few customization to be able to run on macOS:
In the /etc/salt/master file, change max_open_files to 8192 (or just add the line: max_open_files: 8192 (no quote) if it doesn't already exists). You should now be able to launch the Salt master:
There should be no errors when running the above command. NOTE:
Now that the master is set, let's configure a minion on a VM. The Salt minion is going to run on a Virtual Machine. There are a lot of software options that let you run virtual machines on a mac, But for this tutorial we're going to use VirtualBox. In addition to virtualBox, we will use Vagrant, which allows you to create the base VM configuration. Vagrant lets you build ready to use VM images, starting from an OS image and customizing it using "provisioners". In our case, we'll use it to:

Install VirtualBox¶

Go get it here: https://www.virtualBox.org/wiki/Downloads (click on VirtualBox for macOS hosts => x86/amd64)

Install Vagrant¶

Go get it here: http://downloads.vagrantup.com/ and choose the latest version (1.3.5 at time of writing), then the .dmg file. Double-click to install it. Make sure the vagrant command is found when run in the terminal. Type vagrant. It should display a list of commands.

Create The Minion VM Folder¶

Create a folder in which you will store your minion's VM. In this tutorial, it's going to be a minion folder in the $home directory.

Initialize Vagrant¶

From the minion folder, type
This command creates a default Vagrantfile configuration file. This configuration file will be used to pass configuration parameters to the Salt provisioner in Step 3.

Import Precise64 Ubuntu Box¶

NOTE:

Modify the Vagrantfile¶

Modify ./minion/Vagrantfile to use th precise64 box. Change the config.vm.box line to:
Uncomment the line creating a host-only IP. This is the ip of your minion (you can change it to something else if that IP is already in use):
At this point you should have a VM that can run, although there won't be much in it. Let's check that.

Checking The VM¶

From the $home/minion folder type:
A log showing the VM booting should be present. Once it's done you'll be back to the terminal:
The VM should respond to your ping request. Now log into the VM in ssh using Vagrant again:
You should see the shell prompt change to something similar to vagrant@precise64:~$ meaning you're inside the VM. From there, enter the following:
NOTE:
It's now time to connect the VM to the salt master

Creating The Minion Configuration File¶

Create the /etc/salt/minion file. In that file, put the following lines, giving the ID for this minion, and the IP of the master:
Minions authenticate with the master using keys. Keys are generated automatically if you don't provide one and can accept them later on. However, this requires accepting the minion key every time the minion is destroyed or created (which could be quite often). A better way is to create those keys in advance, feed them to the minion, and authorize them once.

Preseed minion keys¶

From the minion folder on your Mac run:
This should create two files: minion1.pem, and minion1.pub. Since those files have been created using sudo, but will be used by vagrant, you need to change ownership:
Then copy the .pub file into the list of accepted minions:

Modify Vagrantfile to Use Salt Provisioner¶

Let's now modify the Vagrantfile used to provision the Salt VM. Add the following section in the Vagrantfile (note: it should be at the same indentation level as the other properties):
Now destroy the vm and recreate it from the /minion folder:
If everything is fine you should see the following message:

Checking Master-Minion Communication¶

To make sure the master and minion are talking to each other, enter the following:
You should see your minion answering the ping. It's now time to do some configuration. In this step we'll use the Salt master to instruct our minion to install Nginx.

Checking the system's original state¶

First, make sure that an HTTP server is not installed on our minion. When opening a browser directed at http://192.168.33.10/ You should get an error saying the site cannot be reached.

Initialize the top.sls file¶

System configuration is done in /srv/salt/top.sls (and subfiles/folders), and then applied by running the state.apply function to have the Salt master order its minions to update their instructions and run the associated commands. First Create an empty file on your Salt master (macOS machine):
When the file is empty, or if no configuration is found for our minion an error is reported:
This should return an error stating: No Top file or external nodes data matches found.

Create The Nginx Configuration¶

Now is finally the time to enter the real meat of our server's configuration. For this tutorial our minion will be treated as a web server that needs to have Nginx installed. Insert the following lines into /srv/salt/top.sls (which should current be empty).
Now create /srv/salt/bin/nginx.sls containing the following:

Check Minion State¶

Finally, run the state.apply function again:
You should see a log showing that the Nginx package has been installed and the service configured. To prove it, open your browser and navigate to http://192.168.33.10/, you should see the standard Nginx welcome page. Congratulations!

Where To Go From Here¶

A full description of configuration management within Salt (sls files among other things) is available here: http://docs.saltstack.com/en/latest/index.html#configuration-management

running salt as normal user tutorial¶

Before continuing make sure you have a working Salt installation by following the installation and the configuration instructions.

Running Salt functions as non root user¶

If you don't want to run salt cloud as root or even install it you can configure it to have a virtual root in your working directory. The salt system uses the salt.syspath module to find the variables If you run the salt-build, it will generated in:
To generate it, run the command:
Copy the generated module into your salt directory
Edit it to include needed variables and your new paths
Create the directory structure
Populate the configuration files:
Edit your root/etc/salt/master configuration that is used by salt-cloud:
Run like this:

Standalone Minion¶

Since the Salt minion contains such extensive functionality it can be useful to run it standalone. A standalone minion can be used to do a number of things:
NOTE:

Minion Configuration¶

Throughout this document there are several references to setting different options to configure a masterless Minion. Salt Minions are easy to configure via a configuration file that is located, by default, in /etc/salt/minion. Note, however, that on FreeBSD systems, the minion configuration file is located in /usr/local/etc/salt/minion. You can learn more about minion configuration options in the Configuring the Salt Minion docs.

Telling Salt Call to Run Masterless¶

The salt-call command is used to run module functions locally on a minion instead of executing them from the master. Normally the salt-call command checks into the master to retrieve file server and pillar data, but when running standalone salt-call needs to be instructed to not check the master for this data. To instruct the minion to not look for a master when running salt-call the file_client configuration option needs to be set. By default the file_client is set to remote so that the minion knows that file server and pillar data are to be gathered from the master. When setting the file_client option to local the minion is configured to not gather this data from the master.
Now the salt-call command will not look for a master and will assume that the local system has all of the file and pillar resources.

Running States Masterless¶

The state system can be easily run without a Salt master, with all needed files local to the minion. To do this the minion configuration file needs to be set up to know how to return file_roots information like the master. The file_roots setting defaults to /srv/salt for the base environment just like on the master:
Now set up the Salt State Tree, top file, and SLS modules in the same way that they would be set up on a master. Now, with the file_client option set to local and an available state tree then calls to functions in the state module will use the information in the file_roots on the minion instead of checking in with the master. Remember that when creating a state tree on a minion there are no syntax or path changes needed, SLS modules written to be used from a master do not need to be modified in any way to work with a minion. This makes it easy to "script" deployments with Salt states without having to set up a master, and allows for these SLS modules to be easily moved into a Salt master as the deployment grows. The declared state can now be executed with:
Or the salt-call command can be executed with the --local flag, this makes it unnecessary to change the configuration file:

External Pillars¶

External pillars are supported when running in masterless mode.

Salt Masterless Quickstart¶

Running a masterless salt-minion lets you use Salt's configuration management for a single machine without calling out to a Salt master on another machine. Since the Salt minion contains such extensive functionality it can be useful to run it standalone. A standalone minion can be used to do a number of things:
It is also useful for testing out state trees before deploying to a production setup.

Bootstrap Salt Minion¶

The salt-bootstrap script makes bootstrapping a server with Salt simple for any OS with a Bourne shell:
See the salt-bootstrap documentation for other one liners. When using Vagrant to test out salt, the Vagrant salt provisioner will provision the VM for you.

Telling Salt to Run Masterless¶

To instruct the minion to not look for a master, the file_client configuration option needs to be set in the minion configuration file. By default the file_client is set to remote so that the minion gathers file server and pillar data from the salt master. When setting the file_client option to local the minion is configured to not gather this data from the master.
Now the salt minion will not look for a master and will assume that the local system has all of the file and pillar resources. Configuration which resided in the master configuration (e.g. /etc/salt/master) should be moved to the minion configuration since the minion does not read the master configuration. NOTE:

Create State Tree¶

Following the successful installation of a salt-minion, the next step is to create a state tree, which is where the SLS files that comprise the possible states of the minion are stored. The following example walks through the steps necessary to create a state tree that ensures that the server has the Apache webserver installed. NOTE:

/srv/salt/top.sls:

/srv/salt/webserver.sls:
NOTE:
The only thing left is to provision our minion using salt-call.

Salt-call¶

The salt-call command is used to run remote execution functions locally on a minion instead of executing them from the master. Normally the salt-call command checks into the master to retrieve file server and pillar data, but when running standalone salt-call needs to be instructed to not check the master for this data:
The --local flag tells the salt-minion to look for the state tree in the local file system and not to contact a Salt Master for instructions. To provide verbose output, use -l debug:
The minion first examines the top.sls file and determines that it is a part of the group matched by * glob and that the webserver SLS should be applied. It then examines the webserver.sls file and finds the apache state, which installs the Apache package. The minion should now have Apache installed, and the next step is to begin learning how to write more complex states.

Dependencies¶

Salt should run on any Unix-like platform so long as the dependencies are met.
Depending on the chosen Salt transport, ZeroMQ or RAET, dependencies vary:
Salt defaults to the ZeroMQ transport, and the choice can be made at install time, for example:
This way, only the required dependencies are pulled by the setup script if need be. If installing using pip, the --salt-transport install option can be provided like:
NOTE:

Optional Dependencies¶

Upgrading Salt¶

When upgrading Salt, the master(s) should always be upgraded first. Backward compatibility for minions running newer versions of salt than their masters is not guaranteed. Whenever possible, backward compatibility between new masters and old minions will be preserved. Generally, the only exception to this policy is in case of a security vulnerability. SEE ALSO:

Building Packages using Salt Pack¶

Salt-pack is an open-source package builder for most commonly used Linux platforms, for example: Redhat/CentOS and Debian/Ubuntu families, utilizing SaltStack states and execution modules to build Salt and a specified set of dependencies, from which a platform specific repository can be built. https://github.com/saltstack/salt-pack

CONFIGURING SALT¶

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

Configuring the Salt Master¶

The Salt system is amazingly simple and easy to configure, the two components of the Salt system each have a respective configuration file. The salt-master is configured via the master configuration file, and the salt-minion is configured via the minion configuration file. SEE ALSO:
The configuration file for the salt-master is located at /etc/salt/master by default. 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.

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

publish_port¶

Default: 4505 The network port to set up the publication interface.

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:

user¶

Default: root The user to run the Salt processes

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

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:

worker_threads¶

Default: 5 The number of threads to start for receiving commands and replies from minions. If minions are stalling on replies because you have many minions, raise the worker_threads value. Worker threads should not be put below 3 when using the peer system, but can drop down to 1 worker otherwise. NOTE:

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.

pidfile¶

Default: /var/run/salt-master.pid Specify the location of the master pidfile.

root_dir¶

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

conf_file¶

Default: /etc/salt/master The path to the master's configuration file.

pki_dir¶

Default: /etc/salt/pki/master The directory to store the pki authentication keys.

extension_modules¶

Changed in version 2016.3.0: The default location for this directory has been moved. Prior to this version, the location was a directory named extmods in the Salt cachedir (on most platforms, /var/cache/salt/extmods). It has been moved into the master cachedir (on most platforms, /var/cache/salt/master/extmods). Directory for custom modules. This directory can contain subdirectories for each of Salt's module types such as runners, output, wheel, modules, states, returners, engines, etc. This path is appended to root_dir.

module_dirs¶

Default: [] Like extension_modules, but a list of extra directories to search for Salt modules.

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.

verify_env¶

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

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.

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.

timeout¶

Default: 5 Set the default timeout for the salt command and api.

loop_interval¶

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

output¶

Default: nested Set the default outputter used by the salt command.

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.

color¶

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

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.

sock_dir¶

Default: /var/run/salt/master Set the location to use for creating Unix sockets for master process communication.

enable_gpu_grains¶

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

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

cache¶

Default: localfs Cache subsystem module to use for minion data cache.

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.

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

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.

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.

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.

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.

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.

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. Note, this does not detect minions that connect to a master via localhost.

transport¶

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

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! Transports are explained in Salt Transports. The following example shows how to start a TCP transport alongside a ZMQ transport.

Salt-SSH Configuration¶

roster_file¶

Default: /etc/salt/roster Pass in an alternative location for the salt-ssh roster file.

ssh_log_file¶

New in version 2016.3.5. Default: /var/log/salt/ssh Specify the log file of the salt-ssh command.

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_use_home_key¶

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

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.

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.

auto_accept¶

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

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.

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.

publisher_acl¶

Default: {} Enable user accounts on the master to execute specific modules. These modules can be expressed as regular expressions. Note that client_acl option is deprecated by publisher_acl option and will be removed in future releases.

publisher_acl_blacklist¶

Default: {} Blacklist users or modules This example would blacklist all non sudo users, including root from running any commands. It would also blacklist any use of the "cmd" module. Note that client_acl_blacklist option is deprecated by publisher_acl_blacklist option and will be removed in future releases. This is completely disabled by default.

external_auth¶

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

token_expire¶

Default: 43200 Time (in seconds) for a newly generated token to live. Default: 12 hours

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:

file_recv¶

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

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.

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_key_name¶

Default: master_sign The customizable name of the signing-key-pair 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_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.

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.

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.

Master Module Management¶

runner_dirs¶

Default: [] Set additional directories to search for runner modules.

cython_enable¶

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

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.

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:

external_nodes¶

Default: None The external_nodes option allows Salt to gather data that would normally be placed in a top file from and external node controller. The external_nodes option is the executable that will return the ENC data. Remember that Salt will look for external nodes AND top files and combine the results if both are enabled and available!

renderer¶

Default: yaml_jinja The renderer to use on the minions to render the state data.

jinja_trim_blocks¶

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_lstrip_blocks¶

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.

failhard¶

Default: False Set the global failhard flag. This informs all states to stop running states at the moment a single state fails.

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_output¶

Default: full The state_output setting changes if the output is the full multi line output for each changed state if set to 'full', but if set to 'terse' the output will be shortened to a single line. If set to 'mixed', the output will be terse unless a state failed, in which case that output will be full. If set to 'changes', the output will be full unless the state didn't change.

state_aggregate¶

Default: False Automatically aggregate all states that have support for mod_aggregate by setting to True. Or pass a list of state module names to automatically aggregate just those types.

state_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>.

yaml_utf8¶

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

runner_returns¶

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

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

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

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

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.

file_buffer_size¶

Default: 1048576 The buffer size in the file server in bytes.

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

roots: Master's Local File Server¶

file_roots¶

Default:
Salt runs a lightweight file server written in ZeroMQ to deliver files to minions. This file server is built into the master daemon and does not require a dedicated port. The file server works on environments passed to the master. Each environment can have multiple root directories. The subdirectories in the multiple file roots cannot match, otherwise the downloaded files will not be able to be reliably ensured. A base environment is required to house the top file. Example:
NOTE:

git: 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.
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 one of the following: pygit2, gitpython, or dulwich. If unset, then each will be tried in that same order, and the first one with a compatible version installed will be the provider that is used.

gitfs_ssl_verify¶

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

gitfs_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 on a per-remote basis, see here for more info.
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.
Changed in version 2014.7.0: Ability to specify gitfs roots on a per-remote basis was added. See here for more info.

gitfs_base¶

Default: master Defines which branch/tag should be used as the base environment.
Changed in version 2014.7.0: Ability to specify the base on a per-remote basis was added. 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_env_whitelist¶

New in version 2014.7.0. 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_env_blacklist¶

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

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

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

gitfs_privkey¶

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

gitfs_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.

hg: 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.
NOTE:

hgfs_branch_method¶

New in version 0.17.0. Default: branches Defines the objects that will be used as fileserver environments.

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.
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.
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_env_whitelist¶

New in version 2014.7.0. Default: [] Used to restrict which environments are made available. Can speed up state runs if your hgfs remotes contain many branches/bookmarks/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID. If used, only branches/bookmarks/tags which match one of the specified expressions will be exposed as fileserver environments. If used in conjunction with hgfs_env_blacklist, then the subset of branches/bookmarks/tags which match the whitelist but do not match the blacklist will be exposed as fileserver environments.

hgfs_env_blacklist¶

New in version 2014.7.0. Default: [] Used to restrict which environments are made available. Can speed up state runs if your hgfs remotes contain many branches/bookmarks/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID. If used, branches/bookmarks/tags which match one of the specified expressions will not be exposed as fileserver environments. If used in conjunction with hgfs_env_whitelist, then the subset of branches/bookmarks/tags which match the whitelist but do not match the blacklist will be exposed as fileserver environments.

svn: 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.
NOTE:

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.
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.
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_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_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_env_whitelist¶

New in version 2014.7.0. Default: [] Used to restrict which environments are made available. Can speed up state runs if your svnfs remotes contain many branches/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID. If used, only branches/tags which match one of the specified expressions will be exposed as fileserver environments. If used in conjunction with svnfs_env_blacklist, then the subset of branches/tags which match the whitelist but do not match the blacklist will be exposed as fileserver environments.

svnfs_env_blacklist¶

New in version 2014.7.0. Default: [] Used to restrict which environments are made available. Can speed up state runs if your svnfs remotes contain many branches/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID. If used, branches/tags which match one of the specified expressions will not be exposed as fileserver environments. If used in conjunction with svnfs_env_whitelist, then the subset of branches/tags which match the whitelist but do not match the blacklist will be exposed as fileserver environments.

minion: MinionFS Remote File Server Backend¶

minionfs_env¶

New in version 2014.7.0. Default: base Environment from which MinionFS files are made available.

minionfs_mountpoint¶

New in version 2014.7.0. Default: '' Specifies a path on the salt fileserver from which minionfs files are served.
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_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.

Pillar Configuration¶

pillar_roots¶

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

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.

ext_pillar¶

The ext_pillar option allows for any number of external pillar interfaces to be called when populating pillar data. The configuration is based on ext_pillar functions. The available ext_pillar functions can be found herein: https://github.com/saltstack/salt/blob/develop/salt/pillar By default, the ext_pillar interface is not configured to run. Default: []
There are additional details at salt-pillars

ext_pillar_first¶

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

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_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_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_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 it's environment to keep it from also being mapped to the base environment.
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.
NOTE:

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

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

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:
New in version 2016.3.4: It will not do any merging at all and only parse the pillar data from the passed environment and 'base' if no environment was specified.

pillar_merge_lists¶

New in version 2015.8.0. Default: False Recursively merge lists by aggregating them instead of replacing them.

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

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

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.
You can optionally connect a syndic to multiple higher level masters by setting the syndic_master value to a list:
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_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_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_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_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.

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.
This will allow all minions to execute all commands:
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_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:

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_level¶

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

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_datefmt¶

Default: %H:%M:%S The date and time format used in console log messages. See also log_datefmt.

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_fmt_console¶

Default: [%(levelname)-8s] %(message)s The format of the console logging messages. See also log_fmt_console. NOTE:

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_granular_levels¶

Default: {} This can be used to control logging levels more specifically. See also log_granular_levels.

Node Groups¶

Default: {} Node groups allow for logical groupings of minion nodes. A group consists of a group name and a compound target.
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

Include Configuration¶

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.

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_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_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_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_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.
To specify a specific revision of the repository, prepend a commit ID to the URL of the repository:
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.
To specify a specific revision of the repository, prepend a commit ID to the URL of the repository:
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_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 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_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_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_pubkey¶

New in version 2015.8.0. Default: '' Along with winrepo_privkey (and optionally winrepo_passphrase), is used to authenticate to SSH remotes.

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

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 ipv4 of the master. Default: salt
The option can can also be set to a list of masters, enabling multi-master mode.
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.
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_type¶

New in version 2014.7.0. Default: str The type of the master variable. Can be str, failover, func or disable.
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.
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.

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.

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

New in version 2014.7.0. Default: False If master is a list of addresses and :conf_minion`master_type` is failover, shuffle them before trying to connect to distribute the minions over all available masters. This uses Python's random.shuffle method.

random_master¶

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.randint method.

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.

master_port¶

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

user¶

Default: root The user to run the Salt processes

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.

pidfile¶

Default: /var/run/salt-minion.pid The location of the daemon's process ID file

root_dir¶

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

conf_file¶

Default: /etc/salt/minion The path to the minion's configuration file.

pki_dir¶

Default: /etc/salt/pki/minion The directory used to store the minion's public and private keys.

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.

minion_id_caching¶

New in version 0.17.2. Default: True Caches the minion id to a file when the minion's

:minion_conf:`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.

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).

cachedir¶

Default: /var/cache/salt/minion The location for minion cache data. This directory may contain sensitive data and should be protected accordingly.

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.

verify_env¶

Default: True Verify and set permissions on configuration directories at startup.
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.

grains¶

Default: (empty) SEE ALSO:
Statically assigns grains to the minion.

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_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.
For example, with these custom grains functions:
Without grains_deep_merge, the result would be:
With grains_deep_merge, the result will be:

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

sock_dir¶

Default: /var/run/salt/minion The directory where Unix sockets will be kept.

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.

acceptance_wait_time¶

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

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.

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.

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).

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_timeout¶

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

auth_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.

recon_default¶

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

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

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.

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.

return_retry_timer¶

Default: 5 The default timeout for a minion return attempt.

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

cache_sreqs¶

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

ipc_mode¶

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

tcp_pub_port¶

Default: 4510 Publish port used when ipc_mode is set to tcp.

tcp_pull_port¶

Default: 4511 Pull port used when ipc_mode is set to tcp.

transport¶

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

syndic_finger¶

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

proxy_host¶

Default: '' The hostname used for HTTP proxy access.

proxy_port¶

Default: 0 The port number used for HTTP proxy access.

proxy_username¶

Default: '' The username used for HTTP proxy access.

proxy_password¶

Default: '' The password used for HTTP proxy access.

Minion Module Management¶

disable_modules¶

Default: [] (all modules are enabled by default) The event may occur in which the administrator desires that a minion should not be able to execute a certain module. The sys module is built into the minion and cannot be disabled. This setting can also tune the minion. Because all modules are loaded into system memory, disabling modules will lover the minion's memory footprint. Modules should be specified according to their file name on the system and not by their virtual name. For example, to disable cmd, use the string cmdmod which corresponds to salt.modules.cmdmod.

disable_returners¶

Default: [] (all returners are enabled by default) If certain returners should be disabled, this is the place

whitelist_modules¶

Default: [] (Module whitelisting is disabled. Adding anything to the config option will cause only the listed modules to be enabled. Modules not in the list will not be loaded.) This option is the reverse of disable_modules. Note that this is a very large hammer and it can be quite difficult to keep the minion working the way you think it should since Salt uses many modules internally itself. At a bare minimum you need the following enabled or else the minion won't start.

module_dirs¶

Default: [] A list of extra directories to search for Salt modules

returner_dirs¶

Default: [] A list of extra directories to search for Salt returners

states_dirs¶

Default: [] A list of extra directories to search for Salt states

grains_dirs¶

Default: [] A list of extra directories to search for Salt grains

render_dirs¶

Default: [] A list of extra directories to search for Salt renderers

cython_enable¶

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

enable_zip_modules¶

New in version 2015.8.0. Default: False Set this value to true to enable loading of zip archives as extension modules. This allows for packing module code with specific dependencies to avoid conflicts and/or having to install specific modules' dependencies in system libraries.

providers¶

Default: (empty) A module provider can be statically overwritten or extended for the minion via the providers option. This can be done on an individual basis in an SLS file, or globally here in the minion config, like below.

State Management Settings¶

renderer¶

Default: yaml_jinja The default renderer used for local state executions

test¶

Default: False Set all state calls to only test if they are going to actually make changes or just post what changes are going to be made.

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_output¶

Default: full The state_output setting changes if the output is the full multi line output for each changed state if set to 'full', but if set to 'terse' the output will be shortened to a single line.

autoload_dynamic_modules¶

Default: True autoload_dynamic_modules turns on automatic loading of modules found in the environments on the master. This is turned on by default. To turn off auto-loading modules when states run, set this value to False.
Default: True clean_dynamic_modules keeps the dynamic modules on the minion in sync with the dynamic modules on the master. This means that if a dynamic module is not on the master it will be deleted from the minion. By default this is enabled and can be disabled by changing this value to False.

environment¶

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

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:

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

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.

default_top¶

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

snapper_states¶

Default: False The snapper_states value is used to enable taking snapper snapshots before and after salt state runs. This allows for state runs to be rolled back. For snapper states to function properly snapper needs to be installed and enabled.

snapper_states_config¶

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

File Directory Settings¶

file_client¶

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

use_master_when_local¶

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

file_roots¶

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

fileserver_followsymlinks¶

New in version 2014.1.0. Default: True By default, the file_server follows symlinks when walking the filesystem tree. Currently this only applies to the default roots fileserver_backend.

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_limit_traversal¶

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

hash_type¶

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

Pillar Configuration¶

pillar_roots¶

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

pillarenv¶

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

pillar_raise_on_missing¶

New in version 2015.5.0. Default: False Set this option to True to force a KeyError to be raised whenever an attempt to retrieve a named value from pillar fails. When this option is set to False, the failed attempt returns an empty string.

minion_pillar_cache¶

New in version 2016.3.0. Default: False The minion can locally cache rendered pillar data under cachedir/pillar. This allows a temporarily disconnected minion to access previously cached pillar data by invoking salt-call with the --local and --pillar_root=:conf_minion: cachedir/pillar options. Before enabling this setting consider that the rendered pillar may contain security sensitive data. Appropriate access restrictions should be in place. By default the saved pillar data will be readable only by the user account running salt. By default this feature is disabled, to enable set minion_pillar_cache to True.

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.

Security Settings¶

open_mode¶

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

master_finger¶

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

verify_master_pubkey_sign¶

Default: False Enables verification of the master-public-signature returned by the master in auth-replies. Please see the tutorial on how to configure this properly Multimaster-PKI with Failover Tutorial New in version 2014.7.0.
If this is set to True, master_sign_pubkey must be also set to True in the master configuration file.

master_sign_key_name¶

Default: master_sign The filename without the .pub suffix of the public key that should be used for verifying the signature from the master. The file must be located in the minion's pki directory. New in version 2014.7.0.

always_verify_signature¶

Default: False If verify_master_pubkey_sign is enabled, the signature is only verified if the public-key of the master changes. If the signature should always be verified, this can be set to True. New in version 2014.7.0.

cmd_blacklist_glob¶

Default: [] If cmd_blacklist_glob is enabled then any shell command called over remote execution or via salt-call will be checked against the glob matches found in the cmd_blacklist_glob list and any matched shell command will be blocked. NOTE:
New in version 2016.11.0.

cmd_whitelist_glob¶

Default: [] If cmd_whitelist_glob is enabled then any shell command called over remote execution or via salt-call will be checked against the glob matches found in the cmd_whitelist_glob list and any shell command NOT found in the list will be blocked. If cmd_whitelist_glob is NOT SET, then all shell commands are permitted. NOTE:
New in version 2016.11.0.

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.

Thread Settings¶

Default: True If multiprocessing is enabled when a minion receives a publication a new process is spawned and the command is executed therein. Conversely, if multiprocessing is disabled the new publication will be run executed in a thread.

Minion Logging Settings¶

log_file¶

Default: /var/log/salt/minion The minion log can be sent to a regular file, local path name, or network location. See also log_file. Examples:

log_level¶

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

log_level_logfile¶

Default: info 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_datefmt¶

Default: %H:%M:%S The date and time format used in console log messages. See also log_datefmt.

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_fmt_console¶

Default: [%(levelname)-8s] %(message)s The format of the console logging messages. See also log_fmt_console. NOTE:

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_granular_levels¶

Default: {} This can be used to control logging levels more specifically. See also log_granular_levels.

zmq_monitor¶

Default: False To diagnose issues with minions disconnecting or missing returns, ZeroMQ supports the use of monitor sockets to log connection events. This feature requires ZeroMQ 4.0 or higher. To enable ZeroMQ monitor sockets, set 'zmq_monitor' to 'True' and log at a debug level or higher. A sample log event is as follows:
All events logged will include the string ZeroMQ event. A connection event should be logged as the minion starts up and initially connects to the master. If not, check for debug log level and that the necessary version of ZeroMQ is installed.

failhard¶

Default: False Set the global failhard flag. This informs all states to stop running states at the moment a single state fails

Include Configuration¶

default_include¶

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

include¶

Default: not defined The minion can include configuration from other files. To enable this, pass a list of paths to this option. The paths can be either relative or absolute; if relative, they are considered to be relative to the 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 minion will log a warning message.

Frozen Build Update Settings¶

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

update_url¶

Default: False (Update feature is disabled) The url to use when looking for application updates. Esky depends on directory listings to search for new versions. A webserver running on your Master is a good starting point for most setups.

update_restart_services¶

Default: [] (service restarting on update is disabled) A list of services to restart when the minion software is updated. This would typically just be a list containing the minion's service name, but you may have other services that need to go with it.

winrepo_cache_expire_min¶

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

winrepo_cache_expire_max¶

New in version 2016.11.0. Default: 21600 If the windows repo metadata is older than this value, and the metadata is needed by a function in the windows pkg module, the metadata will be refreshed.

Standalone Minion Windows Software Repo Settings¶

IMPORTANT:

winrepo_dir¶

Changed in version 2015.8.0: Renamed from win_repo to winrepo_dir. Also, this option did not have a default value until this version. Default: C:\salt\srv\salt\win\repo Location on the minion where the winrepo_remotes are checked out.

winrepo_cachefile¶

Changed in version 2015.8.0: Renamed from win_repo_cachefile to winrepo_cachefile. Also, this option did not have a default value until this version. Default: winrepo.p Path relative to winrepo_dir where the winrepo cache should be created.

winrepo_remotes¶

Changed in version 2015.8.0: Renamed from win_gitrepos to winrepo_remotes. Also, this option did not have a default value until this version. New in version 2015.8.0. Default: ['https://github.com/saltstack/salt-winrepo.git'] List of git repositories to checkout and include in the winrepo
To specify a specific revision of the repository, prepend a commit ID to the URL of the the repository:
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.

Configuration file examples¶

Example master configuration file¶

Example minion configuration file¶

Minion Blackout Configuration¶

New in version 2016.3.0. Salt supports minion blackouts. When a minion is in blackout mode, all remote execution commands are disabled. This allows production minions to be put "on hold", eliminating the risk of an untimely configuration change. Minion blackouts are configured via a special pillar key, minion_blackout. If this key is set to True, then the minion will reject all incoming commands, except for saltutil.refresh_pillar. (The exception is important, so minions can be brought out of blackout mode) Salt also supports an explicit whitelist of additional functions that will be allowed during blackout. This is configured with the special pillar key minion_blackout_whitelist, which is formed as a list:

Access Control System¶

New in version 0.10.4. Salt maintains a standard system used to open granular control to non administrative users to execute Salt commands. The access control system has been applied to all systems used to configure access to non administrative control interfaces in Salt. These interfaces include, the peer system, the external auth system and the publisher acl system. The access control system mandated a standard configuration syntax used in all of the three aforementioned systems. While this adds functionality to the configuration in 0.10.4, it does not negate the old configuration. Now specific functions can be opened up to specific minions from specific users in the case of external auth and publisher ACLs, and for specific minions in the case of the peer system.

Publisher ACL system¶

The salt publisher ACL system is a means to allow system users other than root to have access to execute select salt commands on minions from the master. The publisher ACL system is configured in the master configuration file via the publisher_acl configuration option. Under the publisher_acl configuration option the users open to send commands are specified and then a list of regular expressions which specify the minion functions which will be made available to specified user. This configuration is much like the peer configuration:
WARNING: client_acl and client_acl_blacklist options are deprecated and will be removed in the future releases. Use publisher_acl and publisher_acl_blacklist instead.

Permission Issues¶

Directories required for publisher_acl must be modified to be readable by the users specified:
NOTE:
If you are upgrading from earlier versions of salt you must also remove any existing user keys and re-start the Salt master:

Whitelist and Blacklist¶

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

External Authentication System¶

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

External Authentication System Configuration¶

The external authentication system allows for specific users to be granted access to execute specific functions on specific minions. Access is configured in the master configuration file and uses the access control system:
The above configuration allows the user thatch to execute functions in the test and network modules on the minions that match the web* target. User steve is given unrestricted access to minion commands. Salt respects the current PAM configuration in place, and uses the 'login' service to authenticate. NOTE:
NOTE:
To allow access to wheel modules or runner modules the following @ syntax must be used:
NOTE:
NOTE:
WARNING:

Matching syntax¶

The structure of the external_auth dictionary can take the following shapes. Function matches are regular expressions; minion matches are compound targets. By user:
By user, by minion:

Groups¶

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

Limiting by function arguments¶

Positional arguments or keyword arguments to functions can also be whitelisted. New in version 2016.3.0.
The rules:

Usage¶

The external authentication system can then be used from the command-line by any user on the same system as the master with the -a option:
The system will ask the user for the credentials required by the authentication system and then publish the command.

Tokens¶

With external authentication alone, the authentication credentials will be required with every call to Salt. This can be alleviated with Salt tokens. Tokens are short term authorizations and can be easily created by just adding a -T option when authenticating:
Now a token will be created that has an expiration of 12 hours (by default). This token is stored in a file named salt_token in the active user's home directory. Once the token is created, it is sent with all subsequent communications. User authentication does not need to be entered again until the token expires. Token expiration time can be set in the Salt master config file.

LDAP and Active Directory¶

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

OpenLDAP and similar systems¶

LDAP configuration happens in the Salt master configuration file. Server configuration values and their defaults:
There are two phases to LDAP authentication. First, Salt authenticates to search for a users' Distinguished Name and group membership. The user it authenticates as in this phase is often a special LDAP system user with read-only access to the LDAP directory. After Salt searches the directory to determine the actual user's DN and groups, it re-authenticates as the user running the Salt commands. If you are already aware of the structure of your DNs and permissions in your LDAP store are set such that users can look up their own group memberships, then the first and second users can be the same. To tell Salt this is the case, omit the auth.ldap.bindpw parameter. You can template the binddn like this:
Salt will use the password entered on the salt command line in place of the bindpw. To use two separate users, specify the LDAP lookup user in the binddn directive, and include a bindpw like so
As mentioned before, Salt uses a filter to find the DN associated with a user. Salt substitutes the {{ username }} value for the username when querying LDAP
For OpenLDAP, to determine group membership, one can specify an OU that contains group data. This is prepended to the basedn to create a search path. Then the results are filtered against auth.ldap.groupclass, default posixGroup, and the account's 'name' attribute, memberUid by default.
When using the ldap('DC=domain,DC=com') eauth operator, sometimes the records returned from LDAP or Active Directory have fully-qualified domain names attached, while minion IDs instead are simple hostnames. The parameter below allows the administrator to strip off a certain set of domain names so the hostnames looked up in the directory service can match the minion IDs.

Active Directory¶

Active Directory handles group membership differently, and does not utilize the groupou configuration variable. AD needs the following options in the master config:
To determine group membership in AD, the username and password that is entered when LDAP is requested as the eAuth mechanism on the command line is used to bind to AD's LDAP interface. If this fails, then it doesn't matter what groups the user belongs to, he or she is denied access. Next, the distinguishedName of the user is looked up with the following LDAP search:
This should return a distinguishedName that we can use to filter for group membership. Then the following LDAP query is executed:

To configure a LDAP group, append a % to the ID:
In addition, if there are a set of computers in the directory service that should be part of the eAuth definition, they can be specified like this:
The string inside ldap() above is any valid LDAP/AD tree limiter. OU= in particular is permitted as long as it would return a list of computer objects.

Peer Communication¶

Salt 0.9.0 introduced the capability for Salt minions to publish commands. The intent of this feature is not for Salt minions to act as independent brokers one with another, but to allow Salt minions to pass commands to each other. In Salt 0.10.0 the ability to execute runners from the master was added. This allows for the master to return collective data from runners back to the minions via the peer interface. The peer interface is configured through two options in the master configuration file. For minions to send commands from the master the peer configuration is used. To allow for minions to execute runners from the master the peer_run configuration is used. Since this presents a viable security risk by allowing minions access to the master publisher the capability is turned off by default. The minions can be allowed access to the master publisher on a per minion basis based on regular expressions. Minions with specific ids can be allowed access to certain Salt modules and functions.

Peer Configuration¶

The configuration is done under the peer setting in the Salt master configuration file, here are a number of configuration possibilities. The simplest approach is to enable all communication for all minions, this is only recommended for very secure environments.
This configuration will allow minions with IDs ending in example.com access to the test, ps, and pkg module functions.
The configuration logic is simple, a regular expression is passed for matching minion ids, and then a list of expressions matching minion functions is associated with the named minion. For instance, this configuration will also allow minions ending with foo.org access to the publisher.
NOTE:

Peer Runner Communication¶

Configuration to allow minions to execute runners from the master is done via the peer_run option on the master. The peer_run configuration follows the same logic as the peer option. The only difference is that access is granted to runner modules. To open up access to all minions to all runners:
This configuration will allow minions with IDs ending in example.com access to the manage and jobs runner functions.
NOTE:

Using Peer Communication¶

The publish module was created to manage peer communication. The publish module comes with a number of functions to execute peer communication in different ways. Currently there are three functions in the publish module. These examples will show how to test the peer system via the salt-call command. To execute test.ping on all minions:
To execute the manage.up runner:
To match minions using other matchers, use expr_form:
NOTE:

When to Use Each Authentication System¶

publisher_acl is useful for allowing local system users to run Salt commands without giving them root access. If you can log into the Salt master directly, then publisher_acl allows you to use Salt without root privileges. If the local system is configured to authenticate against a remote system, like LDAP or Active Directory, then publisher_acl will interact with the remote system transparently. external_auth is useful for salt-api or for making your own scripts that use Salt's Python API. It can be used at the CLI (with the -a flag) but it is more cumbersome as there are more steps involved. The only time it is useful at the CLI is when the local system is not configured to authenticate against an external service but you still want Salt to authenticate against an external service.

Examples¶

The access controls are manifested using matchers in these configurations:
In the above example, fred is able to send commands only to minions which match the specified glob target. This can be expanded to include other functions for other minions based on standard targets (all matchers are supported except the compound one).
The above allows for all minions to be hit by test.ping by dave, and adds a few functions that dave can execute on other minions. It also allows steve unrestricted access to salt commands. NOTE:

Job Management¶

New in version 0.9.7. Since Salt executes jobs running on many systems, Salt needs to be able to manage jobs running on many systems.

The Minion proc System¶

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

Functions in the saltutil Module¶

Salt 0.9.7 introduced a few new functions to the saltutil module for managing jobs. These functions are:
These functions make up the core of the back end used to manage jobs at the minion level.

The jobs Runner¶

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

active¶

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

lookup_jid¶

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

list_jobs¶

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

Scheduling Jobs¶

Salt's scheduling system allows incremental executions on minions or the master. The schedule system exposes the execution of any execution function on minions or any runner on the master. Scheduling can be enabled by multiple methods:
NOTE:
A scheduled run has no output on the minion unless the config is set to info level or higher. Refer to minion-logging-settings. States are executed on the minion, as all states are. You can pass positional arguments and provide a YAML dict of named arguments.
This will schedule the command: state.sls httpd test=True every 3600 seconds (every hour).
This will schedule the command: state.sls httpd test=True every 3600 seconds (every hour) splaying the time between 0 and 15 seconds.
This will schedule the command: state.sls httpd test=True every 3600 seconds (every hour) splaying the time between 10 and 15 seconds.

Schedule by Date and Time¶

New in version 2014.7.0. Frequency of jobs can also be specified using date strings supported by the Python dateutil library. This requires the Python dateutil library to be installed.
This will schedule the command: state.sls httpd test=True at 5:00 PM minion localtime.
This will schedule the command: state.sls httpd test=True at 5:00 PM on Monday, Wednesday and Friday, and 3:00 PM on Tuesday and Thursday.
This will schedule the command: state.sls httpd test=True every 3600 seconds (every hour) between the hours of 8:00 AM and 5:00 PM. The range parameter must be a dictionary with the date strings using the dateutil format.
Using the invert option for range, this will schedule the command state.sls httpd test=True every 3600 seconds (every hour) until the current time is between the hours of 8:00 AM and 5:00 PM. The range parameter must be a dictionary with the date strings using the dateutil format.
This will schedule the function pkg.install to be executed once at the specified time. The schedule entry job1 will not be removed after the job completes, therefore use schedule.delete to manually remove it afterwards. The default date format is ISO 8601 but can be overridden by also specifying the once_fmt option, like this:

Maximum Parallel Jobs Running¶

New in version 2014.7.0. The scheduler also supports ensuring that there are no more than N copies of a particular routine running. Use this for jobs that may be long-running and could step on each other or pile up in case of infrastructure outage. The default for maxrunning is 1.

Cron-like Schedule¶

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

Job Data Return¶

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

Job Metadata¶

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

Run on Start¶

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

Until and After¶

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

Scheduling States¶

Scheduling Highstates¶

To set up a highstate to run on a minion every 60 minutes set this in the minion config or pillar:
Time intervals can be specified as seconds, minutes, hours, or days.

Scheduling Runners¶

Runner executions can also be specified on the master within the master configuration file:
The above configuration is analogous to running salt-run state.orch orchestration.my_orch every 6 hours.

Scheduler With Returner¶

The scheduler is also useful for tasks like gathering monitoring data about a minion, this schedule option will gather status data and send it to a MySQL returner database:
Since specifying the returner repeatedly can be tiresome, the schedule_returner option is available to specify one or a list of global returners to be used by the minions when scheduling.

Managing the Job Cache¶

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

Default Job Cache¶

A number of options are available when configuring the job cache. The default caching system uses local storage on the Salt Master and can be found in the job cache directory (on Linux systems this is typically /var/cache/salt/master/jobs). The default caching system is suitable for most deployments as it does not typically require any further configuration or management. The default job cache is a temporary cache and jobs will be stored for 24 hours. If the default cache needs to store jobs for a different period the time can be easily adjusted by changing the keep_jobs parameter in the Salt Master configuration file. The value passed in is measured via hours:

Reducing the Size of the Default Job Cache¶

The Default Job Cache can sometimes be a burden on larger deployments (over 5000 minions). Disabling the job cache will make previously 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. However, you can disable the job_cache by setting it to False in the Salt Master configuration file. Setting this value to False means that the Salt Master will no longer cache minion returns, but a JID directory and jid file for each job will still be created. This JID directory is necessary for checking for and preventing JID collisions. The default location for the job cache is in the /var/cache/salt/master/jobs/ directory. Setting the job_cache` to False in addition to setting the keep_jobs option to a smaller value, such as 1, in the Salt Master configuration file will reduce the size of the Default Job Cache, and thus the burden on the Salt Master. NOTE:

Additional Job Cache Options¶

Many deployments may wish to use an external database to maintain a long term register of executed jobs. Salt comes with two main mechanisms to do this, the master job cache and the external job cache. See Storing Job Results in an External System.

Storing Job Results in an External System¶

After a job executes, job results are returned to the Salt Master by each Salt Minion. These results are stored in the Default Job Cache. In addition to the Default Job Cache, Salt provides two additional mechanisms to send job results to other systems (databases, local syslog, and others):
The major difference between these two mechanism is from where results are returned (from the Salt Master or Salt Minion).

External Job Cache - Minion-Side Returner¶

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

Master Job Cache - Master-Side Returner¶

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

Configure an External or Master Job Cache¶

Step 1: Understand Salt Returners¶

Before you configure a job cache, it is essential to understand Salt returner modules ("returners"). Returners are pluggable Salt Modules that take the data returned by jobs, and then perform any necessary steps to send the data to an external system. For example, a returner might establish a connection, authenticate, and then format and transfer data. The Salt Returner system provides the core functionality used by the External and Master Job Cache systems, and the same returners are used by both systems. Salt currently provides many different returners that let you connect to a wide variety of systems. A complete list is available at all Salt returners. Each returner is configured differently, so make sure you read and follow the instructions linked from that page. For example, the MySQL returner requires:
A simpler returner, such as Slack or HipChat, requires:

Step 2: Configure the Returner¶

After you understand the configuration and have the external system ready, add the returner configuration settings to the Salt Minion configuration file for the External Job Cache, or to the Salt Master configuration file for the Master Job Cache. For example, MySQL requires:
Slack requires:
After you have configured the returner and added settings to the configuration file, you can enable the External or Master Job Cache.

Step 3: Enable the External or Master Job Cache¶

Configuration is a single line that specifies an already-configured returner to use to send all job data to an external system.

External Job Cache¶

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

Master Job Cache¶

To enable a returner as a Master Job Cache (Master-side), add the following line to the Salt Master configuration file:
For example:
Verify that the returner configuration settings are in the Master configuration file, and be sure to restart the salt-master service after you make configuration changes. ( service salt-master restart).

Logging¶

The salt project tries to get the logging to work for you and help us solve any issues you might find along the way. If you want to get some more information on the nitty-gritty of salt's logging system, please head over to the logging development document, if all you're after is salt's logging configurations, please continue reading.

Log Levels¶

The log levels are ordered numerically such that setting the log level to a specific level will record all log statements at that level and higher. For example, setting log_level: error will log statements at error, critical, and quiet levels, although nothing should be logged at quiet level. Most of the logging levels are defined by default in Python's logging library and can be found in the official Python documentation. Salt uses some more levels in addition to the standard levels. All levels available in salt are shown in the table below. NOTE:

Level	Numeric value	Description
quiet	1000	Nothing should be logged at this level
critical	50	Critical errors
error	40	Errors
warning	30	Warnings
info	20	Normal log information
profile	15	Profiling information on salt performance
debug	10	Information useful for debugging both salt implementations and salt code
trace	5	More detailed code debugging information
garbage	1	Even more debugging information
all	0	Everything

Available Configuration Settings¶

log_file¶

The log records can be sent to a regular file, local path name, or network location. Remote logging works best when configured to use rsyslogd(8) (e.g.: file:///dev/log), with rsyslogd(8) configured for network logging. The format for remote addresses is: <file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility>. Where log-facility is the symbolic name of a syslog facility as defined in the SysLogHandler documentation . It defaults to LOG_USER. Default: Dependent of the binary being executed, for example, for salt-master, /var/log/salt/master. Examples:

log_level¶

Default: warning The level of log record messages to send to the console. One of all, garbage, trace, debug, profile, info, warning, error, critical, quiet.
NOTE:

log_level_logfile¶

Default: info The level of messages to send to the log file. One of all, garbage, trace, debug, profile, info, warning, error, critical, quiet.

log_datefmt¶

Default: %H:%M:%S The date and time format used in console log messages. Allowed date/time formatting can be seen on time.strftime.

log_datefmt_logfile¶

Default: %Y-%m-%d %H:%M:%S The date and time format used in log file messages. Allowed date/time formatting can be seen on time.strftime.

log_fmt_console¶

Default: [%(levelname)-8s] %(message)s The format of the console logging messages. All standard python logging LogRecord attributes can be used. Salt also provides these custom LogRecord attributes to colorize console log output:
NOTE:

log_fmt_logfile¶

Default: %(asctime)s,%(msecs)03d [%(name)-17s][%(levelname)-8s] %(message)s The format of the log file logging messages. All standard python logging LogRecord attributes can be used. Salt also provides these custom LogRecord attributes that include padding and enclosing brackets [ and ]:

log_granular_levels¶

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

External Logging Handlers¶

Besides the internal logging handlers used by salt, there are some external which can be used, see the external logging handlers document.

Salt File Server¶

Salt comes with a simple file server suitable for distributing files to the Salt minions. The file server is a stateless ZeroMQ server that is built into the Salt master. The main intent of the Salt file server is to present files for use in the Salt state system. With this said, the Salt file server can be used for any general file transfer from the master to the minions.

File Server Backends¶

In Salt 0.12.0, the modular fileserver was introduced. This feature added the ability for the Salt Master to integrate different file server backends. File server backends allow the Salt file server to act as a transparent bridge to external resources. A good example of this is the git backend, which allows Salt to serve files sourced from one or more git repositories, but there are several others as well. Click here for a full list of Salt's fileserver backends.

Enabling a Fileserver Backend¶

Fileserver backends can be enabled with the fileserver_backend option.
See the documentation for each backend to find the correct value to add to fileserver_backend in order to enable them.

Using Multiple Backends¶

If fileserver_backend is not defined in the Master config file, Salt will use the roots backend, but the fileserver_backend option supports multiple backends. When more than one backend is in use, the files from the enabled backends are merged into a single virtual filesystem. When a file is requested, the backends will be searched in order for that file, and the first backend to match will be the one which returns the file.
With this configuration, the environments and files defined in the file_roots parameter will be searched first, and if the file is not found then the git repositories defined in gitfs_remotes will be searched.

Defining Environments¶

Just as the order of the values in fileserver_backend matters, so too does the order in which different sources are defined within a fileserver environment. For example, given the below file_roots configuration, if both /srv/salt/dev/foo.txt and /srv/salt/prod/foo.txt exist on the Master, then salt://foo.txt would point to /srv/salt/dev/foo.txt in the dev environment, but it would point to /srv/salt/prod/foo.txt in the base environment.
Similarly, when using the git backend, if both repositories defined below have a hotfix23 branch/tag, and both of them also contain the file bar.txt in the root of the repository at that branch/tag, then salt://bar.txt in the hotfix23 environment would be served from the first repository.
NOTE:

Dynamic Module Distribution¶

New in version 0.9.5. Custom Salt execution, state, and other modules can be distributed to Salt minions using the Salt file server. Under the root of any environment defined via the file_roots option on the master server directories corresponding to the type of module can be used. The directories are prepended with an underscore:
The contents of these directories need to be synced over to the minions after Python modules have been created in them. There are a number of ways to sync the modules.

Sync Via States¶

The minion configuration contains an option autoload_dynamic_modules which defaults to True. This option makes the state system refresh all dynamic modules when states are run. To disable this behavior set autoload_dynamic_modules to False in the minion config. When dynamic modules are autoloaded via states, modules only pertinent to the environments matched in the master's top file are downloaded. This is important to remember, because modules can be manually loaded from any specific environment that environment specific modules will be loaded when a state run is executed.

Sync Via the saltutil Module¶

The saltutil module has a number of functions that can be used to sync all or specific dynamic modules. The saltutil module function saltutil.sync_all will sync all module types over to a minion. For more information see: salt.modules.saltutil

Requesting Files from Specific Environments¶

The Salt fileserver supports multiple environments, allowing for SLS files and other files to be isolated for better organization. For the default backend (called roots), environments are defined using the roots option. Other backends (such as gitfs) define environments in their own ways. For a list of available fileserver backends, see here.

Querystring Syntax¶

Any salt:// file URL can specify its fileserver environment using a querystring syntax, like so:
In Reactor configurations, this method must be used to pull files from an environment other than base.

In States¶

Minions can be instructed which environment to use both globally, and for a single state, and multiple methods for each are available:

Globally¶

A minion can be pinned to an environment using the environment option in the minion config file. Additionally, the environment can be set for a single call to the following functions:
NOTE:

On a Per-State Basis¶

Within an individual state, there are two ways of specifying the environment. The first is to add a saltenv argument to the state. This example will pull the file from the config environment:
Another way of doing the same thing is to use the querystring syntax described above:
NOTE:

File Server Configuration¶

The Salt file server is a high performance file server written in ZeroMQ. It manages large files quickly and with little overhead, and has been optimized to handle small files in an extremely efficient manner. The Salt file server is an environment aware file server. This means that files can be allocated within many root directories and accessed by specifying both the file path and the environment to search. The individual environments can span across multiple directory roots to create overlays and to allow for files to be organized in many flexible ways.

Environments¶

The Salt file server defaults to the mandatory base environment. This environment MUST be defined and is used to download files when no environment is specified. Environments allow for files and sls data to be logically separated, but environments are not isolated from each other. This allows for logical isolation of environments by the engineer using Salt, but also allows for information to be used in multiple environments.

Directory Overlay¶

The environment setting is a list of directories to publish files from. These directories are searched in order to find the specified file and the first file found is returned. This means that directory data is prioritized based on the order in which they are listed. In the case of this file_roots configuration:
If a file's URI is salt://httpd/httpd.conf, it will first search for the file at /srv/salt/base/httpd/httpd.conf. If the file is found there it will be returned. If the file is not found there, then /srv/salt/failover/httpd/httpd.conf will be used for the source. This allows for directories to be overlaid and prioritized based on the order they are defined in the configuration. It is also possible to have file_roots which supports multiple environments:
This example ensures that each environment will check the associated environment directory for files first. If a file is not found in the appropriate directory, the system will default to using the base directory.

Local File Server¶

New in version 0.9.8. The file server can be rerouted to run from the minion. This is primarily to enable running Salt states without a Salt master. To use the local file server interface, copy the file server data to the minion and set the file_roots option on the minion to point to the directories copied from the master. Once the minion file_roots option has been set, change the file_client option to local to make sure that the local file server interface is used.

The cp Module¶

The cp module is the home of minion side file server operations. The cp module is used by the Salt state system, salt-cp, and can be used to distribute files presented by the Salt file server.

Escaping Special Characters¶

The salt:// url format can potentially contain a query string, for example salt://dir/file.txt?saltenv=base. You can prevent the fileclient/fileserver from interpreting ? as the initial token of a query string by referencing the file with salt://| rather than salt://.

Environments¶

Since the file server is made to work with the Salt state system, it supports environments. The environments are defined in the master config file and when referencing an environment the file specified will be based on the root directory of the environment.

get_file¶

The cp.get_file function can be used on the minion to download a file from the master, the syntax looks like this:
This will instruct all Salt minions to download the vimrc file and copy it to /etc/vimrc Template rendering can be enabled on both the source and destination file names like so:
This example would instruct all Salt minions to download the vimrc from a directory with the same name as their OS grain and copy it to /etc/vimrc For larger files, the cp.get_file module also supports gzip compression. Because gzip is CPU-intensive, this should only be used in scenarios where the compression ratio is very high (e.g. pretty-printed JSON or YAML files). To use compression, use the gzip named argument. Valid values are integers from 1 to 9, where 1 is the lightest compression and 9 the heaviest. In other words, 1 uses the least CPU on the master (and minion), while 9 uses the most.
Finally, note that by default cp.get_file does not create new destination directories if they do not exist. To change this, use the makedirs argument:
In this example, /etc/vim/ would be created if it didn't already exist.

get_dir¶

The cp.get_dir function can be used on the minion to download an entire directory from the master. The syntax is very similar to get_file:
cp.get_dir supports template rendering and gzip compression arguments just like get_file:

File Server Client Instance¶

A client instance is available which allows for modules and applications to be written which make use of the Salt file server. The file server uses the same authentication and encryption used by the rest of the Salt system for network communication.

fileclient Module¶

The salt/fileclient.py module is used to set up the communication from the minion to the master. When creating a client instance using the fileclient module, the minion configuration needs to be passed in. When using the fileclient module from within a minion module the built in __opts__ data can be passed:
Creating a fileclient instance outside of a minion module where the __opts__ data is not available, it needs to be generated:

Git Fileserver Backend Walkthrough¶

NOTE:
The gitfs backend allows Salt to serve files from git repositories. It can be enabled by adding git to the fileserver_backend list, and configuring one or more repositories in gitfs_remotes. Branches and tags become Salt fileserver environments. NOTE:

Installing Dependencies¶

Beginning with version 2014.7.0, both pygit2 and Dulwich are supported as alternatives to GitPython. The desired provider can be configured using the gitfs_provider parameter in the master config file. If gitfs_provider is not configured, then Salt will prefer pygit2 if a suitable version is available, followed by GitPython and Dulwich. NOTE:

pygit2¶

The minimum supported version of pygit2 is 0.20.3. Availability for this version of pygit2 is still limited, though the SaltStack team is working to get compatible versions available for as many platforms as possible. For the Fedora/EPEL versions which have a new enough version packaged, the following command would be used to install pygit2:
Provided a valid version is packaged for Debian/Ubuntu (which is not currently the case), the package name would be the same, and the following command would be used to install it:
If pygit2 is not packaged for the platform on which the Master is running, the pygit2 website has installation instructions here. Keep in mind however that following these instructions will install libgit2 and pygit2 without system packages. Additionally, keep in mind that SSH authentication in pygit2 requires libssh2 (not libssh) development libraries to be present before libgit2 is built. On some Debian-based distros pkg-config is also required to link libgit2 with libssh2. Additionally, version 0.21.0 of pygit2 introduced a dependency on python-cffi, which in turn depends on newer releases of libffi. Upgrading libffi is not advisable as several other applications depend on it, so on older LTS linux releases pygit2 0.20.3 and libgit2 0.20.0 is the recommended combination. While these are not packaged in the official repositories for Debian and Ubuntu, SaltStack is actively working on adding packages for these to our repositories. The progress of this effort can be tracked here. WARNING:

GitPython¶

GitPython 0.3.0 or newer is required to use GitPython for gitfs. For RHEL-based Linux distros, a compatible version is available in EPEL, and can be easily installed on the master using yum:
Ubuntu 14.04 LTS and Debian Wheezy (7.x) also have a compatible version packaged:
If your master is running an older version (such as Ubuntu 12.04 LTS or Debian Squeeze), then you will need to install GitPython using either pip or easy_install (it is recommended to use pip). Version 0.3.2.RC1 is now marked as the stable release in PyPI, so it should be a simple matter of running pip install GitPython (or easy_install GitPython) as root. WARNING:
WARNING:

Dulwich¶

Dulwich 0.9.4 or newer is required to use Dulwich as backend for gitfs. Dulwich is available in EPEL, and can be easily installed on the master using yum:
For APT-based distros such as Ubuntu and Debian:
IMPORTANT:

Simple Configuration¶

To use the gitfs backend, only two configuration changes are required on the master:
NOTE:

Multiple Remotes¶

The gitfs_remotes option accepts an ordered list of git remotes to cache and search, in listed order, for requested files. A simple scenario illustrates this cascading lookup behavior: If the gitfs_remotes option specifies three remotes:
And each repository contains some files:
Salt will attempt to lookup the requested file from each gitfs remote repository in the order in which they are defined in the configuration. The git://github.com/example/first.git remote will be searched first. If the requested file is found, then it is served and no further searching is executed. For example:
NOTE:
WARNING:

Per-remote Configuration Parameters¶

New in version 2014.7.0. The following master config parameters are global (that is, they apply to all configured gitfs remotes):
These parameters can now be overridden on a per-remote basis. This allows for a tremendous amount of customization. Here's some example usage:
IMPORTANT:
In the example configuration above, the following is true:

Per-Saltenv Configuration Parameters¶

New in version 2016.11.0. For more granular control, Salt allows the following three things to be overridden for individual saltenvs within a given repo:
Here is an example:
Given the above configuration, the following is true:

Configuration Order of Precedence¶

The order of precedence for gitfs configuration is as follows (each level overrides all levels below it):

Serving from a Subdirectory¶

The gitfs_root parameter allows files to be served from a subdirectory within the repository. This allows for only part of a repository to be exposed to the Salt fileserver. Assume the below layout:
The below configuration would serve only the files under foo/baz, ignoring the other files in the repository:
The root can also be configured on a per-remote basis.

Mountpoints¶

New in version 2014.7.0. The gitfs_mountpoint parameter will prepend the specified path to the files served from gitfs. This allows an existing repository to be used, rather than needing to reorganize a repository or design it around the layout of the Salt fileserver. Before the addition of this feature, if a file being served up via gitfs was deeply nested within the root directory (for example, salt://webapps/foo/files/foo.conf, it would be necessary to ensure that the file was properly located in the remote repository, and that all of the the parent directories were present (for example, the directories webapps/foo/files/ would need to exist at the root of the repository). The below example would allow for a file foo.conf at the root of the repository to be served up from the Salt fileserver path salt://webapps/foo/files/foo.conf.
Mountpoints can also be configured on a per-remote basis.

Using gitfs Alongside Other Backends¶

Sometimes it may make sense to use multiple backends; for instance, if sls files are stored in git but larger files are stored directly on the master. The cascading lookup logic used for multiple remotes is also used with multiple backends. If the fileserver_backend option contains multiple backends:
Then the roots backend (the default backend of files in /srv/salt) will be searched first for the requested file; then, if it is not found on the master, each configured git remote will be searched.

Branches, Environments, and Top Files¶

When using the gitfs backend, branches, and tags will be mapped to environments using the branch/tag name as an identifier. There is one exception to this rule: the master branch is implicitly mapped to the base environment. So, for a typical base, qa, dev setup, the following branches could be used:
top.sls files from different branches will be merged into one at runtime. Since this can lead to overly complex configurations, the recommended setup is to have a separate repository, containing only the top.sls file with just one single master branch. To map a branch other than master as the base environment, use the gitfs_base parameter.
The base can also be configured on a per-remote basis.

Environment Whitelist/Blacklist¶

New in version 2014.7.0. The gitfs_env_whitelist and gitfs_env_blacklist parameters allow for greater control over which branches/tags are exposed as fileserver environments. Exact matches, globs, and regular expressions are supported, and are evaluated in that order. If using a regular expression, ^ and $ must be omitted, and the expression must match the entire branch/tag.
NOTE:
The behavior of the blacklist/whitelist will differ depending on which combination of the two options is used:

Authentication¶

pygit2¶

New in version 2014.7.0. Both HTTPS and SSH authentication are supported as of version 0.20.3, which is the earliest version of pygit2 supported by Salt for gitfs. NOTE:

HTTPS¶

For HTTPS repositories which require authentication, the username and password can be provided like so:
If the repository is served over HTTP instead of HTTPS, then Salt will by default refuse to authenticate to it. This behavior can be overridden by adding an insecure_auth parameter:

SSH¶

SSH repositories can be configured using the ssh:// protocol designation, or using scp-like syntax. So, the following two configurations are equivalent:
Both gitfs_pubkey and gitfs_privkey (or their per-remote counterparts) must be configured in order to authenticate to SSH-based repos. If the private key is protected with a passphrase, it can be configured using gitfs_passphrase (or simply passphrase if being configured per-remote). For example:
Finally, the SSH host key must be added to the known_hosts file.

GitPython¶

With GitPython, only passphrase-less SSH public key authentication is supported. The auth parameters (pubkey, privkey, etc.) shown in the pygit2 authentication examples above do not work with GitPython.
Since GitPython wraps the git CLI, the private key must be located in ~/.ssh/id_rsa for the user under which the Master is running, and should have permissions of 0600. Also, in the absence of a user in the repo URL, GitPython will (just as SSH does) attempt to login as the current user (in other words, the user under which the Master is running, usually root). If a key needs to be used, then ~/.ssh/config can be configured to use the desired key. Information on how to do this can be found by viewing the manpage for ssh_config. Here's an example entry which can be added to the ~/.ssh/config to use an alternate key for gitfs:
The Host parameter should be a hostname (or hostname glob) that matches the domain name of the git repository. It is also necessary to add the SSH host key to the known_hosts file. The exception to this would be if strict host key checking is disabled, which can be done by adding StrictHostKeyChecking no to the entry in ~/.ssh/config
However, this is generally regarded as insecure, and is not recommended.

Adding the SSH Host Key to the known_hosts File¶

To use SSH authentication, it is necessary to have the remote repository's SSH host key in the ~/.ssh/known_hosts file. If the master is also a minion, this can be done using the ssh.set_known_host function:
If not, then the easiest way to add the key is to su to the user (usually root) under which the salt-master runs and attempt to login to the server via SSH:
It doesn't matter if the login was successful, as answering yes will write the fingerprint to the known_hosts file.

Verifying the Fingerprint¶

To verify that the correct fingerprint was added, it is a good idea to look it up. One way to do this is to use nmap:
Another way is to check one's own known_hosts file, using this one-liner:
WARNING:
NOTE:

Refreshing gitfs Upon Push¶

By default, Salt updates the remote fileserver backends every 60 seconds. However, if it is desirable to refresh quicker than that, the Reactor System can be used to signal the master to update the fileserver on each push, provided that the git server is also a Salt minion. There are three steps to this process:
The update argument right after event.fire_master in this example can really be anything, as it represents the data being passed in the event, and the passed data is ignored by this reactor. Similarly, the tag name salt/fileserver/gitfs/update can be replaced by anything, so long as the usage is consistent. The root user name in the hook script and sudo policy should be changed to match the user under which the minion is running.

Using Git as an External Pillar Source¶

The git external pillar (a.k.a. git_pillar) has been rewritten for the 2015.8.0 release. This rewrite brings with it pygit2 support (allowing for access to authenticated repositories), as well as more granular support for per-remote configuration. To make use of the new features, changes to the git ext_pillar configuration must be made. The new configuration schema is detailed here. For Salt releases before 2015.8.0, click here for documentation.

Why aren't my custom modules/states/etc. syncing to my Minions?¶

In versions 0.16.3 and older, when using the git fileserver backend, certain versions of GitPython may generate errors when fetching, which Salt fails to catch. While not fatal to the fetch process, these interrupt the fileserver update that takes place before custom types are synced, and thus interrupt the sync itself. Try disabling the git fileserver backend in the master config, restarting the master, and attempting the sync again. This issue is worked around in Salt 0.16.4 and newer.

MinionFS Backend Walkthrough¶

New in version 2014.1.0. NOTE:
Sometimes it is desirable to deploy a file located on one minion to one or more other minions. This is supported in Salt, and can be accomplished in two parts:
This walkthrough will show how to use both of these features.

Enabling File Push¶

To set the master to accept files pushed from minions, the file_recv option in the master config file must be set to True (the default is False).
NOTE:

Pushing Files¶

Once this has been done, files can be pushed to the master using the cp.push function:
This command will store the file in a subdirectory named minions under the master's cachedir. On most masters, this path will be /var/cache/salt/master/minions. Within this directory will be one directory for each minion which has pushed a file to the master, and underneath that the full path to the file on the minion. So, for example, if a minion with an ID of dev1 pushed a file /var/log/myapp.log to the master, it would be saved to /var/cache/salt/master/minions/dev1/var/log/myapp.log.

Serving Pushed Files Using MinionFS¶

While it is certainly possible to add /var/cache/salt/master/minions to the master's file_roots and serve these files, it may only be desirable to expose files pushed from certain minions. Adding /var/cache/salt/master/minions/<minion-id> for each minion that needs to be exposed can be cumbersome and prone to errors. Enter minionfs. This fileserver backend will make files pushed using cp.push available to the Salt fileserver, and provides an easy mechanism to restrict which minions' pushed files are made available.

Simple Configuration¶

To use the minionfs backend, add minion to the list of backends in the fileserver_backend configuration option on the master:
NOTE:
Files made available via minionfs are by default located at salt://<minion-id>/path/to/file. Think back to the earlier example, in which dev1 pushed a file /var/log/myapp.log to the master. With minionfs enabled, this file would be addressable in Salt at salt://dev1/var/log/myapp.log. If many minions have pushed to the master, this will result in many directories in the root of the Salt fileserver. For this reason, it is recommended to use the minionfs_mountpoint config option to organize these files underneath a subdirectory:
Using the above mountpoint, the file in the example would be located at salt://minionfs/dev1/var/log/myapp.log.

Restricting Certain Minions' Files from Being Available Via MinionFS¶

A whitelist and blacklist can be used to restrict the minions whose pushed files are available via minionfs. These lists can be managed using the minionfs_whitelist and minionfs_blacklist config options. Click the links for both of them for a detailed explanation of how to use them. A more complex configuration example, which uses both a whitelist and blacklist, can be found below:

Potential Concerns¶

Salt Package Manager¶

The Salt Package Manager, or SPM, enables Salt formulas to be packaged to simplify distribution to Salt masters. The design of SPM was influenced by other existing packaging systems including RPM, Yum, and Pacman. [image] NOTE:
Packaging System The packaging system is used to package the state, pillar, file templates, and other files used by your formula into a single file. After a formula package is created, it is copied to the Repository System where it is made available to Salt masters. See Building SPM Packages Repo System The Repo system stores the SPM package and metadata files and makes them available to Salt masters via http(s), ftp, or file URLs. SPM repositories can be hosted on a Salt Master, a Salt Minion, or on another system. See Distributing SPM Packages Salt Master SPM provides Salt master settings that let you configure the URL of one or more SPM repos. You can then quickly install packages that contain entire formulas to your Salt masters using SPM. See Installing SPM Packages Contents

Building SPM Packages¶

The first step when using Salt Package Manager is to build packages for each of of the formulas that you want to distribute. Packages can be built on any system where you can install Salt.

Package Build Overview¶

To build a package, all state, pillar, jinja, and file templates used by your formula are assembled into a folder on the build system. These files can be cloned from a Git repository, such as those found at the saltstack-formulas organization on GitHub, or copied directly to the folder. The following diagram demonstrates a typical formula layout on the build system: [image] In this example, all formula files are placed in a myapp-formula folder. This is the folder that is targeted by the spm build command when this package is built. Within this folder, pillar data is placed in a pillar.example file at the root, and all state, jinja, and template files are placed within a subfolder that is named after the application being packaged. State files are typically contained within a subfolder, similar to how state files are organized in the state tree. Any non-pillar files in your package that are not contained in a subfolder are placed at the root of the spm state tree. Additionally, a FORMULA file is created and placed in the root of the folder. This file contains package metadata that is used by SPM.

Package Installation Overview¶

When building packages, it is useful to know where files are installed on the Salt master. During installation, all files except pillar.example and FORMULA are copied directly to the spm state tree on the Salt master (located at \srv\spm\salt). If a pillar.example file is present in the root, it is renamed to <formula name>.sls.orig and placed in the pillar_path. [image] NOTE:

Building an SPM Formula Package¶

Types of Packages¶

SPM supports different types of packages. The function of each package is denoted by its name. For instance, packages which end in -formula are considered to be Salt States (the most common type of formula). Packages which end in -conf contain configuration which is to be placed in the /etc/salt/ directory. Packages which do not contain one of these names are treated as if they have a -formula name.

formula¶

By default, most files from this type of package live in the /srv/spm/salt/ directory. The exception is the pillar.example file, which will be renamed to <package_name>.sls and placed in the pillar directory ( /srv/spm/pillar/ by default).

reactor¶

By default, files from this type of package live in the /srv/spm/reactor/ directory.

conf¶

The files in this type of package are configuration files for Salt, which normally live in the /etc/salt/ directory. Configuration files for packages other than Salt can and should be handled with a Salt State (using a formula type of package).

Technical Information¶

Packages are built using BZ2-compressed tarballs. By default, the package database is stored using the sqlite3 driver (see Loader Modules below). Support for these are built into Python, and so no external dependencies are needed. All other files belonging to SPM use YAML, for portability and ease of use and maintainability.

SPM-Specific Loader Modules¶

SPM was designed to behave like traditional package managers, which apply files to the filesystem and store package metadata in a local database. However, because modern infrastructures often extend beyond those use cases, certain parts of SPM have been broken out into their own set of modules.

Package Database¶

By default, the package database is stored using the sqlite3 module. This module was chosen because support for SQLite3 is built into Python itself. Please see the SPM Development Guide for information on creating new modules for package database management.

Package Files¶

By default, package files are installed using the local module. This module applies files to the local filesystem, on the machine that the package is installed on. Please see the SPM Development Guide for information on creating new modules for package file management.

Distributing SPM Packages¶

SPM packages can be distributed to Salt masters over HTTP(S), FTP, or through the file system. The SPM repo can be hosted on any system where you can install Salt. Salt is installed so you can run the spm create_repo command when you update or add a package to the repo. SPM repos do not require the salt-master, salt-minion, or any other process running on the system. NOTE:

Setting up a Package Repository¶

After packages are built, the generated SPM files are placed in the srv/spm_build folder. Where you place the built SPM files on your repository server depends on how you plan to make them available to your Salt masters. You can share the srv/spm_build folder on the network, or copy the files to your FTP or Web server.

Adding a Package to the repository¶

New packages are added by simply copying the SPM file to the repo folder, and then generating repo metadata.

Generate Repo Metadata¶

Each time you update or add an SPM package to your repository, issue an spm create_repo command:
SPM generates the repository metadata for all of the packages in that directory and places it in an SPM-METADATA file at the folder root. This command is used even if repository metadata already exists in that directory.

Installing SPM Packages¶

SPM packages are installed to your Salt master, where they are available to Salt minions using all of Salt's package management functions.

Configuring Remote Repositories¶

Before SPM can use a repository, two things need to happen. First, the Salt master needs to know where the repository is through a configuration process. Then it needs to pull down the repository metadata.

Repository Configuration Files¶

Repositories are configured by adding each of them to the /etc/salt/spm.repos.d/spm.repo file on each Salt master. This file contains the name of the repository, and the link to the repository:
The URL can use http, https, ftp, or file.

Updating Local Repository Metadata¶

After the repository is configured on the Salt master, repository metadata is downloaded using the spm update_repo command:
NOTE:

Update File Roots¶

SPM packages are installed to the srv/spm/salt folder on your Salt master. This path needs to be added to the file roots on your Salt master manually.
Restart the salt-master service after updating the file_roots setting.

Installing Packages¶

To install a package, use the spm install command:
WARNING:

Installing directly from an SPM file¶

You can also install SPM packages using a local SPM file using the spm local install command:
An SPM repository is not required when using spm local install.

Pillars¶

If an installed package includes Pillar data, be sure to target the installed pillar to the necessary systems using the pillar Top file.

Removing Packages¶

Packages may be removed after they are installed using the spm remove command.
If files have been modified, they will not be removed. Empty directories will also be removed.

SPM Configuration¶

There are a number of options that are specific to SPM. They may be configured in the master configuration file, or in SPM's own spm configuration file (normally located at /etc/salt/spm). If configured in both places, the spm file takes precedence. In general, these values will not need to be changed from the defaults.

spm_logfile¶

Default: /var/log/salt/spm Where SPM logs messages.

spm_repos_config¶

Default: /etc/salt/spm.repos SPM repositories are configured with this file. There is also a directory which corresponds to it, which ends in .d. For instance, if the filename is /etc/salt/spm.repos, the directory will be /etc/salt/spm.repos.d/.

spm_cache_dir¶

Default: /var/cache/salt/spm When SPM updates package repository metadata and downloads packaged, they will be placed in this directory. The package database, normally called packages.db, also lives in this directory.

spm_db¶

Default: /var/cache/salt/spm/packages.db The location and name of the package database. This database stores the names of all of the SPM packages installed on the system, the files that belong to them, and the metadata for those files.

spm_build_dir¶

Default: /srv/spm_build When packages are built, they will be placed in this directory.

spm_build_exclude¶

Default: ['.git'] When SPM builds a package, it normally adds all files in the formula directory to the package. Files listed here will be excluded from that package. This option requires a list to be specified.

Types of Packages¶

SPM supports different types of formula packages. The function of each package is denoted by its name. For instance, packages which end in -formula are considered to be Salt States (the most common type of formula). Packages which end in -conf contain configuration which is to be placed in the /etc/salt/ directory. Packages which do not contain one of these names are treated as if they have a -formula name.

formula¶

By default, most files from this type of package live in the /srv/spm/salt/ directory. The exception is the pillar.example file, which will be renamed to <package_name>.sls and placed in the pillar directory ( /srv/spm/pillar/ by default).

reactor¶

By default, files from this type of package live in the /srv/spm/reactor/ directory.

conf¶

The files in this type of package are configuration files for Salt, which normally live in the /etc/salt/ directory. Configuration files for packages other than Salt can and should be handled with a Salt State (using a formula type of package).

FORMULA File¶

In addition to the formula itself, a FORMULA file must exist which describes the package. An example of this file is:

Required Fields¶

This file must contain at least the following fields:

name¶

The name of the package, as it will appear in the package filename, in the repository metadata, and the package database. Even if the source formula has -formula in its name, this name should probably not include that. For instance, when packaging the apache-formula, the name should be set to apache.

os¶

The value of the os grain that this formula supports. This is used to help users know which operating systems can support this package.

os_family¶

The value of the os_family grain that this formula supports. This is used to help users know which operating system families can support this package.

version¶

The version of the package. While it is up to the organization that manages this package, it is suggested that this version is specified in a YYYYMM format. For instance, if this version was released in June 2015, the package version should be 201506. If multiple releases are made in a month, the release field should be used.

minimum_version¶

Minimum recommended version of Salt to use this formula. Not currently enforced.

release¶

This field refers primarily to a release of a version, but also to multiple versions within a month. In general, if a version has been made public, and immediate updates need to be made to it, this field should also be updated.

summary¶

A one-line description of the package.

description¶

A more detailed description of the package which can contain more than one line.

Optional Fields¶

The following fields may also be present.

top_level_dir¶

This field is optional, but highly recommended. If it is not specified, the package name will be used. Formula repositories typically do not store .sls files in the root of the repository; instead they are stored in a subdirectory. For instance, an apache-formula repository would contain a directory called apache, which would contain an init.sls, plus a number of other related files. In this instance, the top_level_dir should be set to apache. Files outside the top_level_dir, such as README.rst, FORMULA, and LICENSE will not be installed. The exceptions to this rule are files that are already treated specially, such as pillar.example and _modules/.

dependencies¶

A comma-separated list of packages that must be installed along with this package. When this package is installed, SPM will attempt to discover and install these packages as well. If it is unable to, then it will refuse to install this package. This is useful for creating packages which tie together other packages. For instance, a package called wordpress-mariadb-apache would depend upon wordpress, mariadb, and apache.

optional¶

A comma-separated list of packages which are related to this package, but are neither required nor necessarily recommended. This list is displayed in an informational message when the package is installed to SPM.

recommended¶

A comma-separated list of optional packages that are recommended to be installed with the package. This list is displayed in an informational message when the package is installed to SPM.

Building a Package¶

Once a FORMULA file has been created, it is placed into the root of the formula that is to be turned into a package. The spm build command is used to turn that formula into a package:
The resulting file will be placed in the build directory. By default this directory is located at /srv/spm/.

Loader Modules¶

When an execution module is placed in <file_roots>/_modules/ on the master, it will automatically be synced to minions, the next time a sync operation takes place. Other modules are also propagated this way: state modules can be placed in _states/, and so on. When SPM detects a file in a package which resides in one of these directories, that directory will be placed in <file_roots> instead of in the formula directory with the rest of the files.

Removing Packages¶

Packages may be removed once they are installed using the spm remove command.
If files have been modified, they will not be removed. Empty directories will also be removed.

Technical Information¶

Packages are built using BZ2-compressed tarballs. By default, the package database is stored using the sqlite3 driver (see Loader Modules below). Support for these are built into Python, and so no external dependencies are needed. All other files belonging to SPM use YAML, for portability and ease of use and maintainability.

SPM-Specific Loader Modules¶

SPM was designed to behave like traditional package managers, which apply files to the filesystem and store package metadata in a local database. However, because modern infrastructures often extend beyond those use cases, certain parts of SPM have been broken out into their own set of modules.

Package Database¶

By default, the package database is stored using the sqlite3 module. This module was chosen because support for SQLite3 is built into Python itself. Please see the SPM Development Guide for information on creating new modules for package database management.

Package Files¶

By default, package files are installed using the local module. This module applies files to the local filesystem, on the machine that the package is installed on. Please see the SPM Development Guide for information on creating new modules for package file management.

Types of Packages¶

SPM supports different types of formula packages. The function of each package is denoted by its name. For instance, packages which end in -formula are considered to be Salt States (the most common type of formula). Packages which end in -conf contain configuration which is to be placed in the /etc/salt/ directory. Packages which do not contain one of these names are treated as if they have a -formula name.

formula¶

By default, most files from this type of package live in the /srv/spm/salt/ directory. The exception is the pillar.example file, which will be renamed to <package_name>.sls and placed in the pillar directory ( /srv/spm/pillar/ by default).

reactor¶

By default, files from this type of package live in the /srv/spm/reactor/ directory.

conf¶

The files in this type of package are configuration files for Salt, which normally live in the /etc/salt/ directory. Configuration files for packages other than Salt can and should be handled with a Salt State (using a formula type of package).

SPM Development Guide¶

This document discusses developing additional code for SPM.

SPM-Specific Loader Modules¶

SPM was designed to behave like traditional package managers, which apply files to the filesystem and store package metadata in a local database. However, because modern infrastructures often extend beyond those use cases, certain parts of SPM have been broken out into their own set of modules. Each function that accepts arguments has a set of required and optional arguments. Take note that SPM will pass all arguments in, and therefore each function must accept each of those arguments. However, arguments that are marked as required are crucial to SPM's core functionality, while arguments that are marked as optional are provided as a benefit to the module, if it needs to use them.

Package Database¶

By default, the package database is stored using the sqlite3 module. This module was chosen because support for SQLite3 is built into Python itself. Modules for managing the package database are stored in the salt/spm/pkgdb/ directory. A number of functions must exist to support database management.

init()¶

Get a database connection, and initialize the package database if necessary. This function accepts no arguments. If a database is used which supports a connection object, then that connection object is returned. For instance, the sqlite3 module returns a connect() object from the sqlite3 library:
SPM itself will not use this connection object; it will be passed in as-is to the other functions in the module. Therefore, when you set up this object, make sure to do so in a way that is easily usable throughout the module.

info()¶

Return information for a package. This generally consists of the information that is stored in the FORMULA file in the package. The arguments that are passed in, in order, are package (required) and conn (optional). package is the name of the package, as specified in the FORMULA. conn is the connection object returned from init().

list_files()¶

Return a list of files for an installed package. Only the filename should be returned, and no other information. The arguments that are passed in, in order, are package (required) and conn (optional). package is the name of the package, as specified in the FORMULA. conn is the connection object returned from init().

register_pkg()¶

Register a package in the package database. Nothing is expected to be returned from this function. The arguments that are passed in, in order, are name (required), formula_def (required), and conn (optional). name is the name of the package, as specified in the FORMULA. formula_def is the contents of the FORMULA file, as a dict. conn is the connection object returned from init().

register_file()¶

Register a file in the package database. Nothing is expected to be returned from this function. The arguments that are passed in are name (required), member (required), path (required), digest (optional), and conn (optional). name is the name of the package. member is a tarfile object for the package file. It is included, because it contains most of the information for the file. path is the location of the file on the local filesystem. digest is the SHA1 checksum of the file. conn is the connection object returned from init().

unregister_pkg()¶

Unregister a package from the package database. This usually only involves removing the package's record from the database. Nothing is expected to be returned from this function. The arguments that are passed in, in order, are name (required) and conn (optional). name is the name of the package, as specified in the FORMULA. conn is the connection object returned from init().

unregister_file()¶

Unregister a package from the package database. This usually only involves removing the package's record from the database. Nothing is expected to be returned from this function. The arguments that are passed in, in order, are name (required), pkg (optional) and conn (optional). name is the path of the file, as it was installed on the filesystem. pkg is the name of the package that the file belongs to. conn is the connection object returned from init().

db_exists()¶

Check to see whether the package database already exists. This is the path to the package database file. This function will return True or False. The only argument that is expected is db_, which is the package database file.

Package Files¶

By default, package files are installed using the local module. This module applies files to the local filesystem, on the machine that the package is installed on. Modules for managing the package database are stored in the salt/spm/pkgfiles/ directory. A number of functions must exist to support file management.

init()¶

Initialize the installation location for the package files. Normally these will be directory paths, but other external destinations such as databases can be used. For this reason, this function will return a connection object, which can be a database object. However, in the default local module, this object is a dict containing the paths. This object will be passed into all other functions. Three directories are used for the destinations: formula_path, pillar_path, and reactor_path. formula_path is the location of most of the files that will be installed. The default is specific to the operating system, but is normally /srv/salt/. pillar_path is the location that the pillar.example file will be installed to. The default is specific to the operating system, but is normally /srv/pillar/. reactor_path is the location that reactor files will be installed to. The default is specific to the operating system, but is normally /srv/reactor/.

check_existing()¶

Check the filesystem for existing files. All files for the package will be checked, and if any are existing, then this function will normally state that SPM will refuse to install the package. This function returns a list of the files that exist on the system. The arguments that are passed into this function are, in order: package (required), pkg_files (required), formula_def (formula_def), and conn (optional). package is the name of the package that is to be installed. pkg_files is a list of the files to be checked. formula_def is a copy of the information that is stored in the FORMULA file. conn is the file connection object.

install_file()¶

Install a single file to the destination (normally on the filesystem). Nothing is expected to be returned from this function. This function returns the final location that the file was installed to. The arguments that are passed into this function are, in order, package (required), formula_tar (required), member (required), formula_def (required), and conn (optional). package is the name of the package that is to be installed. formula_tar is the tarfile object for the package. This is passed in so that the function can call formula_tar.extract() for the file. member is the tarfile object which represents the individual file. This may be modified as necessary, before being passed into formula_tar.extract(). formula_def is a copy of the information from the FORMULA file. conn is the file connection object.

remove_file()¶

Remove a single file from file system. Normally this will be little more than an os.remove(). Nothing is expected to be returned from this function. The arguments that are passed into this function are, in order, path (required) and conn (optional). path is the absolute path to the file to be removed. conn is the file connection object.

hash_file()¶

Returns the hexdigest hash value of a file. The arguments that are passed into this function are, in order, path (required), hashobj (required), and conn (optional). path is the absolute path to the file. hashobj is a reference to hashlib.sha1(), which is used to pull the hexdigest() for the file. conn is the file connection object. This function will not generally be more complex than:

path_exists()¶

Check to see whether the file already exists on the filesystem. Returns True or False. This function expects a path argument, which is the absolute path to the file to be checked.

path_isdir()¶

Check to see whether the path specified is a directory. Returns True or False. This function expects a path argument, which is the absolute path to be checked.

Storing Data in Other Databases¶

The SDB interface is designed to store and retrieve data that, unlike pillars and grains, is not necessarily minion-specific. The initial design goal was to allow passwords to be stored in a secure database, such as one managed by the keyring package, rather than as plain-text files. However, as a generic database interface, it could conceptually be used for a number of other purposes. SDB was added to Salt in version 2014.7.0.

SDB Configuration¶

In order to use the SDB interface, a configuration profile must be set up in either the master or minion configuration file. The configuration stanza includes the name/ID that the profile will be referred to as, a driver setting, and any other arguments that are necessary for the SDB module that will be used. For instance, a profile called mykeyring, which uses the system service in the keyring module would look like:
It is recommended to keep the name of the profile simple, as it is used in the SDB URI as well.

SDB URIs¶

SDB is designed to make small database queries (hence the name, SDB) using a compact URL. This allows users to reference a database value quickly inside a number of Salt configuration areas, without a lot of overhead. The basic format of an SDB URI is:
The profile refers to the configuration profile defined in either the master or the minion configuration file. The args are specific to the module referred to in the profile, but will typically only need to refer to the key of a key/value pair inside the database. This is because the profile itself should define as many other parameters as possible. For example, a profile might be set up to reference credentials for a specific OpenStack account. The profile might look like:
And the URI used to reference the password might look like:

Getting, Setting and Deleting SDB Values¶

Once an SDB driver is configured, you can use the sdb execution module to get, set and delete values from it. There are two functions that may appear in most SDB modules: get, set and delete. Getting a value requires only the SDB URI to be specified. To retrieve a value from the kevinopenstack profile above, you would use:
Some drivers use slightly more complex URIs. For instance, the vault driver requires the full path to where the key is stored, followed by a question mark, followed by the key to be retrieved. If you were using a profile called myvault, you would use a URI that looks like:
Setting a value uses the same URI as would be used to retrieve it, followed by the value as another argument. For the above myvault URI, you would set a new value using a command like:
Deleting values (if supported by the driver) is done pretty much the same way as getting them. Provided that you have a profile called mykvstore that uses a driver allowing to delete values you would delete a value as shown bellow:
The sdb.get, sdb.set and sdb.delete functions are also available in the runner system:

Using SDB URIs in Files¶

SDB URIs can be used in both configuration files, and files that are processed by the renderer system (jinja, mako, etc.). In a configuration file (such as /etc/salt/master, /etc/salt/minion, /etc/salt/cloud, etc.), make an entry as usual, and set the value to the SDB URI. For instance:
To retrieve this value using a module, the module in question must use the config.get function to retrieve configuration values. This would look something like:
Templating renderers use a similar construct. To get the mykey value from above in Jinja, you would use:
When retrieving data from configuration files using config.get, the SDB URI need only appear in the configuration file itself. If you would like to retrieve a key directly from SDB, you would call the sdb.get function directly, using the SDB URI. For instance, in Jinja:
When writing Salt modules, it is not recommended to call sdb.get directly, as it requires the user to provide values in SDB, using a specific URI. Use config.get instead.

Writing SDB Modules¶

There is currently one function that MUST exist in any SDB module ( get()), one that SHOULD exist ( set_()) and one that MAY exist (delete()). If using a ( set_()) function, a __func_alias__ dictionary MUST be declared in the module as well:
This is because set is a Python built-in, and therefore functions should not be created which are called set(). The __func_alias__ functionality is provided via Salt's loader interfaces, and allows legally-named functions to be referred to using names that would otherwise be unwise to use. The get() function is required, as it will be called via functions in other areas of the code which make use of the sdb:// URI. For example, the config.get function in the config execution module uses this function. The set_() function may be provided, but is not required, as some sources may be read-only, or may be otherwise unwise to access via a URI (for instance, because of SQL injection attacks). The delete() function may be provided as well, but is not required, as many sources may be read-only or restrict such operations. A simple example of an SDB module is salt/sdb/keyring_db.py, as it provides basic examples of most, if not all, of the types of functionality that are available not only for SDB modules, but for Salt modules in general.

Running the Salt Master/Minion as an Unprivileged User¶

While the default setup runs the master and minion as the root user, some may consider it an extra measure of security to run the master as a non-root user. Keep in mind that doing so does not change the master's capability to access minions as the user they are running as. Due to this many feel that running the master as a non-root user does not grant any real security advantage which is why the master has remained as root by default. NOTE:
As of Salt 0.9.10 it is possible to run Salt as a non-root user. This can be done by setting the user parameter in the master configuration file. and restarting the salt-master service. The minion has it's own user parameter as well, but running the minion as an unprivileged user will keep it from making changes to things like users, installed packages, etc. unless access controls (sudo, etc.) are setup on the minion to permit the non-root user to make the needed changes. In order to allow Salt to successfully run as a non-root user, ownership, and permissions need to be set such that the desired user can read from and write to the following directories (and their subdirectories, where applicable):
Ownership can be easily changed with chown, like so:
WARNING:

Using cron with Salt¶

The Salt Minion can initiate its own highstate using the salt-call command.
This will cause the minion to check in with the master and ensure it is in the correct "state".

Use cron to initiate a highstate¶

If you would like the Salt Minion to regularly check in with the master you can use cron to run the salt-call command:
The above cron entry will run a highstate every day at midnight. NOTE:

Hardening Salt¶

This topic contains tips you can use to secure and harden your Salt environment. How you best secure and harden your Salt environment depends heavily on how you use Salt, where you use Salt, how your team is structured, where you get data from, and what kinds of access (internal and external) you require.

General hardening tips¶

Salt hardening tips¶

Security disclosure policy¶

gpg public key:
The SaltStack Security Team is available at security@saltstack.com for security-related bug reports or questions. We request the disclosure of any security-related bugs or issues be reported non-publicly until such time as the issue can be resolved and a security-fix release can be prepared. At that time we will release the fix and make a public announcement with upgrade instructions and download locations.

Security response procedure¶

SaltStack takes security and the trust of our customers and users very seriously. Our disclosure policy is intended to resolve security issues as quickly and safely as is possible.

Receiving security announcements¶

The fastest place to receive security announcements is via the salt-announce mailing list. This list is low-traffic.

Salt Transport¶

One of fundamental features of Salt is remote execution. Salt has two basic "channels" for communicating with minions. Each channel requires a client (minion) and a server (master) implementation to work within Salt. These pairs of channels will work together to implement the specific message passing required by the channel interface.

Pub Channel¶

The pub channel, or publish channel, is how a master sends a job (payload) to a minion. This is a basic pub/sub paradigm, which has specific targeting semantics. All data which goes across the publish system should be encrypted such that only members of the Salt cluster can decrypt the publishes.

Req Channel¶

The req channel is how the minions send data to the master. This interface is primarily used for fetching files and returning job returns. The req channels have two basic interfaces when talking to the master. send is the basic method that guarantees the message is encrypted at least so that only minions attached to the same master can read it-- but no guarantee of minion-master confidentiality, whereas the crypted_transfer_decode_dictentry method does guarantee minion-master confidentiality.

Zeromq Transport¶

NOTE:
Zeromq is a messaging library with bindings into many languages. Zeromq implements a socket interface for message passing, with specific semantics for the socket type.

Pub Channel¶

The pub channel is implemented using zeromq's pub/sub sockets. By default we don't use zeromq's filtering, which means that all publish jobs are sent to all minions and filtered minion side. Zeromq does have publisher side filtering which can be enabled in salt using zmq_filtering.

Req Channel¶

The req channel is implemented using zeromq's req/rep sockets. These sockets enforce a send/recv pattern, which forces salt to serialize messages through these socket pairs. This means that although the interface is asynchronous on the minion we cannot send a second message until we have received the reply of the first message.

TCP Transport¶

The tcp transport is an implementation of Salt's channels using raw tcp sockets. Since this isn't using a pre-defined messaging library we will describe the wire protocol, message semantics, etc. in this document. The tcp transport is enabled by changing the transport setting to tcp on each Salt minion and Salt master.

Wire Protocol¶

This implementation over TCP focuses on flexibility over absolute efficiency. This means we are okay to spend a couple of bytes of wire space for flexibility in the future. That being said, the wire framing is quite efficient and looks like:
Since msgpack is an iterably parsed serialization, we can simply write the serialized payload to the wire. Within that payload we have two items "head" and "body". Head contains header information (such as "message id"). The Body contains the actual message that we are sending. With this flexible wire protocol we can implement any message semantics that we'd like-- including multiplexed message passing on a single socket.

Crypto¶

The current implementation uses the same crypto as the zeromq transport.

Pub Channel¶

For the pub channel we send messages without "message ids" which the remote end interprets as a one-way send. NOTE:

Req Channel¶

For the req channel we send messages with a "message id". This "message id" allows us to multiplex messages across the socket.

The RAET Transport¶

NOTE:
New in version 2014.7.0. The Reliable Asynchronous Event Transport, or RAET, is an alternative transport medium developed specifically with Salt in mind. It has been developed to allow queuing to happen up on the application layer and comes with socket layer encryption. It also abstracts a great deal of control over the socket layer and makes it easy to bubble up errors and exceptions. RAET also offers very powerful message routing capabilities, allowing for messages to be routed between processes on a single machine all the way up to processes on multiple machines. Messages can also be restricted, allowing processes to be sent messages of specific types from specific sources allowing for trust to be established.

Using RAET in Salt¶

Using RAET in Salt is easy, the main difference is that the core dependencies change, instead of needing pycrypto, M2Crypto, ZeroMQ, and PYZMQ, the packages libsodium, libnacl, ioflo, and raet are required. Encryption is handled very cleanly by libnacl, while the queueing and flow control is handled by ioflo. Distribution packages are forthcoming, but libsodium can be easily installed from source, or many distributions do ship packages for it. The libnacl and ioflo packages can be easily installed from pypi, distribution packages are in the works. Once the new deps are installed the 2014.7 release or higher of Salt needs to be installed. Once installed, modify the configuration files for the minion and master to set the transport to raet: /etc/salt/master:
/etc/salt/minion:
Now start salt as it would normally be started, the minion will connect to the master and share long term keys, which can then in turn be managed via salt-key. Remote execution and salt states will function in the same way as with Salt over ZeroMQ.

Limitations¶

The 2014.7 release of RAET is not complete! The Syndic and Multi Master have not been completed yet and these are slated for completion in the 2015.5.0 release. Also, Salt-Raet allows for more control over the client but these hooks have not been implemented yet, thereforre the client still uses the same system as the ZeroMQ client. This means that the extra reliability that RAET exposes has not yet been implemented in the CLI client.

Why?¶

Customer and User Request¶

Why make an alternative transport for Salt? There are many reasons, but the primary motivation came from customer requests, many large companies came with requests to run Salt over an alternative transport, the reasoning was varied, from performance and scaling improvements to licensing concerns. These customers have partnered with SaltStack to make RAET a reality.

More Capabilities¶

RAET has been designed to allow salt to have greater communication capabilities. It has been designed to allow for development into features which out ZeroMQ topologies can't match. Many of the proposed features are still under development and will be announced as they enter proof of concept phases, but these features include salt-fuse - a filesystem over salt, salt-vt - a parallel api driven shell over the salt transport and many others.

RAET Reliability¶

RAET is reliable, hence the name (Reliable Asynchronous Event Transport). The concern posed by some over RAET reliability is based on the fact that RAET uses UDP instead of TCP and UDP does not have built in reliability. RAET itself implements the needed reliability layers that are not natively present in UDP, this allows RAET to dynamically optimize packet delivery in a way that keeps it both reliable and asynchronous.

RAET and ZeroMQ¶

When using RAET, ZeroMQ is not required. RAET is a complete networking replacement. It is noteworthy that RAET is not a ZeroMQ replacement in a general sense, the ZeroMQ constructs are not reproduced in RAET, but they are instead implemented in such a way that is specific to Salt's needs. RAET is primarily an async communication layer over truly async connections, defaulting to UDP. ZeroMQ is over TCP and abstracts async constructs within the socket layer. Salt is not dropping ZeroMQ support and has no immediate plans to do so.

Encryption¶

RAET uses Dan Bernstein's NACL encryption libraries and CurveCP handshake. The libnacl python binding binds to both libsodium and tweetnacl to execute the underlying cryptography. This allows us to completely rely on an externally developed cryptography system.

Programming Intro¶

Intro to RAET Programming¶

NOTE:
The first thing to cover is that RAET does not present a socket api, it presents, and queueing api, all messages in RAET are made available to via queues. This is the single most differentiating factor with RAET vs other networking libraries, instead of making a socket, a stack is created. Instead of calling send() or recv(), messages are placed on the stack to be sent and messages that are received appear on the stack. Different kinds of stacks are also available, currently two stacks exist, the UDP stack, and the UXD stack. The UDP stack is used to communicate over udp sockets, and the UXD stack is used to communicate over Unix Domain Sockets. The UDP stack runs a context for communicating over networks, while the UXD stack has contexts for communicating between processes.

UDP Stack Messages¶

To create a UDP stack in RAET, simply create the stack, manage the queues, and process messages:

Master Tops System¶

In 0.10.4 the external_nodes system was upgraded to allow for modular subsystems to be used to generate the top file data for a highstate run on the master. The old external_nodes option has been removed. The master tops system contains a number of subsystems that are loaded via the Salt loader interfaces like modules, states, returners, runners, etc. Using the new master_tops option is simple:
for Cobbler or:
for Reclass.
for Varstack. It's also possible to create custom master_tops modules. These modules must go in a subdirectory called tops in the extension_modules directory. The extension_modules directory is not defined by default (the default /srv/salt/_modules will NOT work as of this release) Custom tops modules are written like any other execution module, see the source for the two modules above for examples of fully functional ones. Below is a degenerate example: /etc/salt/master:
/srv/salt/modules/tops/customtop.py:
salt minion state.show_top should then display something like:

Returners¶

By default the return values of the commands sent to the Salt minions are returned to the Salt master, however anything at all can be done with the results data. By using a Salt returner, results data can be redirected to external data-stores for analysis and archival. Returners pull their configuration values from the Salt minions. Returners are only configured once, which is generally at load time. The returner interface allows the return data to be sent to any system that can receive data. This means that return data can be sent to a Redis server, a MongoDB server, a MySQL server, or any system. SEE ALSO:

Using Returners¶

All Salt commands will return the command data back to the master. Specifying returners will ensure that the data is _also_ sent to the specified returner interfaces. Specifying what returners to use is done when the command is invoked:
This command will ensure that the redis_return returner is used. It is also possible to specify multiple returners:
In this scenario all three returners will be called and the data from the test.ping command will be sent out to the three named returners.

Writing a Returner¶

A returner is a Python module containing at minimum a returner function. Other optional functions can be included to add support for master_job_cache, external_job_cache, and Event Returners.


The above example of a returner set to send the data to a Redis server serializes the data as JSON and sets it in redis.

Master Job Cache Support¶

master_job_cache, external_job_cache, and Event Returners. Salt's master_job_cache allows returners to be used as a pluggable replacement for the default_job_cache. In order to do so, a returner must implement the following functions: NOTE:

External Job Cache Support¶

Salt's external_job_cache extends the master_job_cache. External Job Cache support requires the following functions in addition to what is required for Master Job Cache support:
Sample:

Sample:

Sample:

Sample:
Please refer to one or more of the existing returners (i.e. mysql, cassandra_cql) if you need further clarification.

Event Support¶

An event_return function must be added to the returner module to allow events to be logged from a master via the returner. A list of events are passed to the function by the master. The following example was taken from the MySQL returner. In this example, each event is inserted into the salt_events table keyed on the event tag. The tag contains the jid and therefore is guaranteed to be unique.

Custom Returners¶

Place custom returners in a _returners directory within the file_roots specified by the master config file. Custom returners are distributed when any of the following are called:
Any custom returners which have been synced to a minion that are named the same as one of Salt's default set of returners will take the place of the default returner with the same name.

Naming the Returner¶

Note that a returner's default name is its filename (i.e. foo.py becomes returner foo), but that its name can be overridden by using a __virtual__ function. A good example of this can be found in the redis returner, which is named redis_return.py but is loaded as simply redis:

Testing the Returner¶

The returner, prep_jid, save_load, get_load, and event_return functions can be tested by configuring the master_job_cache and Event Returners in the master config file and submitting a job to test.ping each minion from the master. Once you have successfully exercised the Master Job Cache functions, test the External Job Cache functions using the ret execution module.

Event Returners¶

For maximum visibility into the history of events across a Salt infrastructure, all events seen by a salt master may be logged to one or more returners. To enable event logging, set the event_return configuration option in the master config to the returner(s) which should be designated as the handler for event returns. NOTE:
NOTE:

Full List of Returners¶

returner modules¶

carbon_return	Take data from salt and "return" it into a carbon receiver
cassandra_cql_return	Return data to a cassandra server
cassandra_return	Return data to a Cassandra ColumnFamily
couchbase_return	Simple returner for Couchbase.
couchdb_return	Simple returner for CouchDB.
django_return	A returner that will infor a Django system that returns are available using Django's signal system.
elasticsearch_return	Return data to an elasticsearch server for indexing.
etcd_return	Return data to an etcd server or cluster
hipchat_return	Return salt data via hipchat.
influxdb_return	Return data to an influxdb server.
kafka_return	Return data to a Kafka topic
local	The local returner is used to test the returner interface, it just prints the
local_cache	Return data to local job cache
memcache_return	Return data to a memcache server
mongo_future_return	Return data to a mongodb server
mongo_return	Return data to a mongodb server
multi_returner	Read/Write multiple returners
mysql	Return data to a mysql server
nagios_return	Return salt data to Nagios
odbc	Return data to an ODBC compliant server.
pgjsonb	Return data to a PostgreSQL server with json data stored in Pg's jsonb data type
postgres	Return data to a postgresql server
postgres_local_cache	Use a postgresql server for the master job cache.
pushover_returner	Return salt data via pushover (http://www.pushover.net)
rawfile_json	Take data from salt and "return" it into a raw file containing the json, with one line per event.
redis_return	Return data to a redis server
sentry_return	Salt returner that reports execution results back to sentry.
slack_returner	Return salt data via slack
sms_return	Return data by SMS.
smtp_return	Return salt data via email
splunk	Send json response data to Splunk via the HTTP Event Collector
sqlite3_return	Insert minion return data into a sqlite3 database
syslog_return	Return data to the host operating system's syslog facility
xmpp_return	Return salt data via xmpp

salt.returners.carbon_return¶

Take data from salt and "return" it into a carbon receiver Add the following configuration to the minion configuration file:
Errors when trying to convert data to numbers may be ignored by setting carbon.skip_on_error to True:
By default, data will be sent to carbon using the plaintext protocol. To use the pickle protocol, set carbon.mode to pickle:

Carbon settings may also be configured as:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
To use the carbon returner, append '--return carbon' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.cassandra_cql_return¶

Return data to a cassandra server New in version 2015.5.0.
Required python modules: cassandra-driver To use the cassandra returner, append '--return cassandra_cql' to the salt command. ex:
Note: if your Cassandra instance has not been tuned much you may benefit from altering some timeouts in cassandra.yaml like so:
As always, your mileage may vary and your Cassandra cluster may have different needs. SaltStack has seen situations where these timeouts can resolve some stacktraces that appear to come from the Datastax Python driver.

salt.returners.cassandra_return¶

Return data to a Cassandra ColumnFamily Here's an example Keyspace / ColumnFamily setup that works with this returner:
Required python modules: pycassa

salt.returners.couchbase_return¶

Simple returner for Couchbase. Optional configuration settings are listed below, along with sane defaults.
To use the couchbase returner, append '--return couchbase' to the salt command. ex:
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.
All of the return data will be stored in documents as follows:

JID¶

load: load obj tgt_minions: list of minions targeted nocache: should we not cache the return data

JID/MINION_ID¶

return: return_data full_ret: full load of job return

salt.returners.couchdb_return¶

Simple returner for CouchDB. Optional configuration settings are listed below, along with sane defaults:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
To use the couchdb returner, append --return couchdb to the salt command. Example:
To use the alternative configuration, append --return_config alternative to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

On concurrent database access¶

As this returner creates a couchdb document with the salt job id as document id and as only one document with a given id can exist in a given couchdb database, it is advised for most setups that every minion be configured to write to it own database (the value of couchdb.db may be suffixed with the minion id), otherwise multi-minion targeting can lead to losing output:

salt.returners.django_return¶

A returner that will infor a Django system that returns are available using Django's signal system. https://docs.djangoproject.com/en/dev/topics/signals/ It is up to the Django developer to register necessary handlers with the signals provided by this returner and process returns as necessary. The easiest way to use signals is to import them from this returner directly and then use a decorator to register them. An example Django module that registers a function called 'returner_callback' with this module's 'returner' function:

salt.returners.elasticsearch_return¶

Return data to an elasticsearch server for indexing.
To enable this returner the elasticsearch python client must be installed on the desired minions (all or some subset). Please see documentation of elasticsearch execution module for a valid connection configuration. WARNING:
To use the returner per salt call:
In order to have the returner apply to all minions:
Minion configuration example:

salt.returners.etcd_return¶

Return data to an etcd server or cluster
In order to return to an etcd server, a profile should be created in the master configuration file:
It is technically possible to configure etcd without using a profile, but this is not considered to be a best practice, especially when multiple etcd servers or clusters are available.
Additionally, two more options must be specified in the top-level configuration in order to use the etcd returner:
The etcd.returner option specifies which configuration profile to use. The etcd.returner_root option specifies the path inside etcd to use as the root of the returner system. Once the etcd options are configured, the returner may be used: CLI Example:
A username and password can be set:
You can also set a TTL (time to live) value for the returner:
Authentication with username and password, and ttl, currently requires the master branch of python-etcd. You may also specify different roles for read and write operations. First, create the profiles as specified above. Then add:

salt.returners.hipchat_return¶

Return salt data via hipchat. New in version 2015.5.0. The following fields can be set in the minion conf file:
NOTE:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
Hipchat settings may also be configured as:
To use the HipChat returner, append '--return hipchat' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.influxdb_return¶

Return data to an influxdb server. New in version 2015.8.0. To enable this returner the minion will need the python client for influxdb installed and the following values configured in the minion or master config, these are the defaults:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
To use the influxdb returner, append '--return influxdb' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.kafka_return¶

Return data to a Kafka topic
To enable this returner install kafka-python and enable the following settings in the minion config:
To use the kafka returner, append '--return kafka' to the Salt command, eg;

salt.returners.local¶

The local returner is used to test the returner interface, it just prints the return data to the console to verify that it is being passed properly

salt.returners.local_cache¶

Return data to local job cache

salt.returners.memcache_return¶

Return data to a memcache server To enable this returner the minion will need the python client for memcache installed and the following values configured in the minion or master config, these are the defaults.
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location.
python2-memcache uses 'localhost' and '11211' as syntax on connection. To use the memcache returner, append '--return memcache' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.mongo_future_return¶

Return data to a mongodb server Required python modules: pymongo This returner will send data from the minions to a MongoDB server. To configure the settings for your MongoDB server, add the following lines to the minion config files:
You can also ask for indexes creation on the most common used fields, which should greatly improve performance. Indexes are not created by default.
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
This mongo returner is being developed to replace the default mongodb returner in the future and should not be considered API stable yet. To use the mongo returner, append '--return mongo' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.mongo_return¶

Return data to a mongodb server Required python modules: pymongo This returner will send data from the minions to a MongoDB server. To configure the settings for your MongoDB server, add the following lines to the minion config files.
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location.
To use the mongo returner, append '--return mongo' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.multi_returner¶

Read/Write multiple returners

salt.returners.mysql¶

Return data to a mysql server
To enable this returner, the minion will need the python client for mysql installed and the following values configured in the minion or master config. These are the defaults:
SSL is optional. The defaults are set to None. If you do not want to use SSL, either exclude these options or set them to None.
Alternative configuration values can be used by prefacing the configuration with alternative.. Any values not found in the alternative configuration will be pulled from the default location. As stated above, SSL configuration is optional. The following ssl options are simply for illustration purposes:
Should you wish the returner data to be cleaned out every so often, set keep_jobs to the number of hours for the jobs to live in the tables. Setting it to 0 or leaving it unset will cause the data to stay in the tables. Should you wish to archive jobs in a different table for later processing, set archive_jobs to True. Salt will create 3 archive tables
and move the contents of jids, salt_returns, and salt_events that are more than keep_jobs hours old to these tables. Use the following mysql database schema:
Required python modules: MySQLdb To use the mysql returner, append '--return mysql' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.nagios_return¶

Return salt data to Nagios The following fields can be set in the minion conf file:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
Nagios settings may also be configured as:
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.odbc¶

Return data to an ODBC compliant server. This driver was developed with Microsoft SQL Server in mind, but theoretically could be used to return data to any compliant ODBC database as long as there is a working ODBC driver for it on your minion platform.
To enable this returner the minion will need On Linux:
On Windows:
unixODBC and FreeTDS need to be configured via /etc/odbcinst.ini and /etc/odbc.ini. /etc/odbcinst.ini:
(Note the above Driver line needs to point to the location of the FreeTDS shared library. This example is for Ubuntu 14.04.) /etc/odbc.ini:
Also you need the following values configured in the minion or master config. Configure as you see fit:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
Running the following commands against Microsoft SQL Server in the desired database as the appropriate user should create the database tables correctly. Replace with equivalent SQL for other ODBC-compliant servers
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.pgjsonb¶

Return data to a PostgreSQL server with json data stored in Pg's jsonb data type
To enable this returner, the minion will need the python client for PostgreSQL installed and the following values configured in the minion or master config. These are the defaults:
SSL is optional. The defaults are set to None. If you do not want to use SSL, either exclude these options or set them to None.
Alternative configuration values can be used by prefacing the configuration with alternative.. Any values not found in the alternative configuration will be pulled from the default location. As stated above, SSL configuration is optional. The following ssl options are simply for illustration purposes:
Use the following Pg database schema:
Required python modules: Psycopg2 To use this returner, append '--return pgjsonb' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.postgres¶

Return data to a postgresql server NOTE:

To enable this returner the minion will need the psycopg2 installed and the following values configured in the minion or master config:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
Running the following commands as the postgres user should create the database correctly:
Required python modules: psycopg2 To use the postgres returner, append '--return postgres' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.postgres_local_cache¶

Use a postgresql server for the master job cache. This helps the job cache to cope with scale. NOTE:

To enable this returner the minion will need the psycopg2 installed and the following values configured in the master config:
Running the following command as the postgres user should create the database correctly:
In case the postgres database is a remote host, you'll need this command also:
and then:
Required python modules: psycopg2

salt.returners.pushover_returner¶

Return salt data via pushover ( http://www.pushover.net) New in version 2016.3.0. The following fields can be set in the minion conf file:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
PushOver settings may also be configured as:
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command.

salt.returners.rawfile_json¶

Take data from salt and "return" it into a raw file containing the json, with one line per event. Add the following to the minion or master configuration file.
Default is /var/log/salt/events. Common use is to log all events on the master. This can generate a lot of noise, so you may wish to configure batch processing and/or configure the event_return_whitelist or event_return_blacklist to restrict the events that are written.

salt.returners.redis_return¶

Return data to a redis server To enable this returner the minion will need the python client for redis installed and the following values configured in the minion or master config, these are the defaults:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
To use the redis returner, append '--return redis' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.sentry_return¶

Salt returner that reports execution results back to sentry. The returner will inspect the payload to identify errors and flag them as such. Pillar needs something like:
or using a dsn:
https://pypi.python.org/pypi/raven must be installed. The pillar can be hidden on sentry return by setting hide_pillar: true. The tags list (optional) specifies grains items that will be used as sentry tags, allowing tagging of events in the sentry ui. To report only errors to sentry, set report_errors_only: true.

salt.returners.slack_returner¶

Return salt data via slack New in version 2015.5.0. The following fields can be set in the minion conf file:

Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
Slack settings may also be configured as:
To use the Slack returner, append '--return slack' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.sms_return¶

Return data by SMS. New in version 2015.5.0.
To enable this returner the minion will need the python twilio library installed and the following values configured in the minion or master config:
To use the sms returner, append '--return sms' to the salt command.

salt.returners.smtp_return¶

Return salt data via email The following fields can be set in the minion conf file. Fields are optional unless noted otherwise.
Below is an example of the above settings in a Salt Minion configuration file:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location. For example:
To use the SMTP returner, append '--return smtp' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.
An easy way to test the SMTP returner is to use the development SMTP server built into Python. The command below will start a single-threaded SMTP server that prints any email it receives to the console.
New in version 2016.11.0. It is possible to send emails with selected Salt events by configuring event_return option for Salt Master. For example:
Also you need to create additional file /srv/salt/templates/email.j2 with email body template:
This configuration enables Salt Master to send an email when accepting or rejecting minions keys.

salt.returners.splunk module¶

Send json response data to Splunk via the HTTP Event Collector Requires the following config values to be specified in config or pillar:
Run a test by using salt-call test.ping --return splunk Written by Scott Pack (github.com/scottjpack)

salt.returners.sqlite3¶

Insert minion return data into a sqlite3 database
Sqlite3 is a serverless database that lives in a single file. In order to use this returner the database file must exist, have the appropriate schema defined, and be accessible to the user whom the minion process is running as. This returner requires the following values configured in the master or minion config:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
Use the commands to create the sqlite3 database and tables:
To use the sqlite returner, append '--return sqlite3' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

salt.returners.syslog_return¶

Return data to the host operating system's syslog facility To use the syslog returner, append '--return syslog' to the salt command.
The following fields can be set in the minion conf file:
Available levels, facilities, and options can be found in the syslog docs for your python version. NOTE:
Configuration example:
Of course you can also nest the options:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
To use the alternative configuration, append --return_config alternative to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.
NOTE:

salt.returners.xmpp_return¶

Return salt data via xmpp
The following fields can be set in the minion conf file:
Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:
XMPP settings may also be configured as:
To use the XMPP returner, append '--return xmpp' to the salt command.
To use the alternative configuration, append '--return_config alternative' to the salt command. New in version 2015.5.0.
To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command. New in version 2016.3.0.

Renderers¶

The Salt state system operates by gathering information from common data types such as lists, dictionaries, and strings that would be familiar to any developer. SLS files are translated from whatever data templating format they are written in back into Python data types to be consumed by Salt. By default SLS files are rendered as Jinja templates and then parsed as YAML documents. But since the only thing the state system cares about is raw data, the SLS files can be any structured format that can be dreamed up. Currently there is support for Jinja + YAML, Mako + YAML, Wempy + YAML, Jinja + json, Mako + json and Wempy + json. Renderers can be written to support any template type. This means that the Salt states could be managed by XML files, HTML files, Puppet files, or any format that can be translated into the Pythonic data structure used by the state system.

Multiple Renderers¶

A default renderer is selected in the master configuration file by providing a value to the renderer key. When evaluating an SLS, more than one renderer can be used. When rendering SLS files, Salt checks for the presence of a Salt-specific shebang line. The shebang line directly calls the name of the renderer as it is specified within Salt. One of the most common reasons to use multiple renderers is to use the Python or py renderer. Below, the first line is a shebang that references the py renderer.

Composing Renderers¶

A renderer can be composed from other renderers by connecting them in a series of pipes( |). In fact, the default Jinja + YAML renderer is implemented by connecting a YAML renderer to a Jinja renderer. Such renderer configuration is specified as: jinja | yaml. Other renderer combinations are possible:
The following is a contrived example SLS file using the jinja | mako | yaml renderer:
For backward compatibility, jinja | yaml can also be written as yaml_jinja, and similarly, the yaml_mako, yaml_wempy, json_jinja, json_mako, and json_wempy renderers are all supported. Keep in mind that not all renderers can be used alone or with any other renderers. For example, the template renderers shouldn't be used alone as their outputs are just strings, which still need to be parsed by another renderer to turn them into highstate data structures. For example, it doesn't make sense to specify yaml | jinja because the output of the YAML renderer is a highstate data structure (a dict in Python), which cannot be used as the input to a template renderer. Therefore, when combining renderers, you should know what each renderer accepts as input and what it returns as output.

Writing Renderers¶

A custom renderer must be a Python module placed in the renderers directory and the module implement the render function. The render function will be passed the path of the SLS file as an argument. The purpose of of render function is to parse the passed file and to return the Python data structure derived from the file. Custom renderers must be placed in a _renderers directory within the file_roots specified by the master config file. Custom renderers are distributed when any of the following are run:
Any custom renderers which have been synced to a minion, that are named the same as one of Salt's default set of renderers, will take the place of the default renderer with the same name.

Examples¶

The best place to find examples of renderers is in the Salt source code. Documentation for renderers included with Salt can be found here: https://github.com/saltstack/salt/blob/develop/salt/renderers Here is a simple YAML renderer example:

Full List of Renderers¶

renderer modules¶

cheetah	Cheetah Renderer for Salt
dson	DSON Renderer for Salt
genshi	Genshi Renderer for Salt
gpg	Renderer that will decrypt GPG ciphers
hjson	Hjson Renderer for Salt
jinja	Jinja loading utils to enable a more powerful backend for jinja templates
json	JSON Renderer for Salt
json5	JSON5 Renderer for Salt
mako	Mako Renderer for Salt
msgpack
py	Pure python state renderer
pydsl	A Python-based DSL
pyobjects	Python renderer that includes a Pythonic Object based interface
stateconf	A flexible renderer that takes a templating engine and a data format
wempy
yaml	YAML Renderer for Salt
yamlex

salt.renderers.cheetah¶

Cheetah Renderer for Salt

salt.renderers.dson¶

DSON Renderer for Salt This renderer is intended for demonstration purposes. Information on the DSON spec can be found here. This renderer requires Dogeon (installable via pip)

salt.renderers.genshi¶

Genshi Renderer for Salt

salt.renderers.gpg¶

Renderer that will decrypt GPG ciphers Any key in the SLS file can be a GPG cipher, and this renderer will decrypt it before passing it off to Salt. This allows you to safely store secrets in source control, in such a way that only your Salt master can decrypt them and distribute them only to the minions that need them. The typical use-case would be to use ciphers in your pillar data, and keep a secret key on your master. You can put the public key in source control so that developers can add new secrets quickly and easily. This renderer requires the gpg binary. No python libraries are required as of the 2015.8.0 release.

Setup¶

To set things up, first generate a keypair. On the master, run the following:
Do not supply a password for the keypair, and use a name that makes sense for your application. Be sure to back up the gpgkeys directory someplace safe! NOTE:

Export the Public Key¶

Import the Public Key¶

To encrypt secrets, copy the public key to your local machine and run:
To generate a cipher from a secret:
To apply the renderer on a file-by-file basis add the following line to the top of any pillar with gpg data in it:
Now with your renderer configured, you can include your ciphers in your pillar data like so:

Encrypted CLI Pillar Data¶

New in version 2016.3.0. Functions like state.highstate and state.sls allow for pillar data to be passed on the CLI.
Starting with the 2016.3.0 release of Salt, it is now possible for this pillar data to be GPG-encrypted, and to use the GPG renderer to decrypt it.

Replacing Newlines¶

To pass encrypted pillar data on the CLI, the ciphertext must have its newlines replaced with a literal backslash-n ( \n), as newlines are not supported within Salt CLI arguments. There are a number of ways to do this: With awk or Perl:
With Python:

The ciphertext can be included in the CLI pillar data like so:
The pillar_enc=gpg argument tells Salt that there is GPG-encrypted pillar data, so that the CLI pillar data is passed through the GPG renderer, which will iterate recursively though the CLI pillar dictionary to decrypt any encrypted values.

Encrypting the Entire CLI Pillar Dictionary¶

If several values need to be encrypted, it may be more convenient to encrypt the entire CLI pillar dictionary. Again, this can be done in several ways: With awk or Perl:
With Python:

With the entire pillar dictionary now encrypted, it can be included in the CLI pillar data like so:

salt.renderers.hjson¶

Hjson Renderer for Salt http://laktak.github.io/hjson/

salt.renderers.jinja¶

Jinja loading utils to enable a more powerful backend for jinja templates For Jinja usage information see Understanding Jinja.

salt.renderers.json¶

JSON Renderer for Salt

salt.renderers.json5¶

JSON5 Renderer for Salt New in version 2016.3.0. JSON5 is an unofficial extension to JSON. See http://json5.org/ for more information. This renderer requires the json5 python bindings, installable via pip.

salt.renderers.mako¶

Mako Renderer for Salt

salt.renderers.msgpack¶

salt.renderers.py¶

Pure python state renderer The SLS file should contain a function called run which returns high state data. In this module, a few objects are defined for you, giving access to Salt's execution functions, grains, pillar, etc. They are:

salt.renderers.pydsl¶

A Python-based DSL
The pydsl renderer allows one to author salt formulas (.sls files) in pure Python using a DSL that's easy to write and easy to read. Here's an example:
Notice that any Python code is allow in the file as it's really a Python module, so you have the full power of Python at your disposal. In this module, a few objects are defined for you, including the usual (with __ added) __salt__ dictionary, __grains__, __pillar__, __opts__, __env__, and __sls__, plus a few more:
A state ID-declaration is created with a state(id) function call. Subsequent state(id) call with the same id returns the same object. This singleton access pattern applies to all declaration objects created with the DSL.
The id argument is optional. If omitted, an UUID will be generated and used as the id. state(id) returns an object under which you can create a state-declaration object by accessing an attribute named after any state module available in Salt.
Then, a function-declaration object can be created from a state-declaration object by one of the following two ways:



With either way of creating a function-declaration object, any function-arg-declaration's can be passed as keyword arguments to the call. Subsequent calls of a function-declaration will update the arg declarations.
As a shortcut, the special name argument can also be passed as the first or second positional argument depending on the first or second way of calling the state-declaration object. In the following two examples ls -la is the name argument.
Finally, a requisite-declaration object with its requisite-reference's can be created by invoking one of the requisite methods (see State Requisites) on either a function-declaration object or a state-declaration object. The return value of a requisite call is also a function-declaration object, so you can chain several requisite calls together. Arguments to a requisite call can be a list of state-declaration objects and/or a set of keyword arguments whose names are state modules and values are IDs of ID-declaration's or names of name-declaration's.
include-declaration objects can be created with the include function, while extend-declaration objects can be created with the extend function, whose arguments are just function-declaration objects.
The include function, by default, causes the included sls file to be rendered as soon as the include function is called. It returns a list of rendered module objects; sls files not rendered with the pydsl renderer return None's. This behavior creates no include-declaration's in the resulting high state data structure.
Notice how you can define a reusable function in your pydsl sls module and then call it via the module returned by include. It's still possible to do late includes by passing the delayed=True keyword argument to include.
Above will just create a include-declaration in the rendered result, and such call always returns None.

Special integration with the cmd state¶

Taking advantage of rendering a Python module, PyDSL allows you to declare a state that calls a pre-defined Python function when the state is executed.
The cmd.call state function takes care of calling our helper function with the arguments we specified in the states, and translates the return value of our function into a structure expected by the state system. See salt.states.cmd.call() for more information.

Implicit ordering of states¶

Salt states are explicitly ordered via requisite-declaration's. However, with pydsl it's possible to let the renderer track the order of creation for function-declaration objects, and implicitly add require requisites for your states to enforce the ordering. This feature is enabled by setting the ordered option on __pydsl__. NOTE:

Notice that the ordered option needs to be set after any extend calls. This is to prevent pydsl from tracking the creation of a state function that's passed to an extend call. Above example should create states from 0 to 9 that will output 0, one, two, 3, ... 9, in that order. It's important to know that pydsl tracks the creations of function-declaration objects, and automatically adds a require requisite to a function-declaration object that requires the last function-declaration object created before it in the sls file. This means later calls (perhaps to update the function's function-arg-declaration) to a previously created function declaration will not change the order.

Render time state execution¶

When Salt processes a salt formula file, the file is rendered to salt's high state data representation by a renderer before the states can be executed. In the case of the pydsl renderer, the .sls file is executed as a python module as it is being rendered which makes it easy to execute a state at render time. In pydsl, executing one or more states at render time can be done by calling a configured ID-declaration object.
Once an ID-declaration is called at render time it is detached from the sls module as if it was never defined. NOTE:

Integration with the stateconf renderer¶

The salt.renderers.stateconf renderer offers a few interesting features that can be leveraged by the pydsl renderer. In particular, when using with the pydsl renderer, we are interested in stateconf's sls namespacing feature (via dot-prefixed id declarations), as well as, the automatic start and goal states generation. Now you can use pydsl with stateconf like this:
-s enables the generation of a stateconf start state, and -p lets us pipe high state data rendered by pydsl to stateconf. This example shows that by require-ing or require_in-ing the included sls' start or goal states, it's possible to ensure that the included sls files can be made to execute before or after a state in the including sls file.

Importing custom Python modules¶

To use a custom Python module inside a PyDSL state, place the module somewhere that it can be loaded by the Salt loader, such as _modules in the /srv/salt directory. Then, copy it to any minions as necessary by using saltutil.sync_modules. To import into a PyDSL SLS, one must bypass the Python importer and insert it manually by getting a reference from Python's sys.modules dictionary. For example:

salt.renderers.pyobjects¶

Python renderer that includes a Pythonic Object based interface
Let's take a look at how you use pyobjects in a state file. Here's a quick example that ensures the /tmp directory is in the correct state.
Nice and Pythonic! By using the "shebang" syntax to switch to the pyobjects renderer we can now write our state data using an object based interface that should feel at home to python developers. You can import any module and do anything that you'd like (with caution, importing sqlalchemy, django or other large frameworks has not been tested yet). Using the pyobjects renderer is exactly the same as using the built-in Python renderer with the exception that pyobjects provides you with an object based interface for generating state data.

Creating state data¶

Pyobjects takes care of creating an object for each of the available states on the minion. Each state is represented by an object that is the CamelCase version of its name (i.e. File, Service, User, etc), and these objects expose all of their available state functions (i.e. File.managed, Service.running, etc). The name of the state is split based upon underscores ( _), then each part is capitalized and finally the parts are joined back together. Some examples:

Context Managers and requisites¶

How about something a little more complex. Here we're going to get into the core of how to use pyobjects to write states.
The objects that are returned from each of the magic method calls are setup to be used a Python context managers ( with) and when you use them as such all declarations made within the scope will automatically use the enclosing state as a requisite! The above could have also been written use direct requisite statements as.
You can use the direct requisite statement for referencing states that are generated outside of the current file.
The last thing that direct requisites provide is the ability to select which of the SaltStack requisites you want to use (require, require_in, watch, watch_in, use & use_in) when using the requisite as a context manager.
The above example would cause all declarations inside the scope of the context manager to automatically have their watch_in set to Service("my-service").

Including and Extending¶

To include other states use the include() function. It takes one name per state to include. To extend another state use the extend() function on the name when creating a state.

Importing from other state files¶

Like any Python project that grows you will likely reach a point where you want to create reusability in your state tree and share objects between state files, Map Data (described below) is a perfect example of this. To facilitate this Python's import statement has been augmented to allow for a special case when working with a Salt state tree. If you specify a Salt url ( salt://...) as the target for importing from then the pyobjects renderer will take care of fetching the file for you, parsing it with all of the pyobjects features available and then place the requested objects in the global scope of the template being rendered. This works for all types of import statements; import X, from X import Y, and from X import Y as Z.
See the Map Data section for a more practical use. Caveats:

Salt object¶

In the spirit of the object interface for creating state data pyobjects also provides a simple object interface to the __salt__ object. A function named salt exists in scope for your sls files and will dispatch its attributes to the __salt__ dictionary. The following lines are functionally equivalent:

Pillar, grain, mine & config data¶

Pyobjects provides shortcut functions for calling pillar.get, grains.get, mine.get & config.get on the __salt__ object. This helps maintain the readability of your state files. Each type of data can be access by a function of the same name: pillar(), grains(), mine() and config(). The following pairs of lines are functionally equivalent:

Map Data¶

When building complex states or formulas you often need a way of building up a map of data based on grain data. The most common use of this is tracking the package and service name differences between distributions. To build map data using pyobjects we provide a class named Map that you use to build your own classes with inner classes for each set of values for the different grain matches.
To use this new data you can import it into your state file and then access your attributes. To access the data in the map you simply access the attribute name on the base class that is extending Map. Assuming the above Map was in the file samba/map.sls, you could do the following.

salt.renderers.stateconf¶

This module provides a custom renderer that processes a salt file with a specified templating engine (e.g. Jinja) and a chosen data renderer (e.g. YAML), extracts arguments for any stateconf.set state, and provides the extracted arguments (including Salt-specific args, such as require, etc) as template context. The goal is to make writing reusable/configurable/parameterized salt files easier and cleaner. To use this renderer, either set it as the default renderer via the renderer option in master/minion's config, or use the shebang line in each individual sls file, like so: #!stateconf. Note, due to the way this renderer works, it must be specified as the first renderer in a render pipeline. That is, you cannot specify #!mako|yaml|stateconf, for example. Instead, you specify them as renderer arguments: #!stateconf mako . yaml. Here's a list of features enabled by this renderer.
When writing sls files with this renderer, one should avoid using what can be defined in a name argument of a state as the state's id. That is, avoid writing states like this:
Instead, define the state id and the name argument separately for each state. Also, the ID should be something meaningful and easy to reference within a requisite (which is a good habit anyway, and such extra indirection would also makes the sls file easier to modify later). Thus, the above states should be written like this:
Moreover, when referencing a state from a requisite, you should reference the state's id plus the state name rather than the state name plus its name argument. (Yes, in the above example, you can actually require the file: /path/to/some/file, instead of the file: add-some-file). The reason is that this renderer will re-write or rename state id's and their references for state id's prefixed with .. So, if you reference name then there's no way to reliably rewrite such reference.

salt.renderers.wempy¶

salt.renderers.yaml¶

Understanding YAML¶

The default renderer for SLS files is the YAML renderer. YAML is a markup language with many powerful features. However, Salt uses a small subset of YAML that maps over very commonly used data structures, like lists and dictionaries. It is the job of the YAML renderer to take the YAML data structure and compile it into a Python data structure for use by Salt. Though YAML syntax may seem daunting and terse at first, there are only three very simple rules to remember when writing YAML for SLS files.

Rule One: Indentation¶

YAML uses a fixed indentation scheme to represent relationships between data layers. Salt requires that the indentation for each level consists of exactly two spaces. Do not use tabs.

Rule Two: Colons¶

Python dictionaries are, of course, simply key-value pairs. Users from other languages may recognize this data type as hashes or associative arrays. Dictionary keys are represented in YAML as strings terminated by a trailing colon. Values are represented by either a string following the colon, separated by a space:
In Python, the above maps to:
Dictionaries can be nested:
And in Python:

Rule Three: Dashes¶

To represent lists of items, a single dash followed by a space is used. Multiple items are a part of the same list as a function of their having the same level of indentation.
Lists can be the value of a key-value pair. This is quite common in Salt:

Reference¶

YAML Renderer for Salt For YAML usage information see Understanding YAML.

salt.renderers.yamlex¶

YAMLEX renderer is a replacement of the YAML renderer. It's 100% YAML with a pinch of Salt magic:
Instructed aggregation within the !aggregation and the !reset tags:
is roughly equivalent to

Reference¶

USING SALT¶

This section describes the fundamental components and concepts that you need to understand to use Salt.

Grains¶

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. The grains interface is made available to Salt modules and components so that the right salt minion commands are automatically available on the right systems. Grain data is relatively static, though if system information changes (for example, if network settings are changed), or if a new value is assigned to a custom grain, grain data is refreshed. NOTE:

Listing Grains¶

Available grains can be listed by using the 'grains.ls' module:
Grains data can be listed by using the 'grains.items' module:

Grains in the Minion Config¶

Grains can also be statically assigned within the minion configuration file. Just add the option grains and pass options to it:
Then status data specific to your servers can be retrieved via Salt, or used inside of the State system for matching. It also makes targeting, in the case of the example above, simply based on specific data about your deployment.

Grains in /etc/salt/grains¶

If you do not want to place your custom static grains in the minion config file, you can also put them in /etc/salt/grains on the minion. They are configured in the same way as in the above example, only without a top-level grains: key:

Matching Grains in the Top File¶

With correctly configured grains on the Minion, the top file used in Pillar or during Highstate can be made very efficient. For example, consider the following configuration:
For this example to work, you would need to have defined the grain node_type for the minions you wish to match. This simple example is nice, but too much of the code is similar. To go one step further, Jinja templating can be used to simplify the top file.
Using Jinja templating, only one match entry needs to be defined. NOTE:

Writing Grains¶

The grains are derived by executing all of the "public" functions (i.e. those which do not begin with an underscore) found in the modules located in the Salt's core grains code, followed by those in any custom grains modules. The functions in a grains module must return a Python dict, where the dictionary keys are the names of grains, and each key's value is that value for that grain. Custom grains modules should be placed in a subdirectory named _grains located under the file_roots specified by the master config file. The default path would be /srv/salt/_grains. Custom grains modules will be distributed to the minions when state.highstate is run, or by executing the saltutil.sync_grains or saltutil.sync_all functions. Grains modules are easy to write, and (as noted above) only need to return a dictionary. For example:
The name of the function does not matter and will not factor into the grains data at all; only the keys/values returned become part of the grains.

When to Use a Custom Grain¶

Before adding new grains, consider what the data is and remember that grains should (for the most part) be static data. If the data is something that is likely to change, consider using Pillar or an execution module instead. If it's a simple set of key/value pairs, pillar is a good match. If compiling the information requires that system commands be run, then putting this information in an execution module is likely a better idea. Good candidates for grains are data that is useful for targeting minions in the top file or the Salt CLI. The name and data structure of the grain should be designed to support many platforms, operating systems or applications. Also, keep in mind that Jinja templating in Salt supports referencing pillar data as well as invoking functions from execution modules, so there's no need to place information in grains to make it available to Jinja templates. For example:
WARNING:

Loading Custom Grains¶

If you have multiple functions specifying grains that are called from a main function, be sure to prepend grain function names with an underscore. This prevents Salt from including the loaded grains from the grain functions in the final grain data structure. For example, consider this custom grain file:
The output of this example renders like so:
However, if you don't prepend the my_custom_grain function with an underscore, the function will be rendered twice by Salt in the items output: once for the my_custom_grain call itself, and again when it is called in the main function:

Precedence¶

Core grains can be overridden by custom grains. As there are several ways of defining custom grains, there is an order of precedence which should be kept in mind when defining them. The order of evaluation is as follows:
Each successive evaluation overrides the previous ones, so any grains defined by custom grains modules synced to minions that have the same name as a core grain will override that core grain. Similarly, grains from /etc/salt/minion override both core grains and custom grain modules, and grains in _grains will override any grains of the same name.

Examples of Grains¶

The core module in the grains package is where the main grains are loaded by the Salt minion and provides the principal example of how to write grains: https://github.com/saltstack/salt/blob/develop/salt/grains/core.py

Syncing Grains¶

Syncing grains can be done a number of ways, they are automatically synced when state.highstate is called, or (as noted above) the grains can be manually synced and reloaded by calling the saltutil.sync_grains or saltutil.sync_all functions.

Storing Static Data in the Pillar¶

Pillar is an interface for Salt designed to offer global values that can be distributed to minions. Pillar data is managed in a similar way as the Salt State Tree. Pillar was added to Salt in version 0.9.8 NOTE:

Declaring the Master Pillar¶

The Salt Master server maintains a pillar_roots setup that matches the structure of the file_roots used in the Salt file server. Like file_roots, the pillar_roots option mapps environments to directories. The pillar data is then mapped to minions based on matchers in a top file which is laid out in the same way as the state top file. Salt pillars can use the same matcher types as the standard top file. conf_master: pillar_roots is configured just like file_roots. For example:
This example configuration declares that the base environment will be located in the /srv/pillar directory. It must not be in a subdirectory of the state tree. The top file used matches the name of the top file used for States, and has the same structure: /srv/pillar/top.sls
In the above top file, it is declared that in the base environment, the glob matching all minions will have the pillar data found in the packages pillar available to it. Assuming the pillar_roots value of /srv/pillar taken from above, the packages pillar would be located at /srv/pillar/packages.sls. Any number of matchers can be added to the base environment. For example, here is an expanded version of the Pillar top file stated above: /srv/pillar/top.sls:
In this expanded top file, minions that match web* will have access to the /srv/pillar/packages.sls file, as well as the /srv/pillar/vim.sls file. Another example shows how to use other standard top matching types to deliver specific salt pillar data to minions with different properties. Here is an example using the grains matcher to target pillars to minions by their os grain:
/srv/pillar/packages.sls
IMPORTANT:
The above pillar sets two key/value pairs. If a minion is running RedHat, then the apache key is set to httpd and the git key is set to the value of git. If the minion is running Debian, those values are changed to apache2 and git-core respectively. All minions that have this pillar targeting to them via a top file will have the key of company with a value of Foo Industries. Consequently this data can be used from within modules, renderers, State SLS files, and more via the shared pillar dict:

Finally, the above states can utilize the values provided to them via Pillar. All pillar values targeted to a minion are available via the 'pillar' dictionary. As seen in the above example, Jinja substitution can then be utilized to access the keys and values in the Pillar dictionary. Note that you cannot just list key/value-information in top.sls. Instead, target a minion to a pillar file and then list the keys and values in the pillar. Here is an example top file that illustrates this point:
And the actual pillar file at '/srv/pillar/common_pillar.sls':

Pillar Namespace Flattening¶

The separate pillar SLS files all merge down into a single dictionary of key-value pairs. When the same key is defined in multiple SLS files, this can result in unexpected behavior if care is not taken to how the pillar SLS files are laid out. For example, given a top.sls containing the following:
with packages.sls containing:
and services.sls containing:
Then a request for the bind pillar key will only return named. The bind9 value will be lost, because services.sls was evaluated later. NOTE:
It can be better to structure your pillar files with more hierarchy. For example the package.sls file could be configured like so:
This would make the packages pillar key a nested dictionary containing a bind key.

Pillar Dictionary Merging¶

If the same pillar key is defined in multiple pillar SLS files, and the keys in both files refer to nested dictionaries, then the content from these dictionaries will be recursively merged. For example, keeping the top.sls the same, assume the following modifications to the pillar SLS files: packages.sls:
services.sls:
The resulting pillar dictionary will be:
Since both pillar SLS files contained a bind key which contained a nested dictionary, the pillar dictionary's bind key contains the combined contents of both SLS files' bind keys.

Including Other Pillars¶

New in version 0.16.0. Pillar SLS files may include other pillar files, similar to State files. Two syntaxes are available for this purpose. The simple form simply includes the additional pillar as if it were part of the same file:
The full include form allows two additional options -- passing default values to the templating engine for the included pillar file as well as an optional key under which to nest the results of the included pillar:
With this form, the included file (users.sls) will be nested within the 'users' key of the compiled pillar. Additionally, the 'sudo' value will be available as a template variable to users.sls.

In-Memory Pillar Data vs. On-Demand Pillar Data¶

Since compiling pillar data is computationally expensive, the minion will maintain a copy of the pillar data in memory to avoid needing to ask the master to recompile and send it a copy of the pillar data each time pillar data is requested. This in-memory pillar data is what is returned by the pillar.item, pillar.get, and pillar.raw functions. Also, for those writing custom execution modules, or contributing to Salt's existing execution modules, the in-memory pillar data is available as the __pillar__ dunder dictionary. The in-memory pillar data is generated on minion start, and can be refreshed using the saltutil.refresh_pillar function:
This function triggers the minion to asynchronously refresh the in-memory pillar data and will always return None. In contrast to in-memory pillar data, certain actions trigger pillar data to be compiled to ensure that the most up-to-date pillar data is available. These actions include:
Performing these actions will not refresh the in-memory pillar data. So, if pillar data is modified, and then states are run, the states will see the updated pillar data, but pillar.item, pillar.get, and pillar.raw will not see this data unless refreshed using saltutil.refresh_pillar.

How Pillar Environments Are Handled¶

When multiple pillar environments are used, the default behavior is for the pillar data from all environments to be merged together. The pillar dictionary will therefore contain keys from all configured environments. The pillarenv minion config option can be used to force the minion to only consider pillar configuration from a single environment. This can be useful in cases where one needs to run states with alternate pillar data, either in a testing/QA environment or to test changes to the pillar data before pushing them live. For example, assume that the following is set in the minion config file:
This would cause that minion to ignore all other pillar environments besides base when compiling the in-memory pillar data. Then, when running states, the pillarenv CLI argument can be used to override the minion's pillarenv config value:
The above command will run the states with pillar data sourced exclusively from the testing environment, without modifying the in-memory pillar data. NOTE:

Viewing Pillar Data¶

To view pillar data, use the pillar execution module. This module includes several functions, each of them with their own use. These functions include:

The pillar.get Function¶

New in version 0.14.0. The pillar.get function works much in the same way as the get method in a python dict, but with an enhancement: nested dictonaries can be traversed using a colon as a delimiter. If a structure like this is in pillar:
Extracting it from the raw pillar in an sls formula or file template is done this way:
Now, with the new pillar.get function the data can be safely gathered and a default can be set, allowing the template to fall back if the value is not available:
This makes handling nested structures much easier. NOTE:

Setting Pillar Data at the Command Line¶

Pillar data can be set at the command line like the following example:
This will add a pillar key of cheese with its value set to spam. NOTE:

Master Config in Pillar¶

For convenience the data stored in the master configuration file can be made available in all minion's pillars. This makes global configuration of services and systems very easy but may not be desired if sensitive data is stored in the master configuration. This option is disabled by default. To enable the master config from being added to the pillar set pillar_opts to True in the minion config file:

Minion Config in Pillar¶

Minion configuration options can be set on pillars. Any option that you want to modify, should be in the first level of the pillars, in the same way you set the options in the config file. For example, to configure the MySQL root password to be used by MySQL Salt execution module, set the following pillar variable:

Master Provided Pillar Error¶

By default if there is an error rendering a pillar, the detailed error is hidden and replaced with:
The error is protected because it's possible to contain templating data which would give that minion information it shouldn't know, like a password! To have the master provide the detailed error that could potentially carry protected data set pillar_safe_render_error to False:

Pillar Walkthrough¶

NOTE:
Pillars are tree-like structures of data defined on the Salt Master and passed through to minions. They allow confidential, targeted data to be securely sent only to the relevant minion. NOTE:
Pillar data is useful for:
Pillar is therefore one of the most important systems when using Salt. This walkthrough is designed to get a simple Pillar up and running in a few minutes and then to dive into the capabilities of Pillar and where the data is available.

Setting Up Pillar¶

The pillar is already running in Salt by default. To see the minion's pillar data:
NOTE:
By default, the contents of the master configuration file are not loaded into pillar for all minions. This default is stored in the pillar_opts setting, which defaults to False. The contents of the master configuration file can be made available to minion pillar files. This makes global configuration of services and systems very easy, but note that this may not be desired or appropriate if sensitive data is stored in the master's configuration file. To enable the master configuration file to be available to a minion's pillar files, set pillar_opts to True in the minion configuration file. Similar to the state tree, the pillar is comprised of sls files and has a top file. The default location for the pillar is in /srv/pillar. NOTE:
To start setting up the pillar, the /srv/pillar directory needs to be present:
Now create a simple top file, following the same format as the top file used for states: /srv/pillar/top.sls:
This top file associates the data.sls file to all minions. Now the /srv/pillar/data.sls file needs to be populated: /srv/pillar/data.sls:
To ensure that the minions have the new pillar data, issue a command to them asking that they fetch their pillars from the master:
Now that the minions have the new pillar, it can be retrieved:
The key info should now appear in the returned pillar data.

More Complex Data¶

Unlike states, pillar files do not need to define formulas. This example sets up user data with a UID: /srv/pillar/users/init.sls:
NOTE:
The top file will need to be updated to include this sls file: /srv/pillar/top.sls:
Now the data will be available to the minions. To use the pillar data in a state, you can use Jinja: /srv/salt/users/init.sls
This approach allows for users to be safely defined in a pillar and then the user data is applied in an sls file.

Parameterizing States With Pillar¶

Pillar data can be accessed in state files to customise behavior for each minion. All pillar (and grain) data applicable to each minion is substituted into the state files through templating before being run. Typical uses include setting directories appropriate for the minion and skipping states that don't apply. A simple example is to set up a mapping of package names in pillar for separate Linux distributions: /srv/pillar/pkg/init.sls:
The new pkg sls needs to be added to the top file: /srv/pillar/top.sls:
Now the minions will auto map values based on respective operating systems inside of the pillar, so sls files can be safely parameterized: /srv/salt/apache/init.sls:
Or, if no pillar is available a default can be set as well: NOTE:
/srv/salt/apache/init.sls:
In the above example, if the pillar value pillar['pkgs']['apache'] is not set in the minion's pillar, then the default of httpd will be used. NOTE:

Pillar Makes Simple States Grow Easily¶

One of the design goals of pillar is to make simple sls formulas easily grow into more flexible formulas without refactoring or complicating the states. A simple formula: /srv/salt/edit/vim.sls:
Can be easily transformed into a powerful, parameterized formula: /srv/salt/edit/vim.sls:
Where the vimrc source location can now be changed via pillar: /srv/pillar/edit/vim.sls:
Ensuring that the right vimrc is sent out to the correct minions.

Setting Pillar Data on the Command Line¶

Pillar data can be set on the command line when running state.apply <salt.modules.state.apply_() like so:
Nested pillar values can also be set via the command line:
NOTE:
The example below will swap the value for vim with telnet in the previously specified list, notice the nested pillar dict:
This will attempt to install telnet on your minions, feel free to uninstall the package or replace telnet value with anything else. NOTE:

More On Pillar¶

Pillar data is generated on the Salt master and securely distributed to minions. Salt is not restricted to the pillar sls files when defining the pillar but can retrieve data from external sources. This can be useful when information about an infrastructure is stored in a separate location. Reference information on pillar and the external pillar interface can be found in the Salt documentation: Pillar

Minion Config in Pillar¶

Minion configuration options can be set on pillars. Any option that you want to modify, should be in the first level of the pillars, in the same way you set the options in the config file. For example, to configure the MySQL root password to be used by MySQL Salt execution module:
This is very convenient when you need some dynamic configuration change that you want to be applied on the fly. For example, there is a chicken and the egg problem if you do this:
The second state will fail, because you changed the root password and the minion didn't notice it. Setting mysql.pass in the pillar, will help to sort out the issue. But always change the root admin password in the first place. This is very helpful for any module that needs credentials to apply state changes: mysql, keystone, etc.

Targeting Minions¶

Targeting minions is specifying which minions should run a command or execute a state by matching against hostnames, or system information, or defined groups, or even combinations thereof. For example the command salt web1 apache.signal restart to restart the Apache httpd server specifies the machine web1 as the target and the command will only be run on that one minion. Similarly when using States, the following top file specifies that only the web1 minion should execute the contents of webserver.sls:
The simple target specifications, glob, regex, and list will cover many use cases, and for some will cover all use cases, but more powerful options exist.

Targeting with Grains¶

The Grains interface was built into Salt to allow minions to be targeted by system properties. So minions running on a particular operating system can be called to execute a function, or a specific kernel. Calling via a grain is done by passing the -G option to salt, specifying a grain and a glob expression to match the value of the grain. The syntax for the target is the grain key followed by a globexpression: "os:Arch*".
Will return True from all of the minions running Fedora. To discover what grains are available and what the values are, execute the grains.item salt function:
more info on using targeting with grains can be found here.

Compound Targeting¶

New in version 0.9.5. Multiple target interfaces can be used in conjunction to determine the command targets. These targets can then be combined using and or or statements. This is well defined with an example:
In this example any minion who's id starts with webser and is running Debian, or any minion who's id starts with db will be matched. The type of matcher defaults to glob, but can be specified with the corresponding letter followed by the @ symbol. In the above example a grain is used with G@ as well as a regular expression with E@. The webser* target does not need to be prefaced with a target type specifier because it is a glob. more info on using compound targeting can be found here.

Node Group Targeting¶

New in version 0.9.5. For certain cases, it can be convenient to have a predefined group of minions on which to execute commands. This can be accomplished using what are called nodegroups. Nodegroups allow for predefined compound targets to be declared in the master configuration file, as a sort of shorthand for having to type out complicated compound expressions.
There are many ways to target individual minions or groups of minions in Salt:

Matching the minion id¶

Each minion needs a unique identifier. By default when a minion starts for the first time it chooses its FQDN as that identifier. The minion id can be overridden via the minion's id configuration setting. TIP:

Globbing¶

The default matching that Salt utilizes is shell-style globbing around the minion id. This also works for states in the top file. NOTE:
Match all minions:
Match all minions in the example.net domain or any of the example domains:
Match all the webN minions in the example.net domain (web1.example.net, web2.example.net … webN.example.net):
Match the web1 through web5 minions:
Match the web1 and web3 minions:
Match the web-x, web-y, and web-z minions:
NOTE:

Regular Expressions¶

Minions can be matched using Perl-compatible regular expressions (which is globbing on steroids and a ton of caffeine). Match both web1-prod and web1-devel minions:
When using regular expressions in a State's top file, you must specify the matcher as the first option. The following example executes the contents of webserver.sls on the above-mentioned minions.

Lists¶

At the most basic level, you can specify a flat list of minion IDs:

Targeting using Grains¶

Grain data can be used when targeting minions. For example, the following matches all CentOS minions:
Match all minions with 64-bit CPUs, and return number of CPU cores for each matching minion:
Additionally, globs can be used in grain matches, and grains that are nested in a dictionary can be matched by adding a colon for each level that is traversed. For example, the following will match hosts that have a grain called ec2_tags, which itself is a dict with a key named environment, which has a value that contains the word production:
IMPORTANT:

Targeting using Pillar¶

Pillar data can be used when targeting minions. This allows for ultimate control and flexibility when targeting minions. NOTE:
Example:
Like with Grains, it is possible to use globbing as well as match nested values in Pillar, by adding colons for each level that is being traversed. The below example would match minions with a pillar named foo, which is a dict containing a key bar, with a value beginning with baz:

Subnet/IP Address Matching¶

Minions can easily be matched based on IP address, or by subnet (using CIDR notation).
Ipcidr matching can also be used in compound matches
It is also possible to use in both pillar and state-matching
NOTE:

Compound matchers¶

Compound matchers allow very granular minion targeting using any of Salt's matchers. The default matcher is a glob match, just as with CLI and top file matching. To match using anything other than a glob, prefix the match string with the appropriate letter from the table below, followed by an @ sign.

Letter	Match Type	Example	Alt Delimiter?
G	Grains glob	G@os:Ubuntu	Yes
E	PCRE Minion ID	E@web\d+\.(dev|qa|prod)\.loc	No
P	Grains PCRE	P@os:(RedHat|Fedora|CentOS)	Yes
L	List of minions	L@minion1.example.com,minion3.domain.com or bl*.domain.com	No
I	Pillar glob	I@pdata:foobar	Yes
J	Pillar PCRE	J@pdata:^(foo|bar)$	Yes
S	Subnet/IP address	S@192.168.1.0/24 or S@192.168.1.100	No
R	Range cluster	R@%foo.bar	No

Matchers can be joined using boolean and, or, and not operators. For example, the following string matches all Debian minions with a hostname that begins with webserv, as well as any minions that have a hostname which matches the regular expression web-dc1-srv.*:
That same example expressed in a top file looks like the following:
New in version 2015.8.0. Excluding a minion based on its ID is also possible:
Versions prior to 2015.8.0 a leading not was not supported in compound matches. Instead, something like the following was required:
Excluding a minion based on its ID was also possible:

Precedence Matching¶

Matchers can be grouped together with parentheses to explicitly declare precedence amongst groups.
NOTE:

Alternate Delimiters¶

New in version 2015.8.0. Matchers that target based on a key value pair use a colon ( :) as a delimiter. Matchers with a Yes in the Alt Delimiters column in the previous table support specifying an alternate delimiter character. This is done by specifying an alternate delimiter character between the leading matcher character and the @ pattern separator character. This avoids incorrect interpretation of the pattern in the case that : is part of the grain or pillar data structure traversal.

Node groups¶

Nodegroups are declared using a compound target specification. The compound target documentation can be found here. The nodegroups master config file parameter is used to define nodegroups. Here's an example nodegroup configuration within /etc/salt/master:
NOTE:
New in version 2015.8.0. NOTE:
New in version 2015.8.0. Compound nodegroups can be either string values or lists of string values. When the nodegroup is A string value will be tokenized by splitting on whitespace. This may be a problem if whitespace is necessary as part of a pattern. When a nodegroup is a list of strings then tokenization will happen for each list element as a whole. To match a nodegroup on the CLI, use the -N command-line option:
NOTE:
To match a nodegroup in your top file, make sure to put - match: nodegroup on the line directly following the nodegroup name.
NOTE:

Defining Nodegroups as Lists of Minion IDs¶

A simple list of minion IDs would traditionally be defined like this:
They can now also be defined as a YAML list, like this:
New in version 2016.11.0.

Using Nodegroups in SLS files¶

To use Nodegroups in Jinja logic for SLS files, the pillar_opts option in /etc/salt/master must be set to True. This will pass the master's configuration as Pillar data to each minion. NOTE:
Once pillar_opts is set to True, you can find the nodegroups under the "master" pillar. To make sure that only the correct minions are targeted, you should use each matcher for the nodegroup definition. For example, to check if a minion is in the 'webserver' nodegroup:

NOTE:

Batch Size¶

The -b (or --batch-size) option allows commands to be executed on only a specified number of minions at a time. Both percentages and finite numbers are supported.
This will only run test.ping on 10 of the targeted minions at a time and then restart apache on 25% of the minions matching os:RedHat at a time and work through them all until the task is complete. This makes jobs like rolling web server restarts behind a load balancer or doing maintenance on BSD firewalls using carp much easier with salt. The batch system maintains a window of running minions, so, if there are a total of 150 minions targeted and the batch size is 10, then the command is sent to 10 minions, when one minion returns then the command is sent to one additional minion, so that the job is constantly running on 10 minions. New in version 2016.3. The --batch-wait argument can be used to specify a number of seconds to wait after a minion returns, before sending the command to a new minion.

SECO Range¶

SECO range is a cluster-based metadata store developed and maintained by Yahoo! The Range project is hosted here: https://github.com/ytoolshed/range Learn more about range here: https://github.com/ytoolshed/range/wiki/

Prerequisites¶

To utilize range support in Salt, a range server is required. Setting up a range server is outside the scope of this document. Apache modules are included in the range distribution. With a working range server, cluster files must be defined. These files are written in YAML and define hosts contained inside a cluster. Full documentation on writing YAML range files is here: https://github.com/ytoolshed/range/wiki/%22yamlfile%22-module-file-spec Additionally, the Python seco range libraries must be installed on the salt master. One can verify that they have been installed correctly via the following command:
If no errors are returned, range is installed successfully on the salt master.

Preparing Salt¶

Range support must be enabled on the salt master by setting the hostname and port of the range server inside the master configuration file:
Following this, the master must be restarted for the change to have an effect.

Targeting with Range¶

Once a cluster has been defined, it can be targeted with a salt command by using the -R or --range flags. For example, given the following range YAML file being served from a range server:
One might target host1 through host100 in the test.com domain with Salt as follows:
The following salt command would target three hosts: frontend, backend, and mysql:

The Salt Mine¶

The Salt Mine is used to collect arbitrary data from Minions and store it on the Master. This data is then made available to all Minions via the salt.modules.mine module. Mine data is gathered on the Minion and sent back to the Master where only the most recent data is maintained (if long term data is required use returners or the external job cache).

Mine vs Grains¶

Mine data is designed to be much more up-to-date than grain data. Grains are refreshed on a very limited basis and are largely static data. Mines are designed to replace slow peer publishing calls when Minions need data from other Minions. Rather than having a Minion reach out to all the other Minions for a piece of data, the Salt Mine, running on the Master, can collect it from all the Minions every mine-interval, resulting in almost fresh data at any given time, with much less overhead.

Mine Functions¶

To enable the Salt Mine the mine_functions option needs to be applied to a Minion. This option can be applied via the Minion's configuration file, or the Minion's Pillar. The mine_functions option dictates what functions are being executed and allows for arguments to be passed in. If no arguments are passed, an empty list must be added:

Mine Functions Aliases¶

Function aliases can be used to provide friendly names, usage intentions or to allow multiple calls of the same function with different arguments. There is a different syntax for passing positional and key-value arguments. Mixing positional and key-value arguments is not supported. New in version 2014.7.0.

Mine Interval¶

The Salt Mine functions are executed when the Minion starts and at a given interval by the scheduler. The default interval is every 60 minutes and can be adjusted for the Minion via the mine_interval option:

Mine in Salt-SSH¶

As of the 2015.5.0 release of salt, salt-ssh supports mine.get. Because the Minions cannot provide their own mine_functions configuration, we retrieve the args for specified mine functions in one of three places, searched in the following order:
The mine_functions are formatted exactly the same as in normal salt, just stored in a different location. Here is an example of a flat roster containing mine_functions:
NOTE:

Minions Targeting with Mine¶

The mine.get function supports various methods of Minions targeting to fetch Mine data from particular hosts, such as glob or regular expression matching on Minion id (name), grains, pillars and compound matches. See the salt.modules.mine module documentation for the reference. NOTE:

Example¶

One way to use data from Salt Mine is in a State. The values can be retrieved via Jinja and used in the SLS file. The following example is a partial HAProxy configuration file and pulls IP addresses from all Minions with the "web" grain to add them to the pool of load balanced servers. /srv/pillar/top.sls:
/srv/pillar/web.sls:
/etc/salt/minion.d/mine.conf:
/srv/salt/haproxy.sls:
/srv/salt/haproxy_config:
NOTE:

Runners¶

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 itself instead of remote Salt minions. A Salt runner can be a simple client call or a complex application. SEE ALSO:

Writing Salt Runners¶

A Salt runner is written in a similar manner to a Salt execution module. Both are Python modules which contain functions and each public function is a runner which may be executed via the salt-run command. For example, if a Python module named test.py is created in the runners directory and contains a function called foo, the test runner could be invoked with the following command:
Runners have several options for controlling output. Any print statement in a runner is automatically also fired onto the master event bus where. For example:
The above would result in an event fired as follows:
A runner may also send a progress event, which is displayed to the user during runner execution and is also passed across the event bus if the display_progress argument to a runner is set to True. A custom runner may send its own progress event by using the __jid_event_.fire_event() method as shown here:
The above would produce output on the console reading: A progress message as well as an event on the event similar to:
A runner could use the same approach to send an event with a customized tag onto the event bus by replacing the second argument ( progress) with whatever tag is desired. However, this will not be shown on the command-line and will only be fired onto the event bus.

Synchronous vs. Asynchronous¶

A runner may be fired asynchronously which will immediately return control. In this case, no output will be display to the user if salt-run is being used from the command-line. If used programmatically, no results will be returned. If results are desired, they must be gathered either by firing events on the bus from the runner and then watching for them or by some other means. NOTE:
In synchronous mode, which is the default, control will not be returned until the runner has finished executing. To add custom runners, put them in a directory and add it to runner_dirs in the master configuration file.

Examples¶

Examples of runners can be found in the Salt distribution: https://github.com/saltstack/salt/blob/develop/salt/runners A simple runner that returns a well-formatted list of the minions that are responding to Salt calls could look like this:

Salt Engines¶

New in version 2015.8.0. Salt Engines are long-running, external system processes that leverage Salt.
Salt engines enhance and replace the external processes functionality.

Configuration¶

Salt engines are configured under an engines top-level section in your Salt master or Salt minion configuration. Provide a list of engines and parameters under this section.
Salt engines must be in the Salt path, or you can add the engines_dirs option in your Salt master configuration with a list of directories under which Salt attempts to find Salt engines.

Writing an Engine¶

An example Salt engine, https://github.com/saltstack/salt/blob/develop/salt/engines/test.py, is available in the Salt source. To develop an engine, the only requirement is that your module implement the start() function.

Understanding YAML¶

The default renderer for SLS files is the YAML renderer. YAML is a markup language with many powerful features. However, Salt uses a small subset of YAML that maps over very commonly used data structures, like lists and dictionaries. It is the job of the YAML renderer to take the YAML data structure and compile it into a Python data structure for use by Salt. Though YAML syntax may seem daunting and terse at first, there are only three very simple rules to remember when writing YAML for SLS files.

Rule One: Indentation¶

YAML uses a fixed indentation scheme to represent relationships between data layers. Salt requires that the indentation for each level consists of exactly two spaces. Do not use tabs.

Rule Two: Colons¶

Python dictionaries are, of course, simply key-value pairs. Users from other languages may recognize this data type as hashes or associative arrays. Dictionary keys are represented in YAML as strings terminated by a trailing colon. Values are represented by either a string following the colon, separated by a space:
In Python, the above maps to:
Alternatively, a value can be associated with a key through indentation.
NOTE:
In Python, the above maps to:
Dictionaries can be nested:
And in Python:

Rule Three: Dashes¶

To represent lists of items, a single dash followed by a space is used. Multiple items are a part of the same list as a function of their having the same level of indentation.
Lists can be the value of a key-value pair. This is quite common in Salt:
In Python, the above maps to:

Learning More¶

One easy way to learn more about how YAML gets rendered into Python data structures is to use an online YAML parser to see the Python output. One excellent choice for experimenting with YAML parsing is: http://yaml-online-parser.appspot.com/

Templating¶

Jinja statements and expressions are allowed by default in SLS files. See Understanding Jinja.

Understanding Jinja¶

Jinja is the default templating language in SLS files.

Jinja in States¶

Jinja is evaluated before YAML, which means it is evaluated before the States are run. The most basic usage of Jinja in state files is using control structures to wrap conditional or redundant state elements:
In this example, the first if block will only be evaluated on minions that aren't running FreeBSD, and the second block changes the file name based on the os grain. Writing if-else blocks can lead to very redundant state files however. In this case, using pillars, or using a previously defined variable might be easier:
Using a variable set by the template, the for loop will iterate over the list of MOTD files to update, adding a state block for each file. The filter_by function can also be used to set variables based on grains:

Include and Import¶

Includes and imports can be used to share common, reusable state configuration between state files and between files.
This would import the test template variable or macro, not the test state element, from the file lib.sls. In the case that the included file performs checks again grains, or something else that requires context, passing the context into the included file is required:

Including Context During Include/Import¶

By adding with context to the include/import directive, the current context can be passed to an included/imported template.

Macros¶

Macros are helpful for eliminating redundant code. Macros are most useful as mini-templates to repeat blocks of strings with a few parameterized variables. Be aware that stripping whitespace from the template block, as well as contained blocks, may be necessary to emulate a variable return from the macro.

This would define a macro that would return a string of the full package name, depending on the packaging system's naming convention. The whitespace of the macro was eliminated, so that the macro would return a string without line breaks, using whitespace control.

Template Inheritance¶

Template inheritance works fine from state files and files. The search path starts at the root of the state tree or pillar.

Filters¶

Saltstack extends builtin filters with these custom filters:

Jinja in Files¶

Jinja_

can be used in the same way in managed files:


As an example, configuration was pulled from the file context and from an external template file. NOTE:

Escaping Jinja¶

Occasionally, it may be necessary to escape Jinja syntax. There are two ways to to do this in Jinja. One is escaping individual variables or strings and the other is to escape entire blocks. To escape a string commonly used in Jinja syntax such as {{, you can use the following syntax:
For larger blocks that contain Jinja syntax that needs to be escaped, you can use raw blocks:
See the Escaping section of Jinja's documentation to learn more. A real-word example of needing to use raw tags to escape a larger block of code is when using file.managed with the contents_pillar option to manage files that contain something like consul-template, which shares a syntax subset with Jinja. Raw blocks are necessary here because the Jinja in the pillar would be rendered before the file.managed is ever called, so the Jinja syntax must be escaped:

Calling Salt Functions¶

The Jinja renderer provides a shorthand lookup syntax for the salt dictionary of execution function. New in version 2014.7.0.

Debugging¶

The show_full_context function can be used to output all variables present in the current Jinja context. New in version 2014.7.0.

Custom Execution Modules¶

Custom execution modules can be used to supplement or replace complex Jinja. Many tasks that require complex looping and logic are trivial when using Python in a Salt execution module. Salt execution modules are easy to write and distribute to Salt minions. Functions in custom execution modules are available in the Salt execution module dictionary just like the built-in execution modules:

Tutorials Index¶

Troubleshooting¶

The intent of the troubleshooting section is to introduce solutions to a number of common issues encountered by users and the tools that are available to aid in developing States and Salt code.

Troubleshooting the Salt Master¶

If your Salt master is having issues such as minions not returning data, slow execution times, or a variety of other issues, the following links contain details on troubleshooting the most common issues encountered:

Troubleshooting the Salt Master¶

Running in the Foreground¶

A great deal of information is available via the debug logging system, if you are having issues with minions connecting or not starting run the master in the foreground:
Anyone wanting to run Salt daemons via a process supervisor such as monit, runit, or supervisord, should omit the -d argument to the daemons and run them in the foreground.

What Ports does the Master Need Open?¶

For the master, TCP ports 4505 and 4506 need to be open. If you've put both your Salt master and minion in debug mode and don't see an acknowledgment that your minion has connected, it could very well be a firewall interfering with the connection. See our firewall configuration page for help opening the firewall on various platforms. If you've opened the correct TCP ports and still aren't seeing connections, check that no additional access control system such as SELinux or AppArmor is blocking Salt.

Too many open files¶

The salt-master needs at least 2 sockets per host that connects to it, one for the Publisher and one for response port. Thus, large installations may, upon scaling up the number of minions accessing a given master, encounter:
The solution to this would be to check the number of files allowed to be opened by the user running salt-master (root by default):
If this value is not equal to at least twice the number of minions, then it will need to be raised. For example, in an environment with 1800 minions, the nofile limit should be set to no less than 3600. This can be done by creating the file /etc/security/limits.d/99-salt.conf, with the following contents:
Replace root with the user under which the master runs, if different. If your master does not have an /etc/security/limits.d directory, the lines can simply be appended to /etc/security/limits.conf. As with any change to resource limits, it is best to stay logged into your current shell and open another shell to run ulimit -n again and verify that the changes were applied correctly. Additionally, if your master is running upstart, it may be necessary to specify the nofile limit in /etc/default/salt-master if upstart isn't respecting your resource limits:
NOTE:

Salt Master Stops Responding¶

There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the Salt master to not respond properly. If you're running a ZeroMQ version greater than or equal to 2.1.9, you can work around the bug by setting the sysctls net.core.rmem_max and net.core.wmem_max to 16777216. Next, set the third field in net.ipv4.tcp_rmem and net.ipv4.tcp_wmem to at least 16777216. You can do it manually with something like:
Or with the following Salt state:

Live Python Debug Output¶

If the master seems to be unresponsive, a SIGUSR1 can be passed to the salt-master threads to display what piece of code is executing. This debug information can be invaluable in tracking down bugs. To pass a SIGUSR1 to the master, first make sure the minion is running in the foreground. Stop the service if it is running as a daemon, and start it in the foreground like so:
Then pass the signal to the master when it seems to be unresponsive:
When filing an issue or sending questions to the mailing list for a problem with an unresponsive daemon, be sure to include this information if possible.

Live Salt-Master Profiling¶

When faced with performance problems one can turn on master process profiling by sending it SIGUSR2.
This will activate yappi profiler inside salt-master code, then after some time one must send SIGUSR2 again to stop profiling and save results to file. If run in foreground salt-master will report filename for the results, which are usually located under /tmp on Unix-based OSes and c:\temp on windows. Results can then be analyzed with kcachegrind or similar tool.

Commands Time Out or Do Not Return Output¶

Depending on your OS (this is most common on Ubuntu due to apt-get) you may sometimes encounter times where a state.apply, or other long running commands do not return output. By default the timeout is set to 5 seconds. The timeout value can easily be increased by modifying the timeout line within your /etc/salt/master configuration file. Having keys accepted for Salt minions that no longer exist or are not reachable also increases the possibility of timeouts, since the Salt master waits for those systems to return command results.

Passing the -c Option to Salt Returns a Permissions Error¶

Using the -c option with the Salt command modifies the configuration directory. When the configuration file is read it will still base data off of the root_dir setting. This can result in unintended behavior if you are expecting files such as /etc/salt/pki to be pulled from the location specified with -c. Modify the root_dir setting to address this behavior.

Salt Master Doesn't Return Anything While Running jobs¶

When a command being run via Salt takes a very long time to return (package installations, certain scripts, etc.) the master may drop you back to the shell. In most situations the job is still running but Salt has exceeded the set timeout before returning. Querying the job queue will provide the data of the job but is inconvenient. This can be resolved by either manually using the -t option to set a longer timeout when running commands (by default it is 5 seconds) or by modifying the master configuration file: /etc/salt/master and setting the timeout value to change the default timeout for all commands, and then restarting the salt-master service.

Salt Master Auth Flooding¶

In large installations, care must be taken not to overwhealm the master with authentication requests. Several options can be set on the master which mitigate the chances of an authentication flood from causing an interruption in service. NOTE:

Running state locally¶

To debug the states, you can use call locally.
The top.sls file is used to map what SLS modules get loaded onto what minions via the state system. It is located in the file defined in the file_roots variable of the salt master configuration file which is defined by found in CONFIG_DIR/master, normally /etc/salt/master The default configuration for the file_roots is:
So the top file is defaulted to the location /srv/salt/top.sls

Salt Master Umask¶

The salt master uses a cache to track jobs as they are published and returns come back. The recommended umask for a salt-master is 022, which is the default for most users on a system. Incorrect umasks can result in permission-denied errors when the master tries to access files in its cache.

Troubleshooting the Salt Minion¶

In the event that your Salt minion is having issues, a variety of solutions and suggestions are available. Please refer to the following links for more information:

Troubleshooting the Salt Minion¶

Running in the Foreground¶

A great deal of information is available via the debug logging system, if you are having issues with minions connecting or not starting run the minion in the foreground:
Anyone wanting to run Salt daemons via a process supervisor such as monit, runit, or supervisord, should omit the -d argument to the daemons and run them in the foreground.

What Ports does the Minion Need Open?¶

No ports need to be opened on the minion, as it makes outbound connections to the master. If you've put both your Salt master and minion in debug mode and don't see an acknowledgment that your minion has connected, it could very well be a firewall interfering with the connection. See our firewall configuration page for help opening the firewall on various platforms. If you have netcat installed, you can check port connectivity from the minion with the nc command:
The Nmap utility can also be used to check if these ports are open:
If you've opened the correct TCP ports and still aren't seeing connections, check that no additional access control system such as SELinux or AppArmor is blocking Salt. Tools like tcptraceroute can also be used to determine if an intermediate device or firewall is blocking the needed TCP ports.

Using salt-call¶

The salt-call command was originally developed for aiding in the development of new Salt modules. Since then, many applications have been developed for running any Salt module locally on a minion. These range from the original intent of salt-call (development assistance), to gathering more verbose output from calls like state.apply. When initially creating your state tree, it is generally recommended to invoke highstates by running state.apply directly from the minion with salt-call, rather than remotely from the master. This displays far more information about the execution than calling it remotely. For even more verbosity, increase the loglevel using the -l argument:
The main difference between using salt and using salt-call is that salt-call is run from the minion, and it only runs the selected function on that minion. By contrast, salt is run from the master, and requires you to specify the minions on which to run the command using salt's targeting system.

Live Python Debug Output¶

If the minion seems to be unresponsive, a SIGUSR1 can be passed to the process to display what piece of code is executing. This debug information can be invaluable in tracking down bugs. To pass a SIGUSR1 to the minion, first make sure the minion is running in the foreground. Stop the service if it is running as a daemon, and start it in the foreground like so:
Then pass the signal to the minion when it seems to be unresponsive:
When filing an issue or sending questions to the mailing list for a problem with an unresponsive daemon, be sure to include this information if possible.

Multiprocessing in Execution Modules¶

As is outlined in github issue #6300, Salt cannot use python's multiprocessing pipes and queues from execution modules. Multiprocessing from the execution modules is perfectly viable, it is just necessary to use Salt's event system to communicate back with the process. The reason for this difficulty is that python attempts to pickle all objects in memory when communicating, and it cannot pickle function objects. Since the Salt loader system creates and manages function objects this causes the pickle operation to fail.

Salt Minion Doesn't Return Anything While Running Jobs Locally¶

When a command being run via Salt takes a very long time to return (package installations, certain scripts, etc.) the minion may drop you back to the shell. In most situations the job is still running but Salt has exceeded the set timeout before returning. Querying the job queue will provide the data of the job but is inconvenient. This can be resolved by either manually using the -t option to set a longer timeout when running commands (by default it is 5 seconds) or by modifying the minion configuration file: /etc/salt/minion and setting the timeout value to change the default timeout for all commands, and then restarting the salt-minion service. NOTE:

Running in the Foreground¶

A great deal of information is available via the debug logging system, if you are having issues with minions connecting or not starting run the minion and/or master in the foreground:
Anyone wanting to run Salt daemons via a process supervisor such as monit, runit, or supervisord, should omit the -d argument to the daemons and run them in the foreground.

What Ports do the Master and Minion Need Open?¶

No ports need to be opened up on each minion. For the master, TCP ports 4505 and 4506 need to be open. If you've put both your Salt master and minion in debug mode and don't see an acknowledgment that your minion has connected, it could very well be a firewall. You can check port connectivity from the minion with the nc command:
There is also a firewall configuration document that might help as well. If you've enabled the right TCP ports on your operating system or Linux distribution's firewall and still aren't seeing connections, check that no additional access control system such as SELinux or AppArmor is blocking Salt.

Using salt-call¶

The salt-call command was originally developed for aiding in the development of new Salt modules. Since then, many applications have been developed for running any Salt module locally on a minion. These range from the original intent of salt-call, development assistance, to gathering more verbose output from calls like state.apply. When initially creating your state tree, it is generally recommended to invoke state.apply directly from the minion with salt-call, rather than remotely from the master. This displays far more information about the execution than calling it remotely. For even more verbosity, increase the loglevel using the -l argument:
The main difference between using salt and using salt-call is that salt-call is run from the minion, and it only runs the selected function on that minion. By contrast, salt is run from the master, and requires you to specify the minions on which to run the command using salt's targeting system.

Too many open files¶

The salt-master needs at least 2 sockets per host that connects to it, one for the Publisher and one for response port. Thus, large installations may, upon scaling up the number of minions accessing a given master, encounter:
The solution to this would be to check the number of files allowed to be opened by the user running salt-master (root by default):
And modify that value to be at least equal to the number of minions x 2. This setting can be changed in limits.conf as the nofile value(s), and activated upon new a login of the specified user. So, an environment with 1800 minions, would need 1800 x 2 = 3600 as a minimum.

Salt Master Stops Responding¶

There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the Salt master to not respond properly. If you're running a ZeroMQ version greater than or equal to 2.1.9, you can work around the bug by setting the sysctls net.core.rmem_max and net.core.wmem_max to 16777216. Next, set the third field in net.ipv4.tcp_rmem and net.ipv4.tcp_wmem to at least 16777216. You can do it manually with something like:
Or with the following Salt state:

Salt and SELinux¶

Currently there are no SELinux policies for Salt. For the most part Salt runs without issue when SELinux is running in Enforcing mode. This is because when the minion executes as a daemon the type context is changed to initrc_t. The problem with SELinux arises when using salt-call or running the minion in the foreground, since the type context stays unconfined_t. This problem is generally manifest in the rpm install scripts when using the pkg module. Until a full SELinux Policy is available for Salt the solution to this issue is to set the execution context of salt-call and salt-minion to rpm_exec_t:
This works well, because the rpm_exec_t context has very broad control over other types.

Red Hat Enterprise Linux 5¶

Salt requires Python 2.6 or 2.7. Red Hat Enterprise Linux 5 and its variants come with Python 2.4 installed by default. When installing on RHEL 5 from the EPEL repository this is handled for you. But, if you run Salt from git, be advised that its dependencies need to be installed from EPEL and that Salt needs to be run with the python26 executable.

Common YAML Gotchas¶

An extensive list of YAML idiosyncrasies has been compiled:

YAML Idiosyncrasies¶

One of Salt's strengths, the use of existing serialization systems for representing SLS data, can also backfire. YAML is a general purpose system and there are a number of things that would seem to make sense in an sls file that cause YAML issues. It is wise to be aware of these issues. While reports or running into them are generally rare they can still crop up at unexpected times.

Spaces vs Tabs¶

YAML uses spaces, period. Do not use tabs in your SLS files! If strange errors are coming up in rendering SLS files, make sure to check that no tabs have crept in! In Vim, after enabling search highlighting with: :set hlsearch, you can check with the following key sequence in normal mode(you can hit ESC twice to be sure): /, Ctrl-v, Tab, then hit Enter. Also, you can convert tabs to 2 spaces by these commands in Vim: :set tabstop=2 expandtab and then :retab.

Indentation¶

The suggested syntax for YAML files is to use 2 spaces for indentation, but YAML will follow whatever indentation system that the individual file uses. Indentation of two spaces works very well for SLS files given the fact that the data is uniform and not deeply nested.

Nested Dictionaries¶

When dicts are nested within other data structures (particularly lists), the indentation logic sometimes changes. Examples of where this might happen include context and default options from the file.managed state:
Notice that while the indentation is two spaces per level, for the values under the context and defaults options there is a four-space indent. If only two spaces are used to indent, then those keys will be considered part of the same dictionary that contains the context key, and so the data will not be loaded correctly. If using a double indent is not desirable, then a deeply-nested dict can be declared with curly braces:
Here is a more concrete example of how YAML actually handles these indentations, using the Python interpreter on the command line:
Note that in the second example, some is added as another key in the same dictionary, whereas in the first example, it's the start of a new dictionary. That's the distinction. context is a common example because it is a keyword arg for many functions, and should contain a dictionary.

True/False, Yes/No, On/Off¶

PyYAML will load these values as boolean True or False. Un-capitalized versions will also be loaded as booleans ( true, false, yes, no, on, and off). This can be especially problematic when constructing Pillar data. Make sure that your Pillars which need to use the string versions of these values are enclosed in quotes. Pillars will be parsed twice by salt, so you'll need to wrap your values in multiple quotes, for example '"false"'.

The '%' Sign¶

The % symbol has a special meaning in YAML, it needs to be passed as a string literal:

Integers are Parsed as Integers¶

NOTE: This has been fixed in salt 0.10.0, as of this release passing an integer that is preceded by a 0 will be correctly parsed When passing integers into an SLS file, they are passed as integers. This means that if a state accepts a string value and an integer is passed, that an integer will be sent. The solution here is to send the integer as a string. This is best explained when setting the mode for a file:
Salt manages this well, since the mode is passed as 644, but if the mode is zero padded as 0644, then it is read by YAML as an integer and evaluated as an octal value, 0644 becomes 420. Therefore, if the file mode is preceded by a 0 then it needs to be passed as a string:

YAML does not like Double Short Decs¶

If I can find a way to make YAML accept "Double Short Decs" then I will, since I think that double short decs would be awesome. So what is a "Double Short Dec"? It is when you declare a multiple short decs in one ID. Here is a standard short dec, it works great:
The short dec means that there are no arguments to pass, so it is not required to add any arguments, and it can save space. YAML though, gets upset when declaring multiple short decs, for the record... THIS DOES NOT WORK:
Similarly declaring a short dec in the same ID dec as a standard dec does not work either... ALSO DOES NOT WORK:
The correct way is to define them like this:
Alternatively, they can be defined the "old way", or with multiple "full decs":

YAML support only plain ASCII¶

According to YAML specification, only ASCII characters can be used. Within double-quotes, special characters may be represented with C-style escape sequences starting with a backslash ( \ ). Examples:
List of usable Unicode characters will help you to identify correct numbers. Python can also be used to discover the Unicode number for a character:
This shell command can find wrong characters in your SLS files:
Alternatively you can toggle the yaml_utf8 setting in your master configuration file. This is still an experimental setting but it should manage the right encoding conversion in salt after yaml states compilations.

Underscores stripped in Integer Definitions¶

If a definition only includes numbers and underscores, it is parsed by YAML as an integer and all underscores are stripped. To ensure the object becomes a string, it should be surrounded by quotes. More information here. Here's an example:

Automatic datetime conversion¶

If there is a value in a YAML file formatted 2014-01-20 14:23:23 or similar, YAML will automatically convert this to a Python datetime object. These objects are not msgpack serializable, and so may break core salt functionality. If values such as these are needed in a salt YAML file (specifically a configuration file), they should be formatted with surrounding strings to force YAML to serialize them as strings:
Additionally, numbers formatted like XXXX-XX-XX will also be converted (or YAML will attempt to convert them, and error out if it doesn't think the date is a real one). Thus, for example, if a minion were to have an ID of 4017-16-20 the minion would not start because YAML would complain that the date was out of range. The workaround is the same, surround the offending string with quotes:

Keys Limited to 1024 Characters¶

Simple keys are limited to a single line and cannot be longer that 1024 characters. This is a limitation from PyYaml, as seen in a comment in PyYAML's code, and applies to anything parsed by YAML in Salt.

Live Python Debug Output¶

If the minion or master seems to be unresponsive, a SIGUSR1 can be passed to the processes to display where in the code they are running. If encountering a situation like this, this debug information can be invaluable. First make sure the master of minion are running in the foreground:
Then pass the signal to the master or minion when it seems to be unresponsive:
Also under BSD and macOS in addition to SIGUSR1 signal, debug subroutine set up for SIGINFO which has an advantage of being sent by Ctrl+T shortcut. When filing an issue or sending questions to the mailing list for a problem with an unresponsive daemon this information can be invaluable.

Salt 0.16.x minions cannot communicate with a 0.17.x master¶

As of release 0.17.1 you can no longer run different versions of Salt on your Master and Minion servers. This is due to a protocol change for security purposes. The Salt team will continue to attempt to ensure versions are as backwards compatible as possible.

Debugging the Master and Minion¶

A list of common master and minion troubleshooting steps provide a starting point for resolving issues you may encounter.

Frequently Asked Questions¶

FAQ¶

Is Salt open-core?¶

No. Salt is 100% committed to being open-source, including all of our APIs. It is developed under the Apache 2.0 license, allowing it to be used in both open and proprietary projects. To expand on this a little: There is much argument over the actual definition of "open core". From our standpoint, Salt is open source because
SaltStack the company does make proprietary products which use Salt and its libraries, like company is free to do, but we do so via the APIs, NOT by forking Salt and creating a different, closed-source version of it for paying customers.

I think I found a bug! What should I do?¶

The salt-users mailing list as well as the salt IRC channel can both be helpful resources to confirm if others are seeing the issue and to assist with immediate debugging. To report a bug to the Salt project, please follow the instructions in reporting a bug.

What ports should I open on my firewall?¶

Minions need to be able to connect to the Master on TCP ports 4505 and 4506. Minions do not need any inbound ports open. More detailed information on firewall settings can be found here.

I'm seeing weird behavior (including but not limited to packages not installing their users properly)¶

This is often caused by SELinux. Try disabling SELinux or putting it in permissive mode and see if the weird behavior goes away.

My script runs every time I run a state.apply. Why?¶

You are probably using cmd.run rather than cmd.wait. A cmd.wait state will only run when there has been a change in a state that it is watching. A cmd.run state will run the corresponding command every time (unless it is prevented from running by the unless or onlyif arguments). More details can be found in the documentation for the cmd states.

When I run test.ping, why don't the Minions that aren't responding return anything? Returning False would be helpful.¶

When you run test.ping the Master tells Minions to run commands/functions, and listens for the return data, printing it to the screen when it is received. If it doesn't receive anything back, it doesn't have anything to display for that Minion. There are a couple options for getting information on Minions that are not responding. One is to use the verbose ( -v) option when you run salt commands, as it will display "Minion did not return" for any Minions which time out.
Another option is to use the manage.down runner:
Also, if the Master is under heavy load, it is possible that the CLI will exit without displaying return data for all targeted Minions. However, this doesn't mean that the Minions did not return; this only means that the Salt CLI timed out waiting for a response. Minions will still send their return data back to the Master once the job completes. If any expected Minions are missing from the CLI output, the jobs.list_jobs runner can be used to show the job IDs of the jobs that have been run, and the jobs.lookup_jid runner can be used to get the return data for that job.
If you find that you are often missing Minion return data on the CLI, only to find it with the jobs runners, then this may be a sign that the worker_threads value may need to be increased in the master config file. Additionally, running your Salt CLI commands with the -t option will make Salt wait longer for the return data before the CLI command exits. For instance, the below command will wait up to 60 seconds for the Minions to return:

How does Salt determine the Minion's id?¶

If the Minion id is not configured explicitly (using the id parameter), Salt will determine the id based on the hostname. Exactly how this is determined varies a little between operating systems and is described in detail here.

I'm trying to manage packages/services but I get an error saying that the state is not available. Why?¶

Salt detects the Minion's operating system and assigns the correct package or service management module based on what is detected. However, for certain custom spins and OS derivatives this detection fails. In cases like this, an issue should be opened on our tracker, with the following information:

Why aren't my custom modules/states/etc. available on my Minions?¶

Custom modules are synced to Minions when saltutil.sync_modules, or saltutil.sync_all is run. Custom modules are also synced by state.apply when run without any arguments. Similarly, custom states are synced to Minions when state.apply, saltutil.sync_states, or saltutil.sync_all is run. Custom states are also synced by state.apply when run without any arguments. Other custom types (renderers, outputters, etc.) have similar behavior, see the documentation for the saltutil module for more information.

Module X isn't available, even though the shell command it uses is installed. Why?¶

This is most likely a PATH issue. Did you custom-compile the software which the module requires? RHEL/CentOS/etc. in particular override the root user's path in /etc/init.d/functions, setting it to /sbin:/usr/sbin:/bin:/usr/bin, making software installed into /usr/local/bin unavailable to Salt when the Minion is started using the initscript. In version 2014.1.0, Salt will have a better solution for these sort of PATH-related issues, but recompiling the software to install it into a location within the PATH should resolve the issue in the meantime. Alternatively, you can create a symbolic link within the PATH using a file.symlink state.

Can I run different versions of Salt on my Master and Minion?¶

This depends on the versions. In general, it is recommended that Master and Minion versions match. When upgrading Salt, the master(s) should always be upgraded first. Backwards compatibility for minions running newer versions of salt than their masters is not guaranteed. Whenever possible, backwards compatibility between new masters and old minions will be preserved. Generally, the only exception to this policy is in case of a security vulnerability. Recent examples of backwards compatibility breakage include the 0.17.1 release (where all backwards compatibility was broken due to a security fix), and the 2014.1.0 release (which retained compatibility between 2014.1.0 masters and 0.17 minions, but broke compatibility for 2014.1.0 minions and older masters).

Does Salt support backing up managed files?¶

Yes. Salt provides an easy to use addition to your file.managed states that allow you to back up files via backup_mode, backup_mode can be configured on a per state basis, or in the minion config (note that if set in the minion config this would simply be the default method to use, you still need to specify that the file should be backed up!).

Is it possible to deploy a file to a specific minion, without other minions having access to it?¶

The Salt fileserver does not yet support access control, but it is still possible to do this. As of Salt 2015.5.0, the file_tree external pillar is available, and allows the contents of a file to be loaded as Pillar data. This external pillar is capable of assigning Pillar values both to individual minions, and to nodegroups. See the documentation for details on how to set this up. Once the external pillar has been set up, the data can be pushed to a minion via a file.managed state, using the contents_pillar argument:
In this example, the source file would be located in a directory called secret_files underneath the file_tree path for the minion. The syntax for specifying the pillar variable is the same one used for pillar.get, with a colon representing a nested dictionary. WARNING:

What is the best way to restart a Salt daemon using Salt?¶

Updating the salt-minion package requires a restart of the salt-minion service. But restarting the service while in the middle of a state run interrupts the process of the minion running states and sending results back to the master. It's a tricky problem to solve, and we're working on it, but in the meantime one way of handling this (on Linux and UNIX-based operating systems) is to use at (a job scheduler which predates cron) to schedule a restart of the service. at is not installed by default on most distros, and requires a service to be running (usually called atd) in order to schedule jobs. Here's an example of how to upgrade the salt-minion package at the end of a Salt run, and schedule a service restart for one minute after the package update completes.

Linux/Unix¶

To ensure that at is installed and atd is running, the following states can be used (be sure to double-check the package name and service name for the distro the minion is running, in case they differ from the example below.
An alternative to using the atd daemon is to fork and disown the process.

Windows¶

For Windows machines, restarting the minion can be accomplished using the following state:
or running immediately from the command line:

Salting the Salt Master¶

In order to configure a master server via states, the Salt master can also be "salted" in order to enforce state on the Salt master as well as the Salt minions. Salting the Salt master requires a Salt minion to be installed on the same machine as the Salt master. Once the Salt minion is installed, the minion configuration file must be pointed to the local Salt master:
Once the Salt master has been "salted" with a Salt minion, it can be targeted just like any other minion. If the minion on the salted master is running, the minion can be targeted via any usual salt command. Additionally, the salt-call command can execute operations to enforce state on the salted master without requiring the minion to be running. More information about salting the Salt master can be found in the salt-formula for salt itself: https://github.com/saltstack-formulas/salt-formula

Is Targeting using Grain Data Secure?¶

Because grains can be set by users that have access to the minion configuration files on the local system, grains are considered less secure than other identifiers in Salt. Use caution when targeting sensitive operations or setting pillar values based on grain data. When possible, you should target sensitive operations and data using the Minion ID. If the Minion ID of a system changes, the Salt Minion's public key must be re-accepted by an administrator on the Salt Master, making it less vulnerable to impersonation attacks.

Why Did the Value for a Grain Change on Its Own?¶

This is usually the result of an upstream change in an OS distribution that replaces or removes something that Salt was using to detect the grain. Fortunately, when this occurs, you can use Salt to fix it with a command similar to the following:
(Replacing grain, ChangedValue, and OldValue with the grain and values that you want to change / set.) You should also file an issue describing the change so it can be fixed in Salt.

Salt Best Practices¶

Salt's extreme flexibility leads to many questions concerning the structure of configuration files. This document exists to clarify these points through examples and code.

General rules¶

Structuring States and Formulas¶

When structuring Salt States and Formulas it is important to begin with the directory structure. A proper directory structure clearly defines the functionality of each state to the user via visual inspection of the state's name. Reviewing the MySQL Salt Formula it is clear to see the benefits to the end-user when reviewing a sample of the available states:
This directory structure would lead to these states being referenced in a top file in the following way:
This clear definition ensures that the user is properly informed of what each state will do. Another example comes from the vim-formula:
Once again viewing how this would look in a top file: /srv/salt/top.sls:
The usage of a clear top-level directory as well as properly named states reduces the overall complexity and leads a user to both understand what will be included at a glance and where it is located. In addition Formulas should be used as often as possible. NOTE:

Structuring Pillar Files¶

Pillars are used to store secure and insecure data pertaining to minions. When designing the structure of the /srv/pillar directory, the pillars contained within should once again be focused on clear and concise data which users can easily review, modify, and understand. The /srv/pillar/ directory is primarily controlled by top.sls. It should be noted that the pillar top.sls is not used as a location to declare variables and their values. The top.sls is used as a way to include other pillar files and organize the way they are matched based on environments or grains. An example top.sls may be as simple as the following: /srv/pillar/top.sls:
Any number of matchers can be added to the base environment. For example, here is an expanded version of the Pillar top file stated above: /srv/pillar/top.sls:
Or an even more complicated example, using a variety of matchers in numerous environments: /srv/pillar/top.sls:
It is clear to see through these examples how the top file provides users with power but when used incorrectly it can lead to confusing configurations. This is why it is important to understand that the top file for pillar is not used for variable definitions. Each SLS file within the /srv/pillar/ directory should correspond to the states which it matches. This would mean that the apache pillar file should contain data relevant to Apache. Structuring files in this way once again ensures modularity, and creates a consistent understanding throughout our Salt environment. Users can expect that pillar variables found in an Apache state will live inside of an Apache pillar: /srv/pillar/apache.sls:
While this pillar file is simple, it shows how a pillar file explicitly relates to the state it is associated with.

Variable Flexibility¶

Salt allows users to define variables in SLS files. When creating a state variables should provide users with as much flexibility as possible. This means that variables should be clearly defined and easy to manipulate, and that sane defaults should exist in the event a variable is not properly defined. Looking at several examples shows how these different items can lead to extensive flexibility. Although it is possible to set variables locally, this is generally not preferred: /srv/salt/apache/conf.sls:
When generating this information it can be easily transitioned to the pillar where data can be overwritten, modified, and applied to multiple states, or locations within a single state: /srv/pillar/apache.sls:
/srv/salt/apache/conf.sls:
This flexibility provides users with a centralized location to modify variables, which is extremely important as an environment grows.

Modularity Within States¶

Ensuring that states are modular is one of the key concepts to understand within Salt. When creating a state a user must consider how many times the state could be re-used, and what it relies on to operate. Below are several examples which will iteratively explain how a user can go from a state which is not very modular to one that is: /srv/salt/apache/init.sls:
The example above is probably the worst-case scenario when writing a state. There is a clear lack of focus by naming both the pkg/service, and managed file directly as the state ID. This would lead to changing multiple requires within this state, as well as others that may depend upon the state. Imagine if a require was used for the httpd package in another state, and then suddenly it's a custom package. Now changes need to be made in multiple locations which increases the complexity and leads to a more error prone configuration. There is also the issue of having the configuration file located in the init, as a user would be unable to simply install the service and use the default conf file. Our second revision begins to address the referencing by using - name, as opposed to direct ID references: /srv/salt/apache/init.sls:
The above init file is better than our original, yet it has several issues which lead to a lack of modularity. The first of these problems is the usage of static values for items such as the name of the service, the name of the managed file, and the source of the managed file. When these items are hard coded they become difficult to modify and the opportunity to make mistakes arises. It also leads to multiple edits that need to occur when changing these items (imagine if there were dozens of these occurrences throughout the state!). There is also still the concern of the configuration file data living in the same state as the service and package. In the next example steps will be taken to begin addressing these issues. Starting with the addition of a map.jinja file (as noted in the Formula documentation), and modification of static values: /srv/salt/apache/map.jinja:
/srv/pillar/apache.sls:
/srv/salt/apache/init.sls:
The changes to this state now allow us to easily identify the location of the variables, as well as ensuring they are flexible and easy to modify. While this takes another step in the right direction, it is not yet complete. Suppose the user did not want to use the provided conf file, or even their own configuration file, but the default apache conf. With the current state setup this is not possible. To attain this level of modularity this state will need to be broken into two states. /srv/salt/apache/map.jinja:
/srv/pillar/apache.sls:
/srv/salt/apache/init.sls:
/srv/salt/apache/conf.sls:
This new structure now allows users to choose whether they only wish to install the default Apache, or if they wish, overwrite the default package, service, configuration file location, or the configuration file itself. In addition to this the data has been broken between multiple files allowing for users to identify where they need to change the associated data.

Storing Secure Data¶

Secure data refers to any information that you would not wish to share with anyone accessing a server. This could include data such as passwords, keys, or other information. As all data within a state is accessible by EVERY server that is connected it is important to store secure data within pillar. This will ensure that only those servers which require this secure data have access to it. In this example a use can go from an insecure configuration to one which is only accessible by the appropriate hosts: /srv/salt/mysql/testerdb.sls:
/srv/salt/mysql/user.sls:
Many users would review this state and see that the password is there in plain text, which is quite problematic. It results in several issues which may not be immediately visible. The first of these issues is clear to most users -- the password being visible in this state. This means that any minion will have a copy of this, and therefore the password which is a major security concern as minions may not be locked down as tightly as the master server. The other issue that can be encountered is access by users on the master. If everyone has access to the states (or their repository), then they are able to review this password. Keeping your password data accessible by only a few users is critical for both security and peace of mind. There is also the issue of portability. When a state is configured this way it results in multiple changes needing to be made. This was discussed in the sections above but it is a critical idea to drive home. If states are not portable it may result in more work later! Fixing this issue is relatively simple, the content just needs to be moved to the associated pillar: /srv/pillar/mysql.sls:
/srv/salt/mysql/testerdb.sls:
/srv/salt/mysql/user.sls:
Now that the database details have been moved to the associated pillar file, only machines which are targeted via pillar will have access to these details. Access to users who should not be able to review these details can also be prevented while ensuring that they are still able to write states which take advantage of this information.

REMOTE EXECUTION¶

Running pre-defined or arbitrary commands on remote hosts, also known as remote execution, is the core function of Salt. The following links explore modules and returners, which are two key elements of remote execution. Salt Execution Modules Salt execution modules are called by the remote execution system to perform a wide variety of tasks. These modules provide functionality such as installing packages, restarting a service, running a remote command, transferring files, and so on.

Remote execution tutorial¶

Before continuing make sure you have a working Salt installation by following the installation and the configuration instructions.

Order your minions around¶

Now that you have a master and at least one minion communicating with each other you can perform commands on the minion via the salt command. Salt calls are comprised of three main components:
SEE ALSO:

target¶

The target component allows you to filter which minions should run the following function. The default filter is a glob on the minion id. For example:
Targets can be based on minion system information using the Grains system:
SEE ALSO:
Targets can be filtered by regular expression:
Targets can be explicitly specified in a list:
Or Multiple target types can be combined in one command:

function¶

A function is some functionality provided by a module. Salt ships with a large collection of available functions. List all available functions on your minions:
Here are some examples: Show all currently available minions:
Run an arbitrary shell command:
SEE ALSO:

arguments¶

Space-delimited arguments to the function:
Optional, keyword arguments are also supported:
They are always in the form of kwarg=argument.

Running Commands on Salt Minions¶

Salt can be controlled by a command line client by the root user on the Salt master. The Salt command line client uses the Salt client API to communicate with the Salt master server. The Salt client is straightforward and simple to use. Using the Salt client commands can be easily sent to the minions. Each of these commands accepts an explicit --config option to point to either the master or minion configuration file. If this option is not provided and the default configuration file does not exist then Salt falls back to use the environment variables SALT_MASTER_CONFIG and SALT_MINION_CONFIG. SEE ALSO:

Using the Salt Command¶

The Salt command needs a few components to send information to the Salt minions. The target minions need to be defined, the function to call and any arguments the function requires.

Defining the Target Minions¶

The first argument passed to salt, defines the target minions, the target minions are accessed via their hostname. The default target type is a bash glob:
Salt can also define the target minions with regular expressions:
Or to explicitly list hosts, salt can take a list:

More Powerful Targets¶

See Targeting.

Calling the Function¶

The function to call on the specified target is placed after the target specification. New in version 0.9.8. Functions may also accept arguments, space-delimited:
Optional, keyword arguments are also supported:
They are always in the form of kwarg=argument. Arguments are formatted as YAML:
Note: dictionaries must have curly braces around them (like the saltenv keyword argument above). This was changed in 0.15.1: in the above example, the first argument used to be parsed as the dictionary {'echo "Hello': '$FIRST_NAME"'}. This was generally not the expected behavior. If you want to test what parameters are actually passed to a module, use the test.arg_repr command:

Finding available minion functions¶

The Salt functions are self documenting, all of the function documentation can be retried from the minions via the sys.doc() function:

Compound Command Execution¶

If a series of commands needs to be sent to a single target specification then the commands can be sent in a single publish. This can make gathering groups of information faster, and lowers the stress on the network for repeated commands. Compound command execution works by sending a list of functions and arguments instead of sending a single function and argument. The functions are executed on the minion in the order they are defined on the command line, and then the data from all of the commands are returned in a dictionary. This means that the set of commands are called in a predictable way, and the returned data can be easily interpreted. Executing compound commands if done by passing a comma delimited list of functions, followed by a comma delimited list of arguments:
The trick to look out for here, is that if a function is being passed no arguments, then there needs to be a placeholder for the absent arguments. This is why in the above example, there are two commas right next to each other. test.ping takes no arguments, so we need to add another comma, otherwise Salt would attempt to pass "foo" to test.ping. If you need to pass arguments that include commas, then make sure you add spaces around the commas that separate arguments. For example:
You may change the arguments separator using the --args-separator option:

CLI Completion¶

Shell completion scripts for the Salt CLI are available in the pkg Salt source directory.

Writing Execution Modules¶

Salt execution modules are the functions called by the salt command.

Modules Are Easy to Write!¶

Writing Salt execution modules is straightforward. A Salt execution module is a Python or Cython module placed in a directory called _modules/ at the root of the Salt fileserver. When using the default fileserver backend (i.e. roots <salt.fileserver.roots), unless environments are otherwise defined in the file_roots config option, the _modules/ directory would be located in /srv/salt/_modules on most systems. Modules placed in _modules/ will be synced to the minions when any of the following Salt functions are called:
Note that a module's default name is its filename (i.e. foo.py becomes module foo), but that its name can be overridden by using a __virtual__ function. If a Salt module has errors and cannot be imported, the Salt minion will continue to load without issue and the module with errors will simply be omitted. If adding a Cython module the file must be named <modulename>.pyx so that the loader knows that the module needs to be imported as a Cython module. The compilation of the Cython module is automatic and happens when the minion starts, so only the *.pyx file is required.

Zip Archives as Modules¶

Python 2.3 and higher allows developers to directly import zip archives containing Python code. By setting enable_zip_modules to True in the minion config, the Salt loader will be able to import .zip files in this fashion. This allows Salt module developers to package dependencies with their modules for ease of deployment, isolation, etc. For a user, Zip Archive modules behave just like other modules. When executing a function from a module provided as the file my_module.zip, a user would call a function within that module as my_module.<function>.

Creating a Zip Archive Module¶

A Zip Archive module is structured similarly to a simple Python package. The .zip file contains a single directory with the same name as the module. The module code traditionally in <module_name>.py goes in <module_name>/__init__.py. The dependency packages are subdirectories of <module_name>/. Here is an example directory structure for the lumberjack module, which has two library dependencies ( sleep and work) to be included.
The contents of lumberjack/__init__.py show how to import and use these included libraries.
Then, create the zip:
Once placed in file_roots, Salt users can distribute and use lumberjack.zip like any other module.

Cross Calling Execution Modules¶

All of the Salt execution modules are available to each other and modules can call functions available in other execution modules. The variable __salt__ is packed into the modules after they are loaded into the Salt minion. The __salt__ variable is a Python dictionary containing all of the Salt functions. Dictionary keys are strings representing the names of the modules and the values are the functions themselves. Salt modules can be cross-called by accessing the value in the __salt__ dict:
This code will call the run function in the cmd module and pass the argument bar to it.

Calling Execution Modules on the Salt Master¶

New in version 2016.11.0. Execution modules can now also be called via the salt-run command using the salt runner.

Preloaded Execution Module Data¶

When interacting with execution modules often it is nice to be able to read information dynamically about the minion or to load in configuration parameters for a module. Salt allows for different types of data to be loaded into the modules by the minion.

Grains Data¶

The values detected by the Salt Grains on the minion are available in a dict named __grains__ and can be accessed from within callable objects in the Python modules. To see the contents of the grains dictionary for a given system in your deployment run the grains.items() function:
Any value in a grains dictionary can be accessed as any other Python dictionary. For example, the grain representing the minion ID is stored in the id key and from an execution module, the value would be stored in __grains__['id'].

Module Configuration¶

Since parameters for configuring a module may be desired, Salt allows for configuration information from the minion configuration file to be passed to execution modules. Since the minion configuration file is a YAML document, arbitrary configuration data can be passed in the minion config that is read by the modules. It is therefore strongly recommended that the values passed in the configuration file match the module name. A value intended for the test execution module should be named test.<value>. The test execution module contains usage of the module configuration and the default configuration file for the minion contains the information and format used to pass data to the modules. salt.modules.test, conf/minion.

Strings and Unicode¶

An execution module author should always assume that strings fed to the module have already decoded from strings into Unicode. In Python 2, these will be of type 'Unicode' and in Python 3 they will be of type str. Calling from a state to other Salt sub-systems, should pass Unicode (or bytes if passing binary data). In the rare event that a state needs to write directly to disk, Unicode should be encoded to a string immediately before writing to disk. An author may use __salt_system_encoding__ to learn what the encoding type of the system is. For example, 'my_string'.encode(__salt_system_encoding__').

Outputter Configuration¶

Since execution module functions can return different data, and the way the data is printed can greatly change the presentation, Salt allows for a specific outputter to be set on a function-by-function basis. This is done be declaring an __outputter__ dictionary in the global scope of the module. The __outputter__ dictionary contains a mapping of function names to Salt outputters.
This will ensure that the txt outputter is used to display output from the run function.

Virtual Modules¶

Virtual modules let you override the name of a module in order to use the same name to refer to one of several similar modules. The specific module that is loaded for a virtual name is selected based on the current platform or environment. For example, packages are managed across platforms using the pkg module. pkg is a virtual module name that is an alias for the specific package manager module that is loaded on a specific system (for example, yumpkg on RHEL/CentOS systems , and aptpkg on Ubuntu). Virtual module names are set using the __virtual__ function and the virtual name.

__virtual__ Function¶

The __virtual__ function returns either a string, True, False, or False with an error string. If a string is returned then the module is loaded using the name of the string as the virtual name. If True is returned the module is loaded using the current module name. If False is returned the module is not loaded. False lets the module perform system checks and prevent loading if dependencies are not met. Since __virtual__ is called before the module is loaded, __salt__ will be unavailable as it will not have been packed into the module at this point in time. NOTE:

Returning Error Information from __virtual__¶

Optionally, Salt plugin modules, such as execution, state, returner, beacon, etc. modules may additionally return a string containing the reason that a module could not be loaded. For example, an execution module called cheese and a corresponding state module also called cheese, both depending on a utility called enzymes should have __virtual__ functions that handle the case when the dependency is unavailable.

Examples¶

The package manager modules are among the best examples of using the __virtual__ function. A table of all the virtual pkg modules can be found here.

Overriding Virtual Module Providers¶

Salt often uses OS grains ( os, osrelease, os_family, etc.) to determine which module should be loaded as the virtual module for pkg, service, etc. Sometimes this OS detection is incomplete, with new distros popping up, existing distros changing init systems, etc. The virtual modules likely to be affected by this are in the list below (click each item for more information):
If Salt is using the wrong module for one of these, first of all, please report it on the issue tracker, so that this issue can be resolved for a future release. To make it easier to troubleshoot, please also provide the grains.items output, taking care to redact any sensitive information. Then, while waiting for the SaltStack development team to fix the issue, Salt can be made to use the correct module using the providers option in the minion config file:
The above example will force the minion to use the systemd module to provide service management, and the aptpkg module to provide package management.

__virtualname__¶

__virtualname__ is a variable that is used by the documentation build system to know the virtual name of a module without calling the __virtual__ function. Modules that return a string from the __virtual__ function must also set the __virtualname__ variable. To avoid setting the virtual name string twice, you can implement __virtual__ to return the value set for __virtualname__ using a pattern similar to the following:

Documentation¶

Salt execution modules are documented. The sys.doc() function will return the documentation for all available modules:
The sys.doc function simply prints out the docstrings found in the modules; when writing Salt execution modules, please follow the formatting conventions for docstrings as they appear in the other modules.

Adding Documentation to Salt Modules¶

It is strongly suggested that all Salt modules have documentation added. To add documentation add a Python docstring to the function.
Now when the sys.doc call is executed the docstring will be cleanly returned to the calling terminal. Documentation added to execution modules in docstrings will automatically be added to the online web-based documentation.

Add Execution Module Metadata¶

When writing a Python docstring for an execution module, add information about the module using the following field lists:
The maintainer field is a comma-delimited list of developers who help maintain this module. The maturity field indicates the level of quality and testing for this module. Standard labels will be determined. The depends field is a comma-delimited list of modules that this module depends on. The platform field is a comma-delimited list of platforms that this module is known to run on.

Log Output¶

You can call the logger from custom modules to write messages to the minion logs. The following code snippet demonstrates writing log messages:

Aliasing Functions¶

Sometimes one wishes to use a function name that would shadow a python built-in. A common example would be set(). To support this, append an underscore to the function definition, def set_():, and use the __func_alias__ feature to provide an alias to the function. __func_alias__ is a dictionary where each key is the name of a function in the module, and each value is a string representing the alias for that function. When calling an aliased function from a different execution module, state module, or from the cli, the alias name should be used.

Private Functions¶

In Salt, Python callable objects contained within an execution module are made available to the Salt minion for use. The only exception to this rule is a callable object with a name starting with an underscore _.

Objects Loaded Into the Salt Minion¶

Objects NOT Loaded into the Salt Minion¶

Useful Decorators for Modules¶

Depends Decorator¶

When writing execution modules there are many times where some of the module will work on all hosts but some functions have an external dependency, such as a service that needs to be installed or a binary that needs to be present on the system. Instead of trying to wrap much of the code in large try/except blocks, a decorator can be used. If the dependencies passed to the decorator don't exist, then the salt minion will remove those functions from the module on that host. If a fallback_function is defined, it will replace the function instead of removing it
In addition to global dependencies the depends decorator also supports raw booleans.

CONFIGURATION MANAGEMENT¶

Salt contains a robust and flexible configuration management framework, which is built on the remote execution core. This framework executes on the minions, allowing effortless, simultaneous configuration of tens of thousands of hosts, by rendering language specific state files. The following links provide resources to learn more about state and renderers.
NOTE:

How Do I Use Salt States?¶

Simplicity, Simplicity, Simplicity Many of the most powerful and useful engineering solutions are founded on simple principles. Salt States strive to do just that: K.I.S.S. (Keep It Stupidly Simple) The core of the Salt State system is the SLS, or SaLt State file. The SLS is a representation of the state in which a system should be in, and is set up to contain this data in a simple format. This is often called configuration management. NOTE:

It is All Just Data¶

Before delving into the particulars, it will help to understand that the SLS file is just a data structure under the hood. While understanding that the SLS is just a data structure isn't critical for understanding and making use of Salt States, it should help bolster knowledge of where the real power is. SLS files are therefore, in reality, just dictionaries, lists, strings, and numbers. By using this approach Salt can be much more flexible. As one writes more state files, it becomes clearer exactly what is being written. The result is a system that is easy to understand, yet grows with the needs of the admin or developer.

The Top File¶

The example SLS files in the below sections can be assigned to hosts using a file called top.sls. This file is described in-depth here.

Default Data - YAML¶

By default Salt represents the SLS data in what is one of the simplest serialization formats available - YAML. A typical SLS file will often look like this in YAML: NOTE:

This SLS data will ensure that the package named apache is installed, and that the apache service is running. The components can be explained in a simple way. The first line is the ID for a set of data, and it is called the ID Declaration. This ID sets the name of the thing that needs to be manipulated. The second and third lines contain the state module function to be run, in the format <state_module>.<function>. The pkg.installed state module function ensures that a software package is installed via the system's native package manager. The service.running state module function ensures that a given system daemon is running. Finally, on line five, is the word require. This is called a Requisite Statement, and it makes sure that the Apache service is only started after a successful installation of the apache package.

Adding Configs and Users¶

When setting up a service like an Apache web server, many more components may need to be added. The Apache configuration file will most likely be managed, and a user and group may need to be set up.
This SLS data greatly extends the first example, and includes a config file, a user, a group and new requisite statement: watch. Adding more states is easy, since the new user and group states are under the Apache ID, the user and group will be the Apache user and group. The require statements will make sure that the user will only be made after the group, and that the group will be made only after the Apache package is installed. Next, the require statement under service was changed to watch, and is now watching 3 states instead of just one. The watch statement does the same thing as require, making sure that the other states run before running the state with a watch, but it adds an extra component. The watch statement will run the state's watcher function for any changes to the watched states. So if the package was updated, the config file changed, or the user uid modified, then the service state's watcher will be run. The service state's watcher just restarts the service, so in this case, a change in the config file will also trigger a restart of the respective service.

Moving Beyond a Single SLS¶

When setting up Salt States in a scalable manner, more than one SLS will need to be used. The above examples were in a single SLS file, but two or more SLS files can be combined to build out a State Tree. The above example also references a file with a strange source - salt://apache/httpd.conf. That file will need to be available as well. The SLS files are laid out in a directory structure on the Salt master; an SLS is just a file and files to download are just files. The Apache example would be laid out in the root of the Salt file server like this:
So the httpd.conf is just a file in the apache directory, and is referenced directly.
But when using more than one single SLS file, more components can be added to the toolkit. Consider this SSH example: ssh/init.sls:
ssh/server.sls:
NOTE:
Now our State Tree looks like this:
This example now introduces the include statement. The include statement includes another SLS file so that components found in it can be required, watched or as will soon be demonstrated - extended. The include statement allows for states to be cross linked. When an SLS has an include statement it is literally extended to include the contents of the included SLS files. Note that some of the SLS files are called init.sls, while others are not. More info on what this means can be found in the States Tutorial.

Extending Included SLS Data¶

Sometimes SLS data needs to be extended. Perhaps the apache service needs to watch additional resources, or under certain circumstances a different file needs to be placed. In these examples, the first will add a custom banner to ssh and the second will add more watchers to apache to include mod_python. ssh/custom-server.sls:
python/mod_python.sls:
The custom-server.sls file uses the extend statement to overwrite where the banner is being downloaded from, and therefore changing what file is being used to configure the banner. In the new mod_python SLS the mod_python package is added, but more importantly the apache service was extended to also watch the mod_python package.

Understanding the Render System¶

Since SLS data is simply that (data), it does not need to be represented with YAML. Salt defaults to YAML because it is very straightforward and easy to learn and use. But the SLS files can be rendered from almost any imaginable medium, so long as a renderer module is provided. The default rendering system is the yaml_jinja renderer. The yaml_jinja renderer will first pass the template through the Jinja2 templating system, and then through the YAML parser. The benefit here is that full programming constructs are available when creating SLS files. Other renderers available are yaml_mako and yaml_wempy which each use the Mako or Wempy templating system respectively rather than the jinja templating system, and more notably, the pure Python or py, pydsl & pyobjects renderers. The py renderer allows for SLS files to be written in pure Python, allowing for the utmost level of flexibility and power when preparing SLS data; while the pydsl renderer provides a flexible, domain-specific language for authoring SLS data in Python; and the pyobjects renderer gives you a "Pythonic" interface to building state data. NOTE:

Getting to Know the Default - yaml_jinja¶

The default renderer - yaml_jinja, allows for use of the jinja templating system. A guide to the Jinja templating system can be found here: http://jinja.pocoo.org/docs When working with renderers a few very useful bits of data are passed in. In the case of templating engine based renderers, three critical components are available, salt, grains, and pillar. The salt object allows for any Salt function to be called from within the template, and grains allows for the Grains to be accessed from within the template. A few examples: apache/init.sls:
This example is simple. If the os grain states that the operating system is Red Hat, then the name of the Apache package and service needs to be httpd. A more aggressive way to use Jinja can be found here, in a module to set up a MooseFS distributed filesystem chunkserver: moosefs/chunk.sls:
This example shows much more of the available power of Jinja. Multiple for loops are used to dynamically detect available hard drives and set them up to be mounted, and the salt object is used multiple times to call shell commands to gather data.

Introducing the Python, PyDSL, and the Pyobjects Renderers¶

Sometimes the chosen default renderer might not have enough logical power to accomplish the needed task. When this happens, the Python renderer can be used. Normally a YAML renderer should be used for the majority of SLS files, but an SLS file set to use another renderer can be easily added to the tree. This example shows a very basic Python SLS file: python/django.sls:
This is a very simple example; the first line has an SLS shebang that tells Salt to not use the default renderer, but to use the py renderer. Then the run function is defined, the return value from the run function must be a Salt friendly data structure, or better known as a Salt HighState data structure. Alternatively, using the pydsl renderer, the above example can be written more succinctly as:
The pyobjects renderer provides an "Pythonic" object based approach for building the state data. The above example could be written as:
These Python examples would look like this if they were written in YAML:
This example clearly illustrates that; one, using the YAML renderer by default is a wise decision and two, unbridled power can be obtained where needed by using a pure Python SLS.

Running and Debugging Salt States¶

Once the rules in an SLS are ready, they should be tested to ensure they work properly. To invoke these rules, simply execute salt '*' state.apply on the command line. If you get back only hostnames with a : after, but no return, chances are there is a problem with one or more of the sls files. On the minion, use the salt-call command to examine the output for errors:
This should help troubleshoot the issue. The minion can also be started in the foreground in debug mode by running salt-minion -l debug.

Next Reading¶

With an understanding of states, the next recommendation is to become familiar with Salt's pillar interface:

States tutorial, part 1 - Basic Usage¶

The purpose of this tutorial is to demonstrate how quickly you can configure a system to be managed by Salt States. For detailed information about the state system please refer to the full states reference. This tutorial will walk you through using Salt to configure a minion to run the Apache HTTP server and to ensure the server is running. Before continuing make sure you have a working Salt installation by following the installation and the configuration instructions.

Setting up the Salt State Tree¶

States are stored in text files on the master and transferred to the minions on demand via the master's File Server. The collection of state files make up the State Tree. To start using a central state system in Salt, the Salt File Server must first be set up. Edit the master config file ( file_roots) and uncomment the following lines:
NOTE:
Restart the Salt master in order to pick up this change:

Preparing the Top File¶

On the master, in the directory uncommented in the previous step, ( /srv/salt by default), create a new file called top.sls and add the following:
The top file is separated into environments (discussed later). The default environment is base. Under the base environment a collection of minion matches is defined; for now simply specify all hosts ( *).

Create an sls file¶

In the same directory as the top file, create a file named webserver.sls, containing the following:
The first line, called the id-declaration, is an arbitrary identifier. In this case it defines the name of the package to be installed. NOTE:
The second line, called the state-declaration, defines which of the Salt States we are using. In this example, we are using the pkg state to ensure that a given package is installed. The third line, called the function-declaration, defines which function in the pkg state module to call.

Install the package¶

Next, let's run the state we created. Open a terminal on the master and run:
Our master is instructing all targeted minions to run state.apply. When this function is executed without any SLS targets, a minion will download the top file and attempt to match the expressions within it. When the minion does match an expression the modules listed for it will be downloaded, compiled, and executed. NOTE:
Once completed, the minion will report back with a summary of all actions taken and all changes made. WARNING:

Next steps¶

This tutorial focused on getting a simple Salt States configuration working. Part 2 will build on this example to cover more advanced sls syntax and will explore more of the states that ship with Salt.

States tutorial, part 2 - More Complex States, Requisites¶

NOTE:
In the last part of the Salt States tutorial we covered the basics of installing a package. We will now modify our webserver.sls file to have requirements, and use even more Salt States.

Call multiple States¶

You can specify multiple state-declaration under an id-declaration. For example, a quick modification to our webserver.sls to also start Apache if it is not running:
Try stopping Apache before running state.apply once again and observe the output. NOTE:

Require other states¶

We now have a working installation of Apache so let's add an HTML file to customize our website. It isn't exactly useful to have a website without a webserver so we don't want Salt to install our HTML file until Apache is installed and running. Include the following at the bottom of your webserver/init.sls file:
line 7 is the id-declaration. In this example it is the location we want to install our custom HTML file. ( Note: the default location that Apache serves may differ from the above on your OS or distro. /srv/www could also be a likely place to look.) Line 8 the state-declaration. This example uses the Salt file state. Line 9 is the function-declaration. The managed function will download a file from the master and install it in the location specified. Line 10 is a function-arg-declaration which, in this example, passes the source argument to the managed function. Line 11 is a requisite-declaration. Line 12 is a requisite-reference which refers to a state and an ID. In this example, it is referring to the ID declaration from our example in part 1. This declaration tells Salt not to install the HTML file until Apache is installed. Next, create the index.html file and save it in the webserver directory:
Last, call state.apply again and the minion will fetch and execute the highstate as well as our HTML file from the master using Salt's File Server:
Verify that Apache is now serving your custom HTML.

Next steps¶

In part 3 we will discuss how to use includes, extends, and templating to make a more complete State Tree configuration.

States tutorial, part 3 - Templating, Includes, Extends¶

NOTE:
This part of the tutorial will cover more advanced templating and configuration techniques for sls files.

Templating SLS modules¶

SLS modules may require programming logic or inline execution. This is accomplished with module templating. The default module templating system used is Jinja2 and may be configured by changing the renderer value in the master config. All states are passed through a templating system when they are initially read. To make use of the templating system, simply add some templating markup. An example of an sls module with templating markup may look like this:
This templated sls file once generated will look like this:
Here's a more complex example:

Using Grains in SLS modules¶

Often times a state will need to behave differently on different systems. Salt grains objects are made available in the template context. The grains can be used from within sls modules:

Using Environment Variables in SLS modules¶

You can use salt['environ.get']('VARNAME') to use an environment variable in a Salt state.

Error checking:

Calling Salt modules from templates¶

All of the Salt modules loaded by the minion are available within the templating system. This allows data to be gathered in real time on the target system. It also allows for shell commands to be run easily from within the sls modules. The Salt module functions are also made available in the template context as salt: The following example illustrates calling the group_to_gid function in the file execution module with a single positional argument called some_group_that_exists.
One way to think about this might be that the gid key is being assigned a value equivelent to the following python pseudo-code:
Note that for the above example to work, some_group_that_exists must exist before the state file is processed by the templating engine. Below is an example that uses the network.hw_addr function to retrieve the MAC address for eth0:
To examine the possible arguments to each execution module function, one can examine the module reference documentation </ref/modules/all>:

Advanced SLS module syntax¶

Lastly, we will cover some incredibly useful techniques for more complex State trees.

Include declaration¶

A previous example showed how to spread a Salt tree across several files. Similarly, requisites span multiple files by using an include-declaration. For example: python/python-libs.sls:
python/django.sls:

Extend declaration¶

You can modify previous declarations by using an extend-declaration. For example the following modifies the Apache tree to also restart Apache when the vhosts file is changed: apache/apache.sls:
apache/mywebsite.sls:

Name declaration¶

You can override the id-declaration by using a name-declaration. For example, the previous example is a bit more maintainable if rewritten as follows: apache/mywebsite.sls:

Names declaration¶

Even more powerful is using a names-declaration to override the id-declaration for multiple states at once. This often can remove the need for looping in a template. For example, the first example in this tutorial can be rewritten without the loop:

Next steps¶

In part 4 we will discuss how to use salt's file_roots to set up a workflow in which states can be "promoted" from dev, to QA, to production.

States tutorial, part 4¶

NOTE:
This part of the tutorial will show how to use salt's file_roots to set up a workflow in which states can be "promoted" from dev, to QA, to production.

Salt fileserver path inheritance¶

Salt's fileserver allows for more than one root directory per environment, like in the below example, which uses both a local directory and a secondary location shared to the salt master via NFS:
Salt's fileserver collapses the list of root directories into a single virtual environment containing all files from each root. If the same file exists at the same relative path in more than one root, then the top-most match "wins". For example, if /srv/salt/foo.txt and /mnt/salt-nfs/base/foo.txt both exist, then salt://foo.txt will point to /srv/salt/foo.txt. NOTE:

Environment configuration¶

Configure a multiple-environment setup like so:
Given the path inheritance described above, files within /srv/salt/prod would be available in all environments. Files within /srv/salt/qa would be available in both qa, and dev. Finally, the files within /srv/salt/dev would only be available within the dev environment. Based on the order in which the roots are defined, new files/states can be placed within /srv/salt/dev, and pushed out to the dev hosts for testing. Those files/states can then be moved to the same relative path within /srv/salt/qa, and they are now available only in the dev and qa environments, allowing them to be pushed to QA hosts and tested. Finally, if moved to the same relative path within /srv/salt/prod, the files are now available in all three environments.

Requesting files from specific fileserver environments¶

See here for documentation on how to request files from specific environments.

Practical Example¶

As an example, consider a simple website, installed to /var/www/foobarcom. Below is a top.sls that can be used to deploy the website: /srv/salt/prod/top.sls:
Using pillar, roles can be assigned to the hosts: /srv/pillar/top.sls:
/srv/pillar/webserver/prod.sls:
/srv/pillar/webserver/qa.sls:
/srv/pillar/webserver/dev.sls:
And finally, the SLS to deploy the website: /srv/salt/prod/webserver/foobarcom.sls:
Given the above SLS, the source for the website should initially be placed in /srv/salt/dev/webserver/src/foobarcom. First, let's deploy to dev. Given the configuration in the top file, this can be done using state.apply:
However, in the event that it is not desirable to apply all states configured in the top file (which could be likely in more complex setups), it is possible to apply just the states for the foobarcom website, by invoking state.apply with the desired SLS target as an argument:
Once the site has been tested in dev, then the files can be moved from /srv/salt/dev/webserver/src/foobarcom to /srv/salt/qa/webserver/src/foobarcom, and deployed using the following:
Finally, once the site has been tested in qa, then the files can be moved from /srv/salt/qa/webserver/src/foobarcom to /srv/salt/prod/webserver/src/foobarcom, and deployed using the following:
Thanks to Salt's fileserver inheritance, even though the files have been moved to within /srv/salt/prod, they are still available from the same salt:// URI in both the qa and dev environments.

Continue Learning¶

The best way to continue learning about Salt States is to read through the reference documentation and to look through examples of existing state trees. Many pre-configured state trees can be found on GitHub in the saltstack-formulas collection of repositories. If you have any questions, suggestions, or just want to chat with other people who are using Salt, we have a very active community and we'd love to hear from you. In addition, by continuing to the Orchestrate Runner docs, you can learn about the powerful orchestration of which Salt is capable.

State System Reference¶

Salt offers an interface to manage the configuration or "state" of the Salt minions. This interface is a fully capable mechanism used to enforce the state of systems from a central manager.

Mod Aggregate State Runtime Modifications¶

New in version 2014.7.0. The mod_aggregate system was added in the 2014.7.0 release of Salt and allows for runtime modification of the executing state data. Simply put, it allows for the data used by Salt's state system to be changed on the fly at runtime, kind of like a configuration management JIT compiler or a runtime import system. All in all, it makes Salt much more dynamic.

How it Works¶

The best example is the pkg state. One of the major requests in Salt has long been adding the ability to install all packages defined at the same time. The mod_aggregate system makes this a reality. While executing Salt's state system, when a pkg state is reached the mod_aggregate function in the state module is called. For pkg this function scans all of the other states that are slated to run, and picks up the references to name and pkgs, then adds them to pkgs in the first state. The result is a single call to yum, apt-get, pacman, etc as part of the first package install.

How to Use it¶

NOTE:

In config files¶

The first way to enable aggregation is with a configuration option in either the master or minion configuration files. Salt will invoke mod_aggregate the first time it encounters a state module that has aggregate support. If this option is set in the master config it will apply to all state runs on all minions, if set in the minion config it will only apply to said minion. Enable for all states:
Enable for only specific state modules:

In states¶

The second way to enable aggregation is with the state-level aggregate keyword. In this configuration, Salt will invoke the mod_aggregate function the first time it encounters this keyword. Any additional occurrences of the keyword will be ignored as the aggregation has already taken place. The following example will trigger mod_aggregate when the lamp_stack state is processed resulting in a single call to the underlying package manager.

Adding mod_aggregate to a State Module¶

Adding a mod_aggregate routine to an existing state module only requires adding an additional function to the state module called mod_aggregate. The mod_aggregate function just needs to accept three parameters and return the low data to use. Since mod_aggregate is working on the state runtime level it does need to manipulate low data. The three parameters are low, chunks, and running. The low option is the low data for the state execution which is about to be called. The chunks is the list of all of the low data dictionaries which are being executed by the runtime and the running dictionary is the return data from all of the state executions which have already be executed. This example, simplified from the pkg state, shows how to create mod_aggregate functions:

Altering States¶

NOTE:

File State Backups¶

In 0.10.2 a new feature was added for backing up files that are replaced by the file.managed and file.recurse states. The new feature is called the backup mode. Setting the backup mode is easy, but it can be set in a number of places. The backup_mode can be set in the minion config file:
Or it can be set for each file:

Backed-up Files¶

The files will be saved in the minion cachedir under the directory named file_backup. The files will be in the location relative to where they were under the root filesystem and be appended with a timestamp. This should make them easy to browse.

Interacting with Backups¶

Starting with version 0.17.0, it will be possible to list, restore, and delete previously-created backups.

Listing¶

The backups for a given file can be listed using file.list_backups:

Restoring¶

Restoring is easy using file.restore_backup, just pass the path and the numeric id found with file.list_backups:
The existing file will be backed up, just in case, as can be seen if file.list_backups is run again:
NOTE:

Deleting¶

Deleting backups can be done using file.delete_backup:

Understanding State Compiler Ordering¶

NOTE:
Salt's state system is built to deliver all of the power of configuration management systems without sacrificing simplicity. This tutorial is made to help users understand in detail just how the order is defined for state executions in Salt. This tutorial is written to represent the behavior of Salt as of version 0.17.0.

Compiler Basics¶

To understand ordering in depth some very basic knowledge about the state compiler is very helpful. No need to worry though, this is very high level!

High Data and Low Data¶

When defining Salt Formulas in YAML the data that is being represented is referred to by the compiler as High Data. When the data is initially loaded into the compiler it is a single large python dictionary, this dictionary can be viewed raw by running:
This "High Data" structure is then compiled down to "Low Data". The Low Data is what is matched up to create individual executions in Salt's configuration management system. The low data is an ordered list of single state calls to execute. Once the low data is compiled the evaluation order can be seen. The low data can be viewed by running:
NOTE:
As an example, a state written thusly:
Will have High Data which looks like this represented in json:
The subsequent Low Data will look like this:
This tutorial discusses the Low Data evaluation and the state runtime.

Ordering Layers¶

Salt defines 2 order interfaces which are evaluated in the state runtime and defines these orders in a number of passes.

Definition Order¶

NOTE:
The top level of ordering is the Definition Order. The Definition Order is the order in which states are defined in salt formulas. This is very straightforward on basic states which do not contain include statements or a top file, as the states are just ordered from the top of the file, but the include system starts to bring in some simple rules for how the Definition Order is defined. Looking back at the "Low Data" and "High Data" shown above, the order key has been transparently added to the data to enable the Definition Order.

The Include Statement¶

Basically, if there is an include statement in a formula, then the formulas which are included will be run BEFORE the contents of the formula which is including them. Also, the include statement is a list, so they will be loaded in the order in which they are included. In the following case: foo.sls
bar.sls
baz.sls
In the above case if state.apply foo were called then the formulas will be loaded in the following order:

The order Flag¶

The Definition Order happens transparently in the background, but the ordering can be explicitly overridden using the order flag in states:
This order flag will over ride the definition order, this makes it very simple to create states that are always executed first, last or in specific stages, a great example is defining a number of package repositories that need to be set up before anything else, or final checks that need to be run at the end of a state run by using order: last or order: -1. When the order flag is explicitly set the Definition Order system will omit setting an order for that state and directly use the order flag defined.

Lexicographical Fall-back¶

Salt states were written to ALWAYS execute in the same order. Before the introduction of Definition Order in version 0.17.0 everything was ordered lexicographically according to the name of the state, then function then id. This is the way Salt has always ensured that states always run in the same order regardless of where they are deployed, the addition of the Definition Order method mealy makes this finite ordering easier to follow. The lexicographical ordering is still applied but it only has any effect when two order statements collide. This means that if multiple states are assigned the same order number that they will fall back to lexicographical ordering to ensure that every execution still happens in a finite order. NOTE:

Requisite Ordering¶

Salt states are fully declarative, in that they are written to declare the state in which a system should be. This means that components can require that other components have been set up successfully. Unlike the other ordering systems, the Requisite system in Salt is evaluated at runtime. The requisite system is also built to ensure that the ordering of execution never changes, but is always the same for a given set of states. This is accomplished by using a runtime that processes states in a completely predictable order instead of using an event loop based system like other declarative configuration management systems.

Runtime Requisite Evaluation¶

The requisite system is evaluated as the components are found, and the requisites are always evaluated in the same order. This explanation will be followed by an example, as the raw explanation may be a little dizzying at first as it creates a linear dependency evaluation sequence. The "Low Data" is an ordered list or dictionaries, the state runtime evaluates each dictionary in the order in which they are arranged in the list. When evaluating a single dictionary it is checked for requisites, requisites are evaluated in order, require then watch then prereq. NOTE:
Each requisite contains an ordered list of requisites, these requisites are looked up in the list of dictionaries and then executed. Once all requisites have been evaluated and executed then the requiring state can safely be run (or not run if requisites have not been met). This means that the requisites are always evaluated in the same order, again ensuring one of the core design principals of Salt's State system to ensure that execution is always finite is intact.

Simple Runtime Evaluation Example¶

Given the above "Low Data" the states will be evaluated in the following order:

Best Practice¶

The best practice in Salt is to choose a method and stick with it, official states are written using requisites for all associations since requisites create clean, traceable dependency trails and make for the most portable formulas. To accomplish something similar to how classical imperative systems function all requisites can be omitted and the failhard option then set to True in the master configuration, this will stop all state runs at the first instance of a failure. In the end, using requisites creates very tight and fine grained states, not using requisites makes full sequence runs and while slightly easier to write, and gives much less control over the executions.

Extending External SLS Data¶

Sometimes a state defined in one SLS file will need to be modified from a separate SLS file. A good example of this is when an argument needs to be overwritten or when a service needs to watch an additional state.

The Extend Declaration¶

The standard way to extend is via the extend declaration. The extend declaration is a top level declaration like include and encapsulates ID declaration data included from other SLS files. A standard extend looks like this:
A few critical things happened here, first off the SLS files that are going to be extended are included, then the extend dec is defined. Under the extend dec 2 IDs are extended, the apache ID's file state is overwritten with a new name and source. Then the ssh server is extended to watch the banner file in addition to anything it is already watching.

Extend is a Top Level Declaration¶

This means that extend can only be called once in an sls, if if is used twice then only one of the extend blocks will be read. So this is WRONG:

The Requisite in Statement¶

Since one of the most common things to do when extending another SLS is to add states for a service to watch, or anything for a watcher to watch, the requisite in statement was added to 0.9.8 to make extending the watch and require lists easier. The ssh-server extend statement above could be more cleanly defined like so:

Rules to Extend By¶

There are a few rules to remember when extending states:

Failhard Global Option¶

Normally, when a state fails Salt continues to execute the remainder of the defined states and will only refuse to execute states that require the failed state. But the situation may exist, where you would want all state execution to stop if a single state execution fails. The capability to do this is called failing hard.

State Level Failhard¶

A single state can have a failhard set, this means that if this individual state fails that all state execution will immediately stop. This is a great thing to do if there is a state that sets up a critical config file and setting a require for each state that reads the config would be cumbersome. A good example of this would be setting up a package manager early on:
In this situation, the yum repo is going to be configured before other states, and if it fails to lay down the config file, than no other states will be executed.

Global Failhard¶

It may be desired to have failhard be applied to every state that is executed, if this is the case, then failhard can be set in the master configuration file. Setting failhard in the master configuration file will result in failing hard when any minion gathering states from the master have a state fail. This is NOT the default behavior, normally Salt will only fail states that require a failed state. Using the global failhard is generally not recommended, since it can result in states not being executed or even checked. It can also be confusing to see states failhard if an admin is not actively aware that the failhard has been set. To use the global failhard set failhard: True in the master configuration file.

Global State Arguments¶

NOTE:

Highstate data structure definitions¶

The Salt State Tree¶

A state tree is a collection of SLS files and directories that live under the directory specified in file_roots. NOTE:

Top file¶

The main state file that instructs minions what environment and modules to use during state execution. Configurable via state_top. SEE ALSO:

Include declaration¶

Defines a list of Module reference strings to include in this SLS. Occurs only in the top level of the SLS data structure. Example:

Module reference¶

The name of a SLS module defined by a separate SLS file and residing on the Salt Master. A module named edit.vim is a reference to the SLS file salt://edit/vim.sls.

ID declaration¶

Defines an individual highstate component. Always references a value of a dictionary containing keys referencing State declaration and Requisite declaration. Can be overridden by a Name declaration or a Names declaration. Occurs on the top level or under the Extend declaration. Must be unique across entire state tree. If the same ID declaration is used twice, only the first one matched will be used. All subsequent ID declarations with the same name will be ignored. NOTE:

Extend declaration¶

Extends a Name declaration from an included SLS module. The keys of the extend declaration always refer to an existing ID declaration which have been defined in included SLS modules. Occurs only in the top level and defines a dictionary. States cannot be extended more than once in a single state run. Extend declarations are useful for adding-to or overriding parts of a State declaration that is defined in another SLS file. In the following contrived example, the shown mywebsite.sls file is include -ing and extend -ing the apache.sls module in order to add a watch declaration that will restart Apache whenever the Apache configuration file, mywebsite changes.
SEE ALSO:

State declaration¶

A list which contains one string defining the Function declaration and any number of Function arg declaration dictionaries. Can, optionally, contain a number of additional components like the name override components — name and names. Can also contain requisite declarations. Occurs under an ID declaration.

Requisite declaration¶

A list containing requisite references. Used to build the action dependency tree. While Salt states are made to execute in a deterministic order, this order is managed by requiring and watching other Salt states. Occurs as a list component under a State declaration or as a key under an ID declaration.

Requisite reference¶

A single key dictionary. The key is the name of the referenced State declaration and the value is the ID of the referenced ID declaration. Occurs as a single index in a Requisite declaration list.

Function declaration¶

The name of the function to call within the state. A state declaration can contain only a single function declaration. For example, the following state declaration calls the installed function in the pkg state module:
The function can be declared inline with the state as a shortcut. The actual data structure is compiled to this form:
Where the function is a string in the body of the state declaration. Technically when the function is declared in dot notation the compiler converts it to be a string in the state declaration list. Note that the use of the first example more than once in an ID declaration is invalid yaml. INVALID:
When passing a function without arguments and another state declaration within a single ID declaration, then the long or "standard" format needs to be used since otherwise it does not represent a valid data structure. VALID:
Occurs as the only index in the State declaration list.

Function arg declaration¶

A single key dictionary referencing a Python type which is to be passed to the named Function declaration as a parameter. The type must be the data type expected by the function. Occurs under a Function declaration. For example in the following state declaration user, group, and mode are passed as arguments to the managed function in the file state module:

Name declaration¶

Overrides the name argument of a State declaration. If name is not specified the ID declaration satisfies the name argument. The name is always a single key dictionary referencing a string. Overriding name is useful for a variety of scenarios. For example, avoiding clashing ID declarations. The following two state declarations cannot both have /etc/motd as the ID declaration:
Another common reason to override name is if the ID declaration is long and needs to be referenced in multiple places. In the example below it is much easier to specify mywebsite than to specify /etc/apache2/sites-available/mywebsite.com multiple times:

Names declaration¶

Expands the contents of the containing State declaration into multiple state declarations, each with its own name. For example, given the following state declaration:
Once converted into the lowstate data structure the above state declaration will be expanded into the following three state declarations:
Other values can be overridden during the expansion by providing an additional dictionary level. New in version 2014.7.0.

Large example¶

Here is the layout in yaml using the names of the highdata structure components.

Include and Exclude¶

Salt SLS files can include other SLS files and exclude SLS files that have been otherwise included. This allows for an SLS file to easily extend or manipulate other SLS files.

Include¶

When other SLS files are included, everything defined in the included SLS file will be added to the state run. When including define a list of SLS formulas to include:
The include statement will include SLS formulas from the same environment that the including SLS formula is in. But the environment can be explicitly defined in the configuration to override the running environment, therefore if an SLS formula needs to be included from an external environment named "dev" the following syntax is used:
NOTE: include does not simply inject the states where you place it in the SLS file. If you need to guarantee order of execution, consider using requisites.

Relative Include¶

In Salt 0.16.0, the capability to include SLS formulas which are relative to the running SLS formula was added. Simply precede the formula name with a .:
In Salt 2015.8, the ability to include SLS formulas which are relative to the parents of the running SLS formula was added. In order to achieve this, precede the formula name with more than one . (dot). Much like Python's relative import abilities, two or more leading dots represent a relative include of the parent or parents of the current package, with each . representing one level after the first. The following SLS configuration, if placed within example.dev.virtual, would result in example.http and base being included respectively:

Exclude¶

The exclude statement, added in Salt 0.10.3, allows an SLS to hard exclude another SLS file or a specific id. The component is excluded after the high data has been compiled, so nothing should be able to override an exclude. Since the exclude can remove an id or an sls the type of component to exclude needs to be defined. An exclude statement that verifies that the running highstate does not contain the http sls and the /etc/vimrc id would look like this:
NOTE:

State System Layers¶

The Salt state system is comprised of multiple layers. While using Salt does not require an understanding of the state layers, a deeper understanding of how Salt compiles and manages states can be very beneficial.

Function Call¶

The lowest layer of functionality in the state system is the direct state function call. State executions are executions of single state functions at the core. These individual functions are defined in state modules and can be called directly via the state.single command.

Low Chunk¶

The low chunk is the bottom of the Salt state compiler. This is a data representation of a single function call. The low chunk is sent to the state caller and used to execute a single state function. A single low chunk can be executed manually via the state.low command.
The passed data reflects what the state execution system gets after compiling the data down from sls formulas.

Low State¶

The Low State layer is the list of low chunks "evaluated" in order. To see what the low state looks like for a highstate, run:
This will display the raw lowstate in the order which each low chunk will be evaluated. The order of evaluation is not necessarily the order of execution, since requisites are evaluated at runtime. Requisite execution and evaluation is finite; this means that the order of execution can be ascertained with 100% certainty based on the order of the low state.

High Data¶

High data is the data structure represented in YAML via SLS files. The High data structure is created by merging the data components rendered inside sls files (or other render systems). The High data can be easily viewed by executing the state.show_highstate or state.show_sls functions. Since this data is a somewhat complex data structure, it may be easier to read using the json, yaml, or pprint outputters:

SLS¶

Above "High Data", the logical layers are no longer technically required to be executed, or to be executed in a hierarchy. This means that how the High data is generated is optional and very flexible. The SLS layer allows for many mechanisms to be used to render sls data from files or to use the fileserver backend to generate sls and file data from external systems. The SLS layer can be called directly to execute individual sls formulas. NOTE:
To call a single SLS formula named edit.vim, execute state.apply and pass edit.vim as an argument:

HighState¶

Calling SLS directly logically assigns what states should be executed from the context of the calling minion. The Highstate layer is used to allow for full contextual assignment of what is executed where to be tied to groups of, or individual, minions entirely from the master. This means that the environment of a minion, and all associated execution data pertinent to said minion, can be assigned from the master without needing to execute or configure anything on the target minion. This also means that the minion can independently retrieve information about its complete configuration from the master. To execute the highstate use state.apply:

Orchestrate¶

The orchestrate layer expresses the highest functional layer of Salt's automated logic systems. The Overstate allows for stateful and functional orchestration of routines from the master. The orchestrate defines in data execution stages which minions should execute states, or functions, and in what order using requisite logic.

The Orchestrate Runner¶

NOTE:

Ordering States¶

The way in which configuration management systems are executed is a hotly debated topic in the configuration management world. Two major philosophies exist on the subject, to either execute in an imperative fashion where things are executed in the order in which they are defined, or in a declarative fashion where dependencies need to be mapped between objects. Imperative ordering is finite and generally considered easier to write, but declarative ordering is much more powerful and flexible but generally considered more difficult to create. Salt has been created to get the best of both worlds. States are evaluated in a finite order, which guarantees that states are always executed in the same order, and the states runtime is declarative, making Salt fully aware of dependencies via the requisite system.

State Auto Ordering¶

Salt always executes states in a finite manner, meaning that they will always execute in the same order regardless of the system that is executing them. But in Salt 0.17.0, the state_auto_order option was added. This option makes states get evaluated in the order in which they are defined in sls files, including the top.sls file. The evaluation order makes it easy to know what order the states will be executed in, but it is important to note that the requisite system will override the ordering defined in the files, and the order option described below will also override the order in which states are defined in sls files. If the classic ordering is preferred (lexicographic), then set state_auto_order to False in the master configuration file. Otherwise, state_auto_order defaults to True.

Requisite Statements¶

NOTE:
Often when setting up states any single action will require or depend on another action. Salt allows for the building of relationships between states with requisite statements. A requisite statement ensures that the named state is evaluated before the state requiring it. There are three types of requisite statements in Salt, require, watch, and prereq. These requisite statements are applied to a specific state declaration:
In this example, the require requisite is used to declare that the file /etc/httpd/conf/httpd.conf should only be set up if the pkg state executes successfully. The requisite system works by finding the states that are required and executing them before the state that requires them. Then the required states can be evaluated to see if they have executed correctly. Require statements can refer to any state defined in Salt. The basic examples are pkg, service, and file, but any used state can be referenced. In addition to state declarations such as pkg, file, etc., sls type requisites are also recognized, and essentially allow 'chaining' of states. This provides a mechanism to ensure the proper sequence for complex state formulas, especially when the discrete states are split or groups into separate sls files:
In this example, the httpd service running state will not be applied (i.e., the httpd service will not be started) unless both the httpd package is installed AND the network state is satisfied. NOTE:

Multiple Requisites¶

The requisite statement is passed as a list, allowing for the easy addition of more requisites. Both requisite types can also be separately declared:
In this example, the httpd service is only going to be started if the package, user, group, and file are executed successfully.

Requisite Documentation¶

For detailed information on each of the individual requisites, please look here.

The Order Option¶

Before using the order option, remember that the majority of state ordering should be done with a requisite-declaration, and that a requisite declaration will override an order option, so a state with order option should not require or required by other states. The order option is used by adding an order number to a state declaration with the option order:
By adding the order option to 1 this ensures that the vim package will be installed in tandem with any other state declaration set to the order 1. Any state declared without an order option will be executed after all states with order options are executed. But this construct can only handle ordering states from the beginning. Certain circumstances will present a situation where it is desirable to send a state to the end of the line. To do this, set the order to last:

State Providers¶

New in version 0.9.8. Salt predetermines what modules should be mapped to what uses based on the properties of a system. These determinations are generally made for modules that provide things like package and service management. Sometimes in states, it may be necessary to use an alternative module to provide the needed functionality. For instance, an very old Arch Linux system may not be running systemd, so instead of using the systemd service module, you can revert to the default service module:
In this instance, the basic service module (which manages sysvinit-based services) will replace the systemd module which is used by default on Arch Linux. This change only affects this one state though. If it is necessary to make this override for most or every service, it is better to just override the provider in the minion config file, as described here. Also, keep in mind that this only works for states with an identically-named virtual module ( pkg, service, etc.).

Arbitrary Module Redirects¶

The provider statement can also be used for more powerful means, instead of overwriting or extending the module used for the named service an arbitrary module can be used to provide certain functionality.
In this example, the state is being instructed to use a custom module to invoke commands. Arbitrary module redirects can be used to dramatically change the behavior of a given state.

Requisites and Other Global State Arguments¶

Requisites¶

The Salt requisite system is used to create relationships between states. The core idea being that, when one state is dependent somehow on another, that inter-dependency can be easily defined. These dependencies are expressed by declaring the relationships using state names and ID's or names. The generalized form of a requisite target is <state name> : <ID or name>. The specific form is defined as a Requisite Reference Requisites come in two types: Direct requisites (such as require), and requisite_ins (such as require_in). The relationships are directional: a direct requisite requires something from another state. However, a requisite_in inserts a requisite into the targeted state pointing to the targeting state. The following example demonstrates a direct requisite:
In the example above, the file /etc/vimrc depends on the vim package. Requisite_in statements are the opposite. Instead of saying "I depend on something", requisite_ins say "Someone depends on me":
So here, with a requisite_in, the same thing is accomplished as in the first example, but the other way around. The vim package is saying "/etc/vimrc depends on me". This will result in a require being inserted into the /etc/vimrc state which targets the vim state. In the end, a single dependency map is created and everything is executed in a finite and predictable order.

Requisite matching¶

Requisites need two pieces of information for matching: The state module name – e.g. pkg –, and the identifier – e.g. vim –, which can be either the ID (the first line in the stanza) or the - name parameter.

Omitting state module in requisites¶

New in version 2016.3.0. In version 2016.3.0, the state module name was made optional. If the state module is omitted, all states matching the ID will be required, regardless of which module they are using.

State target matching¶

In order to understand how state targets are matched, it is helpful to know how the state compiler is working. Consider the following example:
The first formula is converted to a dictionary which looks as follows (represented as YAML, some properties omitted for simplicity) as High Data:
The file.managed format used in the formula is essentially syntactic sugar: at the end, the target is file, which is used in the Extract server package state above.

Identifier matching¶

Requisites match on both the ID Declaration and the name parameter. This means that, in the "Deploy server package" example above, a require requisite would match with with Deploy server package or /usr/local/share/myapp.tar.xz, so either of the following versions for "Extract server package" works:

Direct Requisite and Requisite_in types¶

There are several direct requisite statements that can be used in Salt:
Each direct requisite also has a corresponding requisite_in:
All of the requisites define specific relationships and always work with the dependency logic defined above.

require¶

The use of require demands that the required state executes before the dependent state. The state containing the require requisite is defined as the dependent state. The state specified in the require statement is defined as the required state. If the required state's execution succeeds, the dependent state will then execute. If the required state's execution fails, the dependent state will not execute. In the first example above, the file /etc/vimrc will only execute after the vim package is installed successfully.

Require an Entire SLS File¶

As of Salt 0.16.0, it is possible to require an entire sls file. Do this first by including the sls file and then setting a state to require the included sls file:
This will add all of the state declarations found in the given sls file. This means that every state in sls foo will be required. This makes it very easy to batch large groups of states easily in any requisite statement.

watch¶

watch statements are used to add additional behavior when there are changes in other states. NOTE:
The state containing the watch requisite is defined as the watching state. The state specified in the watch statement is defined as the watched state. When the watched state executes, it will return a dictionary containing a key named "changes". Here are two examples of state return dictionaries, shown in json for clarity:
If the "result" of the watched state is True, the watching state will execute normally, and if it is False, the watching state will never run. This part of watch mirrors the functionality of the require requisite. If the "result" of the watched state is True and the "changes" key contains a populated dictionary (changes occurred in the watched state), then the watch requisite can add additional behavior. This additional behavior is defined by the mod_watch function within the watching state module. If the mod_watch function exists in the watching state module, it will be called in addition to the normal watching state. The return data from the mod_watch function is what will be returned to the master in this case; the return data from the main watching function is discarded. If the "changes" key contains an empty dictionary, the watch requisite acts exactly like the require requisite (the watching state will execute if "result" is True, and fail if "result" is False in the watched state). NOTE:
A good example of using watch is with a service.running state. When a service watches a state, then the service is reloaded/restarted when the watched state changes, in addition to Salt ensuring that the service is running.

prereq¶

New in version 0.16.0. prereq allows for actions to be taken based on the expected results of a state that has not yet been executed. The state containing the prereq requisite is defined as the pre-requiring state. The state specified in the prereq statement is defined as the pre-required state. When a prereq requisite is evaluated, the pre-required state reports if it expects to have any changes. It does this by running the pre-required single state as a test-run by enabling test=True. This test-run will return a dictionary containing a key named "changes". (See the watch section above for examples of "changes" dictionaries.) If the "changes" key contains a populated dictionary, it means that the pre-required state expects changes to occur when the state is actually executed, as opposed to the test-run. The pre-requiring state will now actually run. If the pre-requiring state executes successfully, the pre-required state will then execute. If the pre-requiring state fails, the pre-required state will not execute. If the "changes" key contains an empty dictionary, this means that changes are not expected by the pre-required state. Neither the pre-required state nor the pre-requiring state will run. The best way to define how prereq operates is displayed in the following practical example: When a service should be shut down because underlying code is going to change, the service should be off-line while the update occurs. In this example, graceful-down is the pre-requiring state and site-code is the pre-required state.
In this case the apache server will only be shutdown if the site-code state expects to deploy fresh code via the file.recurse call. The site-code deployment will only be executed if the graceful-down run completes successfully.

onfail¶

New in version 2014.7.0. The onfail requisite allows for reactions to happen strictly as a response to the failure of another state. This can be used in a number of ways, such as executing a second attempt to set up a service or begin to execute a separate thread of states because of a failure. The onfail requisite is applied in the same way as require as watch:
NOTE:

onchanges¶

New in version 2014.7.0. The onchanges requisite makes a state only apply if the required states generate changes, and if the watched state's "result" is True. This can be a useful way to execute a post hook after changing aspects of a system. If a state has multiple onchanges requisites then the state will trigger if any of the watched states changes. NOTE:

use¶

The use requisite is used to inherit the arguments passed in another id declaration. This is useful when many files need to have the same defaults.
The use statement was developed primarily for the networking states but can be used on any states in Salt. This makes sense for the networking state because it can define a long list of options that need to be applied to multiple network interfaces. The use statement does not inherit the requisites arguments of the targeted state. This means also a chain of use requisites would not inherit inherited options.

The _in versions of requisites¶

All of the requisites also have corresponding requisite_in versions, which do the reverse of their normal counterparts. The examples below all use require_in as the example, but note that all of the _in requisites work the same way: They result in a normal requisite in the targeted state, which targets the state which has defines the requisite_in. Thus, a require_in causes the target state to require the targeting state. Similarly, a watch_in causes the target state to watch the targeting state. This pattern continues for the rest of the requisites. If a state declaration needs to be required by another state declaration then require_in can accommodate it. Therefore, these two sls files would be the same in the end: Using require
Using require_in
The require_in statement is particularly useful when assigning a require in a separate sls file. For instance it may be common for httpd to require components used to set up PHP or mod_python, but the HTTP state does not need to be aware of the additional components that require it when it is set up: http.sls
php.sls
mod_python.sls
Now the httpd server will only start if php or mod_python are first verified to be installed. Thus allowing for a requisite to be defined "after the fact".

Fire Event Notifications¶

New in version 2015.8.0. The fire_event option in a state will cause the minion to send an event to the Salt Master upon completion of that individual state. The following example will cause the minion to send an event to the Salt Master with a tag of salt/state_result/20150505121517276431/dasalt/nano and the result of the state will be the data field of the event. Notice that the name of the state gets added to the tag.
In the following example instead of setting fire_event to True, fire_event is set to an arbitrary string, which will cause the event to be sent with this tag: salt/state_result/20150505121725642845/dasalt/custom/tag/nano/finished

Altering States¶

The state altering system is used to make sure that states are evaluated exactly as the user expects. It can be used to double check that a state preformed exactly how it was expected to, or to make 100% sure that a state only runs under certain conditions. The use of unless or onlyif options help make states even more stateful. The check_cmd option helps ensure that the result of a state is evaluated correctly.

Reload¶

reload_modules is a boolean option that forces salt to reload its modules after a state finishes. reload_pillar and reload_grains can also be set. See Reloading Modules.

Unless¶

New in version 2014.7.0. The unless requisite specifies that a state should only run when any of the specified commands return False. The unless requisite operates as NAND and is useful in giving more granular control over when a state should execute. NOTE: Under the hood unless calls cmd.retcode with python_shell=True. This means the commands referenced by unless will be parsed by a shell, so beware of side-effects as this shell will be run with the same privileges as the salt-minion. Also be aware that the boolean value is determined by the shell's concept of True and False, rather than Python's concept of True and False.
In the example above, the state will only run if either the vim-enhanced package is not installed (returns False) or if /usr/bin/vim does not exist (returns False). The state will run if both commands return False. However, the state will not run if both commands return True. Unless checks are resolved for each name to which they are associated. For example:
In the above case, some_check will be run prior to _each_ name -- once for first_deploy_cmd and a second time for second_deploy_cmd.

Onlyif¶

New in version 2014.7.0. The onlyif requisite specifies that if each command listed in onlyif returns True, then the state is run. If any of the specified commands return False, the state will not run. NOTE: Under the hood onlyif calls cmd.retcode with python_shell=True. This means the commands referenced by onlyif will be parsed by a shell, so beware of side-effects as this shell will be run with the same privileges as the salt-minion. Also be aware that the boolean value is determined by the shell's concept of True and False, rather than Python's concept of True and False.
The above example ensures that the stop_volume and delete modules only run if the gluster commands return a 0 ret value.

Listen/Listen_in¶

New in version 2014.7.0. listen and its counterpart listen_in trigger mod_wait functions for states, when those states succeed and result in changes, similar to how watch its counterpart watch_in. Unlike watch and watch_in, listen, and listen_in will not modify the order of states and can be used to ensure your states are executed in the order they are defined. All listen/listen_in actions will occur at the end of a state run, after all states have completed.
This example will cause apache2 to be restarted when the apache2.conf file is changed, but the apache2 restart will happen at the end of the state run.
This example does the same as the above example, but puts the state argument on the file resource, rather than the service resource.

check_cmd¶

New in version 2014.7.0. Check Command is used for determining that a state did or did not run as expected. NOTE: Under the hood check_cmd calls cmd.retcode with python_shell=True. This means the commands referenced by unless will be parsed by a shell, so beware of side-effects as this shell will be run with the same privileges as the salt-minion.
This will attempt to do a replace on all enabled=0 in the .repo file, and replace them with enabled=1. The check_cmd is just a bash command. It will do a grep for enabled=0 in the file, and if it finds any, it will return a 0, which will be inverted by the leading !, causing check_cmd to set the state as failed. If it returns a 1, meaning it didn't find any enabled=0, it will be inverted by the leading !, returning a 0, and declaring the function succeeded. NOTE: This requisite check_cmd functions differently than the check_cmd of the file.managed state.

Overriding Checks¶

There are two commands used for the above checks. mod_run_check is used to check for onlyif and unless. If the goal is to override the global check for these to variables, include a mod_run_check in the salt/states/ file. mod_run_check_cmd is used to check for the check_cmd options. To override this one, include a mod_run_check_cmd in the states file for the state.

Startup States¶

Sometimes it may be desired that the salt minion execute a state run when it is started. This alleviates the need for the master to initiate a state run on a new minion and can make provisioning much easier. As of Salt 0.10.3 the minion config reads options that allow for states to be executed at startup. The options are startup_states, sls_list, and top_file. The startup_states option can be passed one of a number of arguments to define how to execute states. The available options are:

Examples:¶

Execute state.apply to run the highstate when starting the minion:
Execute the sls files edit.vim and hyper:

State Testing¶

Executing a Salt state run can potentially change many aspects of a system and it may be desirable to first see what a state run is going to change before applying the run. Salt has a test interface to report on exactly what will be changed, this interface can be invoked on any of the major state run functions:
The test run is mandated by adding the test=True option to the states. The return information will show states that will be applied in yellow and the result is reported as None.

Default Test¶

If the value test is set to True in the minion configuration file then states will default to being executed in test mode. If this value is set then states can still be run by calling test=False:

The Top File¶

Introduction¶

Most infrastructures are made up of groups of machines, each machine in the group performing a role similar to others. Those groups of machines work in concert with each other to create an application stack. To effectively manage those groups of machines, an administrator needs to be able to create roles for those groups. For example, a group of machines that serve front-end web traffic might have roles which indicate that those machines should all have the Apache webserver package installed and that the Apache service should always be running. In Salt, the file which contains a mapping between groups of machines on a network and the configuration roles that should be applied to them is called a top file. Top files are named top.sls by default and they are so-named because they always exist in the "top" of a directory hierarchy that contains state files. That directory hierarchy is called a state tree.

A Basic Example¶

Top files have three components:
The relationship between these three components is nested as follows:
Putting these concepts together, we can describe a scenario in which all minions with an ID that begins with web have an apache state applied to them:

Environments¶

Environments are directory hierarchies which contain a top files and a set of state files. Environments can be used in many ways, however there is no requirement that they be used at all. In fact, the most common way to deploy Salt is with a single environment, called base. It is recommended that users only create multiple environments if they have a use case which specifically calls for multiple versions of state trees.

Getting Started with Top Files¶

Each environment is defined inside a salt master configuration variable called, file_roots . In the most common single-environment setup, only the base environment is defined in file_roots along with only one directory path for the state tree.
In the above example, the top file will only have a single environment to pull from. Next is a simple single-environment top file placed in /srv/salt/top.sls, illustrating that for the environment called base, all minions will have the state files named core.sls and edit.sls applied to them.
Assuming the file_roots configuration from above, Salt will look in the /srv/salt directory for core.sls and edit.sls.

Multiple Environments¶

In some cases, teams may wish to create versioned state trees which can be used to test Salt configurations in isolated sets of systems such as a staging environment before deploying states into production. For this case, multiple environments can be used to accomplish this task. To create multiple environments, the file_roots option can be expanded:
In the above, we declare three environments: dev, qa and prod. Each environment has a single directory assigned to it. Our top file references the environments:
As seen above, the top file now declares the three environments and for each, targets are defined to map globs of minion IDs to state files. For example, all minions which have an ID beginning with the string webserver will have the webserver state from the requested environment assigned to it. In this manner, a proposed change to a state could first be made in a state file in /srv/salt/dev and then be applied to development webservers before moving the state into QA by copying the state file into /srv/salt/qa.

Choosing an Environment to Target¶

The top file is used to assign a minion to an environment unless overridden using the methods described below. The environment in the top file must match valid fileserver environment (a.k.a. saltenv) in order for any states to be applied to that minion. When using the default fileserver backend, environments are defined in file_roots. The states that will be applied to a minion in a given environment can be viewed using the state.show_top function. Minions may be pinned to a particular environment by setting the environment value in the minion configuration file. In doing so, a minion will only request files from the environment to which it is assigned. The environment may also be dynamically selected at runtime by passing it to the salt, salt-call or salt-ssh command. This is most commonly done with functions in the state module by using the saltenv argument. For example, to run a highstate on all minions, using only the top file and SLS files in the prod environment, run: salt '*' state.highstate saltenv=prod. NOTE:

Shorthand¶

If you assign only one SLS to a system, as in this example, a shorthand is also available:

Advanced Minion Targeting¶

In addition to globs, minions can be specified in top files a few other ways. Some common ones are compound matches and node groups. Below is a slightly more complex top file example, showing the different types of matches you can perform:

How Top Files Are Compiled¶

When a highstate is executed and an environment is specified (either using the environment config option or by passing the saltenv when executing the highstate), then that environment's top file is the only top file used to assign states to minions, and only states from the specified environment will be run. The remainder of this section applies to cases in which a highstate is executed without an environment specified. With no environment specified, the minion will look for a top file in each environment, and each top file will be processed to determine the SLS files to run on the minions. By default, the top files from each environment will be merged together. In configurations with many environments, such as with GitFS where each branch and tag is treated as a distinct environment, this may cause unexpected results as SLS files from older tags cause defunct SLS files to be included in the highstate. In cases like this, it can be helpful to set top_file_merging_strategy to same to force each environment to use its own top file.
Another option would be to set state_top_saltenv to a specific environment, to ensure that any top files in other environments are disregarded:
With GitFS, it can also be helpful to simply manage each environment's top file separately, and/or manually specify the environment when executing the highstate to avoid any complicated merging scenarios. gitfs_env_whitelist and gitfs_env_blacklist can also be used to hide unneeded branches and tags from GitFS to reduce the number of top files in play. When using multiple environments, it is not necessary to create a top file for each environment. The easiest-to-maintain approach is to use a single top file placed in the base environment. This is often infeasible with GitFS though, since branching/tagging can easily result in extra top files. However, when only the default ( roots) fileserver backend is used, a single top file in the base environment is the most common way of configuring a highstate. The following minion configuration options affect how top files are compiled when no environment is specified, it is recommended to follow the below four links to learn more about how these options work:

Top File Compilation Examples¶

For the scenarios below, assume the following configuration: /etc/salt/master:
/srv/salt/base/top.sls:
/srv/salt/dev/top.sls:
NOTE:

Scenario 1 - dev Environment Specified¶

In this scenario, the highstate was either invoked with saltenv=dev or the minion has environment: dev set in the minion config file. The result will be that only the dev2 SLS from the dev environment will be part of the highstate, and it will be applied to minion2, while minion1 will have no states applied to it. If the base environment were specified, the result would be that only the base1 SLS from the base environment would be part of the highstate, and it would be applied to all minions. If the qa environment were specified, the highstate would exit with an error.

Scenario 2 - No Environment Specified, top_file_merging_strategy is merge¶

In this scenario, assuming that the base environment's top file was evaluated first, the base1, dev1, and qa1 states would be applied to all minions. If, for instance, the qa environment is not defined in /srv/salt/base/top.sls, then because there is no top file for the qa environment, no states from the qa environment would be applied.

Scenario 3 - No Environment Specified, top_file_merging_strategy is same¶

Changed in version 2016.11.0: In prior versions, "same" did not quite work as described below (see here). This has now been corrected. It was decided that changing something like top file handling in a point release had the potential to unexpectedly impact users' top files too much, and it would be better to make this correction in a feature release. In this scenario, base1 from the base environment is applied to all minions. Additionally, dev2 from the dev environment is applied to minion2. If default_top is unset (or set to base, which happens to be the default), then qa1 from the qa environment will be applied to all minions. If default_top were set to dev, then both qa1 and qa2 from the qa environment would be applied to all minions.

Scenario 4 - No Environment Specified, top_file_merging_strategy is merge_all¶

New in version 2016.11.0. In this scenario, all configured states in all top files are applied. From the base environment, base1 would be applied to all minions, with base2 being applied only to minion1. From the dev environment, dev1 would be applied to all minions, with dev2 being applied only to minion2. Finally, from the qa environment, both the qa1 and qa2 states will be applied to all minions. Note that the qa1 states would not be applied twice, even though qa1 appears twice.

SLS Template Variable Reference¶

The template engines available to sls files and file templates come loaded with a number of context variables. These variables contain information and functions to assist in the generation of templates. See each variable below for its availability -- not all variables are available in all templating contexts.

Salt¶

The salt variable is available to abstract the salt library functions. This variable is a python dictionary containing all of the functions available to the running salt minion. It is available in all salt templates.

Opts¶

The opts variable abstracts the contents of the minion's configuration file directly to the template. The opts variable is a dictionary. It is available in all templates.
The config.get function also searches for values in the opts dictionary.

Pillar¶

The pillar dictionary can be referenced directly, and is available in all templates:
Using the pillar.get function via the salt variable is generally recommended since a default can be safely set in the event that the value is not available in pillar and dictionaries can be traversed directly:

Grains¶

The grains dictionary makes the minion's grains directly available, and is available in all templates:
The grains.get function can be used to traverse deeper grains and set defaults:

saltenv¶

The saltenv variable is available in only in sls files when gathering the sls from an environment.

sls¶

The sls variable contains the sls reference value, and is only available in the actual SLS file (not in any files referenced in that SLS). The sls reference value is the value used to include the sls in top files or via the include option.

slspath¶

The slspath variable contains the path to the current sls file. The value of slspath in files referenced in the current sls depends on the reference method. For jinja includes slspath is the path to the current file. For salt includes slspath is the path to the included file.

State Modules¶

State Modules are the components that map to actual enforcement and management of Salt states.

States are Easy to Write!¶

State Modules should be easy to write and straightforward. The information passed to the SLS data structures will map directly to the states modules. Mapping the information from the SLS data is simple, this example should illustrate:
Therefore this SLS data can be directly linked to a module, function, and arguments passed to that function. This does issue the burden, that function names, state names and function arguments should be very human readable inside state modules, since they directly define the user interface.

Using Custom State Modules¶

Place your custom state modules inside a _states directory within the file_roots specified by the master config file. These custom state modules can then be distributed in a number of ways. Custom state modules are distributed when state.apply is run, or by executing the saltutil.sync_states or saltutil.sync_all functions. Any custom states which have been synced to a minion, that are named the same as one of Salt's default set of states, will take the place of the default state with the same name. Note that a state's default name is its filename (i.e. foo.py becomes state foo), but that its name can be overridden by using a __virtual__ function.

Cross Calling Execution Modules from States¶

As with Execution Modules, State Modules can also make use of the __salt__ and __grains__ data. See cross calling execution modules. It is important to note that the real work of state management should not be done in the state module unless it is needed. A good example is the pkg state module. This module does not do any package management work, it just calls the pkg execution module. This makes the pkg state module completely generic, which is why there is only one pkg state module and many backend pkg execution modules. On the other hand some modules will require that the logic be placed in the state module, a good example of this is the file module. But in the vast majority of cases this is not the best approach, and writing specific execution modules to do the backend work will be the optimal solution.

Cross Calling State Modules¶

All of the Salt state modules are available to each other and state modules can call functions available in other state modules. The variable __states__ is packed into the modules after they are loaded into the Salt minion. The __states__ variable is a Python dictionary containing all of the state modules. Dictionary keys are strings representing the names of the modules and the values are the functions themselves. Salt state modules can be cross-called by accessing the value in the __states__ dict:
This code will call the managed function in the file state module and pass the arguments name and source to it.

Return Data¶

A State Module must return a dict containing the following keys/values:
The return data can also, include the pchanges key, this stands for predictive changes. The pchanges key informs the State system what changes are predicted to occur. NOTE:

Test State¶

All states should check for and support test being passed in the options. This will return data about what changes would occur if the state were actually run. An example of such a check could look like this:
Make sure to test and return before performing any real actions on the minion. NOTE:

Watcher Function¶

If the state being written should support the watch requisite then a watcher function needs to be declared. The watcher function is called whenever the watch requisite is invoked and should be generic to the behavior of the state itself. The watcher function should accept all of the options that the normal state functions accept (as they will be passed into the watcher function). A watcher function typically is used to execute state specific reactive behavior, for instance, the watcher for the service module restarts the named service and makes it useful for the watcher to make the service react to changes in the environment. The watcher function also needs to return the same data that a normal state function returns.

Mod_init Interface¶

Some states need to execute something only once to ensure that an environment has been set up, or certain conditions global to the state behavior can be predefined. This is the realm of the mod_init interface. A state module can have a function called mod_init which executes when the first state of this type is called. This interface was created primarily to improve the pkg state. When packages are installed the package metadata needs to be refreshed, but refreshing the package metadata every time a package is installed is wasteful. The mod_init function for the pkg state sets a flag down so that the first, and only the first, package installation attempt will refresh the package database (the package database can of course be manually called to refresh via the refresh option in the pkg state). The mod_init function must accept the Low State Data for the given executing state as an argument. The low state data is a dict and can be seen by executing the state.show_lowstate function. Then the mod_init function must return a bool. If the return value is True, then the mod_init function will not be executed again, meaning that the needed behavior has been set up. Otherwise, if the mod_init function returns False, then the function will be called the next time. A good example of the mod_init function is found in the pkg state module:
The mod_init function in the pkg state accepts the low state data as low and then checks to see if the function being called is going to install packages, if the function is not going to install packages then there is no need to refresh the package database. Therefore if the package database is prepared to refresh, then return True and the mod_init will not be called the next time a pkg state is evaluated, otherwise return False and the mod_init will be called next time a pkg state is evaluated.

Log Output¶

You can call the logger from custom modules to write messages to the minion logs. The following code snippet demonstrates writing log messages:

Strings and Unicode¶

A state module author should always assume that strings fed to the module have already decoded from strings into Unicode. In Python 2, these will be of type 'Unicode' and in Python 3 they will be of type str. Calling from a state to other Salt sub-systems, such as execution modules should pass Unicode (or bytes if passing binary data). In the rare event that a state needs to write directly to disk, Unicode should be encoded to a string immediately before writing to disk. An author may use __salt_system_encoding__ to learn what the encoding type of the system is. For example, 'my_string'.encode(__salt_system_encoding__').

Full State Module Example¶

The following is a simplistic example of a full state module and function. Remember to call out to execution modules to perform all the real work. The state module should only perform "before" and "after" checks.

Example state module¶

State Management¶

State management, also frequently called Software Configuration Management (SCM), is a program that puts and keeps a system into a predetermined state. It installs software packages, starts or restarts services or puts configuration files in place and watches them for changes. Having a state management system in place allows one to easily and reliably configure and manage a few servers or a few thousand servers. It allows configurations to be kept under version control. Salt States is an extension of the Salt Modules that we discussed in the previous remote execution tutorial. Instead of calling one-off executions the state of a system can be easily defined and then enforced.

Understanding the Salt State System Components¶

The Salt state system is comprised of a number of components. As a user, an understanding of the SLS and renderer systems are needed. But as a developer, an understanding of Salt states and how to write the states is needed as well. NOTE:

Salt SLS System¶

The primary system used by the Salt state system is the SLS system. SLS stands for SaLt State. The Salt States are files which contain the information about how to configure Salt minions. The states are laid out in a directory tree and can be written in many different formats. The contents of the files and they way they are laid out is intended to be as simple as possible while allowing for maximum flexibility. The files are laid out in states and contains information about how the minion needs to be configured.

SLS File Layout¶

SLS files are laid out in the Salt file server. A simple layout can look like this:
The top.sls file is a key component. The top.sls files is used to determine which SLS files should be applied to which minions. The rest of the files with the .sls extension in the above example are state files. Files without a .sls extensions are seen by the Salt master as files that can be downloaded to a Salt minion. States are translated into dot notation. For example, the ssh.sls file is seen as the ssh state and the users/admin.sls file is seen as the users.admin state. Files named init.sls are translated to be the state name of the parent directory, so the web/init.sls file translates to the web state. In Salt, everything is a file; there is no "magic translation" of files and file types. This means that a state file can be distributed to minions just like a plain text or binary file.

SLS Files¶

The Salt state files are simple sets of data. Since SLS files are just data they can be represented in a number of different ways. The default format is YAML generated from a Jinja template. This allows for the states files to have all the language constructs of Python and the simplicity of YAML. State files can then be complicated Jinja templates that translate down to YAML, or just plain and simple YAML files. The State files are simply common data structures such as dictionaries and lists, constructed using a templating language such as YAML. Here is an example of a Salt State:
This short stanza will ensure that vim is installed, Salt is installed and up to date, the salt-master and salt-minion daemons are running and the Salt minion configuration file is in place. It will also ensure everything is deployed in the right order and that the Salt services are restarted when the watched file updated.

The Top File¶

The top file controls the mapping between minions and the states which should be applied to them. The top file specifies which minions should have which SLS files applied and which environments they should draw those SLS files from. The top file works by specifying environments on the top-level. Each environment contains globs to match minions. Finally, each glob contains a list of lists of Salt states to apply to matching minions:
This above example uses the base environment which is built into the default Salt setup. The base environment has two globs. First, the '*' glob contains a list of SLS files to apply to all minions. The second glob contains a regular expression that will match all minions with an ID matching saltmaster.* and specifies that for those minions, the salt.master state should be applied.

Reloading Modules¶

Some Salt states require that specific packages be installed in order for the module to load. As an example the pip state module requires the pip package for proper name and version parsing. In most of the common cases, Salt is clever enough to transparently reload the modules. For example, if you install a package, Salt reloads modules because some other module or state might require just that package which was installed. On some edge-cases salt might need to be told to reload the modules. Consider the following state file which we'll call pep8.sls:
The above example installs pip using easy_install from setuptools and installs pep8 using pip, which, as told earlier, requires pip to be installed system-wide. Let's execute this state:
The execution output would be something like:
If we executed the state again the output would be:
Since we installed pip using cmd, Salt has no way to know that a system-wide package was installed. On the second execution, since the required pip package was installed, the state executed correctly. NOTE:
So how do we solve this edge-case? reload_modules! reload_modules is a boolean option recognized by salt on all available states which forces salt to reload its modules once a given state finishes. The modified state file would now be:
Let's run it, once:
The output is:

UTILITY MODULES - CODE REUSE IN CUSTOM MODULES¶

New in version 2015.5.0. Changed in version 2016.11.0: These can now be synced to the Master for use in custom Runners, and in custom execution modules called within Pillar SLS files. When extending Salt by writing custom (state modules), execution modules, etc., sometimes there is a need for a function to be available to more than just one kind of custom module. For these cases, Salt supports what are called "utility modules". These modules are like normal execution modules, but instead of being invoked in Salt code using __salt__, the __utils__ prefix is used instead. For example, assuming the following simple utility module, saved to salt://_utils/foo.py
Once synced to a minion, this function would be available to other custom Salt types like so:
Utility modules, like any other kind of Salt extension, support using a __virtual__ function to conditionally load them, or load them under a different namespace. For instance, if the utility module above were named salt://_utils/mymodule.py it could be made to be loaded as the foo utility module with a __virtual__ function.
These are, of course, contrived examples, but they should serve to show some of the possibilities opened up by writing utility modules. Keep in mind though that States still have access to all of the execution modules, so it is not necessary to write a utility module to make a function available to both a state and an execution module. One good use case for utililty modules is one where it is necessary to invoke the same function from a custom outputter/returner, as well as an execution module. Utility modules placed in salt://_utils/ will be synced to the minions when any of the following Salt functions are called:
To sync to the Master, use either of the following:

EVENTS & REACTOR¶

Event System¶

The Salt Event System is used to fire off events enabling third party applications or external processes to react to behavior within Salt. The event system is comprised of a two primary components:

Event types¶

Salt Master Events¶

These events are fired on the Salt Master event bus. This list is not comprehensive.

Authentication events¶

Start events¶

Key events¶

WARNING:

Job events¶

Runner Events¶

Presence Events¶

Cloud Events¶

Unlike other Master events, salt-cloud events are not fired on behalf of a Salt Minion. Instead, salt-cloud events are fired on behalf of a VM. This is because the minion-to-be may not yet exist to fire events to or also may have been destroyed. This behavior is reflected by the name variable in the event data for salt-cloud events as compared to the id variable for Salt Minion-triggered events.

Listening for Events¶

Salt's Event Bus is used heavily within Salt and it is also written to integrate heavily with existing tooling and scripts. There is a variety of ways to consume it.

From the CLI¶

The quickest way to watch the event bus is by calling the state.event runner:
That runner is designed to interact with the event bus from external tools and shell scripts. See the documentation for more examples.

Remotely via the REST API¶

Salt's event bus can be consumed salt.netapi.rest_cherrypy.app.Events as an HTTP stream from external tools or services.

From Python¶

Python scripts can access the event bus only as the same system user that Salt is running as. The event system is accessed via the event library and can only be accessed by the same system user that Salt is running as. To listen to events a SaltEvent object needs to be created and then the get_event function needs to be run. The SaltEvent object needs to know the location that the Salt Unix sockets are kept. In the configuration this is the sock_dir option. The sock_dir option defaults to "/var/run/salt/master" on most systems. The following code will check for a single event:
Events will also use a "tag". Tags allow for events to be filtered by prefix. By default all events will be returned. If only authentication events are desired, then pass the tag "salt/auth". The get_event method has a default poll time assigned of 5 seconds. To change this time set the "wait" option. The following example will only listen for auth events and will wait for 10 seconds instead of the default 5.
To retrieve the tag as well as the event data, pass full=True:
Instead of looking for a single event, the iter_events method can be used to make a generator which will continually yield salt events. The iter_events method also accepts a tag but not a wait time:
And finally event tags can be globbed, such as they can be in the Reactor, using the fnmatch library.

Firing Events¶

It is possible to fire events on either the minion's local bus or to fire events intended for the master. To fire a local event from the minion on the command line call the event.fire execution function:
To fire an event to be sent up to the master from the minion call the event.send execution function. Remember YAML can be used at the CLI in function arguments:
If a process is listening on the minion, it may be useful for a user on the master to fire an event to it:

Firing Events from Python¶

From Salt execution modules¶

Events can be very useful when writing execution modules, in order to inform various processes on the master when a certain task has taken place. This is easily done using the normal cross-calling syntax:

From Custom Python Scripts¶

Firing events from custom Python code is quite simple and mirrors how it is done at the CLI:

Beacons¶

Beacons let you use the Salt event system to monitor non-Salt processes. The beacon system allows the minion to hook into a variety of system processes and continually monitor these processes. When monitored activity occurs in a system process, an event is sent on the Salt event bus that can be used to trigger a reactor. Salt beacons can currently monitor and send Salt events for many system activities, including:
See beacon modules for a current list. NOTE:

Configuring Beacons¶

Salt beacons do not require any changes to the system components that are being monitored, everything is configured using Salt. Beacons are typically enabled by placing a beacons: top level block in /etc/salt/minion or any file in /etc/salt/minion.d/ such as /etc/salt/minion.d/beacons.conf:
The beacon system, like many others in Salt, can also be configured via the minion pillar, grains, or local config file. NOTE:

Beacon Monitoring Interval¶

Beacons monitor on a 1-second interval by default. To set a different interval, provide an interval argument to a beacon. The following beacons run on 5- and 10-second intervals:

Avoiding Event Loops¶

It is important to carefully consider the possibility of creating a loop between a reactor and a beacon. For example, one might set up a beacon which monitors whether a file is read which in turn fires a reactor to run a state which in turn reads the file and re-fires the beacon. To avoid these types of scenarios, the disable_during_state_run argument may be set. If a state run is in progress, the beacon will not be run on its regular interval until the minion detects that the state run has completed, at which point the normal beacon interval will resume.
NOTE:

Beacon Example¶

This example demonstrates configuring the inotify beacon to monitor a file for changes, and then restores the file to its original contents if a change was made. NOTE:

Create Watched File¶

Create the file named /etc/important_file and add some simple content:

Add Beacon Configs to Minion¶

On the Salt minion, add the following configuration to /etc/salt/minion.d/beacons.conf:
Save the configuration file and restart the minion service. The beacon is now set up to notify salt upon modifications made to the file. NOTE:

View Events on the Master¶

On your Salt master, start the event runner using the following command:
This runner displays events as they are received by the master on the Salt event bus. To test the beacon you set up in the previous section, make and save a modification to /etc/important_file. You'll see an event similar to the following on the event bus:
This indicates that the event is being captured and sent correctly. Now you can create a reactor to take action when this event occurs.

Create a Reactor¶

This reactor reverts the file named /etc/important_file to the contents provided by salt each time it is modified.

Reactor SLS¶

On your Salt master, create a file named /srv/reactor/revert.sls. NOTE:
Add the following to /srv/reactor/revert.sls:
NOTE:
NOTE:

State SLS¶

Create the state sls file referenced by the reactor sls file. This state file will be located at /srv/salt/maintain_important_file.sls.

Master Config¶

Configure the master to map the inotify beacon event to the revert reaction in /etc/salt/master.d/reactor.conf:
NOTE:

Start the Salt Master in Debug Mode¶

To help with troubleshooting, start the Salt master in debug mode:
When debug logging is enabled, event and reactor data are displayed so you can discover syntax and other issues.

Trigger the Reactor¶

On your minion, make and save another change to /etc/important_file. On the Salt master, you'll see debug messages that indicate the event was received and the state.apply job was sent. When you inspect the file on the minion, you'll see that the file contents have been restored to important_config: True. All beacons are configured using a similar process of enabling the beacon, writing a reactor SLS (and state SLS if needed), and mapping a beacon event to the reactor SLS.

Writing Beacon Plugins¶

Beacon plugins use the standard Salt loader system, meaning that many of the constructs from other plugin systems holds true, such as the __virtual__ function. The important function in the Beacon Plugin is the beacon function. When the beacon is configured to run, this function will be executed repeatedly by the minion. The beacon function therefore cannot block and should be as lightweight as possible. The beacon also must return a list of dicts, each dict in the list will be translated into an event on the master. Beacons may also choose to implement a __validate__ function which takes the beacon configuration as an argument and ensures that it is valid prior to continuing. This function is called automatically by the Salt loader when a beacon is loaded. Please see the inotify beacon as an example.

The beacon Function¶

The beacons system will look for a function named beacon in the module. If this function is not present then the beacon will not be fired. This function is called on a regular basis and defaults to being called on every iteration of the minion, which can be tens to hundreds of times a second. This means that the beacon function cannot block and should not be CPU or IO intensive. The beacon function will be passed in the configuration for the executed beacon. This makes it easy to establish a flexible configuration for each called beacon. This is also the preferred way to ingest the beacon's configuration as it allows for the configuration to be dynamically updated while the minion is running by configuring the beacon in the minion's pillar.

The Beacon Return¶

The information returned from the beacon is expected to follow a predefined structure. The returned value needs to be a list of dictionaries (standard python dictionaries are preferred, no ordered dicts are needed). The dictionaries represent individual events to be fired on the minion and master event buses. Each dict is a single event. The dict can contain any arbitrary keys but the 'tag' key will be extracted and added to the tag of the fired event. The return data structure would look something like this:

Calling Execution Modules¶

Execution modules are still the preferred location for all work and system interaction to happen in Salt. For this reason the __salt__ variable is available inside the beacon. Please be careful when calling functions in __salt__, while this is the preferred means of executing complicated routines in Salt not all of the execution modules have been written with beacons in mind. Watch out for execution modules that may be CPU intense or IO bound. Please feel free to add new execution modules and functions to back specific beacons.

Distributing Custom Beacons¶

Custom beacons can be distributed to minions using saltutil, see Dynamic Module Distribution.

Reactor System¶

Salt's Reactor system gives Salt the ability to trigger actions in response to an event. It is a simple interface to watching Salt's event bus for event tags that match a given pattern and then running one or more commands in response. This system binds sls files to event tags on the master. These sls files then define reactions. This means that the reactor system has two parts. First, the reactor option needs to be set in the master configuration file. The reactor option allows for event tags to be associated with sls reaction files. Second, these reaction files use highdata (like the state system) to define reactions to be executed.

Event System¶

A basic understanding of the event system is required to understand reactors. The event system is a local ZeroMQ PUB interface which fires salt events. This event bus is an open system used for sending information notifying Salt and other systems about operations. The event system fires events with a very specific criteria. Every event has a tag. Event tags allow for fast top level filtering of events. In addition to the tag, each event has a data structure. This data structure is a dict, which contains information about the event.

Mapping Events to Reactor SLS Files¶

Reactor SLS files and event tags are associated in the master config file. By default this is /etc/salt/master, or /etc/salt/master.d/reactor.conf. New in version 2014.7.0: Added Reactor support for salt:// file paths. In the master config section 'reactor:' is a list of event tags to be matched and each event tag has a list of reactor SLS files to be run.
NOTE:
Reactor sls files are similar to state and pillar sls files. They are by default yaml + Jinja templates and are passed familiar context variables. They differ because of the addition of the tag and data variables.
Here is a simple reactor sls:
This simple reactor file uses Jinja to further refine the reaction to be made. If the id in the event data is mysql1 (in other words, if the name of the minion is mysql1) then the following reaction is defined. The same data structure and compiler used for the state system is used for the reactor system. The only difference is that the data is matched up to the salt command API and the runner system. In this example, a command is published to the mysql1 minion with a function of state.apply. Similarly, a runner can be called:
This example will execute the state.orchestrate runner and initiate an orchestrate execution.

The Goal of Writing Reactor SLS Files¶

Reactor SLS files share the familiar syntax from Salt States but there are important differences. The goal of a Reactor file is to process a Salt event as quickly as possible and then to optionally start a new process in response.
Matching and rendering Reactor SLS files is done sequentially in a single process. Complex Jinja that calls out to slow Execution or Runner modules slows down the rendering and causes other reactions to pile up behind the current one. The worker pool is designed to handle complex and long-running processes such as Salt Orchestrate. tl;dr: Rendering Reactor SLS files MUST be simple and quick. The new process started by the worker threads can be long-running.

Jinja Context¶

Reactor files only have access to a minimal Jinja context. grains and pillar are not available. The salt object is available for calling Runner and Execution modules but it should be used sparingly and only for quick tasks for the reasons mentioned above.

Advanced State System Capabilities¶

Reactor SLS files, by design, do not support Requisites, ordering, onlyif/ unless conditionals and most other powerful constructs from Salt's State system. Complex Master-side operations are best performed by Salt's Orchestrate system so using the Reactor to kick off an Orchestrate run is a very common pairing. For example:

Beacons and Reactors¶

An event initiated by a beacon, when it arrives at the master will be wrapped inside a second event, such that the data object containing the beacon information will be data['data'], rather than data. For example, to access the id field of the beacon event in a reactor file, you will need to reference {{ data['data']['id'] }} rather than {{ data['id'] }} as for events initiated directly on the event bus. See the beacon documentation for examples.

Fire an event¶

To fire an event from a minion call event.send
After this is called, any reactor sls files matching event tag foo will execute with {{ data['data']['orchestrate'] }} equal to 'refresh'. See salt.modules.event for more information.

Knowing what event is being fired¶

The best way to see exactly what events are fired and what data is available in each event is to use the state.event runner. SEE ALSO:
Example usage:
Example output:

Debugging the Reactor¶

The best window into the Reactor is to run the master in the foreground with debug logging enabled. The output will include when the master sees the event, what the master does in response to that event, and it will also include the rendered SLS file (or any errors generated while rendering the SLS file).

Understanding the Structure of Reactor Formulas¶

I.e., when to use `arg` and `kwarg` and when to specify the function arguments directly. While the reactor system uses the same basic data structure as the state system, the functions that will be called using that data structure are different functions than are called via Salt's state system. The Reactor can call Runner modules using the runner prefix, Wheel modules using the wheel prefix, and can also cause minions to run Execution modules using the local prefix. Changed in version 2014.7.0: The cmd prefix was renamed to local for consistency with other parts of Salt. A backward-compatible alias was added for cmd. The Reactor runs on the master and calls functions that exist on the master. In the case of Runner and Wheel functions the Reactor can just call those functions directly since they exist on the master and are run on the master. In the case of functions that exist on minions and are run on minions, the Reactor still needs to call a function on the master in order to send the necessary data to the minion so the minion can execute that function. The Reactor calls functions exposed in Salt's Python API documentation. and thus the structure of Reactor files very transparently reflects the function signatures of those functions.

Calling Execution modules on Minions¶

The Reactor sends commands down to minions in the exact same way Salt's CLI interface does. It calls a function locally on the master that sends the name of the function as well as a list of any arguments and a dictionary of any keyword arguments that the minion should use to execute that function. Specifically, the Reactor calls the async version of this function. You can see that function has 'arg' and 'kwarg' parameters which are both values that are sent down to the minion. Executing remote commands maps to the LocalClient interface which is used by the salt command. This interface more specifically maps to the cmd_async method inside of the LocalClient class. This means that the arguments passed are being passed to the cmd_async method, not the remote method. A field starts with local to use the LocalClient subsystem. The result is, to execute a remote command, a reactor formula would look like this:
The arg option takes a list of arguments as they would be presented on the command line, so the above declaration is the same as running this salt command:
Use the expr_form argument to specify a matcher:
NOTE:
Any other parameters in the LocalClient().cmd() method can be specified as well.

Executing Reactors from the Minion¶

The minion can be setup to use the Reactor via a reactor engine. This just sets up and listens to the minions event bus, instead of to the masters. The biggest difference is that you have to use the caller method on the Reactor, which is the equivalent of salt-call, to run your commands. Reactor Engine setup
NOTE:

Calling Runner modules and Wheel modules¶

Calling Runner modules and Wheel modules from the Reactor uses a more direct syntax since the function is being executed locally instead of sending a command to a remote system to be executed there. There are no 'arg' or 'kwarg' parameters (unless the Runner function or Wheel function accepts a parameter with either of those names.) For example:
If the the runner takes arguments then they must be specified as keyword arguments.
To determine the proper names for the arguments, check the documentation or source code for the runner function you wish to call.

Passing event data to Minions or Orchestrate as Pillar¶

An interesting trick to pass data from the Reactor script to state.apply is to pass it as inline Pillar data since both functions take a keyword argument named pillar. The following example uses Salt's Reactor to listen for the event that is fired when the key for a new minion is accepted on the master using salt-key. /etc/salt/master.d/reactor.conf:
The Reactor then fires a : state.apply command targeted to the HAProxy servers and passes the ID of the new minion from the event to the state file via inline Pillar. /srv/salt/haproxy/react_new_minion.sls:
The above command is equivalent to the following command at the CLI:
This works with Orchestrate files as well:
Which is equivalent to the following command at the CLI:
Finally, that data is available in the state file using the normal Pillar lookup syntax. The following example is grabbing web server names and IP addresses from Salt Mine. If this state is invoked from the Reactor then the custom Pillar value from above will be available and the new minion will be added to the pool but with the disabled flag so that HAProxy won't yet direct traffic to it. /srv/salt/haproxy/refresh_pool.sls:

A Complete Example¶

In this example, we're going to assume that we have a group of servers that will come online at random and need to have keys automatically accepted. We'll also add that we don't want all servers being automatically accepted. For this example, we'll assume that all hosts that have an id that starts with 'ink' will be automatically accepted and have state.apply executed. On top of this, we're going to add that a host coming up that was replaced (meaning a new key) will also be accepted. Our master configuration will be rather simple. All minions that attempte to authenticate will match the tag of salt/auth. When it comes to the minion key being accepted, we get a more refined tag that includes the minion id, which we can use for matching. /etc/salt/master.d/reactor.conf:
In this sls file, we say that if the key was rejected we will delete the key on the master and then also tell the master to ssh in to the minion and tell it to restart the minion, since a minion process will die if the key is rejected. We also say that if the key is pending and the id starts with ink we will accept the key. A minion that is waiting on a pending key will retry authentication every ten seconds by default. /srv/reactor/auth-pending.sls:
No if statements are needed here because we already limited this action to just Ink servers in the master configuration. /srv/reactor/auth-complete.sls:
The above will also return the highstate result data using the smtp_return returner (use virtualname like when using from the command line with --return). The returner needs to be configured on the minion for this to work. See salt.returners.smtp_return documentation for that.

Syncing Custom Types on Minion Start¶

Salt will sync all custom types (by running a saltutil.sync_all) on every highstate. However, there is a chicken-and-egg issue where, on the initial highstate, a minion will not yet have these custom types synced when the top file is first compiled. This can be worked around with a simple reactor which watches for minion_start events, which each minion fires when it first starts up and connects to the master. On the master, create /srv/reactor/sync_grains.sls with the following contents:
And in the master config file, add the following reactor configuration:
This will cause the master to instruct each minion to sync its custom grains when it starts, making these grains available when the initial highstate is executed. Other types can be synced by replacing local.saltutil.sync_grains with local.saltutil.sync_modules, local.saltutil.sync_all, or whatever else suits the intended use case.

ORCHESTRATION¶

Orchestrate Runner¶

Orchestration is accomplished in salt primarily through the Orchestrate Runner. Added in version 0.17.0, this Salt Runner can use the full suite of requisites available in states, and can also execute states/functions using salt-ssh.

The Orchestrate Runner¶

New in version 0.17.0. NOTE:
The orchestrate runner generalizes the Salt state system to a Salt master context. Whereas the state.sls, state.highstate, et al functions are concurrently and independently executed on each Salt minion, the state.orchestrate runner is executed on the master, giving it a master-level view and control over requisites, such as state ordering and conditionals. This allows for inter minion requisites, like ordering the application of states on different minions that must not happen simultaneously, or for halting the state run on all minions if a minion fails one of its states. If you want to setup a load balancer in front of a cluster of web servers, for example, you can ensure the load balancer is setup before the web servers or stop the state run altogether if one of the minions does not set up correctly. The state.sls, state.highstate, et al functions allow you to statefully manage each minion and the state.orchestrate runner allows you to statefully manage your entire infrastructure.

Executing the Orchestrate Runner¶

The Orchestrate Runner command format is the same as for the state.sls function, except that since it is a runner, it is executed with salt-run rather than salt. Assuming you have a state.sls file called /srv/salt/orch/webserver.sls the following command run on the master will apply the states defined in that file.
NOTE:
Changed in version 2014.1.1: The runner function was renamed to state.orchestrate to avoid confusion with the state.sls execution function. In versions 0.17.0 through 2014.1.0, state.sls must be used.

Masterless Orchestration¶

New in version 2016.11.0. To support salt orchestration on masterless minions, the Orchestrate Runner is available as an execution module. The syntax for masterless orchestration is exactly the same, but it uses the salt-call command and the minion configuration must contain the file_mode: local option. Alternatively, use salt-call --local on the command line.
NOTE:

Examples¶

Function¶

To execute a function, use salt.function:

If you omit the "name" argument, the ID of the state will be the default name, or in the case of salt.function, the execution module function to run. You can specify the "name" argument to avoid conflicting IDs:

State¶

To execute a state, use salt.state.

Highstate¶

To run a highstate, set highstate: True in your state config:

More Complex Orchestration¶

Many states/functions can be configured in a single file, which when combined with the full suite of requisites, can be used to easily configure complex orchestration tasks. Additionally, the states/functions will be executed in the order in which they are defined, unless prevented from doing so by any requisites, as is the default in SLS files since 0.17.0.
Given the above setup, the orchestration will be carried out as follows:
NOTE:

SALT SSH¶

Getting Started¶

Salt SSH is very easy to use, simply set up a basic roster file of the systems to connect to and run salt-ssh commands in a similar way as standard salt commands.

Salt SSH Roster¶

The roster system in Salt allows for remote minions to be easily defined. NOTE:
Simply create the roster file, the default location is /etc/salt/roster:
This is a very basic roster file where a Salt ID is being assigned to an IP address. A more elaborate roster can be created:
NOTE:

Deploy ssh key for salt-ssh¶

By default, salt-ssh will generate key pairs for ssh, the default path will be /etc/salt/pki/master/ssh/salt-ssh.rsa You can use ssh-copy-id, (the OpenSSH key deployment tool) to deploy keys to your servers.
One could also create a simple shell script, named salt-ssh-copy-id.sh as follows:
NOTE:

Once keys are successfully deployed, salt-ssh can be used to control them. Alternatively ssh agent forwarding can be used by setting the priv to agent-forwarding.

Calling Salt SSH¶

NOTE:
The salt-ssh command can be easily executed in the same way as a salt command:
Commands with salt-ssh follow the same syntax as the salt command. The standard salt functions are available! The output is the same as salt and many of the same flags are available. Please see http://docs.saltstack.com/ref/cli/salt-ssh.html for all of the available options.

Raw Shell Calls¶

By default salt-ssh runs Salt execution modules on the remote system, but salt-ssh can also execute raw shell commands:

States Via Salt SSH¶

The Salt State system can also be used with salt-ssh. The state system abstracts the same interface to the user in salt-ssh as it does when using standard salt. The intent is that Salt Formulas defined for standard salt will work seamlessly with salt-ssh and vice-versa. The standard Salt States walkthroughs function by simply replacing salt commands with salt-ssh.

Targeting with Salt SSH¶

Due to the fact that the targeting approach differs in salt-ssh, only glob and regex targets are supported as of this writing, the remaining target systems still need to be implemented. NOTE:

Configuring Salt SSH¶

Salt SSH takes its configuration from a master configuration file. Normally, this file is in /etc/salt/master. If one wishes to use a customized configuration file, the -c option to Salt SSH facilitates passing in a directory to look inside for a configuration file named master.

Minion Config¶

New in version 2015.5.1. Minion config options can be defined globally using the master configuration option ssh_minion_opts. It can also be defined on a per-minion basis with the minion_opts entry in the roster.

Running Salt SSH as non-root user¶

By default, Salt read all the configuration from /etc/salt/. If you are running Salt SSH with a regular user you have to modify some paths or you will get "Permission denied" messages. You have to modify two parameters: pki_dir and cachedir. Those should point to a full path writable for the user. It's recommended not to modify /etc/salt for this purpose. Create a private copy of /etc/salt for the user and run the command with -c /new/config/path.

Define CLI Options with Saltfile¶

If you are commonly passing in CLI options to salt-ssh, you can create a Saltfile to automatically use these options. This is common if you're managing several different salt projects on the same server. So you can cd into a directory that has a Saltfile with the following YAML contents:
Instead of having to call salt-ssh --config-dir=path/to/config/dir --max-procs=30 --wipe \* test.ping you can call salt-ssh \* test.ping. Boolean-style options should be specified in their YAML representation. NOTE:
NOTE:

Debugging salt-ssh¶

One common approach for debugging salt-ssh is to simply use the tarball that salt ships to the remote machine and call salt-call directly. To determine the location of salt-call, simply run salt-ssh with the -ltrace flag and look for a line containing the string, SALT_ARGV. This contains the salt-call command that salt-ssh attempted to execute. It is recommended that one modify this command a bit by removing the -l quiet, --metadata and --output json to get a better idea of what's going on on the target system.

Salt Rosters¶

Salt rosters are pluggable systems added in Salt 0.17.0 to facilitate the salt-ssh system. The roster system was created because salt-ssh needs a means to identify which systems need to be targeted for execution. SEE ALSO:
NOTE:
Since the roster system is pluggable, it can be easily augmented to attach to any existing systems to gather information about what servers are presently available and should be attached to by salt-ssh. By default the roster file is located at /etc/salt/roster.

How Rosters Work¶

The roster system compiles a data structure internally referred to as targets. The targets is a list of target systems and attributes about how to connect to said systems. The only requirement for a roster module in Salt is to return the targets data structure.

Targets Data¶

The information which can be stored in a roster target is the following:

thin_dir¶

Salt needs to upload a standalone environment to the target system, and this defaults to /tmp/salt-<hash>. This directory will be cleaned up per normal systems operation. If you need a persistent Salt environment, for instance to set persistent grains, this value will need to be changed.

SALT CLOUD¶

Configuration¶

Salt Cloud provides a powerful interface to interact with cloud hosts. This interface is tightly integrated with Salt, and new virtual machines are automatically connected to your Salt master after creation. Since Salt Cloud is designed to be an automated system, most configuration is done using the following YAML configuration files:

Configuration Inheritance¶

Configuration settings are inherited in order from the cloud config => providers => profile. [image] For example, if you wanted to use the same image for all virtual machines for a specific provider, the image name could be placed in the provider file. This value is inherited by all profiles that use that provider, but is overridden if a image name is defined in the profile. Most configuration settings can be defined in any file, the main difference being how that setting is inherited.

QuickStart¶

The Salt Cloud Quickstart walks you through defining a provider, a VM profile, and shows you how to create virtual machines using Salt Cloud. Note that if you installed Salt via Salt Bootstrap, it may not have automatically installed salt-cloud for you. Use your distribution's package manager to install the salt-cloud package from the same repo that you used to install Salt. These repos will automatically be setup by Salt Bootstrap. If there is no salt-cloud package, install with pip install salt-cloud.

Using Salt Cloud¶

salt-cloud¶

Provision virtual machines in the cloud with Salt

Synopsis¶

Description¶

Salt Cloud is the system used to provision virtual machines on various public clouds via a cleanly controlled profile and mapping system.

Options¶

Execution Options¶

Query Options¶

Cloud Providers Listings¶

Cloud Credentials¶

Output Options¶

Examples¶

To create 4 VMs named web1, web2, db1, and db2 from specified profiles:
To read in a map file and create all VMs specified therein:
To read in a map file and create all VMs specified therein in parallel:
To delete any VMs specified in the map file:
To delete any VMs NOT specified in the map file:
To display the status of all VMs specified in the map file:

See also¶

salt-cloud(7) salt(7) salt-master(1) salt-minion(1)

Salt Cloud basic usage¶

Salt Cloud needs, at least, one configured Provider and Profile to be functional.

Creating a VM¶

To create a VM with salt cloud, use command:
Assuming there is a profile configured as following:
Then, the command to create new VM named fedora_http_01 is:

Destroying a VM¶

To destroy a created-by-salt-cloud VM, use command:
For example, to delete the VM created on above example, use:

VM Profiles¶

Salt cloud designates virtual machines inside the profile configuration file. The profile configuration file defaults to /etc/salt/cloud.profiles and is a yaml configuration. The syntax for declaring profiles is simple:
It should be noted that the script option defaults to bootstrap-salt, and does not normally need to be specified. Further examples in this document will not show the script option. A few key pieces of information need to be declared and can change based on the cloud provider. A number of additional parameters can also be inserted:
The image must be selected from available images. Similarly, sizes must be selected from the list of sizes. To get a list of available images and sizes use the following command:
Some parameters can be specified in the main Salt cloud configuration file and then are applied to all cloud profiles. For instance if only a single cloud provider is being used then the provider option can be declared in the Salt cloud configuration file.

Multiple Configuration Files¶

In addition to /etc/salt/cloud.profiles, profiles can also be specified in any file matching cloud.profiles.d/*conf which is a sub-directory relative to the profiles configuration file(with the above configuration file as an example, /etc/salt/cloud.profiles.d/*.conf). This allows for more extensible configuration, and plays nicely with various configuration management tools as well as version control systems.

Larger Example¶

Cloud Map File¶

A number of options exist when creating virtual machines. They can be managed directly from profiles and the command line execution, or a more complex map file can be created. The map file allows for a number of virtual machines to be created and associated with specific profiles. The map file is designed to be run once to create these more complex scenarios using salt-cloud. Map files have a simple format, specify a profile and then a list of virtual machines to make from said profile:
This map file can then be called to roll out all of these virtual machines. Map files are called from the salt-cloud command with the -m option:
Remember, that as with direct profile provisioning the -P option can be passed to create the virtual machines in parallel:
NOTE:
A map file can also be enforced to represent the total state of a cloud deployment by using the --hard option. When using the hard option any vms that exist but are not specified in the map file will be destroyed:
Be careful with this argument, it is very dangerous! In fact, it is so dangerous that in order to use it, you must explicitly enable it in the main configuration file.
A map file can include grains and minion configuration options:
A map file may also be used with the various query options:
...or with the delete option:
WARNING:

Setting up New Salt Masters¶

Bootstrapping a new master in the map is as simple as:
Notice that ALL bootstrapped minions from the map will answer to the newly created salt-master. To make any of the bootstrapped minions answer to the bootstrapping salt-master as opposed to the newly created salt-master, as an example:
The above says the minion running on the newly created salt-master responds to the local master, ie, the master used to bootstrap these VMs. Another example:
The above example makes the web3 minion answer to the local master, not the newly created master.

Cloud Actions¶

Once a VM has been created, there are a number of actions that can be performed on it. The "reboot" action can be used across all providers, but all other actions are specific to the cloud provider. In order to perform an action, you may specify it from the command line, including the name(s) of the VM to perform the action on:
Or you may specify a map which includes all VMs to perform the action on:
The following is a list of actions currently supported by salt-cloud:
Another useful reference for viewing more salt-cloud actions is the :ref:Salt Cloud Feature Matrix <salt-cloud-feature-matrix>

Cloud Functions¶

Cloud functions work much the same way as cloud actions, except that they don't perform an operation on a specific instance, and so do not need a machine name to be specified. However, since they perform an operation on a specific cloud provider, that provider must be specified.
There are three universal salt-cloud functions that are extremely useful for gathering information about instances on a provider basis:

Another useful reference for viewing salt-cloud functions is the Salt Cloud Feature Matrix.

Core Configuration¶

Install Salt Cloud¶

Salt Cloud is now part of Salt proper. It was merged in as of Salt version 2014.1.0. On Ubuntu, install Salt Cloud by using following command:
If using Salt Cloud on macOS, curl-ca-bundle must be installed. Presently, this package is not available via brew, but it is available using MacPorts:
Salt Cloud depends on apache-libcloud. Libcloud can be installed via pip with pip install apache-libcloud.

Installing Salt Cloud for development¶

Installing Salt for development enables Salt Cloud development as well, just make sure apache-libcloud is installed as per above paragraph. See these instructions: Installing Salt for development.

Core Configuration¶

A number of core configuration options and some options that are global to the VM profiles can be set in the cloud configuration file. By default this file is located at /etc/salt/cloud.

Thread Pool Size¶

When salt cloud is operating in parallel mode via the -P argument, you can control the thread pool size by specifying the pool_size parameter with a positive integer value. By default, the thread pool size will be set to the number of VMs that salt cloud is operating on.

Minion Configuration¶

The default minion configuration is set up in this file. Minions created by salt-cloud derive their configuration from this file. Almost all parameters found in Configuring the Salt Minion can be used here.
In particular, this is the location to specify the location of the salt master and its listening port, if the port is not set to the default. Similar to most other settings, Minion configuration settings are inherited across configuration files. For example, the master setting might be contained in the main cloud configuration file as demonstrated above, but additional settings can be placed in the provider or profile:

Cloud Configuration Syntax¶

The data specific to interacting with public clouds is set up here. Cloud provider configuration settings can live in several places. The first is in /etc/salt/cloud:
Cloud provider configuration data can also be housed in /etc/salt/cloud.providers or any file matching /etc/salt/cloud.providers.d/*.conf. All files in any of these locations will be parsed for cloud provider data. Using the example configuration above:
NOTE:
It is also possible to have multiple cloud configuration blocks within the same alias block. For example:
However, using this configuration method requires a change with profile configuration blocks. The provider alias needs to have the provider key value appended as in the following example:
Notice that because of the multiple entries, one has to be explicit about the provider alias and name, from the above example, production-config: ec2. This data interactions with the salt-cloud binary regarding its --list-location, --list-images, and --list-sizes which needs a cloud provider as an argument. The argument used should be the configured cloud provider alias. If the provider alias has multiple entries, <provider-alias>: <provider-name> should be used. To allow for a more extensible configuration, --providers-config, which defaults to /etc/salt/cloud.providers, was added to the cli parser. It allows for the providers' configuration to be added on a per-file basis.

Pillar Configuration¶

It is possible to configure cloud providers using pillars. This is only used when inside the cloud module. You can setup a variable called cloud that contains your profile and provider to pass that information to the cloud servers instead of having to copy the full configuration to every minion. In your pillar file, you would use something like this:

Cloud Configurations¶

Scaleway¶

To use Salt Cloud with Scaleway, you need to get an access key and an API token. API tokens are unique identifiers associated with your Scaleway account. To retrieve your access key and API token, log-in to the Scaleway control panel, open the pull-down menu on your account name and click on "My Credentials" link. If you do not have API token you can create one by clicking the "Create New Token" button on the right corner.
NOTE:

Rackspace¶

Rackspace cloud requires two configuration options; a user and an apikey:
NOTE:

Amazon AWS¶

A number of configuration options are required for Amazon AWS including id, key, keyname, securitygroup, and private_key:
NOTE:

Linode¶

Linode requires a single API key, but the default root password also needs to be set:
The password needs to be 8 characters and contain lowercase, uppercase, and numbers. NOTE:

Joyent Cloud¶

The Joyent cloud requires three configuration parameters: The username and password that are used to log into the Joyent system, as well as the location of the private SSH key associated with the Joyent account. The SSH key is needed to send the provisioning commands up to the freshly created virtual machine.
NOTE:

GoGrid¶

To use Salt Cloud with GoGrid, log into the GoGrid web interface and create an API key. Do this by clicking on "My Account" and then going to the API Keys tab. The apikey and the sharedsecret configuration parameters need to be set in the configuration file to enable interfacing with GoGrid:
NOTE:

OpenStack¶

OpenStack configuration differs between providers, and at the moment several options need to be specified. This module has been officially tested against the HP and the Rackspace implementations, and some examples are provided for both.
If you have an API key for your provider, it may be specified instead of a password:
NOTE:
You will certainly need to configure the user, tenant, and either password or apikey. If your OpenStack instances only have private IP addresses and a CIDR range of private addresses are not reachable from the salt-master, you may set your preference to have Salt ignore it:
For in-house OpenStack Essex installation, libcloud needs the service_type :

DigitalOcean¶

Using Salt for DigitalOcean requires a client_key and an api_key. These can be found in the DigitalOcean web interface, in the "My Settings" section, under the API Access tab.
NOTE:

Parallels¶

Using Salt with Parallels requires a user, password and URL. These can be obtained from your cloud provider.
NOTE:

Proxmox¶

Using Salt with Proxmox requires a user, password, and URL. These can be obtained from your cloud host. Both PAM and PVE users can be used.
NOTE:

LXC¶

The lxc driver uses saltify to install salt and attach the lxc container as a new lxc minion. As soon as we can, we manage baremetal operation over SSH. You can also destroy those containers via this driver.
And in the map file:
NOTE:

Saltify¶

The Saltify driver is a new, experimental driver designed to install Salt on a remote machine, virtual or bare metal, using SSH. This driver is useful for provisioning machines which are already installed, but not Salted. For more information about using this driver and for configuration examples, please see the Gettting Started with Saltify documentation.

Extending Profiles and Cloud Providers Configuration¶

As of 0.8.7, the option to extend both the profiles and cloud providers configuration and avoid duplication was added. The extends feature works on the current profiles configuration, but, regarding the cloud providers configuration, only works in the new syntax and respective configuration files, i.e. /etc/salt/salt/cloud.providers or /etc/salt/cloud.providers.d/*.conf. NOTE:

Extending Profiles¶

Some example usage on how to use extends with profiles. Consider /etc/salt/salt/cloud.profiles containing:
The above configuration, once parsed would generate the following profiles data:
Pretty cool right?

Extending Providers¶

Some example usage on how to use extends within the cloud providers configuration. Consider /etc/salt/salt/cloud.providers containing:
The above configuration, once parsed would generate the following providers data:

Windows Configuration¶

Spinning up Windows Minions¶

It is possible to use Salt Cloud to spin up Windows instances, and then install Salt on them. This functionality is available on all cloud providers that are supported by Salt Cloud. However, it may not necessarily be available on all Windows images.

Requirements¶

Salt Cloud makes use of impacket and winexe to set up the Windows Salt Minion installer. impacket is usually available as either the impacket or the python-impacket package, depending on the distribution. More information on impacket can be found at the project home:
winexe is less commonly available in distribution-specific repositories. However, it is currently being built for various distributions in 3rd party channels:

Optionally WinRM can be used instead of winexe if the python module pywinrm is available and WinRM is supported on the target Windows version. Information on pywinrm can be found at the project home:
Additionally, a copy of the Salt Minion Windows installer must be present on the system on which Salt Cloud is running. This installer may be downloaded from saltstack.com:

Firewall Settings¶

Because Salt Cloud makes use of smbclient and winexe, port 445 must be open on the target image. This port is not generally open by default on a standard Windows distribution, and care must be taken to use an image in which this port is open, or the Windows firewall is disabled. If supported by the cloud provider, a PowerShell script may be used to open up this port automatically, using the cloud provider's userdata. The following script would open up port 445, and apply the changes:
For EC2, this script may be saved as a file, and specified in the provider or profile configuration as userdata_file. For instance:
If you are using WinRM on EC2 the HTTPS port for the WinRM service must also be enabled in your userdata. By default EC2 Windows images only have insecure HTTP enabled. To enable HTTPS and basic authentication required by pywinrm consider the following userdata example:
No certificate store is available by default on EC2 images and creating one does not seem possible without an MMC (cannot be automated). To use the default EC2 Windows images the above copies the RDP store.

Configuration¶

Configuration is set as usual, with some extra configuration settings. The location of the Windows installer on the machine that Salt Cloud is running on must be specified. This may be done in any of the regular configuration files (main, providers, profiles, maps). For example: Setting the installer in /etc/salt/cloud.providers:
The default Windows user is Administrator, and the default Windows password is blank. If WinRM is to be used use_winrm needs to be set to True. winrm_port can be used to specify a custom port (must be HTTPS listener).

Auto-Generated Passwords on EC2¶

On EC2, when the win_password is set to auto, Salt Cloud will query EC2 for an auto-generated password. This password is expected to take at least 4 minutes to generate, adding additional time to the deploy process. When the EC2 API is queried for the auto-generated password, it will be returned in a message encrypted with the specified keyname. This requires that the appropriate private_key file is also specified. Such a profile configuration might look like:

Cloud Provider Specifics¶

Getting Started With Aliyun ECS¶

The Aliyun ECS (Elastic Computer Service) is one of the most popular public cloud hosts in China. This cloud host can be used to manage aliyun instance using salt-cloud. http://www.aliyun.com/

Dependencies¶

This driver requires the Python requests library to be installed.

Configuration¶

Using Salt for Aliyun ECS requires aliyun access key id and key secret. These can be found in the aliyun web interface, in the "User Center" section, under "My Service" tab.
NOTE:

Profiles¶

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles or in the /etc/salt/cloud.profiles.d/ directory:
Sizes can be obtained using the --list-sizes option for the salt-cloud command:
Images can be obtained using the --list-images option for the salt-cloud command:
Locations can be obtained using the --list-locations option for the salt-cloud command:
Security Group can be obtained using the -f list_securitygroup option for the salt-cloud command:
NOTE:

Getting Started With Azure¶

New in version 2014.1.0. Azure is a cloud service by Microsoft providing virtual machines, SQL services, media services, and more. This document describes how to use Salt Cloud to create a virtual machine on Azure, with Salt installed. More information about Azure is located at http://www.windowsazure.com/.

Dependencies¶

NOTE:

Configuration¶

Set up the provider config at /etc/salt/cloud.providers.d/azure.conf:
The certificate used must be generated by the user. OpenSSL can be used to create the management certificates. Two certificates are needed: a .cer file, which is uploaded to Azure, and a .pem file, which is stored locally. To create the .pem file, execute the following command:
To create the .cer file, execute the following command:
After creating these files, the .cer file will need to be uploaded to Azure via the "Upload a Management Certificate" action of the "Management Certificates" tab within the "Settings" section of the management portal. Optionally, a management_host may be configured, if necessary for the region. NOTE:

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles:
These options are described in more detail below. Once configured, the profile can be realized with a salt command:
This will create an salt minion instance named newinstance in Azure. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

Profile Options¶

The following options are currently available for Azure.

provider¶

The name of the provider as configured in /etc/salt/cloud.providers.d/azure.conf.

image¶

The name of the image to use to create a VM. Available images can be viewed using the following command:

size¶

The name of the size to use to create a VM. Available sizes can be viewed using the following command:

location¶

The name of the location to create a VM in. Available locations can be viewed using the following command:

affinity_group¶

The name of the affinity group to create a VM in. Either a location or an affinity_group may be specified, but not both. See Affinity Groups below.

ssh_username¶

The user to use to log into the newly-created VM to install Salt.

ssh_password¶

The password to use to log into the newly-created VM to install Salt.

slot¶

The environment to which the hosted service is deployed. Valid values are staging or production. When set to production, the resulting URL of the new VM will be <vm_name>.cloudapp.net. When set to staging, the resulting URL will contain a generated hash instead.

media_link¶

This is the URL of the container that will store the disk that this VM uses. Currently, this container must already exist. If a VM has previously been created in the associated account, a container should already exist. In the web interface, go into the Storage area and click one of the available storage selections. Click the Containers link, and then copy the URL from the container that will be used. It generally looks like:

service_name¶

The name of the service in which to create the VM. If this is not specified, then a service will be created with the same name as the VM.

virtual_network_name¶

Optional. The name of the virtual network for the VM to join. If this is not specified, then no virtual network will be joined.

subnet_name¶

Optional. The name of the subnet in the virtual network for the VM to join. Requires that a virtual_network_name is specified.

Show Instance¶

This action is a thin wrapper around --full-query, which displays details on a single instance only. In an environment with several machines, this will save a user from having to sort through all instance data, just to examine a single instance.

Destroying VMs¶

There are certain options which can be specified in the global cloud configuration file (usually /etc/salt/cloud) which affect Salt Cloud's behavior when a VM is destroyed.

cleanup_disks¶

New in version 2015.8.0. Default is False. When set to True, Salt Cloud will wait for the VM to be destroyed, then attempt to destroy the main disk that is associated with the VM.

cleanup_vhds¶

New in version 2015.8.0. Default is False. Requires cleanup_disks to be set to True. When also set to True, Salt Cloud will ask Azure to delete the VHD associated with the disk that is also destroyed.

cleanup_services¶

New in version 2015.8.0. Default is False. Requires cleanup_disks to be set to True. When also set to True, Salt Cloud will wait for the disk to be destroyed, then attempt to remove the service that is associated with the VM. Because the disk belongs to the service, the disk must be destroyed before the service can be.

Managing Hosted Services¶

New in version 2015.8.0. An account can have one or more hosted services. A hosted service is required in order to create a VM. However, as mentioned above, if a hosted service is not specified when a VM is created, then one will automatically be created with the name of the name. The following functions are also available.

create_service¶

Create a hosted service. The following options are available.

name¶

Required. The name of the hosted service to create.

label¶

Required. A label to apply to the hosted service.

description¶

Optional. A longer description of the hosted service.

location¶

Required, if affinity_group is not set. The location in which to create the hosted service. Either the location or the affinity_group must be set, but not both.

affinity_group¶

Required, if location is not set. The affinity group in which to create the hosted service. Either the location or the affinity_group must be set, but not both.

extended_properties¶

Optional. Dictionary containing name/value pairs of hosted service properties. You can have a maximum of 50 extended property name/value pairs. The maximum length of the Name element is 64 characters, only alphanumeric characters and underscores are valid in the Name, and the name must start with a letter. The value has a maximum length of 255 characters.

CLI Example¶

The following example illustrates creating a hosted service.

show_service¶

Return details about a specific hosted service. Can also be called with get_service.

list_services¶

List all hosted services associates with the subscription.

delete_service¶

Delete a specific hosted service.

Managing Storage Accounts¶

New in version 2015.8.0. Salt Cloud can manage storage accounts associated with the account. The following functions are available. Deprecated marked as deprecated are marked as such as per the SDK documentation, but are still included for completeness with the SDK.

create_storage¶

Create a storage account. The following options are supported.

name¶

Required. The name of the storage account to create.

label¶

Required. A label to apply to the storage account.

description¶

Optional. A longer description of the storage account.

location¶

Required, if affinity_group is not set. The location in which to create the storage account. Either the location or the affinity_group must be set, but not both.

affinity_group¶

Required, if location is not set. The affinity group in which to create the storage account. Either the location or the affinity_group must be set, but not both.

extended_properties¶

Optional. Dictionary containing name/value pairs of storage account properties. You can have a maximum of 50 extended property name/value pairs. The maximum length of the Name element is 64 characters, only alphanumeric characters and underscores are valid in the Name, and the name must start with a letter. The value has a maximum length of 255 characters.

geo_replication_enabled¶

Deprecated. Replaced by the account_type parameter.

account_type¶

Specifies whether the account supports locally-redundant storage, geo-redundant storage, zone-redundant storage, or read access geo-redundant storage. Possible values are:

CLI Example¶

The following example illustrates creating a storage account.

list_storage¶

List all storage accounts associates with the subscription.

show_storage¶

Return details about a specific storage account. Can also be called with get_storage.

update_storage¶

Update details concerning a storage account. Any of the options available in create_storage can be used, but the name cannot be changed.

delete_storage¶

Delete a specific storage account.

show_storage_keys¶

Returns the primary and secondary access keys for the specified storage account.

regenerate_storage_keys¶

Regenerate storage account keys. Requires a key_type ("primary" or "secondary") to be specified.

Managing Disks¶

New in version 2015.8.0. When a VM is created, a disk will also be created for it. The following functions are available for managing disks. Deprecated marked as deprecated are marked as such as per the SDK documentation, but are still included for completeness with the SDK.

show_disk¶

Return details about a specific disk. Can also be called with get_disk.

list_disks¶

List all disks associates with the account.

update_disk¶

Update details for a disk. The following options are available.

name¶

Required. The name of the disk to update.

has_operating_system¶

Deprecated.

label¶

Required. The label for the disk.

media_link¶

Deprecated. The location of the disk in the account, including the storage container that it is in. This should not need to be changed.

new_name¶

Deprecated. If renaming the disk, the new name.

os¶

Deprecated.

CLI Example¶

The following example illustrates updating a disk.

delete_disk¶

Delete a specific disk.

Managing Service Certificates¶

New in version 2015.8.0. Stored at the cloud service level, these certificates are used by your deployed services. For more information on service certificates, see the following link:
The following functions are available.

list_service_certificates¶

List service certificates associated with the account.

show_service_certificate¶

Show the data for a specific service certificate associated with the account. The name, thumbprint, and thumbalgorithm can be obtained from list_service_certificates. Can also be called with get_service_certificate.

add_service_certificate¶

Add a service certificate to the account. This requires that a certificate already exists, which is then added to the account. For more information on creating the certificate itself, see:
The following options are available.

name¶

Required. The name of the hosted service that the certificate will belong to.

data¶

Required. The base-64 encoded form of the pfx file.

certificate_format¶

Required. The service certificate format. The only supported value is pfx.

password¶

The certificate password.

delete_service_certificate¶

Delete a service certificate from the account. The name, thumbprint, and thumbalgorithm can be obtained from list_service_certificates.

Managing Management Certificates¶

New in version 2015.8.0. A Azure management certificate is an X.509 v3 certificate used to authenticate an agent, such as Visual Studio Tools for Windows Azure or a client application that uses the Service Management API, acting on behalf of the subscription owner to manage subscription resources. Azure management certificates are uploaded to Azure and stored at the subscription level. The management certificate store can hold up to 100 certificates per subscription. These certificates are used to authenticate your Windows Azure deployment. For more information on management certificates, see the following link.
The following functions are available.

list_management_certificates¶

List management certificates associated with the account.

show_management_certificate¶

Show the data for a specific management certificate associated with the account. The name, thumbprint, and thumbalgorithm can be obtained from list_management_certificates. Can also be called with get_management_certificate.

add_management_certificate¶

Management certificates must have a key length of at least 2048 bits and should reside in the Personal certificate store. When the certificate is installed on the client, it should contain the private key of the certificate. To upload to the certificate to the Microsoft Azure Management Portal, you must export it as a .cer format file that does not contain the private key. For more information on creating management certificates, see the following link:
The following options are available.

public_key¶

A base64 representation of the management certificate public key.

thumbprint¶

The thumb print that uniquely identifies the management certificate.

data¶

The certificate's raw data in base-64 encoded .cer format.

delete_management_certificate¶

Delete a management certificate from the account. The thumbprint can be obtained from list_management_certificates.

Virtual Network Management¶

New in version 2015.8.0. The following are functions for managing virtual networks.

list_virtual_networks¶

List input endpoints associated with the deployment.

Managing Input Endpoints¶

New in version 2015.8.0. Input endpoints are used to manage port access for roles. Because endpoints cannot be managed by the Azure Python SDK, Salt Cloud uses the API directly. With versions of Python before 2.7.9, the requests-python package needs to be installed in order for this to work. Additionally, the following needs to be set in the master's configuration file:
The following functions are available.

list_input_endpoints¶

List input endpoints associated with the deployment

show_input_endpoint¶

Show an input endpoint associated with the deployment

add_input_endpoint¶

Add an input endpoint to the deployment. Please note that there may be a delay before the changes show up. The following options are available.

service¶

Required. The name of the hosted service which the VM belongs to.

deployment¶

Required. The name of the deployment that the VM belongs to. If the VM was created with Salt Cloud, the deployment name probably matches the VM name.

role¶

Required. The name of the role that the VM belongs to. If the VM was created with Salt Cloud, the role name probably matches the VM name.

name¶

Required. The name of the input endpoint. This typically matches the port that the endpoint is set to. For instance, port 22 would be called SSH.

port¶

Required. The public (Internet-facing) port that is used for the endpoint.

local_port¶

Optional. The private port on the VM itself that will be matched with the port. This is typically the same as the port. If this value is not specified, it will be copied from port.

protocol¶

Required. Either tcp or udp.

enable_direct_server_return¶

Optional. If an internal load balancer exists in the account, it can be used with a direct server return. The default value is False. Please see the following article for an explanation of this option.

timeout_for_tcp_idle_connection¶

Optional. The default value is 4. Please see the following article for an explanation of this option.

CLI Example¶

The following example illustrates adding an input endpoint.

update_input_endpoint¶

Updates the details for a specific input endpoint. All options from add_input_endpoint are supported.

delete_input_endpoint¶

Delete an input endpoint from the deployment. Please note that there may be a delay before the changes show up. The following items are required.

CLI Example¶

The following example illustrates deleting an input endpoint.

service¶

The name of the hosted service which the VM belongs to.

deployment¶

The name of the deployment that the VM belongs to. If the VM was created with Salt Cloud, the deployment name probably matches the VM name.

role¶

The name of the role that the VM belongs to. If the VM was created with Salt Cloud, the role name probably matches the VM name.

name¶

The name of the input endpoint. This typically matches the port that the endpoint is set to. For instance, port 22 would be called SSH.

Managing Affinity Groups¶

New in version 2015.8.0. Affinity groups allow you to group your Azure services to optimize performance. All services and VMs within an affinity group will be located in the same region. For more information on Affinity groups, see the following link:
The following functions are available.

list_affinity_groups¶

List input endpoints associated with the account

show_affinity_group¶

Show an affinity group associated with the account

create_affinity_group¶

Create a new affinity group. The following options are supported.

name¶

Required. The name of the new affinity group.

location¶

Required. The region in which the affinity group lives.

label¶

Required. A label describing the new affinity group.

description¶

Optional. A longer description of the affinity group.

update_affinity_group¶

Update an affinity group's properties

delete_affinity_group¶

Delete a specific affinity group associated with the account

Managing Blob Storage¶

New in version 2015.8.0. Azure storage containers and their contents can be managed with Salt Cloud. This is not as elegant as using one of the other available clients in Windows, but it benefits Linux and Unix users, as there are fewer options available on those platforms.

Blob Storage Configuration¶

Blob storage must be configured differently than the standard Azure configuration. Both a storage_account and a storage_key must be specified either through the Azure provider configuration (in addition to the other Azure configuration) or via the command line.

storage_account¶

This is one of the storage accounts that is available via the list_storage function.

storage_key¶

Both a primary and a secondary storage_key can be obtained by running the show_storage_keys function. Either key may be used.

Blob Functions¶

The following functions are made available through Salt Cloud for managing blog storage.

make_blob_url¶

Creates the URL to access a blob

container¶

Name of the container.

blob¶

Name of the blob.

account¶

Name of the storage account. If not specified, derives the host base from the provider configuration.

protocol¶

Protocol to use: 'http' or 'https'. If not specified, derives the host base from the provider configuration.

host_base¶

Live host base URL. If not specified, derives the host base from the provider configuration.

list_storage_containers¶

List containers associated with the storage account

create_storage_container¶

Create a storage container

name¶

Name of container to create.

meta_name_values¶

Optional. A dict with name_value pairs to associate with the container as metadata. Example:{'Category':'test'}

blob_public_access¶

Optional. Possible values include: container, blob

fail_on_exist¶

Specify whether to throw an exception when the container exists.

show_storage_container¶

Show a container associated with the storage account

name¶

Name of container to show.

show_storage_container_metadata¶

Show a storage container's metadata

name¶

Name of container to show.

lease_id¶

If specified, show_storage_container_metadata only succeeds if the container's lease is active and matches this ID.

set_storage_container_metadata¶

Set a storage container's metadata

name¶

Name of existing container. meta_name_values ```````````` A dict containing name, value for metadata. Example: {'category':'test'} lease_id ```` If specified, set_storage_container_metadata only succeeds if the container's lease is active and matches this ID.

show_storage_container_acl¶

Show a storage container's acl

name¶

Name of existing container.

lease_id¶

If specified, show_storage_container_acl only succeeds if the container's lease is active and matches this ID.

set_storage_container_acl¶

Set a storage container's acl

name¶

Name of existing container.

signed_identifiers¶

SignedIdentifers instance

blob_public_access¶

Optional. Possible values include: container, blob

lease_id¶

If specified, set_storage_container_acl only succeeds if the container's lease is active and matches this ID.

delete_storage_container¶

Delete a container associated with the storage account

name¶

Name of container to create.

fail_not_exist¶

Specify whether to throw an exception when the container exists.

lease_id¶

If specified, delete_storage_container only succeeds if the container's lease is active and matches this ID.

lease_storage_container¶

Lease a container associated with the storage account

name¶

Name of container to create.

lease_action¶

Required. Possible values: acquire|renew|release|break|change

lease_id¶

Required if the container has an active lease.

lease_duration¶

Specifies the duration of the lease, in seconds, or negative one (-1) for a lease that never expires. A non-infinite lease can be between 15 and 60 seconds. A lease duration cannot be changed using renew or change. For backwards compatibility, the default is 60, and the value is only used on an acquire operation.

lease_break_period¶

Optional. For a break operation, this is the proposed duration of seconds that the lease should continue before it is broken, between 0 and 60 seconds. This break period is only used if it is shorter than the time remaining on the lease. If longer, the time remaining on the lease is used. A new lease will not be available before the break period has expired, but the lease may be held for longer than the break period. If this header does not appear with a break operation, a fixed-duration lease breaks after the remaining lease period elapses, and an infinite lease breaks immediately.

proposed_lease_id¶

Optional for acquire, required for change. Proposed lease ID, in a GUID string format.

list_blobs¶

List blobs associated with the container

container¶

The name of the storage container

prefix¶

Optional. Filters the results to return only blobs whose names begin with the specified prefix.

marker¶

Optional. A string value that identifies the portion of the list to be returned with the next list operation. The operation returns a marker value within the response body if the list returned was not complete. The marker value may then be used in a subsequent call to request the next set of list items. The marker value is opaque to the client.

maxresults¶

Optional. Specifies the maximum number of blobs to return, including all BlobPrefix elements. If the request does not specify maxresults or specifies a value greater than 5,000, the server will return up to 5,000 items. Setting maxresults to a value less than or equal to zero results in error response code 400 (Bad Request).

include¶

Optional. Specifies one or more datasets to include in the response. To specify more than one of these options on the URI, you must separate each option with a comma. Valid values are:

delimiter¶

Optional. When the request includes this parameter, the operation returns a BlobPrefix element in the response body that acts as a placeholder for all blobs whose names begin with the same substring up to the appearance of the delimiter character. The delimiter may be a single character or a string.

show_blob_service_properties¶

Show a blob's service properties

set_blob_service_properties¶

Sets the properties of a storage account's Blob service, including Windows Azure Storage Analytics. You can also use this operation to set the default request version for all incoming requests that do not have a version specified.

properties¶

a StorageServiceProperties object.

timeout¶

Optional. The timeout parameter is expressed in seconds.

show_blob_properties¶

Returns all user-defined metadata, standard HTTP properties, and system properties for the blob.

container¶

Name of existing container.

blob¶

Name of existing blob.

lease_id¶

Required if the blob has an active lease.

set_blob_properties¶

Set a blob's properties

container¶

Name of existing container.

blob¶

Name of existing blob.

blob_cache_control¶

Optional. Modifies the cache control string for the blob.

blob_content_type¶

Optional. Sets the blob's content type.

blob_content_md5¶

Optional. Sets the blob's MD5 hash.

blob_content_encoding¶

Optional. Sets the blob's content encoding.

blob_content_language¶

Optional. Sets the blob's content language.

lease_id¶

Required if the blob has an active lease.

blob_content_disposition¶

Optional. Sets the blob's Content-Disposition header. The Content-Disposition response header field conveys additional information about how to process the response payload, and also can be used to attach additional metadata. For example, if set to attachment, it indicates that the user-agent should not display the response, but instead show a Save As dialog with a filename other than the blob name specified.

put_blob¶

Upload a blob

container¶

Name of existing container.

name¶

Name of existing blob.

blob_path¶

The path on the local machine of the file to upload as a blob. Either this or blob_content must be specified.

blob_content¶

The actual content to be uploaded as a blob. Either this or blob_path must me specified.

cache_control¶

Optional. The Blob service stores this value but does not use or modify it.

content_language¶

Optional. Specifies the natural languages used by this resource.

content_md5¶

Optional. An MD5 hash of the blob content. This hash is used to verify the integrity of the blob during transport. When this header is specified, the storage service checks the hash that has arrived with the one that was sent. If the two hashes do not match, the operation will fail with error code 400 (Bad Request).

blob_content_type¶

Optional. Set the blob's content type.

blob_content_encoding¶

Optional. Set the blob's content encoding.

blob_content_language¶

Optional. Set the blob's content language.

blob_content_md5¶

Optional. Set the blob's MD5 hash.

blob_cache_control¶

Optional. Sets the blob's cache control.

meta_name_values¶

A dict containing name, value for metadata.

lease_id¶

Required if the blob has an active lease.

get_blob¶

Download a blob

container¶

Name of existing container.

name¶

Name of existing blob.

local_path¶

The path on the local machine to download the blob to. Either this or return_content must be specified.

return_content¶

Whether or not to return the content directly from the blob. If specified, must be True or False. Either this or the local_path must be specified.

snapshot¶

Optional. The snapshot parameter is an opaque DateTime value that, when present, specifies the blob snapshot to retrieve.

lease_id¶

Required if the blob has an active lease.

progress_callback¶

callback for progress with signature function(current, total) where current is the number of bytes transferred so far, and total is the size of the blob.

max_connections¶

Maximum number of parallel connections to use when the blob size exceeds 64MB. Set to 1 to download the blob chunks sequentially. Set to 2 or more to download the blob chunks in parallel. This uses more system resources but will download faster.

max_retries¶

Number of times to retry download of blob chunk if an error occurs.

retry_wait¶

Sleep time in secs between retries.

Getting Started With Azure ARM¶

New in version 2016.11.0. Azure is a cloud service by Microsoft providing virtual machines, SQL services, media services, and more. Azure ARM (aka, the Azure Resource Manager) is a next generatiom version of the Azure portal and API. This document describes how to use Salt Cloud to create a virtual machine on Azure ARM, with Salt installed. More information about Azure is located at http://www.windowsazure.com/.

Dependencies¶

Configuration¶

Set up the provider config at /etc/salt/cloud.providers.d/azurearm.conf:

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles:
These options are described in more detail below. Once configured, the profile can be realized with a salt command:
This will create an salt minion instance named newinstance in Azure. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

Profile Options¶

The following options are currently available for Azure ARM.

provider¶

The name of the provider as configured in /etc/salt/cloud.providers.d/azure.conf.

image¶

Required. The name of the image to use to create a VM. Available images can be viewed using the following command:
As you will see in --list-images, image names are comprised of the following fields, separated by the pipe ( |) character:
It is possible to specify the URL of a custom image that you have access to, such as:

size¶

Required. The name of the size to use to create a VM. Available sizes can be viewed using the following command:

location¶

Required. The name of the location to create a VM in. Available locations can be viewed using the following command:

ssh_username¶

Required for Linux. The user to use to log into the newly-created Linux VM to install Salt.

ssh_password¶

Required for Linux. The password to use to log into the newly-created Linux VM to install Salt.

win_username¶

Required for Windows. The user to use to log into the newly-created Windows VM to install Salt.

win_password¶

Required for Windows. The password to use to log into the newly-created Windows VM to install Salt.

resource_group¶

Required. The resource group that all VM resources (VM, network interfaces, etc) will be created in.

network_resource_group¶

Optional. If specified, then the VM will be connected to the network resources in this group, rather than the group that it was created in. The VM interfaces and IPs will remain in the configured resource_group with the VM.

cleanup_disks¶

Optional. Default is False. If set to True, disks will be cleaned up when the VM that they belong to is deleted.

cleanup_vhds¶

Optional. Default is False. If set to True, VHDs will be cleaned up when the VM and disk that they belong to are deleted. Requires cleanup_disks to be set to True.

cleanup_data_disks¶

Optional. Default is False. If set to True, data disks (non-root volumes) will be cleaned up whtn the VM that they are attached to is deleted. Requires cleanup_disks to be set to True.

cleanup_interfaces¶

Optional. Default is False. Normally when a VM is deleted, its associated interfaces and IPs are retained. This is useful if you expect the deleted VM to be recreated with the same name and network settings. If you would like interfaces and IPs to be deleted when their associated VM is deleted, set this to True.

custom_data¶

Any custom cloud data that needs to be specified. How this data is used depends on the operating system and image that is used. For instance, Linux images that use cloud-init will import this data for use with that program. Some Windows images will create a file with a copy of this data, and others will ignore it. If a Windows image creates a file, then the location will depend upon the version of Windows.

expire_publisher_cache¶

Optional. Default is 604800. When fetching image data using --list-images, a number of web calls need to be made to the Azure ARM API. This is normally very fast when performed using a VM that exists inside Azure itself, but can be very slow when made from an external connection. By default, the publisher data will be cached, and only updated every 604800 seconds (7 days). If you need the publisher cache to be updated at a different frequency, change this setting. Setting it to 0 will turn off the publisher cache.

expire_offer_cache¶

Optional. Default is 604800. See expire_publisher_cache for details on why this exists. By default, the offer data will be cached, and only updated every 604800 seconds (7 days). If you need the offer cache to be updated at a different frequency, change this setting. Setting it to 0 will turn off the publiser cache.

expire_sku_cache¶

Optional. Default is 604800. See expire_publisher_cache for details on why this exists. By default, the sku data will be cached, and only updated every 604800 seconds (7 days). If you need the sku cache to be updated at a different frequency, change this setting. Setting it to 0 will turn off the sku cache.

expire_version_cache¶

Optional. Default is 604800. See expire_publisher_cache for details on why this exists. By default, the version data will be cached, and only updated every 604800 seconds (7 days). If you need the version cache to be updated at a different frequency, change this setting. Setting it to 0 will turn off the version cache.

expire_group_cache¶

Optional. Default is 604800. See expire_publisher_cache for details on why this exists. By default, the resource group data will be cached, and only updated every 604800 seconds (7 days). If you need the resource group cache to be updated at a different frequency, change this setting. Setting it to 0 will turn off the resource group cache.

expire_interface_cache¶

Optional. Default is 3600. See expire_publisher_cache for details on why this exists. By default, the interface data will be cached, and only updated every 3600 seconds (1 hour). If you need the interface cache to be updated at a different frequency, change this setting. Setting it to 0 will turn off the interface cache.

expire_network_cache¶

Optional. Default is 3600. See expire_publisher_cache for details on why this exists. By default, the network data will be cached, and only updated every 3600 seconds (1 hour). If you need the network cache to be updated at a different frequency, change this setting. Setting it to 0 will turn off the network cache.

expire_subnet_cache¶

Optional. Default is 3600. See expire_publisher_cache for details on why this exists. By default, the subnet data will be cached, and only updated every 3600 seconds (1 hour). If you need the subnet cache to be updated at a different frequency, change this setting. Setting it to 0 will turn off the subnet cache.

Show Instance¶

This action is a thin wrapper around --full-query, which displays details on a single instance only. In an environment with several machines, this will save a user from having to sort through all instance data, just to examine a single instance.

Getting Started With DigitalOcean¶

DigitalOcean is a public cloud host that specializes in Linux instances.

Configuration¶

Using Salt for DigitalOcean requires a personal_access_token, an ssh_key_file, and at least one SSH key name in ssh_key_names. More ssh_key_names can be added by separating each key with a comma. The personal_access_token can be found in the DigitalOcean web interface in the "Apps & API" section. The SSH key name can be found under the "SSH Keys" section.
NOTE:

Profiles¶

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles or in the /etc/salt/cloud.profiles.d/ directory:
Locations can be obtained using the --list-locations option for the salt-cloud command:
Sizes can be obtained using the --list-sizes option for the salt-cloud command:
Images can be obtained using the --list-images option for the salt-cloud command:

Profile Specifics:¶

ssh_username¶

If using a FreeBSD image from Digital Ocean, you'll need to set the ssh_username setting to freebsd in your profile configuration.

Miscellaneous Information¶

NOTE:
NOTE:
NOTE:
NOTE:

Getting Started With Dimension Data Cloud¶

Dimension Data are a global IT Services company and form part of the NTT Group. Dimension Data provide IT-as-a-Service to customers around the globe on their cloud platform (Compute as a Service). The CaaS service is available either on one of the public cloud instances or as a private instance on premises. http://cloud.dimensiondata.com/ CaaS has its own non-standard

`API`_

, SaltStack provides a wrapper on top of this

`API`_

with common methods with other IaaS solutions and Public cloud providers. Therefore, you can use use the Dimension Data module to communicate with both the public and private clouds.

Dependencies¶

This driver requires the Python apache-libcloud and netaddr library to be installed.

Configuration¶

When you instantiate a driver you need to pass the following arguments to the driver constructor:
Possible regions:

NOTE:

Profiles¶

Cloud Profiles¶

Dimension Data images have an inbuilt size configuration, there is no list of sizes (although, if the command --list-sizes is run a default will be returned). Images can be obtained using the --list-images option for the salt-cloud command:
Locations can be obtained using the --list-locations option for the salt-cloud command:
NOTE:

Getting Started With AWS EC2¶

Amazon EC2 is a very widely used public cloud platform and one of the core platforms Salt Cloud has been built to support. Previously, the suggested driver for AWS EC2 was the aws driver. This has been deprecated in favor of the ec2 driver. Configuration using the old aws driver will still function, but that driver is no longer in active development.

Dependencies¶

This driver requires the Python requests library to be installed.

Configuration¶

The following example illustrates some of the options that can be set. These parameters are discussed in more detail below.
NOTE:

Access Credentials¶

The id and key settings may be found in the Security Credentials area of the AWS Account page: https://portal.aws.amazon.com/gp/aws/securityCredentials Both are located in the Access Credentials area of the page, under the Access Keys tab. The id setting is labeled Access Key ID, and the key setting is labeled Secret Access Key. Note: if either id or key is set to 'use-instance-role-credentials' it is assumed that Salt is running on an AWS instance, and the instance role credentials will be retrieved and used. Since both the id and key are required parameters for the AWS ec2 provider, it is recommended to set both to 'use-instance-role-credentials' for this functionality. A "static" and "permanent" Access Key ID and Secret Key can be specified, but this is not recommended. Instance role keys are rotated on a regular basis, and are the recommended method of specifying AWS credentials.

Windows Deploy Timeouts¶

For Windows instances, it may take longer than normal for the instance to be ready. In these circumstances, the provider configuration can be configured with a win_deploy_auth_retries and/or a win_deploy_auth_retry_delay setting, which default to 10 retries and a one second delay between retries. These retries and timeouts relate to validating the Administrator password once AWS provides the credentials via the AWS API.

Key Pairs¶

In order to create an instance with Salt installed and configured, a key pair will need to be created. This can be done in the EC2 Management Console, in the Key Pairs area. These key pairs are unique to a specific region. Keys in the us-east-1 region can be configured at: https://console.aws.amazon.com/ec2/home?region=us-east-1#s=KeyPairs Keys in the us-west-1 region can be configured at https://console.aws.amazon.com/ec2/home?region=us-west-1#s=KeyPairs ...and so on. When creating a key pair, the browser will prompt to download a pem file. This file must be placed in a directory accessible by Salt Cloud, with permissions set to either 0400 or 0600.

Security Groups¶

An instance on EC2 needs to belong to a security group. Like key pairs, these are unique to a specific region. These are also configured in the EC2 Management Console. Security groups for the us-east-1 region can be configured at: https://console.aws.amazon.com/ec2/home?region=us-east-1#s=SecurityGroups ...and so on. A security group defines firewall rules which an instance will adhere to. If the salt-master is configured outside of EC2, the security group must open the SSH port (usually port 22) in order for Salt Cloud to install Salt.

IAM Profile¶

Amazon EC2 instances support the concept of an instance profile, which is a logical container for the IAM role. At the time that you launch an EC2 instance, you can associate the instance with an instance profile, which in turn corresponds to the IAM role. Any software that runs on the EC2 instance is able to access AWS using the permissions associated with the IAM role. Scaffolding the profile is a 2-step configuration process:
Once the profile is created, you can use the PROFILE_NAME to configure your cloud profiles.

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles:
The profile can now be realized with a salt command:
This will create an instance named ami.example.com in EC2. The minion that is installed on this instance will have an id of ami.example.com. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

Required Settings¶

The following settings are always required for EC2:

Optional Settings¶

EC2 allows a userdata file to be passed to the instance to be created. This functionality was added to Salt in the 2015.5.0 release.
EC2 allows a location to be set for servers to be deployed in. Availability zones exist inside regions, and may be added to increase specificity.
EC2 instances can have a public or private IP, or both. When an instance is deployed, Salt Cloud needs to log into it via SSH to run the deploy script. By default, the public IP will be used for this. If the salt-cloud command is run from another EC2 instance, the private IP should be used.
Many EC2 instances do not allow remote access to the root user by default. Instead, another user must be used to run the deploy script using sudo. Some common usernames include ec2-user (for Amazon Linux), ubuntu (for Ubuntu instances), admin (official Debian) and bitnami (for images provided by Bitnami).
Multiple usernames can be provided, in which case Salt Cloud will attempt to guess the correct username. This is mostly useful in the main configuration file:
Multiple security groups can also be specified in the same fashion:
EC2 instances can be added to an AWS Placement Group by specifying the placementgroup option:
Your instances may optionally make use of EC2 Spot Instances. The following example will request that spot instances be used and your maximum bid will be $0.10. Keep in mind that different spot prices may be needed based on the current value of the various EC2 instance sizes. You can check current and past spot instance pricing via the EC2 API or AWS Console.
By default, the spot instance type is set to 'one-time', meaning it will be launched and, if it's ever terminated for whatever reason, it will not be recreated. If you would like your spot instances to be relaunched after a termination (by your or AWS), set the type to 'persistent'. NOTE: Spot instances are a great way to save a bit of money, but you do run the risk of losing your spot instances if the current price for the instance size goes above your maximum bid. The following parameters may be set in the cloud configuration file to control various aspects of the spot instance launching:
If you find that you're being throttled by AWS while polling for spot instances, you can set the following in your core cloud configuration file that will double the polling interval after each request to AWS.
See the AWS Spot Instances documentation for more information. Block device mappings enable you to specify additional EBS volumes or instance store volumes when the instance is launched. This setting is also available on each cloud profile. Note that the number of instance stores varies by instance type. If more mappings are provided than are supported by the instance type, mappings will be created in the order provided and additional mappings will be ignored. Consult the AWS documentation for a listing of the available instance stores, and device names.
You can also use block device mappings to change the size of the root device at the provisioning time. For example, assuming the root device is '/dev/sda', you can set its size to 100G by using the following configuration.
Existing EBS volumes may also be attached (not created) to your instances or you can create new EBS volumes based on EBS snapshots. To simply attach an existing volume use the volume_id parameter.
Or, to create a volume from an EBS snapshot, use the snapshot parameter.
Note that volume_id will take precedence over the snapshot parameter. Tags can be set once an instance has been launched.

Setting up a Master inside EC2¶

Salt Cloud can configure Salt Masters as well as Minions. Use the make_master setting to use this functionality.
When creating a Salt Master inside EC2 with make_master: True, or when the Salt Master is already located and configured inside EC2, by default, minions connect to the master's public IP address during Salt Cloud's provisioning process. Depending on how your security groups are defined, the minions may or may not be able to communicate with the master. In order to use the master's private IP in EC2 instead of the public IP, set the salt_interface to private_ips.

Modify EC2 Tags¶

One of the features of EC2 is the ability to tag resources. In fact, under the hood, the names given to EC2 instances by salt-cloud are actually just stored as a tag called Name. Salt Cloud has the ability to manage these tags:
It is possible to manage tags on any resource in EC2 with a Resource ID, not just instances:

Rename EC2 Instances¶

As mentioned above, EC2 instances are named via a tag. However, renaming an instance by renaming its tag will cause the salt keys to mismatch. A rename function exists which renames both the instance, and the salt keys.

Rename on Destroy¶

When instances on EC2 are destroyed, there will be a lag between the time that the action is sent, and the time that Amazon cleans up the instance. During this time, the instance still retains a Name tag, which will cause a collision if the creation of an instance with the same name is attempted before the cleanup occurs. In order to avoid such collisions, Salt Cloud can be configured to rename instances when they are destroyed. The new name will look something like:
In order to enable this, add rename_on_destroy line to the main configuration file:

Listing Images¶

Normally, images can be queried on a cloud provider by passing the --list-images argument to Salt Cloud. This still holds true for EC2:
However, the full list of images on EC2 is extremely large, and querying all of the available images may cause Salt Cloud to behave as if frozen. Therefore, the default behavior of this option may be modified, by adding an owner argument to the provider configuration:
The possible values for this setting are amazon, aws-marketplace, self, <AWS account ID> or all. The default setting is amazon. Take note that all and aws-marketplace may cause Salt Cloud to appear as if it is freezing, as it tries to handle the large amount of data. It is also possible to perform this query using different settings without modifying the configuration files. To do this, call the avail_images function directly:

EC2 Images¶

The following are lists of available AMI images, generally sorted by OS. These lists are on 3rd-party websites, are not managed by Salt Stack in any way. They are provided here as a reference for those who are interested, and contain no warranty (express or implied) from anyone affiliated with Salt Stack. Most of them have never been used, much less tested, by the Salt Stack team.

show_image¶

This is a function that describes an AMI on EC2. This will give insight as to the defaults that will be applied to an instance using a particular AMI.

show_instance¶

This action is a thin wrapper around --full-query, which displays details on a single instance only. In an environment with several machines, this will save a user from having to sort through all instance data, just to examine a single instance.

ebs_optimized¶

This argument enables switching of the EbsOptimized setting which default to 'false'. Indicates whether the instance is optimized for EBS I/O. This optimization provides dedicated throughput to Amazon EBS and an optimized configuration stack to provide optimal Amazon EBS I/O performance. This optimization isn't available with all instance types. Additional usage charges apply when using an EBS-optimized instance. This setting can be added to the profile or map file for an instance. If set to True, this setting will enable an instance to be EbsOptimized
This can also be set as a cloud provider setting in the EC2 cloud configuration:

del_root_vol_on_destroy¶

This argument overrides the default DeleteOnTermination setting in the AMI for the EBS root volumes for an instance. Many AMIs contain 'false' as a default, resulting in orphaned volumes in the EC2 account, which may unknowingly be charged to the account. This setting can be added to the profile or map file for an instance. If set, this setting will apply to the root EBS volume
This can also be set as a cloud provider setting in the EC2 cloud configuration:

del_all_vols_on_destroy¶

This argument overrides the default DeleteOnTermination setting in the AMI for the not-root EBS volumes for an instance. Many AMIs contain 'false' as a default, resulting in orphaned volumes in the EC2 account, which may unknowingly be charged to the account. This setting can be added to the profile or map file for an instance. If set, this setting will apply to any (non-root) volumes that were created by salt-cloud using the 'volumes' setting. The volumes will not be deleted under the following conditions * If a volume is detached before terminating the instance * If a volume is created without this setting and attached to the instance
This can also be set as a cloud provider setting in the EC2 cloud configuration:
The setting for this may be changed on all volumes of an existing instance using one of the following commands:
The setting for this may be changed on a volume on an existing instance using one of the following commands:

EC2 Termination Protection¶

EC2 allows the user to enable and disable termination protection on a specific instance. An instance with this protection enabled cannot be destroyed. The EC2 driver adds a show_term_protect action to the regular EC2 functionality.

Alternate Endpoint¶

Normally, EC2 endpoints are build using the region and the service_url. The resulting endpoint would follow this pattern:
This results in an endpoint that looks like:
There are other projects that support an EC2 compatibility layer, which this scheme does not account for. This can be overridden by specifying the endpoint directly in the main cloud configuration file:

Volume Management¶

The EC2 driver has several functions and actions for management of EBS volumes.

Creating Volumes¶

A volume may be created, independent of an instance. A zone must be specified. A size or a snapshot may be specified (in GiB). If neither is given, a default size of 10 GiB will be used. If a snapshot is given, the size of the snapshot will be used. The following parameters may also be set (when providing a snapshot OR size):

Attaching Volumes¶

Unattached volumes may be attached to an instance. The following values are required; name or instance_id, volume_id, and device.

Show a Volume¶

The details about an existing volume may be retrieved.

Detaching Volumes¶

An existing volume may be detached from an instance.

Deleting Volumes¶

A volume that is not attached to an instance may be deleted.

Managing Key Pairs¶

The EC2 driver has the ability to manage key pairs.

Creating a Key Pair¶

A key pair is required in order to create an instance. When creating a key pair with this function, the return data will contain a copy of the private key. This private key is not stored by Amazon, will not be obtainable past this point, and should be stored immediately.

Importing a Key Pair¶

Show a Key Pair¶

This function will show the details related to a key pair, not including the private key itself (which is not stored by Amazon).

Delete a Key Pair¶

This function removes the key pair from Amazon.

Launching instances into a VPC¶

Simple launching into a VPC¶

In the amazon web interface, identify the id or the name of the subnet into which your image should be created. Then, edit your cloud.profiles file like so:-
Note that 'subnetid' takes precedence over 'subnetname', but 'securitygroupid' and 'securitygroupname' are merged toghether to generate a single list for SecurityGroups of instances.

Specifying interface properties¶

New in version 2014.7.0. Launching into a VPC allows you to specify more complex configurations for the network interfaces of your virtual machines, for example:-
Note that it is an error to assign a 'subnetid', 'subnetname', 'securitygroupid' or 'securitygroupname' to a profile where the interfaces are manually configured like this. These are both really properties of each network interface, not of the machine itself.

Getting Started With GoGrid¶

GoGrid is a public cloud host that supports Linux and Windows.

Configuration¶

To use Salt Cloud with GoGrid log into the GoGrid web interface and create an API key. Do this by clicking on "My Account" and then going to the API Keys tab. The apikey and the sharedsecret configuration parameters need to be set in the configuration file to enable interfacing with GoGrid:
NOTE:
NOTE:

Profiles¶

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles or in the /etc/salt/cloud.profiles.d/ directory:
Sizes can be obtained using the --list-sizes option for the salt-cloud command:
Images can be obtained using the --list-images option for the salt-cloud command:

Assigning IPs¶

New in version 2015.8.0. The GoGrid API allows IP addresses to be manually assigned. Salt Cloud supports this functionality by allowing an IP address to be specified using the assign_public_ip argument. This likely makes the most sense inside a map file, but it may also be used inside a profile.

Getting Started With Google Compute Engine¶

Google Compute Engine (GCE) is Google-infrastructure as a service that lets you run your large-scale computing workloads on virtual machines. This document covers how to use Salt Cloud to provision and manage your virtual machines hosted within Google's infrastructure. You can find out more about GCE and other Google Cloud Platform services at https://cloud.google.com.

Dependencies¶

Google Compute Engine Setup¶

Provider Configuration¶

Set up the provider cloud config at /etc/salt/cloud.providers or /etc/salt/cloud.providers.d/*.conf:
NOTE:
NOTE:

Profile Configuration¶

Set up an initial profile at /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/*.conf:
The profile can be realized now with a salt command:
This will create an salt minion instance named gce-instance in GCE. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Once the instance has been created with a salt-minion installed, connectivity to it can be verified with Salt:

GCE Specific Settings¶

Consult the sample profile below for more information about GCE specific settings. Some of them are mandatory and are properly labeled below but typically also include a hard-coded default.

Initial Profile¶

Set up an initial profile at /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/gce.conf:

image¶

Image is used to define what Operating System image should be used to for the instance. Examples are Debian 7 (wheezy) and CentOS 6. Required.

size¶

A 'size', in GCE terms, refers to the instance's 'machine type'. See the on-line documentation for a complete list of GCE machine types. Required.

location¶

A 'location', in GCE terms, refers to the instance's 'zone'. GCE has the notion of both Regions (e.g. us-central1, europe-west1, etc) and Zones (e.g. us-central1-a, us-central1-b, etc). Required.

network¶

Use this setting to define the network resource for the instance. All GCE projects contain a network named 'default' but it's possible to use this setting to create instances belonging to a different network resource.

tags¶

GCE supports instance/network tags and this setting allows you to set custom tags. It should be a list of strings and must be parse-able by the python ast.literal_eval() function to convert it to a python list.

metadata¶

GCE supports instance metadata and this setting allows you to set custom metadata. It should be a hash of key/value strings and parse-able by the python ast.literal_eval() function to convert it to a python dictionary.

use_persistent_disk¶

Use this setting to ensure that when new instances are created, they will use a persistent disk to preserve data between instance terminations and re-creations.

delete_boot_pd¶

In the event that you wish the boot persistent disk to be permanently deleted when you destroy an instance, set delete_boot_pd to True.

ssh_interface¶

New in version 2015.5.0. Specify whether to use public or private IP for deploy script. Valid options are:

external_ip¶

Per instance setting: Used a named fixed IP address to this host. Valid options are:
Optionally, pass the name of a GCE address to use a fixed IP address. If the address does not already exist, it will be created.

ex_disk_type¶

GCE supports two different disk types, pd-standard and pd-ssd. The default disk type setting is pd-standard. To specify using an SSD disk, set pd-ssd as the value. New in version 2014.7.0.

ip_forwarding¶

GCE instances can be enabled to use IP Forwarding. When set to True, this options allows the instance to send/receive non-matching src/dst packets. Default is False. New in version 2015.8.1.

Profile with scopes¶

Scopes can be specified by setting the optional ex_service_accounts key in your cloud profile. The following example enables the bigquery scope.
Email can also be specified as an (optional) parameter.
There can be multiple entries for scopes since ex-service_accounts accepts a list of dictionaries. For more information refer to the libcloud documentation on specifying service account scopes.

SSH Remote Access¶

GCE instances do not allow remote access to the root user by default. Instead, another user must be used to run the deploy script using sudo. Append something like this to /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/*.conf:
If you have not already used this SSH key to login to instances in this GCE project you will also need to add the public key to your projects metadata at https://cloud.google.com/console. You could also add it via the metadata setting too:

Single instance details¶

This action is a thin wrapper around --full-query, which displays details on a single instance only. In an environment with several machines, this will save a user from having to sort through all instance data, just to examine a single instance.

Destroy, persistent disks, and metadata¶

As noted in the provider configuration, it's possible to force the boot persistent disk to be deleted when you destroy the instance. The way that this has been implemented is to use the instance metadata to record the cloud profile used when creating the instance. When destroy is called, if the instance contains a salt-cloud-profile key, it's value is used to reference the matching profile to determine if delete_boot_pd is set to True. Be aware that any GCE instances created with salt cloud will contain this custom salt-cloud-profile metadata entry.

List various resources¶

It's also possible to list several GCE resources similar to what can be done with other providers. The following commands can be used to list GCE zones (locations), machine types (sizes), and images.

Persistent Disk¶

The Compute Engine provider provides functions via salt-cloud to manage your Persistent Disks. You can create and destroy disks as well as attach and detach them from running instances.

Create¶

When creating a disk, you can create an empty disk and specify its size (in GB), or specify either an 'image' or 'snapshot'.

Delete¶

Deleting a disk only requires the name of the disk to delete

Attach¶

Attaching a disk to an existing instance is really an 'action' and requires both an instance name and disk name. It's possible to use this ation to create bootable persistent disks if necessary. Compute Engine also supports attaching a persistent disk in READ_ONLY mode to multiple instances at the same time (but then cannot be attached in READ_WRITE to any instance).

Detach¶

Detaching a disk is also an action against an instance and only requires the name of the disk. Note that this does not safely sync and umount the disk from the instance. To ensure no data loss, you must first make sure the disk is unmounted from the instance.

Show disk¶

It's also possible to look up the details for an existing disk with either a function or an action.

Create snapshot¶

You can take a snapshot of an existing disk's content. The snapshot can then in turn be used to create other persistent disks. Note that to prevent data corruption, it is strongly suggested that you unmount the disk prior to taking a snapshot. You must name the snapshot and provide the name of the disk.

Delete snapshot¶

You can delete a snapshot when it's no longer needed by specifying the name of the snapshot.

Show snapshot¶

Use this function to look up information about the snapshot.

Networking¶

Compute Engine supports multiple private networks per project. Instances within a private network can easily communicate with each other by an internal DNS service that resolves instance names. Instances within a private network can also communicate with either directly without needing special routing or firewall rules even if they span different regions/zones. Networks also support custom firewall rules. By default, traffic between instances on the same private network is open to all ports and protocols. Inbound SSH traffic (port 22) is also allowed but all other inbound traffic is blocked.

Create network¶

New networks require a name and CIDR range. New instances can be created and added to this network by setting the network name during create. It is not possible to add/remove existing instances to a network.

Destroy network¶

Destroy a network by specifying the name. Make sure that there are no instances associated with the network prior to deleting it or you'll have a bad day.

Show network¶

Specify the network name to view information about the network.

Create address¶

Create a new named static IP address in a region.

Delete address¶

Delete an existing named fixed IP address.

Show address¶

View details on a named address.

Create firewall¶

You'll need to create custom firewall rules if you want to allow other traffic than what is described above. For instance, if you run a web service on your instances, you'll need to explicitly allow HTTP and/or SSL traffic. The firewall rule must have a name and it will use the 'default' network unless otherwise specified with a 'network' attribute. Firewalls also support instance tags for source/destination

Delete firewall¶

Deleting a firewall rule will prevent any previously allowed traffic for the named firewall rule.

Show firewall¶

Use this function to review an existing firewall rule's information.

Load Balancer¶

Compute Engine possess a load-balancer feature for splitting traffic across multiple instances. Please reference the documentation for a more complete description. The load-balancer functionality is slightly different than that described in Google's documentation. The concept of TargetPool and ForwardingRule are consolidated in salt-cloud/libcloud. HTTP Health Checks are optional.

HTTP Health Check¶

HTTP Health Checks can be used as a means to toggle load-balancing across instance members, or to detect if an HTTP site is functioning. A common use-case is to set up a health check URL and if you want to toggle traffic on/off to an instance, you can temporarily have it return a non-200 response. A non-200 response to the load-balancer's health check will keep the LB from sending any new traffic to the "down" instance. Once the instance's health check URL beings returning 200-responses, the LB will again start to send traffic to it. Review Compute Engine's documentation for allowable parameters. You can use the following salt-cloud functions to manage your HTTP health checks.

Load-balancer¶

When creating a new load-balancer, it requires a name, region, port range, and list of members. There are other optional parameters for protocol, and list of health checks. Deleting or showing details about the LB only requires the name.
You can also create a load balancer using a named fixed IP addressby specifying the name of the address. If the address does not exist yet it will be created.

Attach and Detach LB¶

It is possible to attach or detach an instance from an existing load-balancer. Both the instance and load-balancer must exist before using these functions.

Getting Started With HP Cloud¶

HP Cloud is a major public cloud platform and uses the libcloud openstack driver. The current version of OpenStack that HP Cloud uses is Havana. When an instance is booted, it must have a floating IP added to it in order to connect to it and further below you will see an example that adds context to this statement.

Set up a cloud provider configuration file¶

To use the openstack driver for HP Cloud, set up the cloud provider configuration file as in the example shown below: /etc/salt/cloud.providers.d/hpcloud.conf:
The subsequent example that follows is using the openstack driver. NOTE:

Compute Region¶

Originally, HP Cloud, in its OpenStack Essex version (1.0), had 3 availability zones in one region, US West (region-a.geo-1), which each behaved each as a region. This has since changed, and the current OpenStack Havana version of HP Cloud (1.1) now has simplified this and now has two regions to choose from:

Authentication¶

The user is the same user as is used to log into the HP Cloud management UI. The tenant can be found in the upper left under "Project/Region/Scope". It is often named the same as user albeit with a -project1 appended. The password is of course what you created your account with. The management UI also has other information such as being able to select US East or US West.

Set up a cloud profile config file¶

The profile shown below is a know working profile for an Ubuntu instance. The profile configuration file is stored in the following location: /etc/salt/cloud.profiles.d/hp_ae1_ubuntu.conf:
Some important things about the example above:

Launch an instance¶

To instantiate a machine based on this profile (example):
After several minutes, this will create an instance named ubuntu_instance_1 running in HP Cloud in the US East region and will set up the minion and then return information about the instance once completed.

Manage the instance¶

Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

SSH to the instance¶

Additionally, the instance can be accessed via SSH using the floating IP assigned to it

Using a private IP¶

Alternatively, in the cloud profile, using the private IP to log into the instance to set up the minion is another option, particularly if salt-cloud is running within the cloud on an instance that is on the same network with all the other instances (minions) The example below is a modified version of the previous example. Note the use of ssh_interface:
With this setup, salt-cloud will use the private IP address to ssh into the instance and set up the salt-minion

Getting Started With Joyent¶

Joyent is a public cloud host that supports SmartOS, Linux, FreeBSD, and Windows.

Dependencies¶

This driver requires the Python requests library to be installed.

Configuration¶

The Joyent cloud requires three configuration parameters. The user name and password that are used to log into the Joyent system, and the location of the private ssh key associated with the Joyent account. The ssh key is needed to send the provisioning commands up to the freshly created virtual machine.
NOTE:

Profiles¶

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles or in the /etc/salt/cloud.profiles.d/ directory:
Sizes can be obtained using the --list-sizes option for the salt-cloud command:
Images can be obtained using the --list-images option for the salt-cloud command:

SmartDataCenter¶

This driver can also be used with the Joyent SmartDataCenter project. More details can be found at: Using SDC requires that an api_host_suffix is set. The default value for this is .api.joyentcloud.com. All characters, including the leading ., should be included:

Miscellaneous Configuration¶

The following configuration items can be set in either provider or profile confuration files.

use_ssl¶

When set to True (the default), attach https:// to any URL that does not already have http:// or https:// included at the beginning. The best practice is to leave the protocol out of the URL, and use this setting to manage it.

verify_ssl¶

When set to True (the default), the underlying web library will verify the SSL certificate. This should only be set to False for debugging.`

Getting Started With Linode¶

Linode is a public cloud host with a focus on Linux instances. Starting with the 2015.8.0 release of Salt, the Linode driver uses Linode's native REST API. There are no external dependencies required to use the Linode driver, other than a Linode account.

Provider Configuration¶

Linode requires a single API key, but the default root password for new instances also needs to be set. The password needs to be eight characters and contain lowercase, uppercase, and numbers. Set up the provider cloud configuration file at /etc/salt/cloud.providers or /etc/salt/cloud.providers.d/*.conf.
NOTE:

Profile Configuration¶

Linode profiles require a provider, size, image, and location. Set up an initial profile at /etc/salt/cloud.profiles or in the /etc/salt/cloud.profiles.d/ directory:
The profile can be realized now with a salt command:
This will create an salt minion instance named linode-instance in Linode. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Once the instance has been created with a salt-minion installed, connectivity to it can be verified with Salt:

Listing Sizes¶

Sizes can be obtained using the --list-sizes option for the salt-cloud command:

Listing Images¶

Images can be obtained using the --list-images option for the salt-cloud command:

Listing Locations¶

Locations can be obtained using the --list-locations option for the salt-cloud command:

Linode Specific Settings¶

There are several options outlined below that can be added to either the Linode provider of profile configuration files. Some options are mandatory and are properly labeled below but typically also include a hard-coded default.

image¶

Image is used to define what Operating System image should be used for the instance. Examples are Ubuntu 14.04 LTS and CentOS 7. This option should be specified in the profile config. Required.

location¶

Location is used to define which Linode data center the instance will reside in. Required.

size¶

Size is used to define the instance's "plan type" which includes memory, storage, and price. Required.

assign_private_ip¶

New in version 2016.3.0. Assigns a private IP address to a Linode when set to True. Default is False.

ssh_interface¶

New in version 2016.3.0. Specify whether to use a public or private IP for the deploy script. Valid options are:
If specifying private_ips, the Linodes must be hosted within the same data center and have the Network Helper enabled on your entire account. The instance that is running the Salt-Cloud provisioning command must also have a private IP assigned to it. Newer accounts created on Linode have the Network Helper setting enabled by default, account-wide. Legacy accounts do not have this setting enabled by default. To enable the Network Helper on your Linode account, please see Linode's Network Helper documentation. If you're running into problems, be sure to restart the instance that is running Salt Cloud after adding its own private IP address or enabling the Network Helper.

clonefrom¶

Setting the clonefrom option to a specified instance enables the new instance to be cloned from the named instance instead of being created from scratch. If using the clonefrom option, it is likely a good idea to also specify script_args: -C if a minion is already installed on the to-be-cloned instance. See the Cloning section below for more information.

Cloning¶

To clone a Linode, add a profile with a clonefrom key, and a script_args: -C. clonefrom should be the name of the Linode that is the source for the clone. script_args: -C passes a -C to the salt-bootstrap script, which only configures the minion and doesn't try to install a new copy of salt-minion. This way the minion gets new keys and the keys get pre-seeded on the master, and the /etc/salt/minion file has the right minion 'id:' declaration. Cloning requires a post 2015-02-01 salt-bootstrap. It is safest to clone a stopped machine. To stop a machine run
To create a new machine based on another machine, add an entry to your linode cloud profile that looks like this:
Then run salt-cloud as normal, specifying -p li-clone. The profile name can be anything; It doesn't have to be li-clone. clonefrom: is the name of an existing machine in Linode from which to clone. Script_args: -C -F is necessary to avoid re-deploying Salt via salt-bootstrap. -C will just re-deploy keys so the new minion will not have a duplicate key or minion_id on the Master, and -F will force a rewrite of the Minion config file on the new Minion. If -F isn't provided, the new Minion will have the machine_to_clone's Minion ID, instead of its own Minion ID, which can cause problems. NOTE:
If the machine_to_clone does not have Salt installed on it, refrain from using the script_args: -C -F altogether, because the new machine will need to have Salt installed.

Getting Started With LXC¶

The LXC module is designed to install Salt in an LXC container on a controlled and possibly remote minion. In other words, Salt will connect to a minion, then from that minion:

Limitations¶

Operation¶

Salt's LXC support does use lxc.init via the lxc.cloud_init_interface and seeds the minion via seed.mkconfig. You can provide to those lxc VMs a profile and a network profile like if you were directly using the minion module. Order of operation:

Provider configuration¶

Here is a simple provider configuration:
NOTE:

Profile configuration¶

Please read tutorial-lxc before anything else. And specially tutorial-lxc-profiles. Here are the options to configure your containers:
Using profiles:
Using inline profiles (eg to override the network bridge):
Using a lxc template instead of a clone:
Static ip:
DHCP:

Driver Support¶

Getting Started with OpenNebula¶

OpenNebula is an open-source solution for the comprehensive management of virtualized data centers to enable the mixed use of private, public, and hybrid IaaS clouds.

Dependencies¶

The driver requires Python's lxml library to be installed. It also requires an OpenNebula installation running version 4.12 or greater.

Configuration¶

The following example illustrates some of the options that can be set. These parameters are discussed in more detail below.

Access Credentials¶

The Salt Cloud driver for OpenNebula was written using OpenNebula's native XML RPC API. Every interaction with OpenNebula's API requires a username and password to make the connection from the machine running Salt Cloud to API running on the OpenNebula instance. Based on the access credentials passed in, OpenNebula filters the commands that the user can perform or the information for which the user can query. For example, the images that a user can view with a --list-images command are the images that the connected user and the connected user's groups can access.

Key Pairs¶

Salt Cloud needs to be able to access a virtual machine in order to install the Salt Minion by using a public/private key pair. The virtual machine will need to be seeded with the public key, which is laid down by the OpenNebula template. Salt Cloud then uses the corresponding private key, provided by the private_key setting in the cloud provider file, to SSH into the new virtual machine. To seed the virtual machine with the public key, the public key must be added to the OpenNebula template. If using the OpenNebula web interface, navigate to the template, then click Update. Click the Context tab. Under the Network & SSH section, click Add SSH Contextualization and paste the public key in the Public Key box. Don't forget to save your changes by clicking the green Update button. NOTE:

Cloud Profiles¶

Set up an initial profile at either /etc/salt/cloud.profiles or the /etc/salt/cloud.profiles.d/ directory.
The profile can now be realized with a salt command:
This will create a new instance named my-new-vm in OpenNebula. The minion that is installed on this instance will have a minion id of my-new-vm. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:
OpenNebula uses an image --> template --> virtual machine paradigm where the template draws on the image, or disk, and virtual machines are created from templates. Because of this, there is no need to define a size in the cloud profile. The size of the virtual machine is defined in the template.

Required Settings¶

The following settings are always required for OpenNebula:

Required Settings for VM Deployment¶

The settings defined in the Required Settings section are required for all interactions with OpenNebula. However, when deploying a virtual machine via Salt Cloud, an additional setting, private_key, is also required:

Listing Images¶

Images can be queried on OpenNebula by passing the --list-images argument to Salt Cloud:

Listing Locations¶

In OpenNebula, locations are defined as hosts. Locations, or "hosts", can be querried on OpenNebula by passing the --list-locations argument to Salt Cloud:

Listing Sizes¶

Sizes are defined by templates in OpenNebula. As such, the --list-sizes call returns an empty dictionary since there are no sizes to return.

Additional OpenNebula API Functionality¶

The Salt Cloud driver for OpenNebula was written using OpenNebula's native XML RPC API. As such, many --function and --action calls were added to the OpenNebula driver to enhance support for an OpenNebula infrastructure with additional control from Salt Cloud. See the OpenNebula function definitions for more information.

Access via DNS entry instead of IP¶

Some OpenNebula installations do not assign IP addresses to new VMs, instead they establish the new VM's hostname based on OpenNebula's name of the VM, and then allocate an IP out of DHCP with dynamic DNS attaching the hostname. This driver supports this behavior by adding the entry fqdn_base to the driver configuration or the OpenNebula profile with a value matching the base fully-qualified domain. For example:

Getting Started With OpenStack¶

OpenStack is one the most popular cloud projects. It's an open source project to build public and/or private clouds. You can use Salt Cloud to launch OpenStack instances.

Dependencies¶

Configuration¶

NOTE:

Using nova client to get information from OpenStack¶

One of the best ways to get information about OpenStack is using the novaclient python package (available in pypi as python-novaclient). The client configuration is a set of environment variables that you can get from the Dashboard. Log in and then go to Project -> Access & security -> API Access and download the "OpenStack RC file". Then:
In the nova endpoints output you can see the information about compute_region and compute_name.

Compute Region¶

It depends on the OpenStack cluster that you are using. Please, have a look at the previous sections.

Authentication¶

The user and password is the same user as is used to log into the OpenStack Dashboard.

Profiles¶

Here is an example of a profile:
The following list explains some of the important properties.
For more information concerning cloud profiles, see here.

change_password¶

If no ssh_key_file is provided, and the server already exists, change_password will use the api to change the root password of the server so that it can be bootstrapped.

userdata_file¶

Use userdata_file to specify the userdata file to upload for use with cloud-init if available.

Getting Started With Parallels¶

Parallels Cloud Server is a product by Parallels that delivers a cloud hosting solution. The PARALLELS module for Salt Cloud enables you to manage instances hosted using PCS. Further information can be found at: http://www.parallels.com/products/pcs/



NOTE:

Access Credentials¶

The user, password, and url will be provided to you by your cloud host. These are all required in order for the PARALLELS driver to work.

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/parallels.conf:
The profile can be realized now with a salt command:
This will create an instance named myubuntu on the cloud host. The minion that is installed on this instance will have an id of myubuntu. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

Required Settings¶

The following settings are always required for PARALLELS:

Optional Settings¶

Unlike other cloud providers in Salt Cloud, Parallels does not utilize a size setting. This is because Parallels allows the end-user to specify a more detailed configuration for their instances than is allowed by many other cloud hosts. The following options are available to be used in a profile, with their default settings listed.

Getting Started With ProfitBricks¶

ProfitBricks provides an enterprise-grade Infrastructure as a Service (IaaS) solution that can be managed through a browser-based "Data Center Designer" (DCD) tool or via an easy to use API. A unique feature of the ProfitBricks platform is that it allows you to define your own settings for cores, memory, and disk size without being tied to a particular server size.

Dependencies¶

Configuration¶

NOTE:

Virtual Data Center¶

ProfitBricks uses the concept of Virtual Data Centers. These are logically separated from one another and allow you to have a self-contained environment for all servers, volumes, networking, snapshots, and so forth. A list of existing virtual data centers can be retrieved with the following command:

Authentication¶

The username and password are the same as those used to log into the ProfitBricks "Data Center Designer".

Profiles¶

Here is an example of a profile:
The following list explains some of the important properties.




For more information concerning cloud profiles, see here.

Getting Started With Proxmox¶

Proxmox Virtual Environment is a complete server virtualization management solution, based on OpenVZ(in Proxmox up to 3.4)/LXC(from Proxmox 4.0 and up) and full virtualization with KVM. Further information can be found at: http://www.proxmox.org/

Dependencies¶

Please note: This module allows you to create OpenVZ/LXC containers and KVM VMs, but installing Salt on it will only be done on containers rather than a KVM virtual machine.

NOTE:

Access Credentials¶

The user, password, and url will be provided to you by your cloud host. These are all required in order for the PROXMOX driver to work.

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/proxmox.conf:

The profile can be realized now with a salt command:
This will create an instance named myubuntu on the cloud host. The minion that is installed on this instance will have a hostname of myubuntu. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

Required Settings¶

The following settings are always required for PROXMOX:

Optional Settings¶

Unlike other cloud providers in Salt Cloud, Proxmox does not utilize a size setting. This is because Proxmox allows the end-user to specify a more detailed configuration for their instances, than is allowed by many other cloud providers. The following options are available to be used in a profile, with their default settings listed.

QEMU¶

Some functionnalities works differently if you use 'qemu' as technology. In order to create a new VM with qemu, you need to specificy some more information. You can also clone a qemu template which already is on your Proxmox server. QEMU profile file (for a new VM):
More information about these parameters can be found on Proxmox API ( http://pve.proxmox.com/pve2-api-doc/) under the 'POST' method of nodes/{node}/qemu QEMU profile file (for a clone):
More information can be found on Proxmox API under the 'POST' method of /nodes/{node}/qemu/{vmid}/clone NOTE:

Getting Started With Rackspace¶

Rackspace is a major public cloud platform which may be configured using either the rackspace or the openstack driver, depending on your needs. Please note that the rackspace driver is intended only for 1st gen instances, aka, "the old cloud" at Rackspace. It is required for 1st gen instances, but will not work with OpenStack-based instances. Unless you explicitly have a reason to use it, it is highly recommended that you use the openstack driver instead.

Dependencies¶

Configuration¶

The settings that follow are for using Rackspace with the openstack driver, and will not work with the rackspace driver. NOTE:

Compute Region¶

Rackspace currently has six compute regions which may be used:
Note: Currently the LON region is only available with a UK account, and UK accounts cannot access other regions

Authentication¶

The user is the same user as is used to log into the Rackspace Control Panel. The tenant and apikey can be found in the API Keys area of the Control Panel. The apikey will be labeled as API Key (and may need to be generated), and tenant will be labeled as Cloud Account Number. An initial profile can be configured in /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/rackspace.conf:
To instantiate a machine based on this profile:
This will create a virtual machine at Rackspace with the name myinstance. This operation may take several minutes to complete, depending on the current load at the Rackspace data center. Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

RackConnect Environments¶

Rackspace offers a hybrid hosting configuration option called RackConnect that allows you to use a physical firewall appliance with your cloud servers. When this service is in use the public_ip assigned by nova will be replaced by a NAT ip on the firewall. For salt-cloud to work properly it must use the newly assigned "access ip" instead of the Nova assigned public ip. You can enable that capability by adding this to your profiles:

Managed Cloud Environments¶

Rackspace offers a managed service level of hosting. As part of the managed service level you have the ability to choose from base of lamp installations on cloud server images. The post build process for both the base and the lamp installations used Chef to install things such as the cloud monitoring agent and the cloud backup agent. It also takes care of installing the lamp stack if selected. In order to prevent the post installation process from stomping over the bootstrapping you can add the below to your profiles.

First and Next Generation Images¶

Rackspace provides two sets of virtual machine images, first, and next generation. As of 0.8.9 salt-cloud will default to using the next generation images. To force the use of first generation images, on the profile configuration please add:

Private Subnets¶

By default salt-cloud will not add Rackspace private networks to new servers. To enable a private network to a server instantiated by salt cloud, add the following section to the provider file (typically /etc/salt/cloud.providers.d/rackspace.conf)
To get the Rackspace private network ID, go to Networking, Networks and hover over the private network name. The order of the networks in the above code block does not map to the order of the ethernet devices on newly created servers. Public IP will always be first ( eth0 ) followed by servicenet ( eth1 ) and then private networks. Enabling the private network per above gives the option of using the private subnet for all master-minion communication, including the bootstrap install of salt-minion. To enable the minion to use the private subnet, update the master: line in the minion: section of the providers file. To configure the master to only listen on the private subnet IP, update the interface: line in the /etc/salt/master file to be the private subnet IP of the salt master.

Getting Started With Scaleway¶

Scaleway is the first IaaS host worldwide to offer an ARM based cloud. It’s the ideal platform for horizontal scaling with BareMetal SSD servers. The solution provides on demand resources: it comes with on-demand SSD storage, movable IPs , images, security group and an Object Storage solution. https://scaleway.com

Configuration¶

Using Salt for Scaleway, requires an access key and an API token. API tokens are unique identifiers associated with your Scaleway account. To retrieve your access key and API token, log-in to the Scaleway control panel, open the pull-down menu on your account name and click on "My Credentials" link. If you do not have API token you can create one by clicking the "Create New Token" button on the right corner.
NOTE:

Profiles¶

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles or in the /etc/salt/cloud.profiles.d/ directory:
Images can be obtained using the --list-images option for the salt-cloud command:
Execute a query and return all information about the nodes running on configured cloud providers using the -Q option for the salt-cloud command:
NOTE:

Getting Started With Saltify¶

The Saltify driver is a new, experimental driver for installing Salt on existing machines (virtual or bare metal).

Dependencies¶

The Saltify driver has no external dependencies.

Configuration¶

Because the Saltify driver does not use an actual cloud provider host, it has a simple provider configuration. The only thing that is required to be set is the driver name, and any other potentially useful information, like the location of the salt-master:

Profiles¶

Saltify requires a profile to be configured for each machine that needs Salt installed. The initial profile can be set up at /etc/salt/cloud.profiles or in the /etc/salt/cloud.profiles.d/ directory. Each profile requires both an ssh_host and an ssh_username key parameter as well as either an key_filename or a password. Profile configuration example:
The machine can now be "Salted" with the following command:
This will install salt on the machine specified by the cloud profile, salt-this-machine, and will give the machine the minion id of my-machine. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Once a salt-minion has been successfully installed on the instance, connectivity to it can be verified with Salt:

Using Map Files¶

The settings explained in the section above may also be set in a map file. An example of how to use the Saltify driver with a map file follows:
Note: When using a cloud map with the Saltify driver, the name of the profile to use, in this case make_salty, must be defined in a profile config. For example:
The machines listed in the map file can now be "Salted" by applying the following salt map command:
This command will install salt on the machines specified in the map and will give each machine their minion id of my-instance-0 and my-instance-1, respectively. If the command was executed on the salt-master, its Salt key will automatically be signed on the master. Connectivity to the new "Salted" instances can now be verified with Salt:

Getting Started With SoftLayer¶

SoftLayer is a public cloud host, and baremetal hardware hosting service.

Dependencies¶

The SoftLayer driver for Salt Cloud requires the softlayer package, which is available at PyPI: https://pypi.python.org/pypi/SoftLayer This package can be installed using pip or easy_install:

Configuration¶

Set up the cloud config at /etc/salt/cloud.providers:
NOTE:

Access Credentials¶

The user setting is the same user as is used to log into the SoftLayer Administration area. The apikey setting is found inside the Admin area after logging in:

Profiles¶

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles:
Most of the above items are required; optional items are specified below.

image¶

Images to build an instance can be found using the --list-images option:
The setting used will be labeled as template.

cpu_number¶

This is the number of CPU cores that will be used for this instance. This number may be dependent upon the image that is used. For instance:
Note that the template (meaning, the image option) for both of these is the same, but the names suggests how many CPU cores are supported.

ram¶

This is the amount of memory, in megabytes, that will be allocated to this instance.

disk_size¶

The amount of disk space that will be allocated to this image, in gigabytes.

Using Multiple Disks¶

New in version 2015.8.1. SoftLayer allows up to 5 disks to be specified for a virtual machine upon creation. Multiple disks can be specified either as a list or a comma-delimited string. The first disk_size specified in the string or list will be the first disk size assigned to the VM. List Example:
String Example:

local_disk¶

When true the disks for the computing instance will be provisioned on the host which it runs, otherwise SAN disks will be provisioned.

hourly_billing¶

When true the computing instance will be billed on hourly usage, otherwise it will be billed on a monthly basis.

domain¶

The domain name that will be used in the FQDN (Fully Qualified Domain Name) for this instance. The domain setting will be used in conjunction with the instance name to form the FQDN.

use_fqdn¶

If set to True, the Minion will be identified by the FQDN (Fully Qualified Domain Name) which is a result of combining the domain configuration value and the Minion name specified either via the CLI or a map file rather than only using the short host name, or Minion ID. Default is False. New in version 2016.3.0. For example, if the value of domain is example.com and a new VM was created via the CLI with salt-cloud -p base_softlayer_ubuntu my-vm, the resulting Minion ID would be my-vm.example.com. NOTE:
Example output displaying the SoftLayer hostname quirk mentioned in the note above (note the Minion ID is my-vm.example.com, but the VM to be destroyed is listed with its short hostname, my-vm):

location¶

Images to build an instance can be found using the --list-locations option:

max_net_speed¶

Specifies the connection speed for the instance's network components. This setting is optional. By default, this is set to 10.

post_uri¶

Specifies the uri location of the script to be downloaded and run after the instance is provisioned. New in version 2015.8.1. Example:

public_vlan¶

If it is necessary for an instance to be created within a specific frontend VLAN, the ID for that VLAN can be specified in either the provider or profile configuration. This ID can be queried using the list_vlans function, as described below. This setting is optional.

private_vlan¶

If it is necessary for an instance to be created within a specific backend VLAN, the ID for that VLAN can be specified in either the provider or profile configuration. This ID can be queried using the list_vlans function, as described below. This setting is optional.

private_network¶

If a server is to only be used internally, meaning it does not have a public VLAN associated with it, this value would be set to True. This setting is optional. The default is False.

private_ssh¶

Whether to run the deploy script on the server using the public IP address or the private IP address. If set to True, Salt Cloud will attempt to SSH into the new server using the private IP address. The default is False. This settiong is optional.

global_identifier¶

When creating an instance using a custom template, this option is set to the corresponding value obtained using the list_custom_images function. This option will not be used if an image is set, and if an image is not set, it is required. The profile can be realized now with a salt command:
Using the above configuration, this will create myserver.example.com. Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

Cloud Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles:
Most of the above items are required; optional items are specified below.

image¶

Images to build an instance can be found using the --list-images option:
A list of id`s and names will be provided. The `name will describe the operating system and architecture. The id will be the setting to be used in the profile.

size¶

Sizes to build an instance can be found using the --list-sizes option:
A list of id`s and names will be provided. The `name will describe the speed and quantity of CPU cores, and the amount of memory that the hardware will contain. The id will be the setting to be used in the profile.

hdd¶

There is currently only one size of hard disk drive (HDD) that is available for hardware instances on SoftLayer:
The hdd setting in the profile should be 1267. Other sizes may be added in the future.

location¶

Locations to build an instance can be found using the --list-images option:
A list of IDs and names will be provided. The location will describe the location in human terms. The id will be the setting to be used in the profile.

domain¶

The domain name that will be used in the FQDN (Fully Qualified Domain Name) for this instance. The domain setting will be used in conjunction with the instance name to form the FQDN.

vlan¶

If it is necessary for an instance to be created within a specific VLAN, the ID for that VLAN can be specified in either the provider or profile configuration. This ID can be queried using the list_vlans function, as described below.

port_speed¶

Specifies the speed for the instance's network port. This setting refers to an ID within the SoftLayer API, which sets the port speed. This setting is optional. The default is 273, or, 100 Mbps Public & Private Networks. The following settings are available:

bandwidth¶

Specifies the network bandwidth available for the instance. This setting refers to an ID within the SoftLayer API, which sets the bandwidth. This setting is optional. The default is 248, or, 5000 GB Bandwidth. The following settings are available:

Actions¶

The following actions are currently supported by the SoftLayer Salt Cloud driver.

show_instance¶

This action is a thin wrapper around --full-query, which displays details on a single instance only. In an environment with several machines, this will save a user from having to sort through all instance data, just to examine a single instance.

Functions¶

The following functions are currently supported by the SoftLayer Salt Cloud driver.

list_vlans¶

This function lists all VLANs associated with the account, and all known data from the SoftLayer API concerning those VLANs.
The id returned in this list is necessary for the vlan option when creating an instance.

list_custom_images¶

This function lists any custom templates associated with the account, that can be used to create a new instance.
The globalIdentifier returned in this list is necessary for the global_identifier option when creating an image using a custom template.

Optional Products for SoftLayer HW¶

The softlayer_hw driver supports the ability to add optional products, which are supported by SoftLayer's API. These products each have an ID associated with them, that can be passed into Salt Cloud with the optional_products option:
These values can be manually obtained by looking at the source of an order page on the SoftLayer web interface. For convenience, many of these values are listed here:

Public Secondary IP Addresses¶

Primary IPv6 Addresses¶

Public Static IPv6 Addresses¶

OS-Specific Addon¶

Control Panel Software¶

Database Software¶

Anti-Virus & Spyware Protection¶

Insurance¶

Monitoring¶

Notification¶

Advanced Monitoring¶

Response¶

Intrusion Detection & Protection¶

Hardware & Software Firewalls¶

Getting Started with VEXXHOST¶

VEXXHOST is a cloud computing host which provides Canadian cloud computing services which are based in Monteral and use the libcloud OpenStack driver. VEXXHOST currently runs the Havana release of OpenStack. When provisioning new instances, they automatically get a public IP and private IP address. Therefore, you do not need to assign a floating IP to access your instance after it's booted.

Cloud Provider Configuration¶

To use the openstack driver for the VEXXHOST public cloud, you will need to set up the cloud provider configuration file as in the example below: /etc/salt/cloud.providers.d/vexxhost.conf: In order to use the VEXXHOST public cloud, you will need to setup a cloud provider configuration file as in the example below which uses the OpenStack driver.
NOTE:

Authentication¶

All of the authentication fields that you need can be found by logging into your VEXXHOST customer center. Once you've logged in, you will need to click on "CloudConsole" and then click on "API Credentials".

Cloud Profile Configuration¶

In order to get the correct image UUID and the instance type to use in the cloud profile, you can run the following command respectively:
Once you have that, you can go ahead and create a new cloud profile. This profile will build an Ubuntu 12.04 LTS nb.2G instance. /etc/salt/cloud.profiles.d/vh_ubuntu1204_2G.conf:

Provision an instance¶

To create an instance based on the sample profile that we created above, you can run the following salt-cloud command.
Typically, instances are provisioned in under 30 seconds on the VEXXHOST public cloud. After the instance provisions, it will be set up a minion and then return all the instance information once it's complete. Once the instance has been setup, you can test connectivity to it by running the following command:
You can now continue to provision new instances and they will all automatically be set up as minions of the master you've defined in the configuration file.

Getting Started With Virtualbox¶

The Virtualbox cloud module allows you to manage a local Virtualbox hypervisor. Remote hypervisors may come later on.

Dependencies¶

The virtualbox module for Salt Cloud requires the Virtualbox SDK which is contained in a virtualbox installation from https://www.virtualbox.org/wiki/Downloads

Configuration¶

The Virtualbox cloud module just needs to use the virtualbox driver for now. Virtualbox will be run as the running user. /etc/salt/cloud.providers or /etc/salt/cloud.providers.d/virtualbox.conf:

Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/virtualbox.conf:

So far only machines can only be cloned and automatically provisioned by Salt Cloud.

Provisioning¶

In order to provision when creating a new machine power_on and deploy have to be True. Furthermore to connect to the VM ssh_username and password will have to be set. sudo and sudo_password are the credentials for getting root access in order to deploy salt

Actions¶

Functions¶

Getting Started With VMware¶

New in version 2015.5.4. Author: Nitin Madhok <nmadhok@clemson.edu> The VMware cloud module allows you to manage VMware ESX, ESXi, and vCenter.

Dependencies¶

The vmware module for Salt Cloud requires the pyVmomi package, which is available at PyPI: https://pypi.python.org/pypi/pyvmomi This package can be installed using pip or easy_install:
NOTE:
NOTE:

Configuration¶

The VMware cloud module needs the vCenter or ESX/ESXi URL, username and password to be set up in the cloud configuration at /etc/salt/cloud.providers or /etc/salt/cloud.providers.d/vmware.conf:
NOTE:
NOTE:

Profiles¶

Set up an initial profile at /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/vmware.conf:

Cloning a VM¶

Cloning VMs/templates is the easiest and the preferred way to work with VMs using the VMware driver. NOTE:
Example of a minimal profile:
When cloning a VM, all the profile configuration parameters are optional and the configuration gets inherited from the clone. Example to add/resize a disk:
Depending on the configuration of the VM that is getting cloned, the disk in the resulting clone will differ. NOTE:
Example to reconfigure the memory and number of vCPUs:

Cloning a Template¶

Cloning a template works similar to cloning a VM except for the fact that a resource pool or cluster must be specified additionally in the profile. Example of a minimal profile:

Cloning from a Snapshot¶

New in version 2016.3.5. Cloning from a snapshot requires that one of the supported options be set in the cloud profile. Supported options are createNewChildDiskBacking, moveChildMostDiskBacking, moveAllDiskBackingsAndAllowSharing and moveAllDiskBackingsAndDisallowSharing. Example of a minimal profile:

Creating a VM¶

New in version 2016.3.0. Creating a VM from scratch means that more configuration has to be specified in the profile because there is no place to inherit configuration from. NOTE:
Example of a minimal profile:
NOTE:
Example of a complete profile:
NOTE:

Specifying disk backing mode¶

New in version 2016.3.5. Disk backing mode can now be specified when cloning a VM. This option can be set in the cloud profile as shown in example below:

Miscellaneous Options¶

Miscellaneous Salt Cloud Options¶

This page describes various miscellaneous options available in Salt Cloud

Deploy Script Arguments¶

Custom deploy scripts are unlikely to need custom arguments to be passed to them, but salt-bootstrap has been extended quite a bit, and this may be necessary. script_args can be specified in either the profile or the map file, to pass arguments to the deploy script:
This has also been tested to work with pipes, if needed:

Selecting the File Transport¶

By default, Salt Cloud uses SFTP to transfer files to Linux hosts. However, if SFTP is not available, or specific SCP functionality is needed, Salt Cloud can be configured to use SCP instead.

Sync After Install¶

Salt allows users to create custom modules, grains, and states which can be synchronised to minions to extend Salt with further functionality. This option will inform Salt Cloud to synchronise your custom modules, grains, states or all these to the minion just after it has been created. For this to happen, the following line needs to be added to the main cloud configuration file:
The available options for this setting are:

Setting Up New Salt Masters¶

It has become increasingly common for users to set up multi-hierarchal infrastructures using Salt Cloud. This sometimes involves setting up an instance to be a master in addition to a minion. With that in mind, you can now lay down master configuration on a machine by specifying master options in the profile or map file.
This will cause Salt Cloud to generate master keys for the instance, and tell salt-bootstrap to install the salt-master package, in addition to the salt-minion package. The default master configuration is usually appropriate for most users, and will not be changed unless specific master configuration has been added to the profile or map:

Setting Up a Salt Syndic with Salt Cloud¶

In addition to setting up new Salt Masters, syndic`s can also be provisioned using Salt Cloud. In order to set up a Salt Syndic via Salt Cloud, a Salt Master needs to be installed on the new machine and a master configuration file needs to be set up using the ``make_master` setting. This setting can be defined either in a profile config file or in a map file:
To install the Salt Syndic, the only other specification that needs to be configured is the syndic_master key to specify the location of the master that the syndic will be reporting to. This modification needs to be placed in the master setting, which can be configured either in the profile, provider, or /etc/salt/cloud config file:
Many other Salt Syndic configuration settings and specifications can be passed through to the new syndic machine via the master configuration setting. See the syndic documentation for more information.

SSH Port¶

By default ssh port is set to port 22. If you want to use a custom port in provider, profile, or map blocks use ssh_port option. New in version 2015.5.0.

SSH Port¶

By default ssh port is set to port 22. If you want to use a custom port in provider, profile, or map blocks use ssh_port option.

Delete SSH Keys¶

When Salt Cloud deploys an instance, the SSH pub key for the instance is added to the known_hosts file for the user that ran the salt-cloud command. When an instance is deployed, a cloud host generally recycles the IP address for the instance. When Salt Cloud attempts to deploy an instance using a recycled IP address that has previously been accessed from the same machine, the old key in the known_hosts file will cause a conflict. In order to mitigate this issue, Salt Cloud can be configured to remove old keys from the known_hosts file when destroying the node. In order to do this, the following line needs to be added to the main cloud configuration file:

Keeping /tmp/ Files¶

When Salt Cloud deploys an instance, it uploads temporary files to /tmp/ for salt-bootstrap to put in place. After the script has run, they are deleted. To keep these files around (mostly for debugging purposes), the --keep-tmp option can be added:
For those wondering why /tmp/ was used instead of /root/, this had to be done for images which require the use of sudo, and therefore do not allow remote root logins, even for file transfers (which makes /root/ unavailable).

Hide Output From Minion Install¶

By default Salt Cloud will stream the output from the minion deploy script directly to STDOUT. Although this can been very useful, in certain cases you may wish to switch this off. The following config option is there to enable or disable this output:

Connection Timeout¶

There are several stages when deploying Salt where Salt Cloud needs to wait for something to happen. The VM getting it's IP address, the VM's SSH port is available, etc. If you find that the Salt Cloud defaults are not enough and your deployment fails because Salt Cloud did not wait log enough, there are some settings you can tweak.
You can tweak these settings globally, per cloud provider, or event per profile definition.

wait_for_ip_timeout¶

The amount of time Salt Cloud should wait for a VM to start and get an IP back from the cloud host. Default: varies by cloud provider ( between 5 and 25 minutes)

wait_for_ip_interval¶

The amount of time Salt Cloud should sleep while querying for the VM's IP. Default: varies by cloud provider ( between .5 and 10 seconds)

ssh_connect_timeout¶

The amount of time Salt Cloud should wait for a successful SSH connection to the VM. Default: varies by cloud provider (between 5 and 15 minutes)

wait_for_passwd_timeout¶

The amount of time until an ssh connection can be established via password or ssh key. Default: varies by cloud provider (mostly 15 seconds)

wait_for_passwd_maxtries¶

The number of attempts to connect to the VM until we abandon. Default: 15 attempts

wait_for_fun_timeout¶

Some cloud drivers check for an available IP or a successful SSH connection using a function, namely, SoftLayer, and SoftLayer-HW. So, the amount of time Salt Cloud should retry such functions before failing. Default: 15 minutes.

wait_for_spot_timeout¶

The amount of time Salt Cloud should wait before an EC2 Spot instance is available. This setting is only available for the EC2 cloud driver. Default: 10 minutes

Salt Cloud Cache¶

Salt Cloud can maintain a cache of node data, for supported providers. The following options manage this functionality.

update_cachedir¶

On supported cloud providers, whether or not to maintain a cache of nodes returned from a --full-query. The data will be stored in msgpack format under <SALT_CACHEDIR>/cloud/active/<DRIVER>/<PROVIDER>/<NODE_NAME>.p. This setting can be True or False.

diff_cache_events¶

When the cloud cachedir is being managed, if differences are encountered between the data that is returned live from the cloud host and the data in the cache, fire events which describe the changes. This setting can be True or False. Some of these events will contain data which describe a node. Because some of the fields returned may contain sensitive data, the cache_event_strip_fields configuration option exists to strip those fields from the event return.
The following are events that can be fired based on this data.

salt/cloud/minionid/cache_node_new¶

A new node was found on the cloud host which was not listed in the cloud cachedir. A dict describing the new node will be contained in the event.

salt/cloud/minionid/cache_node_missing¶

A node that was previously listed in the cloud cachedir is no longer available on the cloud host.

salt/cloud/minionid/cache_node_diff¶

One or more pieces of data in the cloud cachedir has changed on the cloud host. A dict containing both the old and the new data will be contained in the event.

SSH Known Hosts¶

Normally when bootstrapping a VM, salt-cloud will ignore the SSH host key. This is because it does not know what the host key is before starting (because it doesn't exist yet). If strict host key checking is turned on without the key in the known_hosts file, then the host will never be available, and cannot be bootstrapped. If a provider is able to determine the host key before trying to bootstrap it, that provider's driver can add it to the known_hosts file, and then turn on strict host key checking. This can be set up in the main cloud configuration file (normally /etc/salt/cloud) or in the provider-specific configuration file:
If this is not set, it will default to /dev/null, and strict host key checking will be turned off. It is highly recommended that this option is not set, unless the user has verified that the provider supports this functionality, and that the image being used is capable of providing the necessary information. At this time, only the EC2 driver supports this functionality.

SSH Agent¶

New in version 2015.5.0. If the ssh key is not stored on the server salt-cloud is being run on, set ssh_agent, and salt-cloud will use the forwarded ssh-agent to authenticate.

File Map Upload¶

New in version 2014.7.0. The file_map option allows an arbitrary group of files to be uploaded to the target system before running the deploy script. This functionality requires a provider uses salt.utils.cloud.bootstrap(), which is currently limited to the ec2, gce, openstack and nova drivers. The file_map can be configured globally in /etc/salt/cloud, or in any cloud provider or profile file. For example, to upload an extra package or a custom deploy script, a cloud profile using file_map might look like:

Troubleshooting Steps¶

Troubleshooting Salt Cloud¶

This page describes various steps for troubleshooting problems that may arise while using Salt Cloud.

Virtual Machines Are Created, But Do Not Respond¶

Are TCP ports 4505 and 4506 open on the master? This is easy to overlook on new masters. Information on how to open firewall ports on various platforms can be found here.

Generic Troubleshooting Steps¶

This section describes a set of instructions that are useful to a large number of situations, and are likely to solve most issues that arise.

Debug Mode¶

Frequently, running Salt Cloud in debug mode will reveal information about a deployment which would otherwise not be obvious:
Keep in mind that a number of messages will appear that look at first like errors, but are in fact intended to give developers factual information to assist in debugging. A number of messages that appear will be for cloud providers that you do not have configured; in these cases, the message usually is intended to confirm that they are not configured.

Salt Bootstrap¶

By default, Salt Cloud uses the Salt Bootstrap script to provision instances: This script is packaged with Salt Cloud, but may be updated without updating the Salt package:

The Bootstrap Log¶

If the default deploy script was used, there should be a file in the /tmp/ directory called bootstrap-salt.log. This file contains the full output from the deployment, including any errors that may have occurred.

Keeping Temp Files¶

Salt Cloud uploads minion-specific files to instances once they are available via SSH, and then executes a deploy script to put them into the correct place and install Salt. The --keep-tmp option will instruct Salt Cloud not to remove those files when finished with them, so that the user may inspect them for problems:
By default, Salt Cloud will create a directory on the target instance called /tmp/.saltcloud/. This directory should be owned by the user that is to execute the deploy script, and should have permissions of 0700. Most cloud hosts are configured to use root as the default initial user for deployment, and as such, this directory and all files in it should be owned by the root user. The /tmp/.saltcloud/ directory should the following files:

Unprivileged Primary Users¶

Some cloud hosts, most notably EC2, are configured with a different primary user. Some common examples are ec2-user, ubuntu, fedora, and bitnami. In these cases, the /tmp/.saltcloud/ directory and all files in it should be owned by this user. Some cloud hosts, such as EC2, are configured to not require these users to provide a password when using the sudo command. Because it is more secure to require sudo users to provide a password, other hosts are configured that way. If this instance is required to provide a password, it needs to be configured in Salt Cloud. A password for sudo to use may be added to either the provider configuration or the profile configuration:

/tmp/ is Mounted as noexec¶

It is more secure to mount the /tmp/ directory with a noexec option. This is uncommon on most cloud hosts, but very common in private environments. To see if the /tmp/ directory is mounted this way, run the following command:
The if the output of this command includes a line that looks like this, then the /tmp/ directory is mounted as noexec:
If this is the case, then the deploy_command will need to be changed in order to run the deploy script through the sh command, rather than trying to execute it directly. This may be specified in either the provider or the profile config:
Please note that by default, Salt Cloud will place its files in a directory called /tmp/.saltcloud/. This may be also be changed in the provider or profile configuration:
If this directory is changed, then the deploy_command need to be changed in order to reflect the tmp_dir configuration.

Executing the Deploy Script Manually¶

If all of the files needed for deployment were successfully uploaded to the correct locations, and contain the correct permissions and ownerships, the deploy script may be executed manually in order to check for other issues:

Extending Salt Cloud¶

Writing Cloud Driver Modules¶

Salt Cloud runs on a module system similar to the main Salt project. The modules inside saltcloud exist in the salt/cloud/clouds directory of the salt source. There are two basic types of cloud modules. If a cloud host is supported by libcloud, then using it is the fastest route to getting a module written. The Apache Libcloud project is located at: http://libcloud.apache.org/ Not every cloud host is supported by libcloud. Additionally, not every feature in a supported cloud host is necessarily supported by libcloud. In either of these cases, a module can be created which does not rely on libcloud.

All Driver Modules¶

The following functions are required by all driver modules, whether or not they are based on libcloud.

The __virtual__() Function¶

This function determines whether or not to make this cloud module available upon execution. Most often, it uses get_configured_provider() to determine if the necessary configuration has been set up. It may also check for necessary imports, to decide whether to load the module. In most cases, it will return a True or False value. If the name of the driver used does not match the filename, then that name should be returned instead of True. An example of this may be seen in the Azure module: https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/msazure.py

The get_configured_provider() Function¶

This function uses config.is_provider_configured() to determine wither all required information for this driver has been configured. The last value in the list of required settings should be followed by a comma.

Libcloud Based Modules¶

Writing a cloud module based on libcloud has two major advantages. First of all, much of the work has already been done by the libcloud project. Second, most of the functions necessary to Salt have already been added to the Salt Cloud project.

The create() Function¶

The most important function that does need to be manually written is the create() function. This is what is used to request a virtual machine to be created by the cloud host, wait for it to become available, and then (optionally) log in and install Salt on it. A good example to follow for writing a cloud driver module based on libcloud is the module provided for Linode: https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/linode.py The basic flow of a create() function is as follows:
At various points throughout this function, events may be fired on the Salt event bus. Four of these events, which are described below, are required. Other events may be added by the user, where appropriate. When the create() function is called, it is passed a data structure called vm_. This dict contains a composite of information describing the virtual machine to be created. A dict called __opts__ is also provided by Salt, which contains the options used to run Salt Cloud, as well as a set of configuration and environment variables. The first thing the create() function must do is fire an event stating that it has started the create process. This event is tagged salt/cloud/<vm name>/creating. The payload contains the names of the VM, profile, and provider. A set of kwargs is then usually created, to describe the parameters required by the cloud host to request the virtual machine. An event is then fired to state that a virtual machine is about to be requested. It is tagged as salt/cloud/<vm name>/requesting. The payload contains most or all of the parameters that will be sent to the cloud host. Any private information (such as passwords) should not be sent in the event. After a request is made, a set of deploy kwargs will be generated. These will be used to install Salt on the target machine. Windows options are supported at this point, and should be generated, even if the cloud host does not currently support Windows. This will save time in the future if the host does eventually decide to support Windows. An event is then fired to state that the deploy process is about to begin. This event is tagged salt/cloud/<vm name>/deploying. The payload for the event will contain a set of deploy kwargs, useful for debugging purposed. Any private data, including passwords and keys (including public keys) should be stripped from the deploy kwargs before the event is fired. If any Windows options have been passed in, the salt.utils.cloud.deploy_windows() function will be called. Otherwise, it will be assumed that the target is a Linux or Unix machine, and the salt.utils.cloud.deploy_script() will be called. Both of these functions will wait for the target machine to become available, then the necessary port to log in, then a successful login that can be used to install Salt. Minion configuration and keys will then be uploaded to a temporary directory on the target by the appropriate function. On a Windows target, the Windows Minion Installer will be run in silent mode. On a Linux/Unix target, a deploy script ( bootstrap-salt.sh, by default) will be run, which will auto-detect the operating system, and install Salt using its native package manager. These do not need to be handled by the developer in the cloud module. The salt.utils.cloud.validate_windows_cred() function has been extended to take the number of retries and retry_delay parameters in case a specific cloud host has a delay between providing the Windows credentials and the credentials being available for use. In their create() function, or as a a sub-function called during the creation process, developers should use the win_deploy_auth_retries and win_deploy_auth_retry_delay parameters from the provider configuration to allow the end-user the ability to customize the number of tries and delay between tries for their particular host. After the appropriate deploy function completes, a final event is fired which describes the virtual machine that has just been created. This event is tagged salt/cloud/<vm name>/created. The payload contains the names of the VM, profile, and provider. Finally, a dict (queried from the provider) which describes the new virtual machine is returned to the user. Because this data is not fired on the event bus it can, and should, return any passwords that were returned by the cloud host. In some cases (for example, Rackspace), this is the only time that the password can be queried by the user; post-creation queries may not contain password information (depending upon the host).

The libcloudfuncs Functions¶

A number of other functions are required for all cloud hosts. However, with libcloud-based modules, these are all provided for free by the libcloudfuncs library. The following two lines set up the imports:
And then a series of declarations will make the necessary functions available within the cloud module.
If necessary, these functions may be replaced by removing the appropriate declaration line, and then adding the function as normal. These functions are required for all cloud modules, and are described in detail in the next section.

Non-Libcloud Based Modules¶

In some cases, using libcloud is not an option. This may be because libcloud has not yet included the necessary driver itself, or it may be that the driver that is included with libcloud does not contain all of the necessary features required by the developer. When this is the case, some or all of the functions in libcloudfuncs may be replaced. If they are all replaced, the libcloud imports should be absent from the Salt Cloud module. A good example of a non-libcloud driver is the DigitalOcean driver: https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/digital_ocean.py

The create() Function¶

The create() function must be created as described in the libcloud-based module documentation.

The get_size() Function¶

This function is only necessary for libcloud-based modules, and does not need to exist otherwise.

The get_image() Function¶

This function is only necessary for libcloud-based modules, and does not need to exist otherwise.

The avail_locations() Function¶

This function returns a list of locations available, if the cloud host uses multiple data centers. It is not necessary if the cloud host uses only one data center. It is normally called using the --list-locations option.

The avail_images() Function¶

This function returns a list of images available for this cloud provider. There are not currently any known cloud providers that do not provide this functionality, though they may refer to images by a different name (for example, "templates"). It is normally called using the --list-images option.

The avail_sizes() Function¶

This function returns a list of sizes available for this cloud provider. Generally, this refers to a combination of RAM, CPU, and/or disk space. This functionality may not be present on some cloud providers. For example, the Parallels module breaks down RAM, CPU, and disk space into separate options, whereas in other providers, these options are baked into the image. It is normally called using the --list-sizes option.

The script() Function¶

This function builds the deploy script to be used on the remote machine. It is likely to be moved into the salt.utils.cloud library in the near future, as it is very generic and can usually be copied wholesale from another module. An excellent example is in the Azure driver.

The destroy() Function¶

This function irreversibly destroys a virtual machine on the cloud provider. Before doing so, it should fire an event on the Salt event bus. The tag for this event is salt/cloud/<vm name>/destroying. Once the virtual machine has been destroyed, another event is fired. The tag for that event is salt/cloud/<vm name>/destroyed. This function is normally called with the -d options:

The list_nodes() Function¶

This function returns a list of nodes available on this cloud provider, using the following fields:
No other fields should be returned in this function, and all of these fields should be returned, even if empty. The private_ips and public_ips fields should always be of a list type, even if empty, and the other fields should always be of a str type. This function is normally called with the -Q option:

The list_nodes_full() Function¶

All information available about all nodes should be returned in this function. The fields in the list_nodes() function should also be returned, even if they would not normally be provided by the cloud provider. This is because some functions both within Salt and 3rd party will break if an expected field is not present. This function is normally called with the -F option:

The list_nodes_select() Function¶

This function returns only the fields specified in the query.selection option in /etc/salt/cloud. Because this function is so generic, all of the heavy lifting has been moved into the salt.utils.cloud library. A function to call list_nodes_select() still needs to be present. In general, the following code can be used as-is:
However, depending on the cloud provider, additional variables may be required. For instance, some modules use a conn object, or may need to pass other options into list_nodes_full(). In this case, be sure to update the function appropriately:
This function is normally called with the -S option:

The show_instance() Function¶

This function is used to display all of the information about a single node that is available from the cloud provider. The simplest way to provide this is usually to call list_nodes_full(), and return just the data for the requested node. It is normally called as an action:

Actions and Functions¶

Extra functionality may be added to a cloud provider in the form of an --action or a --function. Actions are performed against a cloud instance/virtual machine, and functions are performed against a cloud provider.

Actions¶

Actions are calls that are performed against a specific instance or virtual machine. The show_instance action should be available in all cloud modules. Actions are normally called with the -a option:
Actions must accept a name as a first argument, may optionally support any number of kwargs as appropriate, and must accept an argument of call, with a default of None. Before performing any other work, an action should normally verify that it has been called correctly. It may then perform the desired feature, and return useful information to the user. A basic action looks like:
Please note that generic kwargs, if used, are passed through to actions as kwargs and not **kwargs. An example of this is seen in the Functions section.

Functions¶

Functions are called that are performed against a specific cloud provider. An optional function that is often useful is show_image, which describes an image in detail. Functions are normally called with the -f option:
A function may accept any number of kwargs as appropriate, and must accept an argument of call with a default of None. Before performing any other work, a function should normally verify that it has been called correctly. It may then perform the desired feature, and return useful information to the user. A basic function looks like:
Take note that generic kwargs are passed through to functions as kwargs and not **kwargs.

Cloud deployment scripts¶

Salt Cloud works primarily by executing a script on the virtual machines as soon as they become available. The script that is executed is referenced in the cloud profile as the script. In older versions, this was the os argument. This was changed in 0.8.2. A number of legacy scripts exist in the deploy directory in the saltcloud source tree. The preferred method is currently to use the salt-bootstrap script. A stable version is included with each release tarball starting with 0.8.4. The most updated version can be found at: https://github.com/saltstack/salt-bootstrap Note that, somewhat counter-intuitively, this script is referenced as bootstrap-salt in the configuration. You can specify a deploy script in the cloud configuration file ( /etc/salt/cloud by default):
Or in a provider:
Or in a profile:
If you do not specify a script argument in your cloud configuration file, provider configuration or profile configuration, the "bootstrap-salt" script will be used by default.

Other Generic Deploy Scripts¶

If you want to be assured of always using the latest Salt Bootstrap script, there are a few generic templates available in the deploy directory of your saltcloud source tree:
These are example scripts which were designed to be customized, adapted, and refit to meet your needs. One important use of them is to pass options to the salt-bootstrap script, such as updating to specific git tags.

Custom Deploy Scripts¶

If the Salt Bootstrap script does not meet your needs, you may write your own. The script should be written in shell and is a Jinja template. Deploy scripts need to execute a number of functions to do a complete salt setup. These functions include:
A good, well commented example of this process is the Fedora deployment script: https://github.com/saltstack/salt-cloud/blob/master/saltcloud/deploy/Fedora.sh A number of legacy deploy scripts are included with the release tarball. None of them are as functional or complete as Salt Bootstrap, and are still included for academic purposes. Custom deploy scripts are picked up from /etc/salt/cloud.deploy.d by default, but you can change the location of deploy scripts with the cloud configuration deploy_scripts_search_path. Additionally, if your deploy script has the extension .sh, you can leave out the extension in your configuration. For example, if your custom deploy script is located in /etc/salt/cloud.deploy.d/my_deploy.sh, you could specify it in a cloud profile like this:
You're also free to use the full path to the script if you like. Using full paths, your script doesn't have to live inside /etc/salt/cloud.deploy.d or whatever you've configured with deploy_scripts_search_path.

Post-Deploy Commands¶

Once a minion has been deployed, it has the option to run a salt command. Normally, this would be the state.apply, which would finish provisioning the VM. Another common option (for testing) is to use test.ping. This is configured in the main cloud config file:
This is currently considered to be experimental functionality, and may not work well with all cloud hosts. If you experience problems with Salt Cloud hanging after Salt is deployed, consider using Startup States instead: http://docs.saltstack.com/ref/states/startup.html

Skipping the Deploy Script¶

For whatever reason, you may want to skip the deploy script altogether. This results in a VM being spun up much faster, with absolutely no configuration. This can be set from the command line:
Or it can be set from the main cloud config file:
Or it can be set from the provider's configuration:
Or even on the VM's profile settings:
The default for deploy is True. In the profile, you may also set the script option to None:
This is the slowest option, since it still uploads the None deploy script and executes it.

Updating Salt Bootstrap¶

Salt Bootstrap can be updated automatically with salt-cloud:
Bear in mind that this updates to the latest stable version from: https://bootstrap.saltstack.com/stable/bootstrap-salt.sh To update Salt Bootstrap script to the develop version, run the following command on the Salt minion host with salt-cloud installed:
Or just download the file manually:

Keeping /tmp/ Files¶

When Salt Cloud deploys an instance, it uploads temporary files to /tmp/ for salt-bootstrap to put in place. After the script has run, they are deleted. To keep these files around (mostly for debugging purposes), the --keep-tmp option can be added:
For those wondering why /tmp/ was used instead of /root/, this had to be done for images which require the use of sudo, and therefore do not allow remote root logins, even for file transfers (which makes /root/ unavailable).

Deploy Script Arguments¶

Custom deploy scripts are unlikely to need custom arguments to be passed to them, but salt-bootstrap has been extended quite a bit, and this may be necessary. script_args can be specified in either the profile or the map file, to pass arguments to the deploy script:
This has also been tested to work with pipes, if needed:

Using Salt Cloud from Salt¶

Using the Salt Modules for Cloud¶

In addition to the salt-cloud command, Salt Cloud can be called from Salt, in a variety of different ways. Most users will be interested in either the execution module or the state module, but it is also possible to call Salt Cloud as a runner. Because the actual work will be performed on a remote minion, the normal Salt Cloud configuration must exist on any target minion that needs to execute a Salt Cloud command. Because Salt Cloud now supports breaking out configuration into individual files, the configuration is easily managed using Salt's own file.managed state function. For example, the following directories allow this configuration to be managed easily:

Minion Keys¶

Keep in mind that when creating minions, Salt Cloud will create public and private minion keys, upload them to the minion, and place the public key on the machine that created the minion. It will not attempt to place any public minion keys on the master, unless the minion which was used to create the instance is also the Salt Master. This is because granting arbitrary minions access to modify keys on the master is a serious security risk, and must be avoided.

Execution Module¶

The cloud module is available to use from the command line. At the moment, almost every standard Salt Cloud feature is available to use. The following commands are available:

list_images¶

This command is designed to show images that are available to be used to create an instance using Salt Cloud. In general they are used in the creation of profiles, but may also be used to create an instance directly (see below). Listing images requires a provider to be configured, and specified:

list_sizes¶

This command is designed to show sizes that are available to be used to create an instance using Salt Cloud. In general they are used in the creation of profiles, but may also be used to create an instance directly (see below). This command is not available for all cloud providers; see the provider-specific documentation for details. Listing sizes requires a provider to be configured, and specified:

list_locations¶

This command is designed to show locations that are available to be used to create an instance using Salt Cloud. In general they are used in the creation of profiles, but may also be used to create an instance directly (see below). This command is not available for all cloud providers; see the provider-specific documentation for details. Listing locations requires a provider to be configured, and specified:

query¶

This command is used to query all configured cloud providers, and display all instances associated with those accounts. By default, it will run a standard query, returning the following fields:
This command may also be used to perform a full query or a select query, as described below. The following usages are available:

full_query¶

This command behaves like the query command, but lists all information concerning each instance as provided by the cloud provider, in addition to the fields returned by the query command.

select_query¶

This command behaves like the query command, but only returned select fields as defined in the /etc/salt/cloud configuration file. A sample configuration for this section of the file might look like:
This configuration would only return the id and key_name fields, for those cloud providers that support those two fields. This would be called using the following command:

profile¶

This command is used to create an instance using a profile that is configured on the target minion. Please note that the profile must be configured before this command can be used with it.
Please note that the execution module does not run in parallel mode. Using multiple minions to create instances can effectively perform parallel instance creation.

create¶

This command is similar to the profile command, in that it is used to create a new instance. However, it does not require a profile to be pre-configured. Instead, all of the options that are normally configured in a profile are passed directly to Salt Cloud to create the instance:
Please note that the execution module does not run in parallel mode. Using multiple minions to create instances can effectively perform parallel instance creation.

destroy¶

This command is used to destroy an instance or instances. This command will search all configured providers and remove any instance(s) which matches the name(s) passed in here. The results of this command are non-reversable and should be used with caution.

action¶

This command implements both the action and the function commands used in the standard salt-cloud command. If one of the standard action commands is used, an instance name must be provided. If one of the standard function commands is used, a provider configuration must be named.
The actions available are largely dependent upon the module for the specific cloud provider. The following actions are available for all cloud providers:

State Module¶

A subset of the execution module is available through the cloud state module. Not all functions are currently included, because there is currently insufficient code for them to perform statefully. For example, a command to create an instance may be issued with a series of options, but those options cannot currently be statefully managed. Additional states to manage these options will be released at a later time.

cloud.present¶

This state will ensure that an instance is present inside a particular cloud provider. Any option that is normally specified in the cloud.create execution module and function may be declared here, but only the actual presence of the instance will be managed statefully.

cloud.profile¶

This state will ensure that an instance is present inside a particular cloud provider. This function calls the cloud.profile execution module and function, but as with cloud.present, only the actual presence of the instance will be managed statefully.

cloud.absent¶

This state will ensure that an instance (identified by name) does not exist in any of the cloud providers configured on the target minion. Please note that this state is non-reversable and may be considered especially destructive when issued as a cloud state.

Runner Module¶

The cloud runner module is executed on the master, and performs actions using the configuration and Salt modules on the master itself. This means that any public minion keys will also be properly accepted by the master. Using the functions in the runner module is no different than using those in the execution module, outside of the behavior described in the above paragraph. The following functions are available inside the runner:
Outside of the standard usage of salt-run itself, commands are executed as usual:

CloudClient¶

The execution, state, and runner modules ultimately all use the CloudClient library that ships with Salt. To use the CloudClient library locally (either on the master or a minion), create a client object and issue a command against it:

Reactor¶

Examples of using the reactor with Salt Cloud are available in the ec2-autoscale-reactor and salt-cloud-reactor formulas.

Feature Comparison¶

Feature Matrix¶

A number of features are available in most cloud hosts, but not all are available everywhere. This may be because the feature isn't supported by the cloud host itself, or it may only be that the feature has not yet been added to Salt Cloud. In a handful of cases, it is because the feature does not make sense for a particular cloud provider (Saltify, for instance). This matrix shows which features are available in which cloud hosts, as far as Salt Cloud is concerned. This is not a comprehensive list of all features available in all cloud hosts, and should not be used to make business decisions concerning choosing a cloud host. In most cases, adding support for a feature to Salt Cloud requires only a little effort.

Legacy Drivers¶

Both AWS and Rackspace are listed as "Legacy". This is because those drivers have been replaced by other drivers, which are generally the preferred method for working with those hosts. The EC2 driver should be used instead of the AWS driver, when possible. The OpenStack driver should be used instead of the Rackspace driver, unless the user is dealing with instances in "the old cloud" in Rackspace.

Note for Developers¶

When adding new features to a particular cloud host, please make sure to add the feature to this table. Additionally, if you notice a feature that is not properly listed here, pull requests to fix them is appreciated.

Standard Features¶

These are features that are available for almost every cloud host.

AWS (Legacy)

CloudStack

Digital Ocean

EC2

GoGrid

JoyEnt

Linode

OpenStack

Parallels

Rackspace (Legacy)

Saltify

Softlayer

Softlayer Hardware

Aliyun

Query

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Full Query

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Selective Query

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

List Sizes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

List Images

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

List Locations

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

create

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

destroy

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Actions¶

These are features that are performed on a specific instance, and require an instance name to be passed in. For example:

Actions

AWS (Legacy)

CloudStack

Digital Ocean

EC2

GoGrid

JoyEnt

Linode

OpenStack

Parallels

Rackspace (Legacy)

Saltify

Softlayer

Softlayer Hardware

Aliyun

attach_volume

Yes

create_attach_volumes

Yes

Yes

del_tags

Yes

Yes

delvol_on_destroy

Yes

detach_volume

Yes

disable_term_protect

Yes

Yes

enable_term_protect

Yes

Yes

get_tags

Yes

Yes

keepvol_on_destroy

Yes

list_keypairs

Yes

rename

Yes

Yes

set_tags

Yes

Yes

show_delvol_on_destroy

Yes

show_instance

Yes

Yes

Yes

Yes

Yes

Yes

Yes

show_term_protect

Yes

start

Yes

Yes

Yes

Yes

Yes

Yes

stop

Yes

Yes

Yes

Yes

Yes

Yes

take_action

Yes

Functions¶

These are features that are performed against a specific cloud provider, and require the name of the provider to be passed in. For example:

Functions

AWS (Legacy)

CloudStack

Digital Ocean

EC2

GoGrid

JoyEnt

Linode

OpenStack

Parallels

Rackspace (Legacy)

Saltify

Softlayer

Softlayer Hardware

Aliyun

block_device_mappings

Yes

create_keypair

Yes

create_volume

Yes

delete_key

Yes

delete_keypair

Yes

delete_volume

Yes

get_image

Yes

Yes

Yes

Yes

get_ip

Yes

get_key

Yes

get_keyid

Yes

get_keypair

Yes

get_networkid

Yes

get_node

Yes

get_password

Yes

get_size

Yes

Yes

Yes

get_spot_config

Yes

get_subnetid

Yes

iam_profile

Yes

Yes

Yes

import_key

Yes

key_list

Yes

keyname

Yes

Yes

list_availability_zones

Yes

Yes

list_custom_images

Yes

list_keys

Yes

list_nodes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

list_nodes_full

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

list_nodes_select

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

list_vlans

Yes

Yes

rackconnect

Yes

reboot

Yes

Yes

Yes

reformat_node

Yes

securitygroup

Yes

Yes

securitygroupid

Yes

Yes

show_image

Yes

Yes

Yes

show_key

Yes

show_keypair

Yes

Yes

show_volume

Yes

Yes

Tutorials¶

Salt Cloud Quickstart¶

Salt Cloud is built-in to Salt, and the easiest way to run Salt Cloud is directly from your Salt Master. Note that if you installed Salt via Salt Bootstrap, it may not have automatically installed salt-cloud for you. Use your distribution's package manager to install the salt-cloud package from the same repo that you used to install Salt. These repos will automatically be setup by Salt Bootstrap. If there is no salt-cloud package, install with pip install salt-cloud. This quickstart walks you through the basic steps of setting up a cloud host and defining some virtual machines to create. NOTE:

Define a Provider¶

The first step is to add the credentials for your cloud host. Credentials and other settings provided by the cloud host are stored in provider configuration files. Provider configurations contain the details needed to connect to a cloud host such as EC2, GCE, Rackspace, etc., and any global options that you want set on your cloud minions (such as the location of your Salt Master). On your Salt Master, browse to /etc/salt/cloud.providers.d/ and create a file called <provider>.conf, replacing <provider> with ec2, softlayer, and so on. The name helps you identify the contents, and is not important as long as the file ends in .conf. Next, browse to the Provider specifics and add any required settings for your cloud host to this file. Here is an example for Amazon EC2:
The required configuration varies between cloud hosts so make sure you read the provider specifics.

List Cloud Provider Options¶

You can now query the cloud provider you configured for available locations, images, and sizes. This information is used when you set up VM profiles.
Replace <provider_name> with the name of the provider configuration you defined.

Create VM Profiles¶

On your Salt Master, browse to /etc/salt/cloud.profiles.d/ and create a file called <profile>.conf, replacing <profile> with ec2, softlayer, and so on. The file must end in .conf. You can now add any custom profiles you'd like to define to this file. Here are a few examples:
Notice that the provider in our profile matches the provider name that we defined? That is how Salt Cloud knows how to connect to to a cloud host to create a VM with these attributes.

Create VMs¶

VMs are created by calling salt-cloud with the following options:
For example:

Destroy VMs¶

Add a -d and the minion name you provided to destroy:

Query VMs¶

You can view details about the VMs you've created using --query:

Cloud Map¶

Now that you know how to create and destoy individual VMs, next you should learn how to use a cloud map to create a number of VMs at once. Cloud maps let you define a map of your infrastructure and quickly provision any number of VMs. On subsequent runs, any VMs that do not exist are created, and VMs that are already configured are left unmodified. See Cloud Map File.

Using Salt Cloud with the Event Reactor¶

One of the most powerful features of the Salt framework is the Event Reactor. As the Reactor was in development, Salt Cloud was regularly updated to take advantage of the Reactor upon completion. As such, various aspects of both the creation and destruction of instances with Salt Cloud fire events to the Salt Master, which can be used by the Event Reactor.

Event Structure¶

As of this writing, all events in Salt Cloud have a tag, which includes the ID of the instance being managed, and a payload which describes the task that is currently being handled. A Salt Cloud tag looks like:
For instance, the first event fired when creating an instance named web1 would look like:
Assuming this instance is using the ec2-centos profile, which is in turn using the ec2-config provider, the payload for this tag would look like:

Available Events¶

When an instance is created in Salt Cloud, whether by map, profile, or directly through an API, a minimum of five events are normally fired. More may be available, depending upon the cloud provider being used. Some of the common events are described below.

salt/cloud/<minion_id>/creating¶

This event states simply that the process to create an instance has begun. At this point in time, no actual work has begun. The payload for this event includes: name profile provider

salt/cloud/<minion_id>/requesting¶

Salt Cloud is about to make a request to the cloud provider to create an instance. At this point, all of the variables required to make the request have been gathered, and the payload of the event will reflect those variables which do not normally pose a security risk. What is returned here is dependent upon the cloud provider. Some common variables are: name image size location

salt/cloud/<minion_id>/querying¶

The instance has been successfully requested, but the necessary information to log into the instance (such as IP address) is not yet available. This event marks the beginning of the process to wait for this information. The payload for this event normally only includes the instance_id.

salt/cloud/<minion_id>/waiting_for_ssh¶

The information required to log into the instance has been retrieved, but the instance is not necessarily ready to be accessed. Following this event, Salt Cloud will wait for the IP address to respond to a ping, then wait for the specified port (usually 22) to respond to a connection, and on Linux systems, for SSH to become available. Salt Cloud will attempt to issue the date command on the remote system, as a means to check for availability. If no ssh_username has been specified, a list of usernames (starting with root) will be attempted. If one or more usernames was configured for ssh_username, they will be added to the beginning of the list, in order. The payload for this event normally only includes the ip_address.

salt/cloud/<minion_id>/deploying¶

The necessary port has been detected as available, and now Salt Cloud can log into the instance, upload any files used for deployment, and run the deploy script. Once the script has completed, Salt Cloud will log back into the instance and remove any remaining files. A number of variables are used to deploy instances, and the majority of these will be available in the payload. Any keys, passwords or other sensitive data will be scraped from the payload. Most of the variables returned will be related to the profile or provider config, and any default values that could have been changed in the profile or provider, but weren't.

salt/cloud/<minion_id>/created¶

The deploy sequence has completed, and the instance is now available, Salted, and ready for use. This event is the final task for Salt Cloud, before returning instance information to the user and exiting. The payload for this event contains little more than the initial creating event. This event is required in all cloud providers.

Configuring the Event Reactor¶

The Event Reactor is built into the Salt Master process, and as such is configured via the master configuration file. Normally this will be a YAML file located at /etc/salt/master. Additionally, master configuration items can be stored, in YAML format, inside the /etc/salt/master.d/ directory. These configuration items may be stored in either location; however, they may only be stored in one location. For organizational and security purposes, it may be best to create a single configuration file, which contains only Event Reactor configuration, at /etc/salt/master.d/reactor. The Event Reactor uses a top-level configuration item called reactor. This block contains a list of tags to be watched for, each of which also includes a list of sls files. For instance:
The above configuration configures reactors for three different tags: one which is fired when a minion process has started and is available to receive commands, one which is fired when a cloud instance has been created, and one which is fired when a cloud instance is destroyed. Note that each tag contains a wildcard ( *) in it. For each of these tags, this will normally refer to a minion_id. This is not required of event tags, but is very common.

Reactor SLS Files¶

Reactor sls files should be placed in the /srv/reactor/ directory for consistency between environments, but this is not currently enforced by Salt. Reactor sls files follow a similar format to other sls files in Salt. By default they are written in YAML and can be templated using Jinja, but since they are processed through Salt's rendering system, any available renderer (JSON, Mako, Cheetah, etc.) can be used. As with other sls files, each stanza will start with a declaration ID, followed by the function to run, and then any arguments for that function. For example:
When the Event Reactor receives an event notifying it that a new instance has been created, this sls will create a new incident in PagerDuty, using the configured PagerDuty account. The declaration ID in this example is new_instance_alert. The function called is cmd.pagerduty.create_event. The cmd portion of this function specifies that an execution module and function will be called, in this case, the pagerduty.create_event function. Because an execution module is specified, a target ( tgt) must be specified on which to call the function. In this case, a minion called alertserver has been used. Any arguments passed through to the function are declared in the kwarg block.

Example: Reactor-Based Highstate¶

When Salt Cloud creates an instance, by default it will install the Salt Minion onto the instance, along with any specified minion configuration, and automatically accept that minion's keys on the master. One of the configuration options that can be specified is startup_states, which is commonly set to highstate. This will tell the minion to immediately apply a highstate, as soon as it is able to do so. This can present a problem with some system images on some cloud hosts. For instance, Salt Cloud can be configured to log in as either the root user, or a user with sudo access. While some hosts commonly use images that lock out remote root access and require a user with sudo privileges to log in (notably EC2, with their ec2-user login), most cloud hosts fall back to root as the default login on all images, including for operating systems (such as Ubuntu) which normally disallow remote root login. For users of these operating systems, it is understandable that a highstate would include configuration to block remote root logins again. However, Salt Cloud may not have finished cleaning up its deployment files by the time the minion process has started, and kicked off a highstate run. Users have reported errors from Salt Cloud getting locked out while trying to clean up after itself. The goal of a startup state may be achieved using the Event Reactor. Because a minion fires an event when it is able to receive commands, this event can effectively be used inside the reactor system instead. The following will point the reactor system to the right sls file:
And the following sls file will start a highstate run on the target minion:
Because this event will not be fired until Salt Cloud has cleaned up after itself, the highstate run will not step on salt-cloud's toes. And because every file on the minion is configurable, including /etc/salt/minion, the startup_states can still be configured for future minion restarts, if desired.

SALT PROXY MINION¶

Proxy minions are a developing Salt feature that enables controlling devices that, for whatever reason, cannot run a standard salt-minion. Examples include network gear that has an API but runs a proprietary OS, devices with limited CPU or memory, or devices that could run a minion, but for security reasons, will not. Proxy minions are not an "out of the box" feature. Because there are an infinite number of controllable devices, you will most likely have to write the interface yourself. Fortunately, this is only as difficult as the actual interface to the proxied device. Devices that have an existing Python module (PyUSB for example) would be relatively simple to interface. Code to control a device that has an HTML REST-based interface should be easy. Code to control your typical housecat would be excellent source material for a PhD thesis. Salt proxy-minions provide the 'plumbing' that allows device enumeration and discovery, control, status, remote execution, and state management. See the Proxy Minion Walkthrough for an end-to-end demonstration of a working REST-based proxy minion. See the Proxy Minion SSH Walkthrough for an end-to-end demonstration of a working SSH proxy minion. See Proxyminion States to configure and run salt-proxy on a remote minion. Specify all your master side proxy (pillar) configuration and use this state to remotely configure proxies on one or more minions. See Proxyminion Beacon to help with easy configuration and management of salt-proxy processes.

New in 2016.11.0¶

Proxy minions now support configuration files with names ending in '

*

.conf' and placed in /etc/salt/proxy.d. Proxy minions can now be configured in /etc/salt/proxy or /etc/salt/proxy.d instead of just pillar. Configuration format is the same as it would be in pillar.

New in 2016.3¶

The deprecated config option enumerate_proxy_minions has been removed. As mentioned in earlier documentation, the add_proxymodule_to_opts configuration variable defaults to False in this release. This means if you have proxymodules or other code looking in __opts__['proxymodule'] you will need to set this variable in your /etc/salt/proxy file, or modify your code to use the __proxy__ injected variable. The __proxyenabled__ directive now only applies to grains and proxy modules themselves. Standard execution modules and state modules are not prevented from loading for proxy minions. Enhancements in grains processing have made the __proxyenabled__ directive somewhat redundant in dynamic grains code. It is still required, but best practices for the __virtual__ function in grains files have changed. It is now recommended that the __virtual__ functions check to make sure they are being loaded for the correct proxytype, example below:
The try/except block above exists because grains are processed very early in the proxy minion startup process, sometimes earlier than the proxy key in the __opts__ dictionary is populated. Grains are loaded so early in startup that no dunder dictionaries are present, so __proxy__, __salt__, etc. are not available. Custom grains located in /srv/salt/_grains and in the salt install grains directory can now take a single argument, proxy, that is identical to __proxy__. This enables patterns like
Then the grain ip will contain the result of calling the get_ip() function in the proxymodule called proxymodulename. Proxy modules now benefit from including a function called initialized(). This function should return True if the proxy's init() function has been successfully called. This is needed to make grains processing easier. Finally, if there is a function called grains in the proxymodule, it will be executed on proxy-minion startup and its contents will be merged with the rest of the proxy's grains. Since older proxy-minions might have used other methods to call such a function and add its results to grains, this is config-gated by a new proxy configuration option called proxy_merge_grains_in_module. This defaults to False in this release. It will default to True in the release after next. The next release is 2016.11.0, the following is Nitrogen.

New in 2015.8.2¶

BREAKING CHANGE: Adding the proxymodule variable to __opts__ is deprecated. The proxymodule variable has been moved a new globally-injected variable called __proxy__. A related configuration option called add_proxymodule_to_opts has been added and defaults to True. In the next major release, 2016.3.0, this variable will default to False. In the meantime, proxies that functioned under 2015.8.0 and .1 should continue to work under 2015.8.2. You should rework your proxy code to use __proxy__ as soon as possible. The rest_sample example proxy minion has been updated to use __proxy__. This change was made because proxymodules are a LazyLoader object, but LazyLoaders cannot be serialized. __opts__ gets serialized, and so things like saltutil.sync_all and state.highstate would throw exceptions. Support has been added to Salt's loader allowing custom proxymodules to be placed in salt://_proxy. Proxy minions that need these modules will need to be restarted to pick up any changes. A corresponding utility function, saltutil.sync_proxymodules, has been added to sync these modules to minions. In addition, a salt.utils helper function called is_proxy() was added to make it easier to tell when the running minion is a proxy minion.

New in 2015.8¶

Starting with the 2015.8 release of Salt, proxy processes are no longer forked off from a controlling minion. Instead, they have their own script salt-proxy which takes mostly the same arguments that the standard Salt minion does with the addition of --proxyid. This is the id that the salt-proxy will use to identify itself to the master. Proxy configurations are still best kept in Pillar and their format has not changed. This change allows for better process control and logging. Proxy processes can now be listed with standard process management utilities ( ps from the command line). Also, a full Salt minion is no longer required (though it is still strongly recommended) on machines hosting proxies.

Getting Started¶

The following diagram may be helpful in understanding the structure of a Salt installation that includes proxy-minions: [image] The key thing to remember is the left-most section of the diagram. Salt's nature is to have a minion connect to a master, then the master may control the minion. However, for proxy minions, the target device cannot run a minion. After the proxy minion is started and initiates its connection to the 'dumb' device, it connects back to the salt-master and for all intents and purposes looks like just another minion to the Salt master. To create support for a proxied device one needs to create four things:

Configuration parameters¶

Proxy minions require no configuration parameters in /etc/salt/master. Salt's Pillar system is ideally suited for configuring proxy-minions (though they can be configured in /etc/salt/proxy as well). Proxies can either be designated via a pillar file in pillar_roots, or through an external pillar. External pillars afford the opportunity for interfacing with a configuration management system, database, or other knowledgeable system that that may already contain all the details of proxy targets. To use static files in pillar_roots, pattern your files after the following examples, which are based on the diagram above: /srv/pillar/top.sls
/srv/pillar/dumbdevice1.sls
/srv/pillar/dumbdevice2.sls
/srv/pillar/dumbdevice3.sls
/srv/pillar/dumbdevice4.sls
/srv/pillar/dumbdevice5.sls
/srv/pillar/dumbdevice6.sls
/srv/pillar/dumbdevice7.sls
Note the contents of each minioncontroller key may differ widely based on the type of device that the proxy-minion is managing. In the above example
Because of the way pillar works, each of the salt-proxy processes that fork off the proxy minions will only see the keys specific to the proxies it will be handling. Proxies can be configured in /etc/salt/proxy or with files in /etc/salt/proxy.d as of Salt's 2016.11.0 release. Also, in general, proxy-minions are lightweight, so the machines that run them could conceivably control a large number of devices. To run more than one proxy from a single machine, simply start an additional proxy process with --proxyid set to the id to which you want the proxy to bind. It is possible for the proxy services to be spread across many machines if necessary, or intentionally run on machines that need to control devices because of some physical interface (e.g. i2c and serial above). Another reason to divide proxy services might be security. In more secure environments only certain machines may have a network path to certain devices.

Proxymodules¶

A proxy module encapsulates all the code necessary to interface with a device. Proxymodules are located inside the salt.proxy module, or can be placed in the _proxy directory in your file_roots (default is /srv/salt/_proxy. At a minimum a proxymodule object must implement the following functions: __virtual__(): This function performs the same duty that it does for other types of Salt modules. Logic goes here to determine if the module can be loaded, checking for the presence of Python modules on which the proxy depends. Returning False will prevent the module from loading. init(opts): Perform any initialization that the device needs. This is a good place to bring up a persistent connection to a device, or authenticate to create a persistent authorization token. initialized(): Returns True if init() was successfully called. shutdown(): Code to cleanly shut down or close a connection to a controlled device goes here. This function must exist, but can contain only the keyword pass if there is no shutdown logic required. ping(): While not required, it is highly recommended that this function also be defined in the proxymodule. The code for ping should contact the controlled device and make sure it is really available. grains(): Rather than including grains in /srv/salt/_grains or in the standard install directories for grains, grains can be computed and returned by this function. This function will be called automatically if proxy_merge_grains_in_module is set to True in /etc/salt/proxy. This variable defaults to False in 2016.3 but will default to True in the release code-named Nitrogen. Pre 2015.8 the proxymodule also must have an id() function. 2015.8 and following don't use this function because the proxy's id is required on the command line. Here is an example proxymodule used to interface to a very simple REST server. Code for the server is in the salt-contrib GitHub repository This proxymodule enables "service" enumeration, starting, stopping, restarting, and status; "package" installation, and a ping.
Grains are data about minions. Most proxied devices will have a paltry amount of data as compared to a typical Linux server. By default, a proxy minion will have several grains taken from the host. Salt core code requires values for kernel, os, and os_family--all of these are forced to be proxy for proxy-minions. To add others to your proxy minion for a particular device, create a file in salt/grains named [proxytype].py and place inside it the different functions that need to be run to collect the data you are interested in. Here's an example. Note the function below called proxy_functions. It demonstrates how a grains function can take a single argument, which will be set to the value of __proxy__. Dunder variables are not yet injected into Salt processes at the time grains are loaded, so this enables us to get a handle to the proxymodule so we can cross-call the functions therein used to commmunicate with the controlled device. Note that as of 2016.3, grains values can also be calculated in a function called grains() in the proxymodule itself. This might be useful if a proxymodule author wants to keep all the code for the proxy interface in the same place instead of splitting it between the proxy and grains directories. This function will only be called automatically if the configuration variable proxy_merge_grains_in_module is set to True in the proxy configuration file (default /etc/salt/proxy). This variable will default to True in the release code-named Nitrogen.

The __proxyenabled__ directive¶

In previous versions of Salt the __proxyenabled__ directive controlled loading of all Salt modules for proxies (e.g. grains, execution modules, state modules). From 2016.3 on, the only modules that respect __proxyenabled__ are grains and proxy modules. These modules need to be told which proxy they work with. __proxyenabled__ is a list, and can contain a single '*' to indicate a grains module works with all proxies. Example from salt/grains/rest_sample.py:

Salt Proxy Minion End-to-End Example¶

The following is walkthrough that documents how to run a sample REST service and configure one or more proxy minions to talk to and control it.


[image] Now, configure your salt-proxy.



This says that Salt's pillar should load some values for the proxy p8000 from the file /srv/pillar/p8000.sls (if you have not changed your default pillar_roots)

In other words, if your REST service is listening on port 8000 on 127.0.0.1 the 'url' key above should say url: http://127.0.0.1:8000

SSH Proxymodules¶

See above for a general introduction to writing proxy modules. All of the guidelines that apply to REST are the same for SSH. This sections specifically talks about the SSH proxy module and explains the working of the example proxy module ssh_sample. Here is a simple example proxymodule used to interface to a device over SSH. Code for the SSH shell is in the salt-contrib GitHub repository This proxymodule enables "package" installation.

Connection Setup¶

The init() method is responsible for connection setup. It uses the host, username and password config variables defined in the pillar data. The prompt kwarg can be passed to SSHConnection if your SSH server's prompt differs from the example's prompt (Cmd). Instantiating the SSHConnection class establishes an SSH connection to the ssh server (using Salt VT).

Command execution¶

The package_* methods use the SSH connection (established in init()) to send commands out to the SSH server. The sendline() method of SSHConnection class can be used to send commands out to the server. In the above example we send commands like pkg_list or pkg_install. You can send any SSH command via this utility.

Output parsing¶

Output returned by sendline() is a tuple of strings representing the stdout and the stderr respectively. In the toy example shown we simply scrape the output and convert it to a python dictionary, as shown in the parse method. You can tailor this method to match your parsing logic.

Connection teardown¶

The shutdown method is responsible for calling the close_connection() method of SSHConnection class. This ends the SSH connection to the server. For more information please refer to class SSHConnection.

Salt Proxy Minion SSH End-to-End Example¶

The following is walkthrough that documents how to run a sample SSH service and configure one or more proxy minions to talk to and control it.
Now, configure your salt-proxy.



This says that Salt's pillar should load some values for the proxy p8000 from the file /srv/pillar/p8000.sls (if you have not changed your default pillar_roots)








New in version 2015.8.3.

Proxy Minion Beacon¶

The salt proxy beacon is meant to facilitate configuring multiple proxies on one or many minions. This should simplify configuring and managing multiple salt-proxy processes.

This says that Salt's pillar should load some values for the proxy p8000 from the file /srv/pillar/p8000.sls (if you have not changed your default pillar_roots)

This should complete the proxy setup for p8000

Once this beacon is configured it will automatically start the salt-proxy process. If the salt-proxy process is terminated the beacon will re-start it.



New in version 2015.8.2.

Proxy Minion States¶

Salt proxy state can be used to deploy, configure and run a salt-proxy instance on your minion. Configure proxy settings on the master side and the state configures and runs salt-proxy on the remote end.

This says that Salt's pillar should load some values for the proxy p8000 from the file /srv/pillar/p8000.sls (if you have not changed your default pillar_roots)




Example using state.sls to configure and run salt-proxy
This starts salt-proxy on device_minion

ESXi Proxy Minion¶

New in version 2015.8.4. NOTE:
Salt's ESXi Proxy Minion allows a VMware ESXi host to be treated as an individual Salt Minion, without installing a Salt Minion on the ESXi host. Since an ESXi host may not necessarily run on an OS capable of hosting a Python stack, the ESXi host can't run a regular Salt Minion directly. Therefore, Salt's Proxy Minion functionality enables you to designate another machine to host a proxy process that "proxies" communication from the Salt Master to the ESXi host. The master does not know or care that the ESXi target is not a "real" Salt Minion. More in-depth conceptual reading on Proxy Minions can be found in the Proxy Minion section of Salt's documentation. Salt's ESXi Proxy Minion was added in the 2015.8.4 release of Salt. NOTE:

Dependencies¶

Manipulation of the ESXi host via a Proxy Minion requires the machine running the Proxy Minion process to have the ESXCLI package (and all of it's dependencies) and the pyVmomi Python Library to be installed.

ESXi Password¶

The ESXi Proxy Minion uses VMware's API to perform tasks on the host as if it was a regular Salt Minion. In order to access the API that is already running on the ESXi host, the ESXi host must have a username and password that is used to log into the host. The username is usually root. Before Salt can access the ESXi host via VMware's API, a default password must be set on the host.

pyVmomi¶

The pyVmomi Python library must be installed on the machine that is running the proxy process. pyVmomi can be installed via pip:
NOTE:
Based on the note above, to install an earlier version of pyVmomi than the version currently listed in PyPi, run the following:
The 5.5.0.2014.1.1 is a known stable version that the original ESXi Proxy Minion was developed against.

ESXCLI¶

Currently, about a third of the functions used for the ESXi Proxy Minion require the ESXCLI package be installed on the machine running the Proxy Minion process. The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware provides vCLI package installation instructions for vSphere 5.5 and vSphere 6.0. Once all of the required dependencies are in place and the vCLI package is installed, you can check to see if you can connect to your ESXi host by running the following command:
If the connection was successful, ESXCLI was successfully installed on your system. You should see output related to the ESXi host's syslog configuration.

Configuration¶

There are several places where various configuration values need to be set in order for the ESXi Proxy Minion to run and connect properly.

Proxy Config File¶

On the machine that will be running the Proxy Minon process(es), a proxy config file must be in place. This file should be located in the /etc/salt/ directory and should be named proxy. If the file is not there by default, create it. This file should contain the location of your Salt Master that the Salt Proxy will connect to. Example Proxy Config File:

Pillar Profiles¶

Proxy minions get their configuration from Salt's Pillar. Every proxy must have a stanza in Pillar and a reference in the Pillar top-file that matches the Proxy ID. At a minimum for communication with the ESXi host, the pillar should look like this:
Some other optional settings are protocol and port. These can be added to the pillar configuration.

proxytype¶

The proxytype key and value pair is critical, as it tells Salt which interface to load from the proxy directory in Salt's install hierarchy, or from /srv/salt/_proxy on the Salt Master (if you have created your own proxy module, for example). To use this ESXi Proxy Module, set this to esxi.

host¶

The location, or ip/dns, of the ESXi host. Required.

username¶

The username used to login to the ESXi host, such as root. Required.

passwords¶

A list of passwords to be used to try and login to the ESXi host. At least one password in this list is required. The proxy integration will try the passwords listed in order. It is configured this way so you can have a regular password and the password you may be updating for an ESXi host either via the vsphere.update_host_password execution module function or via the esxi.password_present state function. This way, after the password is changed, you should not need to restart the proxy minion--it should just pick up the the new password provided in the list. You can then change pillar at will to move that password to the front and retire the unused ones. Use-case/reasoning for using a list of passwords: You are setting up an ESXi host for the first time, and the host comes with a default password. You know that you'll be changing this password during your initial setup from the default to a new password. If you only have one password option, and if you have a state changing the password, any remote execution commands or states that run after the password change will not be able to run on the host until the password is updated in Pillar and the Proxy Minion process is restarted. This allows you to use any number of potential fallback passwords. NOTE:

protocol¶

If the ESXi host is not using the default protocol, set this value to an alternate protocol. Default is https. For example:

port¶

If the ESXi host is not using the default port, set this value to an alternate port. Default is 443.

Example Configuration Files¶

An example of all of the basic configurations that need to be in place before starting the Proxy Minion processes includes the Proxy Config File, Pillar Top File, and any individual Proxy Minion Pillar files. In this example, we'll assuming there are two ESXi hosts to connect to. Therefore, we'll be creating two Proxy Minion config files, one config for each ESXi host. Proxy Config File:
Pillar Top File:
Pillar Config File for the first ESXi host, esxi-1:
Pillar Config File for the second ESXi host, esxi-2:

Starting the Proxy Minion¶

Once all of the correct configuration files are in place, it is time to start the proxy processes!

Executing Commands¶

Now that you've configured your Proxy Minions and have them responding successfully to a test.ping, we can start executing commands against the ESXi hosts via Salt. It's important to understand how this particular proxy works, and there are a couple of important pieces to be aware of in order to start running remote execution and state commands against the ESXi host via a Proxy Minion: the vSphere Execution Module, the ESXi Execution Module, and the ESXi State Module.

vSphere Execution Module¶

The Salt.modules.vsphere is a standard Salt execution module that does the bulk of the work for the ESXi Proxy Minion. If you pull up the docs for it you'll see that almost every function in the module takes credentials ( username and password) and a target host argument. When credentials and a host aren't passed, Salt runs commands through pyVmomi or ESXCLI against the local machine. If you wanted, you could run functions from this module on any machine where an appropriate version of pyVmomi and ESXCLI are installed, and that machine would reach out over the network and communicate with the ESXi host. You'll notice that most of the functions in the vSphere module require a host, username, and password. These parameters are contained in the Pillar files and passed through to the function via the proxy process that is already running. You don't need to provide these parameters when you execute the commands. See the Running Remote Execution Commands section below for an example.

ESXi Execution Module¶

In order for the Pillar information set up in the Configuration section above to be passed to the function call in the vSphere Execution Module, the salt.modules.esxi execution module acts as a "shim" between the vSphere execution module functions and the proxy process. The "shim" takes the authentication credentials specified in the Pillar files and passes them through to the host, username, password, and optional protocol and port options required by the vSphere Execution Module functions. If the function takes more positional, or keyword, arguments you can append them to the call. It's this shim that speaks to the ESXi host through the proxy, arranging for the credentials and hostname to be pulled from the Pillar section for the ESXi Proxy Minion. Because of the presence of the shim, to lookup documentation for what functions you can use to interface with the ESXi host, you'll want to look in salt.modules.vsphere instead of salt.modules.esxi.

Running Remote Execution Commands¶

To run commands from the Salt Master to execute, via the ESXi Proxy Minion, against the ESXi host, you use the esxi.cmd <vsphere-function-name> syntax to call functions located in the vSphere Execution Module. Both args and kwargs needed for various vsphere execution module functions must be passed through in a kwarg- type manor. For example:

ESXi State Module¶

The ESXi State Module functions similarly to other state modules. The "shim" provided by the ESXi Execution Module passes the necessary host, username, and password credentials through, so those options don't need to be provided in the state. Other than that, state files are written and executed just like any other Salt state. See the salt.modules.esxi state for ESXi state functions. The follow state file is an example of how to configure various pieces of an ESXi host including enabling SSH, uploading and SSH key, configuring a coredump network config, syslog, ntp, enabling VMotion, resetting a host password, and more.
States are called via the ESXi Proxy Minion just as they would on a regular minion. For example:

Relevant Salt Files and Resources¶

SALT VIRT¶

The Salt Virt cloud controller capability was initially added to Salt in version 0.14.0 as an alpha technology. The initial Salt Virt system supports core cloud operations:
Many features are currently under development to enhance the capabilities of the Salt Virt systems. NOTE:
WARNING:

Salt Virt Tutorial¶

A tutorial about how to get Salt Virt up and running has been added to the tutorial section: Cloud Controller Tutorial

The Salt Virt Runner¶

The point of interaction with the cloud controller is the virt runner. The virt runner comes with routines to execute specific virtual machine routines. Reference documentation for the virt runner is available with the runner module documentation: Virt Runner Reference

Based on Live State Data¶

The Salt Virt system is based on using Salt to query live data about hypervisors and then using the data gathered to make decisions about cloud operations. This means that no external resources are required to run Salt Virt, and that the information gathered about the cloud is live and accurate.

Deploy from Network or Disk¶

Virtual Machine Disk Profiles¶

Salt Virt allows for the disks created for deployed virtual machines to be finely configured. The configuration is a simple data structure which is read from the config.option function, meaning that the configuration can be stored in the minion config file, the master config file, or the minion's pillar. This configuration option is called virt.disk. The default virt.disk data structure looks like this:
NOTE:
This configuration sets up a disk profile called default. The default profile creates a single system disk on the virtual machine.

Define More Profiles¶

Many environments will require more complex disk profiles and may require more than one profile, this can be easily accomplished:
This configuration allows for one of three profiles to be selected, allowing virtual machines to be created with different storage needs of the deployed vm.

Virtual Machine Network Profiles¶

Salt Virt allows for the network devices created for deployed virtual machines to be finely configured. The configuration is a simple data structure which is read from the config.option function, meaning that the configuration can be stored in the minion config file, the master config file, or the minion's pillar. This configuration option is called virt.nic. By default the virt.nic option is empty but defaults to a data structure which looks like this:
NOTE:
This configuration sets up a network profile called default. The default profile creates a single Ethernet device on the virtual machine that is bridged to the hypervisor's br0 interface. This default setup does not require setting up the virt.nic configuration, and is the reason why a default install only requires setting up the br0 bridge device on the hypervisor.

Define More Profiles¶

Many environments will require more complex network profiles and may require more than one profile, this can be easily accomplished:
This configuration allows for one of six profiles to be selected, allowing virtual machines to be created which attach to different network depending on the needs of the deployed vm.

Salt as a Cloud Controller¶

In Salt 0.14.0, an advanced cloud control system were introduced, allow private cloud vms to be managed directly with Salt. This system is generally referred to as Salt Virt. The Salt Virt system already exists and is installed within Salt itself, this means that besides setting up Salt, no additional salt code needs to be deployed. NOTE:
The main goal of Salt Virt is to facilitate a very fast and simple cloud. The cloud that can scale and is fully featured. Salt Virt comes with the ability to set up and manage complex virtual machine networking, powerful image and disk management, as well as virtual machine migration with and without shared storage. This means that Salt Virt can be used to create a cloud from a blade center and a SAN, but can also create a cloud out of a swarm of Linux Desktops without a single shared storage system. Salt Virt can make clouds from truly commodity hardware, but can also stand up the power of specialized hardware as well.

Setting up Hypervisors¶

The first step to set up the hypervisors involves getting the correct software installed and setting up the hypervisor network interfaces.

Installing Hypervisor Software¶

Salt Virt is made to be hypervisor agnostic but currently the only fully implemented hypervisor is KVM via libvirt. The required software for a hypervisor is libvirt and kvm. For advanced features install libguestfs or qemu-nbd. NOTE:
This sls will set up the needed software for a hypervisor, and run the routines to set up the libvirt pki keys. NOTE:

Hypervisor Network Setup¶

The hypervisors will need to be running a network bridge to serve up network devices for virtual machines, this formula will set up a standard bridge on a hypervisor connecting the bridge to eth0:

Virtual Machine Network Setup¶

Salt Virt comes with a system to model the network interfaces used by the deployed virtual machines; by default a single interface is created for the deployed virtual machine and is bridged to br0. To get going with the default networking setup, ensure that the bridge interface named br0 exists on the hypervisor and is bridged to an active network device. NOTE:

Libvirt State¶

One of the challenges of deploying a libvirt based cloud is the distribution of libvirt certificates. These certificates allow for virtual machine migration. Salt comes with a system used to auto deploy these certificates. Salt manages the signing authority key and generates keys for libvirt clients on the master, signs them with the certificate authority and uses pillar to distribute them. This is managed via the libvirt state. Simply execute this formula on the minion to ensure that the certificate is in place and up to date: NOTE:

Getting Virtual Machine Images Ready¶

Salt Virt, requires that virtual machine images be provided as these are not generated on the fly. Generating these virtual machine images differs greatly based on the underlying platform. Virtual machine images can be manually created using KVM and running through the installer, but this process is not recommended since it is very manual and prone to errors. Virtual Machine generation applications are available for many platforms:
Once virtual machine images are available, the easiest way to make them available to Salt Virt is to place them in the Salt file server. Just copy an image into /srv/salt and it can now be used by Salt Virt. For purposes of this demo, the file name centos.img will be used.

Existing Virtual Machine Images¶

Many existing Linux distributions distribute virtual machine images which can be used with Salt Virt. Please be advised that NONE OF THESE IMAGES ARE SUPPORTED BY SALTSTACK.

CentOS¶

These images have been prepared for OpenNebula but should work without issue with Salt Virt, only the raw qcow image file is needed: http://wiki.centos.org/Cloud/OpenNebula

Fedora Linux¶

Images for Fedora Linux can be found here: http://fedoraproject.org/en/get-fedora#clouds

openSUSE¶

http://download.opensuse.org/repositories/openSUSE:/Leap:/42.1:/Images/images (look for JeOS-for-kvm-and-xen variant)

SUSE¶

https://www.suse.com/products/server/jeos

Ubuntu Linux¶

Images for Ubuntu Linux can be found here: http://cloud-images.ubuntu.com/

Using Salt Virt¶

With hypervisors set up and virtual machine images ready, Salt can start issuing cloud commands. Start by running a Salt Virt hypervisor info command:
This will query what the running hypervisor stats are and display information for all configured hypervisors. This command will also validate that the hypervisors are properly configured. Now that hypervisors are available a virtual machine can be provisioned. The virt.init routine will create a new virtual machine:
This command assumes that the CentOS virtual machine image is sitting in the root of the Salt fileserver. Salt Virt will now select a hypervisor to deploy the new virtual machine on and copy the virtual machine image down to the hypervisor. Once the VM image has been copied down the new virtual machine will be seeded. Seeding the VMs involves setting pre-authenticated Salt keys on the new VM and if needed, will install the Salt Minion on the new VM before it is started. NOTE:
Now that the new VM has been prepared, it can be seen via the virt.query command:
This command will return data about all of the hypervisors and respective virtual machines. Now that the new VM is booted it should have contacted the Salt Master, a test.ping will reveal if the new VM is running.

Migrating Virtual Machines¶

Salt Virt comes with full support for virtual machine migration, and using the libvirt state in the above formula makes migration possible. A few things need to be available to support migration. Many operating systems turn on firewalls when originally set up, the firewall needs to be opened up to allow for libvirt and kvm to cross communicate and execution migration routines. On Red Hat based hypervisors in particular port 16514 needs to be opened on hypervisors:
NOTE:
Salt also needs an additional flag to be turned on as well. The virt.tunnel option needs to be turned on. This flag tells Salt to run migrations securely via the libvirt TLS tunnel and to use port 16514. Without virt.tunnel libvirt tries to bind to random ports when running migrations. To turn on virt.tunnel simple apply it to the master config file:
Once the master config has been updated, restart the master and send out a call to the minions to refresh the pillar to pick up on the change:
Now, migration routines can be run! To migrate a VM, simply run the Salt Virt migrate routine:

VNC Consoles¶

Salt Virt also sets up VNC consoles by default, allowing for remote visual consoles to be oped up. The information from a virt.query routine will display the vnc console port for the specific vms:
The line Graphics: vnc - hyper6:5900 holds the key. First the port named, in this case 5900, will need to be available in the hypervisor's firewall. Once the port is open, then the console can be easily opened via vncviewer:
By default there is no VNC security set up on these ports, which suggests that keeping them firewalled and mandating that SSH tunnels be used to access these VNC interfaces. Keep in mind that activity on a VNC interface that is accessed can be viewed by any other user that accesses that same VNC interface, and any other user logging in can also operate with the logged in user on the virtual machine.

Conclusion¶

Now with Salt Virt running, new hypervisors can be seamlessly added just by running the above states on new bare metal machines, and these machines will be instantly available to Salt Virt.

COMMAND LINE REFERENCE¶

salt-call¶

salt-call¶

Synopsis¶

Description¶

The salt-call command is used to run module functions locally on a minion instead of executing them from the master. Salt-call is used to run a Standalone Minion, and was originally created for troubleshooting. The Salt Master is contacted to retrieve state files and other resources during execution unless the --local option is specified. NOTE:

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

Output Options¶

See also¶

salt(1) salt-master(1) salt-minion(1)

salt¶

salt¶

Synopsis¶

Description¶

Salt allows for commands to be executed across a swath of remote systems in parallel. This means that remote systems can be both controlled and queried with ease.

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

Target Selection¶

The default matching that Salt utilizes is shell-style globbing around the minion id. See https://docs.python.org/2/library/fnmatch.html#module-fnmatch.

Output Options¶

See also¶

salt(7) salt-master(1) salt-minion(1)

salt-cloud¶

salt-cp¶

salt-cp¶

Copy a file to a set of systems

Synopsis¶

Description¶

Salt copy copies a local file out to all of the Salt minions matched by the given target. Salt copy is only intended for use with small files (< 100KB). If you need to copy large files out to minions please use the cp.get_file function. Note: salt-cp uses salt's publishing mechanism. This means the privacy of the contents of the file on the wire is completely dependent upon the transport in use. In addition, if the salt-master is running with debug logging it is possible that the contents of the file will be logged to disk.

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

Target Selection¶

The default matching that Salt utilizes is shell-style globbing around the minion id. See https://docs.python.org/2/library/fnmatch.html#module-fnmatch.

See also¶

salt(1) salt-master(1) salt-minion(1)

salt-extend¶

salt-extend¶

A utilty to generate extensions to the Salt source-code. This is used for :

Synopsis¶

Description¶

salt-extend is a templating tool for extending SaltStack. If you're looking to add a module to SaltStack, then the salt-extend utility can guide you through the process. You can use Salt Extend to quickly create templated modules for adding new behaviours to some of the module subsystems within Salt. Salt Extend takes a template directory and merges it into a SaltStack source code directory. See also: Salt Extend.

Options¶

See also¶

salt-api(1) salt-call(1) salt-cloud(1) salt-cp(1) salt-key(1) salt-main(1) salt-master(1) salt-minion(1) salt-run(1) salt-ssh(1) salt-syndic(1)

salt-key¶

salt-key¶

Synopsis¶

Description¶

Salt-key executes simple management of Salt server public keys used for authentication. On initial connection, a Salt minion sends its public key to the Salt master. This key must be accepted using the salt-key command on the Salt master. Salt minion keys can be in one of the following states:
To change the state of a minion key, use -d to delete the key and then accept or reject the key.

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

Output Options¶

Actions¶

Key Generation Options¶

See also¶

salt(7) salt-master(1) salt-minion(1)

salt-master¶

salt-master¶

The Salt master daemon, used to control the Salt minions

Synopsis¶

Description¶

The master daemon controls the Salt minions

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

See also¶

salt(1) salt(7) salt-minion(1)

salt-minion¶

salt-minion¶

The Salt minion daemon, receives commands from a remote Salt master.

Synopsis¶

Description¶

The Salt minion receives commands from the central Salt master and replies with the results of said commands.

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

See also¶

salt(1) salt(7) salt-master(1)

salt-proxy¶

salt-proxy¶

Receives commands from a Salt master and proxies these commands to devices that are unable to run a full minion.

Synopsis¶

Description¶

The Salt proxy minion receives commands from a Salt master, transmits appropriate commands to devices that are unable to run a minion, and replies with the results of said commands.

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

See also¶

salt(1) salt(7) salt-master(1) salt-minion(1)

salt-run¶

salt-run¶

Execute a Salt runner

Synopsis¶

Description¶

salt-run is the frontend command for executing Salt Runners. Salt runners are simple modules used to execute convenience functions on the master

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

See also¶

salt(1) salt-master(1) salt-minion(1)

salt-ssh¶

salt-ssh¶

Synopsis¶

Description¶

Salt SSH allows for salt routines to be executed using only SSH for transport

Options¶

Target Selection¶

The default matching that Salt utilizes is shell-style globbing around the minion id. See https://docs.python.org/2/library/fnmatch.html#module-fnmatch.

Logging Options¶

Logging options which override any settings defined on the configuration files.

Output Options¶

See also¶

salt(7) salt-master(1) salt-minion(1)

salt-syndic¶

salt-syndic¶

The Salt syndic daemon, a special minion that passes through commands from a higher master

Synopsis¶

Description¶

The Salt syndic daemon, a special minion that passes through commands from a higher master.

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

See also¶

salt(1) salt-master(1) salt-minion(1)

salt-api¶

salt-api¶

Start interfaces used to remotely connect to the salt master

Synopsis¶

Description¶

The Salt API system manages network api connectors for the Salt Master

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

See also¶

salt-api(7) salt(7) salt-master(1)

spm¶

spm¶

Salt Package Manager

Synopsis¶

Description¶

spm is the frontend command for managing Salt packages. Packages normally only include formulas, meaning a group of SLS files that install into the file_roots on the Salt Master, but Salt modules can also be installed.

Options¶

Logging Options¶

Logging options which override any settings defined on the configuration files.

Commands¶

See also¶

salt(1) salt-master(1) salt-minion(1)

SALT MODULE REFERENCE¶

This section contains a list of the Python modules that are used to extend the various subsystems within Salt.

auth modules¶

auto	An "Always Approved" eauth interface to test against, not intended for
django	Provide authentication using Django Web Framework
keystone	Provide authentication using OpenStack Keystone
ldap	Provide authentication using simple LDAP binds
mysql	Provide authentication using MySQL.
pam	Authenticate against PAM
pki	Authenticate via a PKI certificate.
rest	Provide authentication using a REST call
sharedsecret	Provide authentication using configured shared secret
stormpath	Provide authentication using Stormpath.
yubico	Provide authentication using YubiKey.

salt.auth.auto¶

An "Always Approved" eauth interface to test against, not intended for production use

salt.auth.django¶

Provide authentication using Django Web Framework
Django authentication depends on the presence of the django framework in the PYTHONPATH, the Django project's settings.py file being in the PYTHONPATH and accessible via the DJANGO_SETTINGS_MODULE environment variable. Django auth can be defined like any other eauth module:
This will authenticate Fred via Django and allow him to run any execution module and all runners. The authorization details can optionally be located inside the Django database. The relevant entry in the models.py file would look like this:
The external_auth clause in the master config would then look like this:
When a user attempts to authenticate via Django, Salt will import the package indicated via the keyword ^model. That model must have the fields indicated above, though the model DOES NOT have to be named 'SaltExternalAuthModel'.

salt.auth.keystone¶

Provide authentication using OpenStack Keystone

salt.auth.ldap¶

Provide authentication using simple LDAP binds

salt.auth.mysql¶

Provide authentication using MySQL. When using MySQL as an authentication backend, you will need to create or use an existing table that has a username and a password column. To get started, create a simple table that holds just a username and a password. The password field will hold a SHA256 checksum.
To create a user within MySQL, execute the following statement.

The auth_sql contains the SQL that will validate a user to ensure they are correctly authenticated. This is where you can specify other SQL queries to authenticate users. Enable MySQL authentication.

salt.auth.pam¶

Authenticate against PAM Provides an authenticate function that will allow the caller to authenticate a user against the Pluggable Authentication Modules (PAM) on the system. Implemented using ctypes, so no compilation is necessary. There is one extra configuration option for pam. The pam_service that is authenticated against. This defaults to login
NOTE:

salt.auth.pki¶

Authenticate via a PKI certificate. NOTE:
Provides an authenticate function that will allow the caller to authenticate a user via their public cert against a pre-defined Certificate Authority. TODO: Add a 'ca_dir' option to configure a directory of CA files, a la Apache.

salt.auth.rest module¶

Provide authentication using a REST call REST auth can be defined like any other eauth module:
If there are entries underneath the ^url entry then they are merged with any responses from the REST call. In the above example, assuming the REST call does not return any additional ACLs, this will authenticate Fred via a REST call and allow him to run any execution module and all runners. The REST call should return a JSON object that maps to a regular eauth YAML structure as above.

salt.auth.sharedsecret¶

Provide authentication using configured shared secret
The shared secret should be added to the master configuration, for example in /etc/salt/master.d/sharedsecret.conf (make sure that file is only readable by the user running the master):
This auth module should be used with caution. It was initially designed to work with a frontal that takes care of authentication (for example kerberos) and places the shared secret in the HTTP headers to the salt-api call. This salt-api call should really be done on localhost to avoid someone eavesdropping on the shared secret. See the documentation for cherrypy to setup the headers in your frontal. New in version Beryllium.

salt.auth.stormpath¶

Provide authentication using Stormpath. This driver requires some extra configuration beyond that which Stormpath normally requires.
New in version 2015.8.0.

salt.auth.yubico¶

Provide authentication using YubiKey. New in version 2015.5.0.
To get your YubiKey API key you will need to visit the website below. https://upgrade.yubico.com/getapikey/ The resulting page will show the generated Client ID (aka AuthID or API ID) and the generated API key (Secret Key). Make a note of both and use these two values in your /etc/salt/master configuration.
Please wait five to ten minutes after generating the key before testing so that the API key will be updated on all the YubiCloud servers.

beacon modules¶

adb	Beacon to emit adb device state changes for Android devices
avahi_announce	Beacon to announce via avahi (zeroconf)
bonjour_announce	Beacon to announce via Bonjour (zeroconf)
btmp	Beacon to fire events at failed login of users
diskusage	Beacon to monitor disk usage.
glxinfo	Beacon to emit when a display is available to a linux machine
haproxy	Watch current connections of haproxy server backends.
inotify	Watch files and translate the changes into salt events
journald	A simple beacon to watch journald for specific entries
load	Beacon to emit system load averages
memusage	Beacon to monitor memory usage.
network_info	Beacon to monitor statistics from ethernet adapters
network_settings	Beacon to monitor network adapter setting changes on Linux
pkg	Watch for pkgs that have upgrades, then fire an event.
proxy_example	Example beacon to use with salt-proxy
ps	Send events covering service status
salt_proxy	Beacon to manage and report the status of
service	Send events covering service status
sh	Watch the shell commands being executed actively.
status	The status beacon is intended to send a basic health check event up to the master, this allows for event driven routines based on presence to be set up.
twilio_txt_msg	Beacon to emit Twilio text messages
wtmp	Beacon to fire events at login of users as registered in the wtmp file

salt.beacons.adb module¶

Beacon to emit adb device state changes for Android devices New in version 2016.3.0.

salt.beacons.avahi_announce module¶

Beacon to announce via avahi (zeroconf) New in version 2016.11.0.

Dependencies¶

salt.beacons.bonjour_announce module¶

Beacon to announce via Bonjour (zeroconf)

salt.beacons.btmp¶

Beacon to fire events at failed login of users

salt.beacons.diskusage¶

Beacon to monitor disk usage. New in version 2015.5.0.

salt.beacons.glxinfo module¶

Beacon to emit when a display is available to a linux machine New in version 2016.3.0.

salt.beacons.haproxy module¶

Watch current connections of haproxy server backends. Fire an event when over a specified threshold. New in version 2016.11.0.

salt.beacons.inotify¶

Watch files and translate the changes into salt events

salt.beacons.journald¶

A simple beacon to watch journald for specific entries

salt.beacons.load¶

Beacon to emit system load averages

salt.beacons.memusage module¶

Beacon to monitor memory usage. New in version 2016.3.0.

salt.beacons.network_info¶

Beacon to monitor statistics from ethernet adapters New in version 2015.5.0.

salt.beacons.network_settings¶

Beacon to monitor network adapter setting changes on Linux New in version 2016.3.0.

salt.beacons.pkg¶

Watch for pkgs that have upgrades, then fire an event. New in version 2016.3.0.

salt.beacons.proxy_example module¶

Example beacon to use with salt-proxy

salt.beacons.ps module¶

Send events covering service status

salt.beacons.salt_proxy module¶

Beacon to manage and report the status of one or more salt proxy processes New in version 2015.8.3.

salt.beacons.service¶

Send events covering service status

salt.beacons.sh¶

Watch the shell commands being executed actively. This beacon requires strace.

salt.beacons.status module¶

The status beacon is intended to send a basic health check event up to the master, this allows for event driven routines based on presence to be set up. The intention of this beacon is to add the config options to add monitoring stats to the health beacon making it a one stop shop for gathering systems health and status data New in version 2016.11.0. To configure this beacon to use the defaults, set up an empty dict for it in the minion config:
By default, all of the information from the following execution module functions will be returned:
You can also configure your own set of functions to be returned:
You may also configure only certain fields from each function to be returned. For instance, the loadavg function returns the following fields:
If you wanted to return only the 1-min and 5-min fields for loadavg then you would configure:
Other functions only return a single value instead of a dictionary. With these, you may specify all or 0. The following are both valid:
If a status function returns a list, you may return the index marker or markers for specific list items:

salt.beacons.twilio_txt_msg¶

Beacon to emit Twilio text messages

salt.beacons.wtmp¶

Beacon to fire events at login of users as registered in the wtmp file

engine modules¶

docker_events	Send events from Docker events
http_logstash	HTTP Logstash engine
logentries	An engine that sends events to the Logentries logging service.
logstash	An engine that reads messages from the salt event bus and pushes them onto a logstash endpoint.
reactor	Setup Reactor
redis_sentinel	An engine that reads messages from the redis sentinel pubsub and sends reactor events based on the channels they are subscribed to.
slack	An engine that reads messages from Slack and sends them to the Salt event bus.
sqs_events	An engine that continuously reads messages from SQS and fires them as events.
test	A simple test engine, not intended for real use but as an example
thorium	Manage the Thorium complex event reaction system

salt.engines.docker_events module¶

Send events from Docker events :Depends: Docker API >= 1.22

salt.engines.http_logstash¶

HTTP Logstash engine¶

An engine that reads messages from the salt event bus and pushes them onto a logstash endpoint via HTTP requests.

salt.engines.logentries¶

An engine that sends events to the Logentries logging service.
To enable this engine the master and/or minion will need the following python libraries
If you are running a new enough version of python then the ssl library will be present already. You will also need the following values configured in the minion or master config.
The 'token' can be obtained from the Logentries service. To test this engine

salt.engines.logstash¶

An engine that reads messages from the salt event bus and pushes them onto a logstash endpoint.

salt.engines.reactor module¶

Setup Reactor Example Config in Master or Minion config

salt.engines.redis_sentinel module¶

An engine that reads messages from the redis sentinel pubsub and sends reactor events based on the channels they are subscribed to.

salt.engines.slack module¶

An engine that reads messages from Slack and sends them to the Salt event bus. Alternatively Salt commands can be sent to the Salt master via Slack by setting the control parameter to True and using command prefaced with a !.

salt.engines.sqs_events¶

An engine that continuously reads messages from SQS and fires them as events. Note that long polling is utilized to avoid excessive CPU usage. New in version 2015.8.0.

Configuration¶

This engine can be run on the master or on a minion. Example Config:
Explicit sqs credentials are accepted but this engine can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at:
If IAM roles are not (or for boto version < 2.5.1) used you need to specify them either in a pillar or in the config file of the master or minion, as appropriate: To deserialize the message from json:
It's also possible to specify key, keyid and region via a profile:
A region may also be specified in the configuration:
If a region is not specified, the default is us-east-1. It's also possible to specify key, keyid and region via a profile:
Additionally you can define cross account sqs:

salt.engines.test¶

A simple test engine, not intended for real use but as an example

salt.engines.thorium module¶

Manage the Thorium complex event reaction system

fileserver modules¶

azurefs	The backend for serving files from the Azure blob storage service.
gitfs	Git Fileserver Backend
hgfs	Mercurial Fileserver Backend
minionfs	Fileserver backend which serves files pushed to the Master
roots	The default file server backend
s3fs	Amazon S3 Fileserver Backend
svnfs	Subversion Fileserver Backend

salt.fileserver.azurefs¶

The backend for serving files from the Azure blob storage service. To enable, add azurefs to the fileserver_backend option in the Master config file.
Each environment is configured as a storage container. The name of the container must match the name of the environment. The storage_account is the name of the storage account inside Azure where the container lives, and the storage_key is the access key used for that storage account:
With this configuration, multiple storage accounts can be used with a single salt instrastructure.

salt.fileserver.gitfs¶

Git Fileserver Backend With this backend, branches and tags in a remote git repository are exposed to salt as different environments. To enable, add git to the fileserver_backend option in the Master config file.
As of Salt 2014.7.0, the Git fileserver backend supports GitPython, pygit2, and dulwich to provide the Python interface to git. If more than one of these are present, the order of preference for which one will be chosen is the same as the order in which they were listed: pygit2, GitPython, dulwich (keep in mind, this order is subject to change). An optional master config parameter ( gitfs_provider) can be used to specify which provider should be used. More detailed information on how to use gitfs can be found in the Gitfs Walkthrough. NOTE:

salt.fileserver.hgfs¶

Mercurial Fileserver Backend To enable, add hg to the fileserver_backend option in the Master config file.
After enabling this backend, branches, bookmarks, and tags in a remote mercurial repository are exposed to salt as different environments. This feature is managed by the fileserver_backend option in the salt master config file. This fileserver has an additional option hgfs_branch_method that will set the desired branch method. Possible values are: branches, bookmarks, or mixed. If using branches or mixed, the default branch will be mapped to base. Changed in version 2014.1.0: The hgfs_base master config parameter was added, allowing for a branch other than default to be used for the base environment, and allowing for a base environment to be specified when using an hgfs_branch_method of bookmarks.

salt.fileserver.minionfs¶

Fileserver backend which serves files pushed to the Master The cp.push function allows Minions to push files up to the Master. Using this backend, these pushed files are exposed to other Minions via the Salt fileserver. To enable minionfs, file_recv needs to be set to True in the master config file (otherwise cp.push will not be allowed to push files to the Master), and minion must be added to the fileserver_backends list.
Other minionfs settings include: minionfs_whitelist, minionfs_blacklist, minionfs_mountpoint, and minionfs_env. SEE ALSO:

salt.fileserver.roots¶

The default file server backend This fileserver backend serves files from the Master's local filesystem. If fileserver_backend is not defined in the Master config file, then this backend is enabled by default. If it is defined then roots must be in the fileserver_backend list to enable this backend.
Fileserver environments are defined using the file_roots configuration option.

salt.fileserver.s3fs¶

Amazon S3 Fileserver Backend This backend exposes directories in S3 buckets as Salt environments. To enable this backend, add s3fs to the fileserver_backend option in the Master config file.
S3 credentials must also be set in the master config file:
Alternatively, if on EC2 these credentials can be automatically loaded from instance metadata. This fileserver supports two modes of operation for the buckets:
Note that bucket names must be all lowercase both in the AWS console and in Salt, otherwise you may encounter SignatureDoesNotMatch errors. A multiple-environment bucket must adhere to the following root directory structure:
NOTE:

salt.fileserver.svnfs¶

Subversion Fileserver Backend After enabling this backend, branches, and tags in a remote subversion repository are exposed to salt as different environments. To enable this backend, add svn to the fileserver_backend option in the Master config file.
This backend assumes a standard svn layout with directories for branches, tags, and trunk, at the repository root.
Changed in version 2014.7.0: The paths to the trunk, branches, and tags have been made configurable, via the config options svnfs_trunk, svnfs_branches, and svnfs_tags. svnfs_mountpoint was also added. Finally, support for per-remote configuration parameters was added. See the documentation for more information.

grains modules¶

chronos	Generate chronos proxy minion grains.
core	The static grains, these are the core, or built in grains.
disks	Detect disks
esxi	Generate baseline proxy minion grains for ESXi hosts.
extra
fx2	Generate baseline proxy minion grains for Dell FX2 chassis.
junos	Grains for junos.
marathon	Generate marathon proxy minion grains.
mdadm	Detect MDADM RAIDs
opts	Simple grain to merge the opts into the grains directly if the grain_opts
philips_hue	Static grains for the Philips HUE lamps
rest_sample	Generate baseline proxy minion grains

salt.grains.chronos¶

Generate chronos proxy minion grains. New in version 2015.8.2.

salt.grains.core¶

The static grains, these are the core, or built in grains. When grains are loaded they are not loaded in the same way that modules are loaded, grain functions are detected and executed, the functions MUST return a dict which will be applied to the main grains dict. This module will always be executed first, so that any grains loaded here in the core module can be overwritten just by returning dict keys with the same value as those returned here

salt.grains.disks¶

Detect disks

salt.grains.esxi¶

Generate baseline proxy minion grains for ESXi hosts. ., versionadded:: 2015.8.4

salt.grains.extra¶

salt.grains.fx2¶

Generate baseline proxy minion grains for Dell FX2 chassis. The challenge is that most of Salt isn't bootstrapped yet, so we need to repeat a bunch of things that would normally happen in proxy/fx2.py--just enough to get data from the chassis to include in grains.

salt.grains.junos¶

Grains for junos. NOTE this is a little complicated--junos can only be accessed via salt-proxy-minion.Thus, some grains make sense to get them from the minion (PYTHONPATH), but others don't (ip_interfaces)

salt.grains.marathon¶

Generate marathon proxy minion grains. New in version 2015.8.2.

salt.grains.mdadm¶

Detect MDADM RAIDs

salt.grains.opts¶

Simple grain to merge the opts into the grains directly if the grain_opts configuration value is set

salt.grains.philips_hue¶

Static grains for the Philips HUE lamps New in version 2015.8.3.

salt.grains.rest_sample¶

Generate baseline proxy minion grains

execution modules¶

salt.modules.pkg¶

pkg is a virtual module that is fulfilled by one of the following modules:

Execution Module	Used for
aptpkg	Debian/Ubuntu-based distros which use apt-get(8) for package management
brew	Mac OS software management using Homebrew
ebuild	Gentoo-based systems (utilizes the portage python module as well as emerge(1))
freebsdpkg	FreeBSD-based OSes using pkg_add(1)
openbsdpkg	OpenBSD-based OSes using pkg_add(1)
pacman	Arch Linux-based distros using pacman(8)
pkgin	NetBSD-based OSes using pkgin(1)
pkgng	FreeBSD-based OSes using pkg(8)
pkgutil	Solaris-based OSes using OpenCSW's pkgutil(1)
solarispkg	Solaris-based OSes using pkgadd(1M)
solarisips	Solaris-based OSes using IPS pkg(1)
win_pkg	Salt's Windows Package Manager <windows-package-manager
yumpkg	RedHat-based distros and derivatives using yum(8) or dnf(8)
zypper	SUSE-based distros using zypper(8)

acme	ACME / Let's Encrypt module
aliases	Manage the information in the aliases file
alternatives	Support for Alternatives system
apache	Support for Apache
apcups	Module for apcupsd
apf	Support for Advanced Policy Firewall (APF)
aptpkg	Support for APT (Advanced Packaging Tool)
archive	A module to wrap (non-Windows) archive calls
artifactory	Module for fetching artifacts from Artifactory
at	Wrapper module for at(1)
augeas_cfg	Manages configuration files via augeas
aws_sqs	Support for the Amazon Simple Queue Service.
bamboohr	Support for BambooHR
bcache	Module for managing BCache sets
beacons	Module for managing the Salt beacons on a minion
bigip	An execution module which can manipulate an f5 bigip via iControl REST
blockdev	Module for managing block devices
bluez	Support for Bluetooth (using BlueZ in Linux).
boto_apigateway	Connection module for Amazon APIGateway
boto_asg	Connection module for Amazon Autoscale Groups
boto_cfn	Connection module for Amazon Cloud Formation
boto_cloudtrail	Connection module for Amazon CloudTrail
boto_cloudwatch	Connection module for Amazon CloudWatch
boto_cognitoidentity	Connection module for Amazon CognitoIdentity
boto_datapipeline	Connection module for Amazon Data Pipeline
boto_dynamodb	Connection module for Amazon DynamoDB
boto_ec2	Connection module for Amazon EC2
boto_elasticache	Connection module for Amazon Elasticache
boto_elasticsearch_domain	Connection module for Amazon Elasticsearch Service
boto_elb	Connection module for Amazon ELB
boto_iam	Connection module for Amazon IAM
boto_iot	Connection module for Amazon IoT
boto_kms	Connection module for Amazon KMS
boto_lambda	Connection module for Amazon Lambda
boto_rds	Connection module for Amazon RDS
boto_route53	Connection module for Amazon Route53
boto_secgroup	Connection module for Amazon Security Groups
boto_sns	Connection module for Amazon SNS
boto_sqs	Connection module for Amazon SQS
boto_vpc	Connection module for Amazon VPC
bower	Manage and query Bower packages
bridge	Module for gathering and managing bridging information
bsd_shadow	Manage the password database on BSD systems
btrfs	Module for managing BTRFS file systems.
cabal	Manage and query Cabal packages
cassandra	Cassandra NoSQL Database Module
cassandra_cql	Cassandra Database Module
chassis	Glue execution module to link to the fx2 proxymodule.
chef	Execute chef in server or solo mode
chocolatey	A dead simple module wrapping calls to the Chocolatey package manager
chronos	Module providing a simple management interface to a chronos cluster.
cloud	Salt-specific interface for calling Salt Cloud directly
cmdmod	A module for shelling out.
composer	Use composer to install PHP dependencies for a directory
config	Return config information
consul	Interact with Consul
container_resource	Common resources for LXC and systemd-nspawn containers
cp	Minion side functions for salt-cp
cpan	Manage Perl modules using CPAN
cron	Work with cron
csf	Support for Config Server Firewall (CSF)
cyg	Manage cygwin packages.
cytest
daemontools	daemontools service module. This module will create daemontools type
data	Manage a local persistent data structure that can hold any arbitrary data
ddns	Support for RFC 2136 dynamic DNS updates.
deb_apache	Support for Apache
deb_postgres	Module to provide Postgres compatibility to salt for debian family specific tools.
debbuild	Debian Package builder system
debconfmod	Support for Debconf
debian_ip	The networking module for Debian based distros
debian_service	Service support for Debian systems (uses update-rc.d and /sbin/service)
defaults
devmap	Device-Mapper module
dig	Compendium of generic DNS utilities.
disk	Module for managing disks and blockdevices
djangomod	Manage Django sites
dnsmasq	Module for managing dnsmasq
dnsutil	Compendium of generic DNS utilities
dockercompose	Module to import docker-compose via saltstack
dockerio	Management of Docker Containers
dockerng	Management of Docker Containers
dpkg	Support for DEB packages
drac	Manage Dell DRAC
dracr	Manage Dell DRAC.
drbd	DRBD administration module
ebuild	Support for Portage
eix	Support for Eix
elasticsearch	Elasticsearch - A distributed RESTful search and analytics server
environ	Support for getting and setting the environment variables of the current salt process.
eselect	Support for eselect, Gentoo's configuration and management tool.
esxi	Glues the VMware vSphere Execution Module to the VMware ESXi Proxy Minions to the esxi proxymodule.
etcd_mod	Execution module to work with etcd
ethtool	Module for running ethtool command
event	Use the Salt Event System to fire events from the master to the minion and vice-versa.
extfs	Module for managing ext2/3/4 file systems
file	Manage information about regular files, directories,
firewalld	Support for firewalld.
freebsd_sysctl	Module for viewing and modifying sysctl parameters
freebsdjail	The jail module for FreeBSD
freebsdkmod	Module to manage FreeBSD kernel modules
freebsdpkg	Remote package support using pkg_add(1)
freebsdports	Install software from the FreeBSD ports(7) system
freebsdservice	The service module for FreeBSD
gem	Manage ruby gems.
genesis	Module for managing container and VM images
gentoo_service	Top level package command wrapper, used to translate the os detected by grains
gentoolkitmod	Support for Gentoolkit
git	Support for the Git SCM
github	Module for interacting with the GitHub v3 API.
glance	Module for handling openstack glance calls.
glusterfs	Manage a glusterfs pool
gnomedesktop	GNOME implementations
gpg	Manage a GPG keychains, add keys, create keys, retrieve keys from keyservers.
grains	Return/control aspects of the grains data
group
groupadd	Manage groups on Linux, OpenBSD and NetBSD
grub_legacy	Support for GRUB Legacy
guestfs	Interact with virtual machine images via libguestfs
hadoop	Support for hadoop
haproxyconn	Support for haproxy
hashutil	A collection of hashing and encoding functions
hg	Support for the Mercurial SCM
hipchat	Module for sending messages to hipchat.
hosts	Manage the information in the hosts file
htpasswd	Support for htpasswd command.
http	Module for making various web calls.
ifttt	Support for IFTTT
ilo	Manage HP ILO
img	Virtual machine image management tools
incron	Work with incron
influx	InfluxDB - A distributed time series database
infoblox	Module for managing Infoblox
ini_manage	Edit ini files
inspectlib
inspectlib.collector
inspectlib.dbhandle
inspectlib.exceptions
inspectlib.query
introspect	Functions to perform introspection on a minion, and return data in a format
ipmi	Support IPMI commands over LAN.
ipset	Support for ipset
iptables	Support for iptables
iwtools	Support for Wireless Tools for Linux
jboss7	Module for managing JBoss AS 7 through the CLI interface.
jboss7_cli	Module for low-level interaction with JbossAS7 through CLI.
jenkins	Module for controlling Jenkins
junos	Module for interfacing to Junos devices.
k8s	Salt module to manage Kubernetes cluster
kapacitor	Kapacitor execution module.
kerberos	Manage Kerberos KDC
key	Functions to view the minion's public key information
keyboard	Module for managing keyboards on supported POSIX-like systems using systemd, or such as Redhat, Debian and Gentoo.
keystone	Module for handling openstack keystone calls.
kmod	Module to manage Linux kernel modules
launchctl	Module for the management of MacOS systems that use launchd/launchctl
layman	Support for Layman
ldap3	Query and modify an LDAP database (alternative interface)
ldapmod	Salt interface to LDAP commands
linux_acl	Support for Linux File Access Control Lists
linux_ip	The networking module for Non-RH/Deb Linux distros
linux_lvm	Support for Linux LVM2
linux_sysctl	Module for viewing and modifying sysctl parameters
localemod	Module for managing locales on POSIX-like systems.
locate	Module for using the locate utilities
logadm	Module for managing Solaris logadm based log rotations.
logrotate	Module for managing logrotate.
lvs	Support for LVS (Linux Virtual Server)
lxc	Control Linux Containers via Salt
mac_assistive	This module allows you to manage assistive access on macOS minions with 10.9+
mac_brew	Homebrew for macOS
mac_defaults	Set defaults on Mac OS
mac_desktop	macOS implementations of various commands in the "desktop" interface
mac_group	Manage groups on Mac OS 10.7+
mac_keychain	Install certificates into the keychain on Mac OS
mac_package	Install pkg, dmg and .app applications on macOS minions.
mac_pkgutil	Installer support for macOS.
mac_ports	Support for MacPorts under macOS.
mac_power	Module for editing power settings on macOS
mac_service	The service module for macOS ..
mac_shadow	New in version 2016.3.0.
mac_softwareupdate	Support for the softwareupdate command on MacOS.
mac_user	Manage users on Mac OS 10.7+
mac_sysctl	Module for viewing and modifying sysctl parameters
mac_system	New in version 2016.3.0.
mac_timezone	Module for editing date/time settings on macOS
mac_user	Manage users on Mac OS 10.7+
mac_xattr	This module allows you to manage extended attributes on files or directories
makeconf	Support for modifying make.conf under Gentoo
marathon	Module providing a simple management interface to a marathon cluster.
match	The match module allows for match routines to be run and determine target specs
mdadm	Salt module to manage RAID arrays with mdadm
mdata	Module for managaging metadata in SmartOS Zones
memcached	Module for Management of Memcached Keys
mine	The function cache system allows for data to be stored on the master so it can be easily read by other minions
minion	Module to provide information about minions
mod_random	Provides access to randomness generators.
modjk	Control Modjk via the Apache Tomcat "Status" worker
mongodb	Module to provide MongoDB functionality to Salt
monit	Monit service module.
moosefs	Module for gathering and managing information about MooseFS
mount	Salt module to manage Unix mounts and the fstab file
mssql	Module to provide MS SQL Server compatibility to salt.
munin	Run munin plugins/checks from salt and format the output as data.
mysql	Module to provide MySQL compatibility to salt.
nacl	This module helps include encrypted passwords in pillars, grains and salt state files.
nagios	Run nagios plugins/checks from salt and get the return as data.
nagios_rpc	Check Host & Service status from Nagios via JSON RPC.
napalm_bgp	NAPALM BGP
napalm_network	NAPALM Network
napalm_ntp	NAPALM NTP
napalm_probes	NAPALM Probes
napalm_route	NAPALM Route
napalm_snmp	NAPALM SNMP
napalm_users	NAPALM Users
netaddress	Module for getting information about network addresses.
netbsd_sysctl	Module for viewing and modifying sysctl parameters
netbsdservice	The service module for NetBSD
netscaler	Module to provide Citrix Netscaler compatibility to Salt (compatible with netscaler 9.2+)
network	Module for gathering and managing network information
neutron	Module for handling OpenStack Neutron calls
nfs3	Module for managing NFS version 3.
nftables	Support for nftables
nginx	Support for nginx
nova	Module for handling OpenStack Nova calls
npm	Manage and query NPM packages.
nspawn	Manage nspawn containers
nxos	Execution module for Cisco NX OS Switches Proxy minions
omapi	This module interacts with an ISC DHCP Server via OMAPI.
openbsd_sysctl	Module for viewing and modifying OpenBSD sysctl parameters
openbsdpkg	Package support for OpenBSD
openbsdrcctl	The rcctl service module for OpenBSD
openbsdservice	The service module for OpenBSD
openstack_config	Modify, retrieve, or delete values from OpenStack configuration files.
openvswitch	Support for Open vSwitch - module with basic Open vSwitch commands.
opkg	Support for Opkg
oracle	Oracle DataBase connection module
osquery	Support for OSQuery - https://osquery.io.
pacman	A module to wrap pacman calls, since Arch is the best
pagerduty	Module for Firing Events via PagerDuty
pagerduty_util	Module for manageing PagerDuty resource
pam	Support for pam
parallels	Manage Parallels Desktop VMs with prlctl and prlsrvctl.
parted	Module for managing partitions on POSIX-like systems.
pcs	Configure a Pacemaker/Corosync cluster with PCS
pecl	Manage PHP pecl extensions.
philips_hue	Philips HUE lamps module for proxy.
pillar	Extract the pillar data for this minion
pip	Install Python packages with pip to either the system or a virtualenv
pkg_resource	Resources needed by pkg providers
pkgin	Package support for pkgin based systems, inspired from freebsdpkg module
pkgng	Support for pkgng, the new package manager for FreeBSD
pkgutil	Pkgutil support for Solaris
portage_config	Configure portage(5)
postfix	Support for Postfix
postgres	Module to provide Postgres compatibility to salt.
poudriere	Support for poudriere
powerpath	powerpath support.
proxy	This module allows you to manage proxy settings
ps	A salt interface to psutil, a system and process library.
publish	Publish a command from a minion to a target
puppet	Execute puppet routines
pushbullet	Module for sending messages to Pushbullet (https://www.pushbullet.com)
pushover_notify	Module for sending messages to Pushover (https://www.pushover.net)
pw_group	Manage groups on FreeBSD
pw_user	Manage users with the useradd command
pyenv	Manage python installations with pyenv.
qemu_img	Qemu-img Command Wrapper
qemu_nbd	Qemu Command Wrapper
quota	Module for managing quotas on POSIX-like systems.
rabbitmq	Module to provide RabbitMQ compatibility to Salt.
raet_publish	Publish a command from a minion to a target
rallydev	Support for RallyDev
random_org	Module for retrieving random information from Random.org
rbenv	Manage ruby installations with rbenv.
rdp	Manage RDP Service on Windows servers
redismod	Module to provide redis functionality to Salt
reg
rest_package	Package support for the REST example
rest_service	Provide the service module for the proxy-minion REST sample
restartcheck	checkrestart functionality for Debian and Red Hat Based systems
ret	Module to integrate with the returner system and retrieve data sent to a salt returner
rh_ip	The networking module for RHEL/Fedora based distros
rh_service	Service support for RHEL-based systems, including support for both upstart and sysvinit
riak	Riak Salt Module
rpm	Support for rpm
rpmbuild	RPM Package builder system
rsync	Wrapper for rsync
runit	runit service module
rvm	Manage ruby installations and gemsets with RVM, the Ruby Version Manager.
s3	Connection module for Amazon S3
s6	s6 service module
salt_proxy	Salt proxy module
saltcloudmod	Control a salt cloud system
saltutil	The Saltutil module is used to manage the state of the salt minion itself.
schedule	Module for managing the Salt schedule on a minion
scsi	SCSI administration module
sdb	Module for Manipulating Data via the Salt DB API
seed	Virtual machine image management tools
selinux	Execute calls on selinux
sensors	Read lm-sensors
serverdensity_device	Wrapper around Server Density API
service	If Salt's OS detection does not identify a different virtual service module, the minion will fall back to using this basic module, which simply wraps sysvinit scripts.
shadow	Manage the shadow file on Linux systems
slack_notify	Module for sending messages to Slack
slsutil	Utility functions for use with or in SLS files
smartos_imgadm	Module for running imgadm command on SmartOS
smartos_nictagadm	Module for running nictagadm command on SmartOS
smartos_virt	virst compatibility module for managing VMs on SmartOS
smartos_vmadm	Module for running vmadm command on SmartOS
smbios	Interface to SMBIOS/DMI
smf	Service support for Solaris 10 and 11, should work with other systems that use SMF also.
smtp	Module for Sending Messages via SMTP
solaris_fmadm	Module for running fmadm and fmdump on Solaris
solaris_group	Manage groups on Solaris
solaris_shadow	Manage the password database on Solaris systems
solaris_system	Support for reboot, shutdown, etc
solaris_user	Manage users with the useradd command
solarisips	IPS pkg support for Solaris
solarispkg	Package support for Solaris
solr	Apache Solr Salt Module
splunk	Module for interop with the Splunk API
splunk_search	Module for interop with the Splunk API
sqlite3	Support for SQLite3
ssh	Manage client ssh components
ssh_package	Service support for the REST example
ssh_service	Provide the service module for the proxy-minion SSH sample ..
snapper	Module to manage filesystem snapshots with snapper
state	Control the state system on the minion.
status	Module for returning various status data about a minion.
stormpath	Support for Stormpath
supervisord	Provide the service module for system supervisord or supervisord in a
svn	Subversion SCM
swift	Module for handling OpenStack Swift calls
sysbench	The 'sysbench' module is used to analyze the performance of the minions, right from the master! It measures various system parameters such as CPU, Memory, File I/O, Threads and Mutex.
sysfs	Module for interfacing with SysFS
syslog_ng	Module for getting information about syslog-ng
sysmod	The sys module provides information about the available functions on the minion
sysrc	sysrc module for FreeBSD
system	Support for reboot, shutdown, etc
system_profiler	System Profiler Module
systemd	Provides the service module for systemd
telemetry	Connection module for Telemetry
temp	Simple module for creating temporary directories and files
test	Module for running arbitrary tests
test_virtual	Module for running arbitrary tests with a __virtual__ function
timezone	Module for managing timezone on POSIX-like systems.
tls	A salt module for SSL/TLS.
tomcat	Support for Tomcat
trafficserver	Apache Traffic Server execution module.
tuned	Interface to Red Hat tuned-adm module
twilio_notify	Module for notifications via Twilio
udev	Manage and query udev info
upstart	Module for the management of upstart systems.
uptime	Wrapper around uptime API
user
useradd	Manage users with the useradd command
uwsgi	uWSGI stats server https://uwsgi-docs.readthedocs.io/en/latest/StatsServer.html
varnish	Support for Varnish
vbox_guest	VirtualBox Guest Additions installer
vboxmanage	Support for VirtualBox using the VBoxManage command
victorops	Support for VictorOps
virt	Work with virtual machines managed by libvirt
virtualenv_mod	Create virtualenv environments.
vsphere	Manage VMware vCenter servers and ESXi hosts.
win_autoruns	Module for listing programs that automatically run on startup
win_certutil	This module allows you to install certificates into the windows certificate manager.
win_dacl	Manage DACLs on Windows
win_disk	Module for gathering disk information on Windows
win_dism	Install features/packages for Windows using DISM, which is useful for minions not running server versions of Windows.
win_dns_client	Module for configuring DNS Client on Windows systems
win_dsc	Module for working with DSC (Alpha)
win_file	Manage information about files on the minion, set/read user, group
win_firewall	Module for configuring Windows Firewall
win_groupadd	Manage groups on Windows
win_iis	Microsoft IIS site management via WebAdministration powershell module
win_ip	The networking module for Windows based systems
win_license	This module allows you to manage windows licensing via slmgr.vbs
win_network	Module for gathering and managing network information
win_ntp	Management of NTP servers on Windows
win_path	Manage the Windows System PATH
win_pkg	A module to manage software on Windows
win_powercfg	This module allows you to control the power settings of a windows minion via powercfg.
win_repo	Module to manage Windows software repo on a Standalone Minion
win_servermanager	Manage Windows features via the ServerManager powershell module
win_service	Windows Service module.
win_shadow	Manage the shadow file
win_status	Module for returning various status data about a minion.
win_system	Module for managing windows systems.
win_task	Windows Task Scheduler Module ..
win_timezone	Module for managing timezone on Windows systems.
win_update	Module for running windows updates.
win_useradd	Module for managing Windows Users
win_wua	Module for managing Windows Updates using the Windows Update Agent.
x509	Manage X509 certificates
xapi	This module (mostly) uses the XenAPI to manage Xen virtual machines.
xbps-pkg
xfs	Module for managing XFS file systems.
xmpp	Module for Sending Messages via XMPP (a.k.a.
yumpkg	Support for YUM/DNF
zabbix	Support for Zabbix
zcbuildout	Management of zc.buildout
zenoss	Module for working with the Zenoss API
zfs	Salt interface to ZFS commands
zk_concurrency	Concurrency controls in zookeeper
znc	znc - An advanced IRC bouncer
zpool	Module for running ZFS zpool command
zypper	Package support for openSUSE via the zypper package manager

salt.modules.acme module¶

ACME / Let's Encrypt module¶

This module currently uses letsencrypt-auto, which needs to be available in the path or in /opt/letsencrypt/. NOTE:
NOTE:
WARNING:
Most parameters will fall back to cli.ini defaults if None is given.

salt.modules.aliases¶

Manage the information in the aliases file

salt.modules.alternatives¶

Support for Alternatives system

salt.modules.apache¶

Support for Apache NOTE:

salt.modules.apcups¶

Module for apcupsd

salt.modules.apf¶

Support for Advanced Policy Firewall (APF)¶

salt.modules.aptpkg¶

Support for APT (Advanced Packaging Tool) IMPORTANT:
NOTE:

salt.modules.archive¶

A module to wrap (non-Windows) archive calls New in version 2014.1.0.

salt.modules.artifactory¶

Module for fetching artifacts from Artifactory

salt.modules.at¶

Wrapper module for at(1) Also, a 'tag' feature has been added to more easily tag jobs.

salt.modules.augeas_cfg¶

Manages configuration files via augeas This module requires the augeas Python module. WARNING:

salt.modules.aws_sqs¶

Support for the Amazon Simple Queue Service.

salt.modules.bamboohr¶

Support for BambooHR New in version 2015.8.0. Requires a subdomain and an apikey in /etc/salt/minion:

salt.modules.bcache module¶

Module for managing BCache sets BCache is a block-level caching mechanism similar to ZFS L2ARC/ZIL, dm-cache and fscache. It works by formatting one block device as a cache set, then adding backend devices (which need to be formatted as such) to the set and activating them. It's available in Linux mainline kernel since 3.10 https://www.kernel.org/doc/Documentation/bcache.txt This module needs the bcache userspace tools to function.

salt.modules.beacons¶

Module for managing the Salt beacons on a minion New in version 2015.8.0.

salt.modules.bigip¶

salt.modules.blockdev¶

Module for managing block devices New in version 2014.7.0. Deprecated since version 2016.11.0: Merged to disk module

salt.modules.bluez¶

Support for Bluetooth (using BlueZ in Linux). The following packages are required packages for this module:

salt.modules.boto_apigateway module¶

Connection module for Amazon APIGateway
Changed in version 2015.8.0: All methods now return a dictionary. Create and delete methods return:
or
Request methods (e.g., describe_apigateway) return:
or

salt.modules.boto_asg¶

Connection module for Amazon Autoscale Groups New in version 2014.7.0.

salt.modules.boto_cfn¶

Connection module for Amazon Cloud Formation New in version 2015.5.0.

salt.modules.boto_cloudtrail module¶

Connection module for Amazon CloudTrail New in version 2016.3.0.

salt.modules.boto_cloudwatch¶

Connection module for Amazon CloudWatch New in version 2014.7.0.

salt.modules.boto_cognitoidentity module¶

Connection module for Amazon CognitoIdentity New in version 2016.11.0.
Changed in version 2015.8.0: All methods now return a dictionary. Create, delete, set, and update methods return:
or
Request methods (e.g., describe_identity_pools) return:
or

salt.modules.boto_datapipeline module¶

Connection module for Amazon Data Pipeline New in version 2016.3.0.

salt.modules.boto_dynamodb¶

Connection module for Amazon DynamoDB New in version 2015.5.0.

salt.modules.boto_ec2¶

Connection module for Amazon EC2 New in version 2015.8.0.

salt.modules.boto_elasticache¶

Connection module for Amazon Elasticache New in version 2014.7.0.

salt.modules.boto_elasticsearch_domain module¶

Connection module for Amazon Elasticsearch Service New in version 2016.11.0.

salt.modules.boto_elb¶

Connection module for Amazon ELB New in version 2014.7.0.

salt.modules.boto_iam¶

Connection module for Amazon IAM New in version 2014.7.0.

salt.modules.boto_iot module¶

Connection module for Amazon IoT New in version 2016.3.0.

salt.modules.boto_kms¶

Connection module for Amazon KMS New in version 2015.8.0.

salt.modules.boto_lambda module¶

Connection module for Amazon Lambda New in version 2016.3.0.
Changed in version 2015.8.0: All methods now return a dictionary. Create and delete methods return:
or
Request methods (e.g., describe_function) return:
or

salt.modules.boto_rds¶

Connection module for Amazon RDS New in version 2015.8.0.

salt.modules.boto_route53¶

Connection module for Amazon Route53 New in version 2014.7.0.

salt.modules.boto_secgroup¶

Connection module for Amazon Security Groups New in version 2014.7.0.

salt.modules.boto_sns¶

Connection module for Amazon SNS

salt.modules.boto_sqs¶

Connection module for Amazon SQS New in version 2014.7.0.

salt.modules.boto_vpc¶

Connection module for Amazon VPC New in version 2014.7.0.
Changed in version 2015.8.0: All methods now return a dictionary. Create and delete methods return:
or
Request methods (e.g., describe_vpc) return:
or

New in version 2016.11.0. Functions to request, accept, delete and describe VPC peering connections. Named VPC peering connections can be requested using these modules. VPC owner accounts can accept VPC peering connections (named or otherwise). Examples showing creation of VPC peering connection
Check to see if VPC peering connection is pending
Accept VPC peering connection
Deleting VPC peering connection via this module

salt.modules.bower¶

Manage and query Bower packages¶

This module manages the installed packages using Bower. Note that npm, git and bower must be installed for this module to be available.

salt.modules.bridge¶

Module for gathering and managing bridging information

salt.modules.bsd_shadow¶

Manage the password database on BSD systems IMPORTANT:

salt.modules.btrfs¶

Module for managing BTRFS file systems.

salt.modules.cabal¶

Manage and query Cabal packages¶

New in version 2015.8.0.

salt.modules.cassandra¶

Cassandra NoSQL Database Module

salt.modules.cassandra_cql¶

Cassandra Database Module New in version 2015.5.0.

salt.modules.chassis¶

Glue execution module to link to the fx2 proxymodule. Depends: iDRAC Remote execution module (salt.modules.dracr) For documentation on commands that you can direct to a Dell chassis via proxy, look in the documentation for salt.modules.dracr. This execution module calls through to a function in the fx2 proxy module called chconfig. That function looks up the function passed in the cmd parameter in salt.modules.dracr and calls it. New in version 2015.8.2.

salt.modules.chef¶

Execute chef in server or solo mode

salt.modules.chocolatey¶

A dead simple module wrapping calls to the Chocolatey package manager ( http://chocolatey.org) New in version 2014.1.0.

salt.modules.chronos module¶

Module providing a simple management interface to a chronos cluster. Currently this only works when run through a proxy minion. New in version 2015.8.2.

salt.modules.cloud¶

Salt-specific interface for calling Salt Cloud directly

salt.modules.cmdmod¶

A module for shelling out. Keep in mind that this module is insecure, in that it can give whomever has access to the master root execution access to all salt minions.

salt.modules.composer¶

Use composer to install PHP dependencies for a directory

salt.modules.config¶

Return config information

salt.modules.consul¶

Interact with Consul https://www.consul.io

salt.modules.container_resource¶

Common resources for LXC and systemd-nspawn containers New in version 2015.8.0. These functions are not designed to be called directly, but instead from the lxc, nspawn, and dockerng execution modules. They provide for common logic to be re-used for common actions.

salt.modules.cp¶

Minion side functions for salt-cp

salt.modules.cpan¶

Manage Perl modules using CPAN New in version 2015.5.0.

salt.modules.cron¶

Work with cron NOTE:

salt.modules.csf¶

Support for Config Server Firewall (CSF)¶

salt.modules.cyg¶

Manage cygwin packages. Module file to accompany the cyg state.

salt.modules.daemontools¶

daemontools service module. This module will create daemontools type service watcher. This module is compatible with the service states, so it can be used to maintain services using the provider argument:

salt.modules.data¶

Manage a local persistent data structure that can hold any arbitrary data specific to the minion

salt.modules.ddns¶

Support for RFC 2136 dynamic DNS updates.

salt.modules.deb_apache¶

Support for Apache Please note: The functions in here are Debian-specific. Placing them in this separate file will allow them to load only on Debian-based systems, while still loading under the apache namespace.

salt.modules.deb_postgres¶

Module to provide Postgres compatibility to salt for debian family specific tools.

salt.modules.debbuild¶

Debian Package builder system New in version 2015.8.0. This system allows for all of the components to build debs safely in chrooted environments. This also provides a function to generate debian repositories This module implements the pkgbuild interface

salt.modules.debconfmod¶

Support for Debconf

salt.modules.debian_ip¶

The networking module for Debian based distros References:

salt.modules.debian_service¶

Service support for Debian systems (uses update-rc.d and /sbin/service) IMPORTANT:

salt.modules.defaults¶

salt.modules.devmap¶

Device-Mapper module

salt.modules.dig¶

Compendium of generic DNS utilities. The 'dig' command line tool must be installed in order to use this module.

salt.modules.disk¶

Module for managing disks and blockdevices

salt.modules.djangomod¶

Manage Django sites

salt.modules.dnsmasq¶

Module for managing dnsmasq

salt.modules.dnsutil¶

Compendium of generic DNS utilities

salt.modules.dockercompose module¶

Module to import docker-compose via saltstack New in version 2016.3.0.

Introduction¶

This module allows one to deal with docker-compose file in a directory. This is a first version only, the following commands are missing at the moment but will be built later on if the community is interested in this module:

Installation Prerequisites¶

This execution module requires at least version 1.4.0 of both docker-compose and Docker. docker-compose can easily be installed using pip.install:

How to use this module?¶

In order to use the module if you have no docker-compose file on the server you can issue the command create, it takes two arguments the path where the docker-compose.yml will be stored and the content of this latter:
Then you can execute a list of method defined at the bottom with at least one argument (the path where the docker-compose.yml will be read) and an optional python list which corresponds to the services names:

Docker-compose method supported¶

Functions¶

Detailed Function Documentation¶

salt.modules.dockerio¶

Management of Docker Containers New in version 2014.1.0. Deprecated since version 2015.8.0: Future feature development will be done only in dockerng. See the documentation for this module for information on the deprecation path. NOTE:

General Notes¶

As we use states, we don't want to be continuously popping dockers, so we will map each container id (or image) with a grain whenever it is relevant. As a corollary, we will resolve a container id either directly by the id or try to find a container id matching something stocked in grain.

Installation Prerequisites¶

Prerequisite Pillar Configuration for Authentication¶

salt.modules.dockerng¶

Management of Docker Containers New in version 2015.8.0.

Why Make a Second Docker Execution Module?¶

We have received a lot of feedback on our Docker support. In the process of implementing recommended improvements, it became obvious that major changes needed to be made to the functions and return data. In the end, a complete rewrite was done. The changes being too significant, it was decided that making a separate execution module and state module (called dockerng) would be the best option. This will give users a couple release cycles to modify their scripts, SLS files, etc. to use the new functionality, rather than forcing users to change everything immediately. In the Nitrogen release of Salt (due in 2017), this execution module will take the place of the default Docker execution module, and backwards-compatible naming will be maintained for a couple releases after that to allow users time to replace references to dockerng with docker.

Installation Prerequisites¶

This execution module requires at least version 1.4.0 of both docker-py and Docker. docker-py can easily be installed using pip.install:

Authentication¶

To push or pull images, credentials must be configured. By default dockerng will try to get the credentials from the default docker auth file, located under the home directory of the user running the salt-minion (HOME/.docker/config.json). Because a password must be used, it is recommended to place this configuration in Pillar data. If pillar data specifies a registry already present in the default docker auth file, it will override. The configuration schema is as follows:
For example:
Reauth is an optional parameter that forces the docker login to reauthorize using the credentials passed in the pillar data. Defaults to false. New in version 2016.3.5,2016.11.1. For example:
Mulitiple registries can be configured. This can be done in one of two ways. The first way is to configure each registry under the docker-registries pillar key.
The second way is to use separate pillar variables ending in -docker-registries:
Both methods can be combined; any registry configured under docker-registries or *-docker-registries will be detected.

Configuration Options¶

The following configuration options can be set to fine-tune how Salt uses Docker:
These configuration options are retrieved using config.get (click the link for further information).

Functions¶

Executing Commands Within a Running Container¶

Multiple methods exist for executing commands within Docker containers:
Adding a configuration option (see config.get) called docker.exec_driver will tell Salt which execution driver to use:
If this configuration option is not found, Salt will use the appropriate interface (either nsenter or lxc-attach) based on the Execution Driver value returned from docker info. docker-exec will not be used by default, as it is presently (as of version 1.6.2) only able to execute commands as the effective user of the container. Thus, if a USER directive was used to run as a non-privileged user, docker-exec would be unable to perform the action as root. Salt can still use docker-exec as an execution driver, but must be explicitly configured (as in the example above) to do so at this time. If possible, try to manually specify the execution driver, as it will save Salt a little work. This execution module provides functions that shadow those from the cmd module. They are as follows:

Detailed Function Documentation¶

salt.modules.dpkg¶

Support for DEB packages

salt.modules.drac¶

Manage Dell DRAC

salt.modules.dracr¶

Manage Dell DRAC. New in version 2015.8.2.

salt.modules.drbd¶

DRBD administration module

salt.modules.ebuild¶

Support for Portage IMPORTANT:

For now all package names MUST include the package category, i.e. 'vim' will not work, 'app-editors/vim' will.

salt.modules.eix¶

Support for Eix

salt.modules.elasticsearch¶

Elasticsearch - A distributed RESTful search and analytics server Module to provide Elasticsearch compatibility to Salt (compatible with Elasticsearch version 1.5.2+) New in version 2015.8.0.

salt.modules.environ¶

Support for getting and setting the environment variables of the current salt process.

salt.modules.eselect¶

Support for eselect, Gentoo's configuration and management tool.

salt.modules.esxi¶

Glues the VMware vSphere Execution Module to the VMware ESXi Proxy Minions to the esxi proxymodule. New in version 2015.8.4. Depends: vSphere Remote Execution Module (salt.modules.vsphere) For documentation on commands that you can direct to an ESXi host via proxy, look in the documentation for salt.modules.vsphere. This execution module calls through to a function in the ESXi proxy module called ch_config, which looks up the function passed in the command parameter in salt.modules.vsphere and calls it. To execute commands with an ESXi Proxy Minion using the vSphere Execution Module, use the esxi.cmd <vsphere-function-name> syntax. Both args and kwargs needed for various vsphere execution module functions must be passed through in a kwarg- type manor.

salt.modules.etcd_mod¶

Execution module to work with etcd

Configuration¶

To work with an etcd server you must configure an etcd profile. The etcd config can be set in either the Salt Minion configuration file or in pillar:
It is technically possible to configure etcd without using a profile, but this is not considered to be a best practice, especially when multiple etcd servers or clusters are available.
NOTE:

salt.modules.ethtool module¶

Module for running ethtool command New in version 2016.3.0.

salt.modules.event¶

Use the Salt Event System to fire events from the master to the minion and vice-versa.

salt.modules.extfs¶

Module for managing ext2/3/4 file systems

salt.modules.file¶

Manage information about regular files, directories, and special files on the minion, set/read user, group, mode, and data


































































Forward slashes and single quotes will be escaped automatically in the before and after patterns. CLI Example:

salt.modules.firewalld¶

Support for firewalld. New in version 2015.2.0.

salt.modules.freebsd_sysctl¶

Module for viewing and modifying sysctl parameters

salt.modules.freebsdjail¶

The jail module for FreeBSD

salt.modules.freebsdkmod¶

Module to manage FreeBSD kernel modules

salt.modules.freebsdpkg¶

Remote package support using pkg_add(1) IMPORTANT:
WARNING:
This module acts as the default package provider for FreeBSD 9 and older. If you need to use pkgng on a FreeBSD 9 system, you will need to override the pkg provider by setting the providers parameter in your Minion config file, in order to use pkgng.
More information on pkgng support can be found in the documentation for the pkgng module. This module will respect the PACKAGEROOT and PACKAGESITE environment variables, if set, but these values can also be overridden in several ways:

salt.modules.freebsdports¶

Install software from the FreeBSD ports(7) system New in version 2014.1.0. This module allows you to install ports using BATCH=yes to bypass configuration prompts. It is recommended to use the ports state to install ports, but it it also possible to use this module exclusively from the command line.

salt.modules.freebsdservice¶

The service module for FreeBSD IMPORTANT:

salt.modules.gem¶

Manage ruby gems.

salt.modules.genesis¶

Module for managing container and VM images New in version 2014.7.0.

salt.modules.gentoo_service¶

Top level package command wrapper, used to translate the os detected by grains to the correct service manager IMPORTANT:

salt.modules.gentoolkitmod¶

Support for Gentoolkit

salt.modules.git¶

Support for the Git SCM

salt.modules.github module¶

Module for interacting with the GitHub v3 API. New in version 2016.3.0.

Configuration¶

Configure this module by specifying the name of a configuration profile in the minion config, minion pillar, or master config. The module will use the 'github' key by default, if defined. For example:

salt.modules.glance¶

Module for handling openstack glance calls.

salt.modules.glusterfs¶

Manage a glusterfs pool

salt.modules.gnomedesktop¶

GNOME implementations

salt.modules.gpg¶

Manage a GPG keychains, add keys, create keys, retrieve keys from keyservers. Sign, encrypt and sign plus encrypt text and files. New in version 2015.5.0. NOTE:

salt.modules.grains¶

Return/control aspects of the grains data

salt.modules.groupadd¶

Manage groups on Linux, OpenBSD and NetBSD IMPORTANT:

salt.modules.grub_legacy¶

Support for GRUB Legacy

salt.modules.guestfs¶

Interact with virtual machine images via libguestfs

salt.modules.hadoop¶

Support for hadoop

salt.modules.haproxyconn¶

Support for haproxy New in version 2014.7.0.

salt.modules.hashutil¶

A collection of hashing and encoding functions

salt.modules.hg¶

Support for the Mercurial SCM

salt.modules.hipchat¶

Module for sending messages to hipchat. New in version 2015.5.0.

salt.modules.hosts¶

Manage the information in the hosts file

salt.modules.htpasswd¶

Support for htpasswd command. Requires the apache2-utils package for Debian-based distros. New in version 2014.1.0. The functions here will load inside the webutil module. This allows other functions that don't use htpasswd to use the webutil module name.

salt.modules.http¶

Module for making various web calls. Primarily designed for webhooks and the like, but also useful for basic http testing. New in version 2015.5.0.

salt.modules.ifttt¶

Support for IFTTT New in version 2015.8.0. Requires an api_key in /etc/salt/minion:

salt.modules.ilo¶

Manage HP ILO

salt.modules.img¶

Virtual machine image management tools Deprecated since version 2016.3.0.

salt.modules.incron¶

Work with incron

salt.modules.influx¶

InfluxDB - A distributed time series database Module to provide InfluxDB compatibility to Salt (compatible with InfluxDB version 0.9+)

salt.modules.infoblox¶

Module for managing Infoblox Will look for pillar data infoblox:server, infoblox:user, infoblox:password if not passed to functions New in version 2016.3.0.

salt.modules.ini_manage¶

Edit ini files
(for example /etc/sysctl.conf)

salt.modules.inspectlib package¶

Submodules¶

salt.modules.inspectlib.collector module¶

salt.modules.inspectlib.dbhandle module¶

salt.modules.inspectlib.exceptions module¶

salt.modules.inspectlib.query module¶

Module contents¶

salt.modules.introspect¶

Functions to perform introspection on a minion, and return data in a format usable by Salt States

salt.modules.ipmi¶

Support IPMI commands over LAN. This module does not talk to the local systems hardware through IPMI drivers. It uses a python module pyghmi.

CLI Examples:


CLI Examples:


CLI Example:




CLI Examples:



CLI Examples:


CLI Examples:


CLI Example:


CLI Example:


CLI Example:


return
CLI Examples:


return
CLI Examples:


CLI Examples:


CLI Examples:


CLI Examples:

Returns

dict or True -- If callback is not provided, the response

CLI Examples:

•

user_level_auth -- .INDENT 2.0

User Level Authentication Enable/Disable.

•

access_mode --

Access Mode for IPMI messaging (PEF Alerting is enabled/disabled separately from IPMI messaging)

•

privilege_update_mode --

Channel Privilege Level Limit. This value sets the maximum privilege level that can be accepted on the specified channel.

•

privilege_level -- .INDENT 2.0

Channel Privilege Level Limit

•

kwargs -- .INDENT 2.0

•

api_host=127.0.0.1

•

api_user=admin

•

api_pass=example

•

api_port=623

•

api_kg=None

CLI Examples:


CLI Examples:

Returns

dict -- A dict describing the response retrieved

CLI Examples:



CLI Examples:


CLI Examples:

Returns

True on success when mode = test_password, return False on bad password

CLI Example:


CLI Examples:

salt.modules.ipset¶

Support for ipset

salt.modules.iptables¶

Support for iptables

salt.modules.iwtools module¶

Support for Wireless Tools for Linux

salt.modules.jboss7¶

Module for managing JBoss AS 7 through the CLI interface. New in version 2015.5.0.
Example:

salt.modules.jboss7_cli¶

Module for low-level interaction with JbossAS7 through CLI. This module exposes two ways of interaction with the CLI, either through commands or operations. NOTE:
The difference between calling a command or operation is in handling the result. Commands return a zero return code if operation is successful or return non-zero return code and print an error to standard output in plain text, in case of an error. Operations return a json-like structure, that contain more information about the result. In case of a failure, they also return a specific return code. This module parses the output from the operations and returns it as a dictionary so that an execution of an operation can then be verified against specific errors.
Example:

salt.modules.jenkins module¶

Module for controlling Jenkins New in version 2016.3.0.

salt.modules.junos¶

Module for interfacing to Junos devices.

salt.modules.k8s¶

Salt module to manage Kubernetes cluster New in version 2016.3.0. Roadmap:

salt.modules.kapacitor module¶

Kapacitor execution module.
New in version 2016.11.0.

salt.modules.kerberos¶

Manage Kerberos KDC

On the KDC minion you will need to add the following to the minion configuration file so Salt knows what keytab to use and what principal to authenticate as.

salt.modules.key¶

Functions to view the minion's public key information

salt.modules.keyboard¶

Module for managing keyboards on supported POSIX-like systems using systemd, or such as Redhat, Debian and Gentoo.

salt.modules.keystone¶

Module for handling openstack keystone calls.

salt.modules.kmod¶

Module to manage Linux kernel modules

salt.modules.launchctl¶

Module for the management of MacOS systems that use launchd/launchctl IMPORTANT:

salt.modules.layman¶

Support for Layman

salt.modules.ldap3¶

Query and modify an LDAP database (alternative interface)¶

New in version 2016.3.0. This is an alternative to the ldap interface provided by the ldapmod execution module.

salt.modules.ldapmod¶

Salt interface to LDAP commands
WARNING:

salt.modules.linux_acl¶

Support for Linux File Access Control Lists

salt.modules.linux_ip module¶

The networking module for Non-RH/Deb Linux distros

salt.modules.linux_lvm¶

Support for Linux LVM2

salt.modules.linux_sysctl¶

Module for viewing and modifying sysctl parameters

salt.modules.localemod¶

Module for managing locales on POSIX-like systems.

salt.modules.locate¶

Module for using the locate utilities

salt.modules.logadm¶

Module for managing Solaris logadm based log rotations.

salt.modules.logrotate¶

Module for managing logrotate.

salt.modules.lvs¶

Support for LVS (Linux Virtual Server)

salt.modules.lxc¶

Control Linux Containers via Salt
lxc >= 1.0 (even beta alpha) is required

salt.modules.mac_assistive module¶

This module allows you to manage assistive access on macOS minions with 10.9+ New in version 2016.3.0.

salt.modules.mac_brew module¶

Homebrew for macOS IMPORTANT:

salt.modules.mac_defaults module¶

Set defaults on Mac OS

salt.modules.mac_desktop module¶

macOS implementations of various commands in the "desktop" interface

salt.modules.mac_group¶

Manage groups on Mac OS 10.7+

salt.modules.mac_keychain module¶

Install certificates into the keychain on Mac OS New in version 2016.3.0.

salt.modules.mac_package module¶

Install pkg, dmg and .app applications on macOS minions.

salt.modules.mac_pkgutil module¶

Installer support for macOS. Installer is the native .pkg/.mpkg package manager for macOS.

salt.modules.mac_ports module¶

Support for MacPorts under macOS. This module has some caveats. 1. Updating the database of available ports is quite resource-intensive. However, refresh=True is the default for all operations that need an up-to-date copy of available ports. Consider refresh=False when you are sure no db update is needed. 2. In some cases MacPorts doesn't always realize when another copy of itself is running and will gleefully tromp all over the available ports database. This makes MacPorts behave in undefined ways until a fresh complete copy is retrieved. Because of 1 and 2 it is possible to get the salt-minion into a state where salt mac-machine pkg./something/ won't want to return. Use salt-run jobs.active on the master to check for potentially long-running calls to port. Finally, ports database updates are always handled with port selfupdate as opposed to port sync. This makes sense in the MacPorts user commmunity but may confuse experienced Linux admins as Linux package managers don't upgrade the packaging software when doing a package database update. In other words salt mac-machine pkg.refresh_db is more like apt-get update; apt-get upgrade dpkg apt-get than simply apt-get update.

salt.modules.mac_power module¶

Module for editing power settings on macOS

salt.modules.mac_service module¶

The service module for macOS

salt.modules.mac_shadow module¶

New in version 2016.3.0. Manage macOS local directory passwords and policies. Note that it is usually better to apply password policies through the creation of a configuration profile.

salt.modules.mac_softwareupdate module¶

Support for the softwareupdate command on MacOS.

salt.modules.mac_user¶

Manage users on Mac OS 10.7+ IMPORTANT:

salt.modules.mac_sysctl module¶

Module for viewing and modifying sysctl parameters

salt.modules.mac_system module¶

New in version 2016.3.0. System module for sleeping, restarting, and shutting down the system on Mac OS X. WARNING:

salt.modules.mac_timezone module¶

Module for editing date/time settings on macOS

salt.modules.mac_xattr module¶

This module allows you to manage extended attributes on files or directories

salt.modules.makeconf¶

Support for modifying make.conf under Gentoo

salt.modules.marathon module¶

Module providing a simple management interface to a marathon cluster. Currently this only works when run through a proxy minion. New in version 2015.8.2.

salt.modules.match¶

The match module allows for match routines to be run and determine target specs

salt.modules.mdadm¶

Salt module to manage RAID arrays with mdadm

salt.modules.mdata¶

Module for managaging metadata in SmartOS Zones New in version 2016.3.0.

salt.modules.memcached¶

Module for Management of Memcached Keys New in version 2014.1.0.

salt.modules.mine¶

The function cache system allows for data to be stored on the master so it can be easily read by other minions

salt.modules.minion module¶

Module to provide information about minions

salt.modules.mod_random¶

Provides access to randomness generators.¶

New in version 2014.7.0.

salt.modules.modjk¶

Control Modjk via the Apache Tomcat "Status" worker ( http://tomcat.apache.org/connectors-doc/reference/status.html) Below is an example of the configuration needed for this module. This configuration data can be placed either in grains or pillar. If using grains, this can be accomplished statically or via a grain module. If using pillar, the yaml configuration can be placed directly into a pillar SLS file, making this both the easier and more dynamic method of configuring this module.

salt.modules.mongodb¶

Module to provide MongoDB functionality to Salt

salt.modules.monit¶

Monit service module. This module will create a monit type service watcher.

salt.modules.moosefs¶

Module for gathering and managing information about MooseFS

salt.modules.mount¶

Salt module to manage Unix mounts and the fstab file

salt.modules.mssql¶

Module to provide MS SQL Server compatibility to salt.

salt.modules.munin¶

Run munin plugins/checks from salt and format the output as data.

salt.modules.mysql¶

Module to provide MySQL compatibility to salt.
NOTE:

Changed in version 2014.1.0: 'charset' connection argument added. This is a MySQL charset, not a python one. Changed in version 0.16.2: Connection arguments from the minion config file can be overridden on the CLI by using the arguments defined here. Additionally, it is now possible to setup a user with no password.

salt.modules.nacl¶

This module helps include encrypted passwords in pillars, grains and salt state files.
This is often useful if you wish to store your pillars in source control or share your pillar data with others that you trust. I don't advise making your pillars public regardless if they are encrypted or not. When generating keys and encrypting passwords use --local when using salt-call for extra security. Also consider using just the salt runner nacl when encrypting pillar passwords. The nacl lib uses 32byte keys, these keys are base64 encoded to make your life more simple. To generate your key or keyfile you can use:
Now with your key, you can encrypt some data:
To decrypt the data:
The following optional configurations can be defined in the minion or master config. Avoid storing the config in pillars!
When the key is defined in the master config you can use it from the nacl runner:
Now you can create a pillar with protected data like:
Or do something interesting with grains like:
Multi-line text items like certificates require a bit of extra work. You have to strip the new lines and replace them with '/n' characters. Certificates specifically require some leading white space when calling nacl.enc so that the '--' in the first line (commonly -----BEGIN CERTIFICATE-----) doesn't get interpreted as an argument to nacl.enc. For instance if you have a certificate file that lives in cert.crt:
Pillar data should look the same, even though the secret will be quite long. However, when calling multiline encrypted secrets from pillar in a state, use the following format to avoid issues with /n creating extra whitespace at the beginning of each line in the cert file:
The '{{-' will tell jinja to strip the whitespace from the beginning of each of the new lines.

salt.modules.nagios¶

Run nagios plugins/checks from salt and get the return as data.

salt.modules.nagios_rpc¶

Check Host & Service status from Nagios via JSON RPC. New in version 2015.8.0.

salt.modules.napalm_bgp module¶

NAPALM BGP¶

Manages BGP configuration on network devices and provides statistics.

Dependencies¶

New in version 2016.11.0.

salt.modules.napalm_network module¶

NAPALM Network¶

Basic methods for interaction with the network device through the virtual proxy 'napalm'.

Dependencies¶

New in version 2016.11.0.

salt.modules.napalm_ntp module¶

NAPALM NTP¶

Manages NTP on network devices.

Dependencies¶

SEE ALSO:
New in version 2016.11.0.

salt.modules.napalm_probes module¶

NAPALM Probes¶

Manages RPM/SLA probes on the network device.

Dependencies¶

SEE ALSO:
New in version 2016.11.0.

salt.modules.napalm_route module¶

NAPALM Route¶

Retrieves route details from network devices.

Dependencies¶

New in version 2016.11.0.

salt.modules.napalm_snmp module¶

NAPALM SNMP¶

Manages SNMP on network devices.

Dependencies¶

SEE ALSO:
New in version 2016.11.0.

salt.modules.napalm_users module¶

NAPALM Users¶

Manages the configuration of the users on network devices.

Dependencies¶

SEE ALSO:
New in version 2016.11.0.

salt.modules.netaddress¶

Module for getting information about network addresses. New in version 2016.3.0.

salt.modules.netbsd_sysctl¶

Module for viewing and modifying sysctl parameters

salt.modules.netbsdservice¶

The service module for NetBSD IMPORTANT:

salt.modules.netscaler¶

Module to provide Citrix Netscaler compatibility to Salt (compatible with netscaler 9.2+) New in version 2015.2.0.

NOTE:

salt.modules.network¶

Module for gathering and managing network information

salt.modules.neutron¶

Module for handling OpenStack Neutron calls

salt.modules.nfs3¶

Module for managing NFS version 3.

salt.modules.nftables¶

Support for nftables

salt.modules.nginx¶

Support for nginx

salt.modules.nova¶

Module for handling OpenStack Nova calls

salt.modules.npm¶

Manage and query NPM packages.

salt.modules.nspawn¶

Manage nspawn containers New in version 2015.8.0. systemd-nspawn(1) is a tool used to manage lightweight namespace containers. This execution module provides several functions to help manage these containers. Minions running systemd >= 219 will place new containers in /var/lib/machines, while those running systemd < 219 will place them in /var/lib/container.

salt.modules.nxos module¶

Execution module for Cisco NX OS Switches Proxy minions New in version 2016.11.0. For documentation on setting up the nxos proxy minion look in the documentation for salt.proxy.nxos.

salt.modules.omapi¶

This module interacts with an ISC DHCP Server via OMAPI. server_ip and server_port params may be set in the minion config or pillar:

salt.modules.openbsd_sysctl¶

Module for viewing and modifying OpenBSD sysctl parameters

salt.modules.openbsdpkg¶

Package support for OpenBSD IMPORTANT:

salt.modules.openbsdrcctl¶

The rcctl service module for OpenBSD

salt.modules.openbsdservice¶

The service module for OpenBSD IMPORTANT:

salt.modules.openstack_config¶

Modify, retrieve, or delete values from OpenStack configuration files.

salt.modules.openvswitch module¶

Support for Open vSwitch - module with basic Open vSwitch commands. Suitable for setting up Openstack Neutron.

salt.modules.opkg module¶

Support for Opkg IMPORTANT:
NOTE:

salt.modules.oracle¶

Oracle DataBase connection module

salt.modules.osquery¶

Support for OSQuery - https://osquery.io. New in version 2015.8.0.

salt.modules.pacman¶

A module to wrap pacman calls, since Arch is the best ( https://wiki.archlinux.org/index.php/Arch_is_the_best) IMPORTANT:

salt.modules.pagerduty¶

Module for Firing Events via PagerDuty New in version 2014.1.0.

salt.modules.pagerduty_util¶

Module for manageing PagerDuty resource
For PagerDuty API details, see https://developer.pagerduty.com/documentation/rest

salt.modules.pam¶

Support for pam

salt.modules.parallels module¶

Manage Parallels Desktop VMs with prlctl and prlsrvctl. Only some of the prlctl commands implemented so far. Of those that have been implemented, not all of the options may have been provided yet. For a complete reference, see the Parallels Desktop Reference Guide. What has not been implemented yet can be accessed through parallels.prlctl and parallels.prlsrvctl (note the preceeding double dash -- as necessary): New in version 2016.3.0.

salt.modules.parted¶

Module for managing partitions on POSIX-like systems.
Some functions may not be available, depending on your version of parted. Check the manpage for parted(8) for more information, or the online docs at: http://www.gnu.org/software/parted/manual/html_chapter/parted_2.html In light of parted not directly supporting partition IDs, some of this module has been written to utilize sfdisk instead. For further information, please reference the man page for sfdisk(8).

salt.modules.pcs module¶

Configure a Pacemaker/Corosync cluster with PCS¶

Configure Pacemaker/Cororsync clusters with the Pacemaker/Cororsync conifguration system (PCS)
New in version 2016.3.0.

salt.modules.pecl¶

Manage PHP pecl extensions.

salt.modules.philips_hue module¶

Philips HUE lamps module for proxy. New in version 2015.8.3.

salt.modules.pillar¶

Extract the pillar data for this minion

salt.modules.pip¶

Install Python packages with pip to either the system or a virtualenv

Windows Support¶

New in version 2014.7.4. Salt now uses a portable python. As a result the entire pip module is now functional on the salt installation itself. You can pip install dependencies for your custom modules. You can even upgrade salt itself using pip. For this to work properly, you must specify the Current Working Directory ( cwd) and the Pip Binary ( bin_env) salt should use. The variable pip_bin can be either a virtualenv path or the path to the pip binary itself. For example, the following command will list all software installed using pip to your current salt environment:
Specifying the cwd and bin_env options ensures you're modifying the salt environment. If these are omitted, it will default to the local installation of python. If python is not installed locally it will fail saying it couldn't find pip.

State File Support¶

This functionality works in states as well. If you need to pip install colorama with a state, for example, the following will work:

Upgrading Salt using Pip¶

You can now update salt using pip to any version from the 2014.7 branch forward. Previous version require recompiling some of the dependencies which is painful in windows. To do this you just use pip with git to update to the version you want and then restart the service. Here is a sample state file that upgrades salt to the head of the 2015.5 branch:
NOTE:

salt.modules.pkg_resource¶

Resources needed by pkg providers

salt.modules.pkgin¶

Package support for pkgin based systems, inspired from freebsdpkg module IMPORTANT:

salt.modules.pkgng¶

Support for pkgng, the new package manager for FreeBSD IMPORTANT:
WARNING:
This module provides an interface to pkg(8). It acts as the default package provider for FreeBSD 10 and newer. For FreeBSD hosts which have been upgraded to use pkgng, you will need to override the pkg provider by setting the providers parameter in your Minion config file, in order to use this module to manage packages, like so:

salt.modules.pkgutil¶

Pkgutil support for Solaris IMPORTANT:

salt.modules.portage_config¶

Configure portage(5)

salt.modules.postfix¶

Support for Postfix This module is currently little more than a config file viewer and editor. It is able to read the master.cf file (which is one style) and files in the style of main.cf (which is a different style, that is used in multiple postfix configuration files). The design of this module is such that when files are edited, a minimum of changes are made to them. Each file should look as if it has been edited by hand; order, comments and whitespace are all preserved.

salt.modules.postgres¶

Module to provide Postgres compatibility to salt.

salt.modules.poudriere¶

Support for poudriere

salt.modules.powerpath¶

powerpath support. Assumes RedHat

salt.modules.proxy module¶

This module allows you to manage proxy settings

salt.modules.ps¶

A salt interface to psutil, a system and process library. See http://code.google.com/p/psutil.

salt.modules.publish¶

Publish a command from a minion to a target

salt.modules.puppet¶

Execute puppet routines

salt.modules.pushbullet module¶

Module for sending messages to Pushbullet ( https://www.pushbullet.com) New in version 2015.8.0. Requires an api_key in /etc/salt/minion: For example:

salt.modules.pushover_notify¶

Module for sending messages to Pushover ( https://www.pushover.net) New in version 2016.3.0.

salt.modules.pw_group¶

Manage groups on FreeBSD IMPORTANT:

salt.modules.pw_user¶

Manage users with the useradd command IMPORTANT:

salt.modules.pyenv¶

Manage python installations with pyenv. NOTE:
New in version v2014.04.

salt.modules.qemu_img¶

Qemu-img Command Wrapper¶

The qemu img command is wrapped for specific functions

salt.modules.qemu_nbd¶

Qemu Command Wrapper The qemu system comes with powerful tools, such as qemu-img and qemu-nbd which are used here to build up kvm images.

salt.modules.quota¶

Module for managing quotas on POSIX-like systems.

salt.modules.rabbitmq¶

Module to provide RabbitMQ compatibility to Salt. Todo: A lot, need to add cluster support, logging, and minion configuration data.

salt.modules.raet_publish¶

Publish a command from a minion to a target

salt.modules.rallydev¶

Support for RallyDev New in version 2015.8.0. Requires a username and a password in /etc/salt/minion:

salt.modules.random_org¶

Module for retrieving random information from Random.org New in version 2015.5.0.

salt.modules.rbenv¶

Manage ruby installations with rbenv. rbenv is supported on Linux and macOS. rbenv doesn't work on Windows (and isn't really necessary on Windows as there is no system Ruby on Windows). On Windows, the RubyInstaller and/or Pik are both good alternatives to work with multiple versions of Ruby on the same box. http://misheska.com/blog/2013/06/15/using-rbenv-to-manage-multiple-versions-of-ruby/ New in version 0.16.0.

salt.modules.rdp¶

Manage RDP Service on Windows servers

salt.modules.redis¶

Module to provide redis functionality to Salt New in version 2014.7.0.

salt.modules.reg¶

Manage the Windows registry¶

Hives¶

Hives are the main sections of the registry and all begin with the word HKEY. - HKEY_LOCAL_MACHINE - HKEY_CURRENT_USER - HKEY_USER

Keys¶

Keys are the folders in the registry. Keys can have many nested subkeys. Keys can have a value assigned to them under the (Default)

Values or Entries¶

Values/Entries are name/data pairs. There can be many values in a key. The (Default) value corresponds to the Key, the rest are their own value pairs.

salt.modules.rest_package¶

Package support for the REST example

salt.modules.rest_service¶

Provide the service module for the proxy-minion REST sample

salt.modules.restartcheck module¶

checkrestart functionality for Debian and Red Hat Based systems Identifies services (processes) that are linked against deleted files (for example after downloading an updated binary of a shared library). Based on checkrestart script from debian-goodies (written by Matt Zimmerman for the Debian GNU/Linux distribution, https://packages.debian.org/debian-goodies) and psdel by Sam Morris.

salt.modules.ret¶

Module to integrate with the returner system and retrieve data sent to a salt returner

salt.modules.rh_ip¶

The networking module for RHEL/Fedora based distros

salt.modules.rh_service¶

Service support for RHEL-based systems, including support for both upstart and sysvinit IMPORTANT:

salt.modules.riak¶

Riak Salt Module

salt.modules.rpm¶

Support for rpm

salt.modules.rpmbuild¶

RPM Package builder system New in version 2015.8.0. This system allows for all of the components to build rpms safely in chrooted environments. This also provides a function to generate yum repositories This module implements the pkgbuild interface

salt.modules.rsync¶

Wrapper for rsync New in version 2014.1.0. This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar.

salt.modules.runit¶

runit service module ( http://smarden.org/runit) This module is compatible with the service states, so it can be used to maintain services using the provider argument:
Provides virtual service module on systems using runit as init. Service management rules ( sv command):
Service auto-start/stop mechanism:
Service's alias:

salt.modules.rvm¶

Manage ruby installations and gemsets with RVM, the Ruby Version Manager.

salt.modules.s3¶

Connection module for Amazon S3

salt.modules.s6 module¶

s6 service module This module is compatible with the service states, so it can be used to maintain services using the provider argument:
Note that the enabled argument is not available with this provider.

salt.modules.salt_proxy module¶

Salt proxy module New in version 2015.8.3. Module to deploy and manage salt-proxy processes on a minion.

salt.modules.saltcloudmod¶

Control a salt cloud system

salt.modules.saltutil¶

The Saltutil module is used to manage the state of the salt minion itself. It is used to manage minion modules as well as automate updates to the salt minion.

salt.modules.schedule¶

Module for managing the Salt schedule on a minion New in version 2014.7.0.

salt.modules.scsi¶

SCSI administration module

salt.modules.sdb¶

Module for Manipulating Data via the Salt DB API¶

salt.modules.seed¶

Virtual machine image management tools

salt.modules.selinux¶

Execute calls on selinux NOTE:

salt.modules.sensors¶

Read lm-sensors New in version 2014.1.3.

salt.modules.serverdensity_device¶

Wrapper around Server Density API¶

New in version 2014.7.0.

salt.modules.service¶

service is a virtual module that is fulfilled by one of the following modules:

Execution Module	Used for
debian_service	Debian Wheezy and earlier
freebsdservice	FreeBSD-based OSes using service(8)
gentoo_service	Gentoo Linux using sysvinit and rc-update(8)
launchctl	Mac OS hosts using launchctl(1)
netbsdservice	NetBSD-based OSes
openbsdservice	OpenBSD-based OSes
rh_service	RedHat-based distros and derivatives using service(8) and chkconfig(8). Supports both pure sysvinit and mixed sysvinit/upstart systems.
service	Fallback which simply wraps sysvinit scripts
smf	Solaris-based OSes which use SMF
systemd	Linux distros which use systemd
upstart	Ubuntu-based distros using upstart
win_service	Windows

If Salt's OS detection does not identify a different virtual service module, the minion will fall back to using this basic module, which simply wraps sysvinit scripts.

salt.modules.shadow¶

shadow is a virtual module that is fulfilled by one of the following modules:

Execution Module	Used for
shadow	Linux
bsd_shadow	FreeBSD, OpenBSD, NetBSD
solaris_shadow	Solaris-based OSes
win_shadow	Windows

Manage the shadow file on Linux systems IMPORTANT:

salt.modules.slack_notify¶

Module for sending messages to Slack New in version 2015.5.0.

salt.modules.slsutil¶

Utility functions for use with or in SLS files

salt.modules.smartos_imgadm¶

Module for running imgadm command on SmartOS

salt.modules.smartos_nictagadm module¶

Module for running nictagadm command on SmartOS :maintainer: Jorge Schrauwen < sjorge@blackdot.be> :maturity: new :depends: nictagadm binary, dladm binary :platform: smartos ..versionadded:: 2016.11.0

salt.modules.smartos_virt¶

virst compatibility module for managing VMs on SmartOS

salt.modules.smartos_vmadm¶

Module for running vmadm command on SmartOS

CLI Example:



CLI Example:




CLI Example:






CLI Example:

salt.modules.smbios¶

Interface to SMBIOS/DMI (Parsing through dmidecode)

External References¶

Desktop Management Interface (DMI)
System Management BIOS
DMIdecode

salt.modules.smf¶

Service support for Solaris 10 and 11, should work with other systems that use SMF also. (e.g. SmartOS) IMPORTANT:

salt.modules.smtp¶

Module for Sending Messages via SMTP New in version 2014.7.0.

salt.modules.solaris_fmadm¶

Module for running fmadm and fmdump on Solaris
New in version 2016.3.0.

salt.modules.solaris_group¶

Manage groups on Solaris IMPORTANT:

salt.modules.solaris_shadow¶

Manage the password database on Solaris systems IMPORTANT:

salt.modules.solaris_system¶

Support for reboot, shutdown, etc This module is assumes we are using solaris-like shutdown New in version 2016.3.0.

salt.modules.solaris_user¶

Manage users with the useradd command IMPORTANT:

salt.modules.solarisips¶

IPS pkg support for Solaris IMPORTANT:
This module provides support for Solaris 11 new package management - IPS (Image Packaging System). This is the default pkg module for Solaris 11 (and later). If you want to use also other packaging module (e.g. pkgutil) together with IPS, you need to override the pkg provider in sls for each package:
Or you can override it globally by setting the providers parameter in your Minion config file like this:
Or you can override it globally by setting the providers parameter in your Minion config file like this:

salt.modules.solarispkg¶

Package support for Solaris IMPORTANT:

salt.modules.solr¶

Apache Solr Salt Module Author: Jed Glazner Version: 0.2.1 Modified: 12/09/2011 This module uses HTTP requests to talk to the apache solr request handlers to gather information and report errors. Because of this the minion doesn't necessarily need to reside on the actual slave. However if you want to use the signal function the minion must reside on the physical solr host. This module supports multi-core and standard setups. Certain methods are master/slave specific. Make sure you set the solr.type. If you have questions or want a feature request please ask.

Coming Features in 0.3¶

Override these in the minion config¶

Required Options for DIH¶

salt.modules.splunk¶

Module for interop with the Splunk API New in version 2016.3.0..

salt.modules.splunk_search¶

Module for interop with the Splunk API New in version 2015.5.0.

salt.modules.sqlite3¶

Support for SQLite3

salt.modules.ssh¶

Manage client ssh components NOTE:

salt.modules.ssh_package module¶

Service support for the REST example

salt.modules.ssh_service module¶

Provide the service module for the proxy-minion SSH sample

salt.modules.snapper module¶

Module to manage filesystem snapshots with snapper New in version 2016.11.0.

salt.modules.state¶

Control the state system on the minion.

State Caching¶

When a highstate is called, the minion automatically caches a copy of the last high data. If you then run a highstate with cache=True it will use that cached highdata and won't hit the fileserver except for salt:// links in the states themselves.

salt.modules.status¶

Module for returning various status data about a minion. These data can be useful for compiling into stats later.

salt.modules.stormpath¶

Support for Stormpath New in version 2015.8.0.

salt.modules.supervisord¶

Provide the service module for system supervisord or supervisord in a virtualenv

salt.modules.svn¶

Subversion SCM

salt.modules.swift¶

Module for handling OpenStack Swift calls Author: Anthony Stanton < anthony.stanton@gmail.com> Inspired by the S3 and Nova modules

salt.modules.sysbench¶

The 'sysbench' module is used to analyze the performance of the minions, right from the master! It measures various system parameters such as CPU, Memory, File I/O, Threads and Mutex.

salt.modules.sysfs module¶

Module for interfacing with SysFS SEE ALSO:
New in version 2016.3.0.

salt.modules.syslog_ng¶

Module for getting information about syslog-ng
This module is capable of managing syslog-ng instances which were installed via a package manager or from source. Users can use a directory as a parameter in the case of most functions, which contains the syslog-ng and syslog-ng-ctl binaries. Syslog-ng can be installed via a package manager or from source. In the latter case, the syslog-ng and syslog-ng-ctl binaries are not available from the PATH, so users should set location of the sbin directory with syslog_ng.set_binary_path. Similarly, users can specify the location of the configuration file with syslog_ng.set_config_file, then the module will use it. If it is not set, syslog-ng uses the default configuration file.

salt.modules.sysmod¶

The sys module provides information about the available functions on the minion

salt.modules.sysrc¶

sysrc module for FreeBSD

salt.modules.system¶

Support for reboot, shutdown, etc

salt.modules.system_profiler¶

System Profiler Module Interface with macOS's command-line System Profiler utility to get information about package receipts and installed applications. New in version 2015.5.0.

salt.modules.systemd¶

Provides the service module for systemd New in version 0.10.0. IMPORTANT:

salt.modules.telemetry¶

Connection module for Telemetry New in version 2016.3.0. https://github.com/mongolab/mongolab-telemetry-api-docs/blob/master/alerts.md

salt.modules.temp¶

Simple module for creating temporary directories and files This is a thin wrapper around Pythons tempfile module New in version 2015.8.0.

salt.modules.test¶

Module for running arbitrary tests

salt.modules.test_virtual¶

Module for running arbitrary tests with a __virtual__ function

salt.modules.timezone¶

Module for managing timezone on POSIX-like systems.

salt.modules.tls¶

A salt module for SSL/TLS. Can create a Certificate Authority (CA) or use Self-Signed certificates.
CLI Example #1 Creating a CA, a server request and its signed certificate:
CLI Example #2: Creating a client request and its signed certificate
CLI Example #3: Creating both a server and client req + cert for the same CN
CLI Example #4: Create a server req + cert with non-CN filename for the cert

salt.modules.tomcat¶

Support for Tomcat This module uses the manager webapp to manage Apache tomcat webapps. If the manager webapp is not configured some of the functions won't work.
The following grains/pillar should be set:
or the old format:
Also configure a user in the conf/tomcat-users.xml file:
NOTE:

salt.modules.trafficserver¶

Apache Traffic Server execution module. New in version 2015.8.0. traffic_ctl is used to execute individual Traffic Server commands and to script multiple commands in a shell.

salt.modules.tuned¶

Interface to Red Hat tuned-adm module

salt.modules.twilio_notify¶

Module for notifications via Twilio New in version 2014.7.0.

salt.modules.udev¶

Manage and query udev info New in version 2015.8.0.

salt.modules.upstart¶

Module for the management of upstart systems. The Upstart system only supports service starting, stopping and restarting. IMPORTANT:
Currently (as of Ubuntu 12.04) there is no tool available to disable Upstart services (like update-rc.d). This[1] is the recommended way to disable an Upstart service. So we assume that all Upstart services that have not been disabled in this manner are enabled. But this is broken because we do not check to see that the dependent services are enabled. Otherwise we would have to do something like parse the output of "initctl show-config" to determine if all service dependencies are enabled to start on boot. For example, see the "start on" condition for the lightdm service below[2]. And this would be too hard. So we wait until the upstart developers have solved this problem. :) This is to say that an Upstart service that is enabled may not really be enabled. Also, when an Upstart service is enabled, should the dependent services be enabled too? Probably not. But there should be a notice about this, at least. [1] http://upstart.ubuntu.com/cookbook/#disabling-a-job-from-automatically-starting [2] example upstart configuration file:
WARNING:

salt.modules.uptime¶

Wrapper around uptime API¶

salt.modules.useradd¶

Manage users with the useradd command IMPORTANT:

salt.modules.uwsgi¶

uWSGI stats server https://uwsgi-docs.readthedocs.io/en/latest/StatsServer.html

salt.modules.varnish¶

Support for Varnish New in version 2014.7.0. NOTE:

salt.modules.vbox_guest¶

VirtualBox Guest Additions installer

salt.modules.vboxmanage module¶

Support for VirtualBox using the VBoxManage command New in version 2016.3.0. If the vboxdrv kernel module is not loaded, this module can automatically load it by configuring autoload_vboxdrv in /etc/salt/minion: The default for this setting is False.

salt.modules.victorops¶

Support for VictorOps New in version 2015.8.0. Requires an api_key in /etc/salt/minion:

salt.modules.virt¶

Work with virtual machines managed by libvirt

salt.modules.virtualenv¶

Create virtualenv environments. New in version 0.17.0.

salt.modules.vsphere¶

Manage VMware vCenter servers and ESXi hosts. New in version 2015.8.4.

Dependencies¶

pyVmomi¶

PyVmomi can be installed via pip:
NOTE:
Based on the note above, to install an earlier version of pyVmomi than the version currently listed in PyPi, run the following:
The 5.5.0.2014.1.1 is a known stable version that this original vSphere Execution Module was developed against.

ESXCLI¶

Currently, about a third of the functions used in the vSphere Execution Module require the ESXCLI package be installed on the machine running the Proxy Minion process. The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware provides vCLI package installation instructions for vSphere 5.5 and vSphere 6.0. Once all of the required dependencies are in place and the vCLI package is installed, you can check to see if you can connect to your ESXi host or vCenter server by running the following command:
If the connection was successful, ESXCLI was successfully installed on your system. You should see output related to the ESXi host's syslog configuration. NOTE:

About¶

This execution module was designed to be able to handle connections both to a vCenter Server, as well as to an ESXi host. It utilizes the pyVmomi Python library and the ESXCLI package to run remote execution functions against either the defined vCenter server or the ESXi host. Whether or not the function runs against a vCenter Server or an ESXi host depends entirely upon the arguments passed into the function. Each function requires a host location, username, and password. If the credentials provided apply to a vCenter Server, then the function will be run against the vCenter Server. For example, when listing hosts using vCenter credentials, you'll get a list of hosts associated with that vCenter Server:
However, some functions should be used against ESXi hosts, not vCenter Servers. Functionality such as getting a host's coredump network configuration should be performed against a host and not a vCenter server. If the authentication information you're using is against a vCenter server and not an ESXi host, you can provide the host name that is associated with the vCenter server in the command, as a list, using the host_names or esxi_host kwarg. For example:
You can also use these functions against an ESXi host directly by establishing a connection to an ESXi host using the host's location, username, and password. If ESXi connection credentials are used instead of vCenter credentials, the host_names and esxi_hosts arguments are not needed.

salt.modules.win_autoruns¶

Module for listing programs that automatically run on startup (very alpha...not tested on anything but my Win 7x64)

salt.modules.win_certutil module¶

This module allows you to install certificates into the windows certificate manager.

salt.modules.win_dacl¶

Manage DACLs on Windows

salt.modules.win_disk¶

Module for gathering disk information on Windows

salt.modules.win_dism module¶

Install features/packages for Windows using DISM, which is useful for minions not running server versions of Windows. Some functions are only available on Windows 10.

salt.modules.win_dns_client¶

Module for configuring DNS Client on Windows systems

salt.modules.win_dsc¶

Module for working with DSC (Alpha)

salt.modules.win_file¶

Manage information about files on the minion, set/read user, group data

salt.modules.win_firewall¶

Module for configuring Windows Firewall

salt.modules.win_groupadd¶

Manage groups on Windows IMPORTANT:

salt.modules.win_iis module¶

Microsoft IIS site management via WebAdministration powershell module
New in version 2016.3.0.

salt.modules.win_ip¶

The networking module for Windows based systems

salt.modules.win_license module¶

This module allows you to manage windows licensing via slmgr.vbs

salt.modules.win_network¶

Module for gathering and managing network information

salt.modules.win_ntp¶

Management of NTP servers on Windows New in version 2014.1.0.

salt.modules.win_path¶

Manage the Windows System PATH Note that not all Windows applications will rehash the PATH environment variable, Only the ones that listen to the WM_SETTINGCHANGE message http://support.microsoft.com/kb/104011

salt.modules.win_pkg¶

A module to manage software on Windows IMPORTANT:
The following functions require the existence of a windows repository metadata DB, typically created by running pkg.refresh_db:
If a metadata DB does not already exist and one of these functions is run, then one will be created from the repo SLS files that are present. As the creation of this metadata can take some time, the winrepo_cache_expire_min minion config option can be used to suppress refreshes when the metadata is less than a given number of seconds old.

salt.modules.win_powercfg¶

This module allows you to control the power settings of a windows minion via powercfg. New in version 2015.8.0.

salt.modules.win_repo¶

Module to manage Windows software repo on a Standalone Minion file_client: local must be set in the minion config file. For documentation on Salt's Windows Repo feature, see here.

salt.modules.win_servermanager¶

Manage Windows features via the ServerManager powershell module

salt.modules.win_service¶

Windows Service module. Changed in version 2016.11.0: - Rewritten to use PyWin32

•

password (str) -- The password for the account name specified in

•

For the above built-in accounts, this can be None. (account_name.) --

•

a password must be specified. (Otherwise) --

CLI Example:

•

load_order_group -- The name of the load order group to which this service belongs

•

dependencies (list) -- A list of services or load ordering groups that

•

start before this service (must) --

•

account_name (str) -- The name of the account under which the service

•

run. For own type services this should be in the (should) --

•

format. The following are examples of valid built-in (domain\username) --

•

accounts (service) -- .INDENT 2.0

•

NT Authority\LocalService

•

NT Authority\NetworkService

•

NT Authority\LocalSystem

•

.\LocalSystem

•

account_password (str) -- The password for the account name specified in

•

For the above built-in accounts, this can be None. (account_name.) --

•

a password must be specified. (Otherwise) --

•

run_interactive (bool) -- If this setting is True, the service will be

•

to interact with the user. Not recommended for services that run (allowed) --

•

elevated privileges. (with) --

Returns

A dictionary containing information about the new service

Return type

dict

CLI Example:

•

account_password (str) -- The password for the account name specified in

•

For the above built-in accounts, this can be None. (account_name.) --

•

a password must be specified. (Otherwise) --

•

run_interactive (bool) -- If this setting is True, the service will be

•

to interact with the user. Not recommended for services that run (allowed) --

•

elevated privileges. (with) --

Returns (dict): A dictionary of changes made CLI Example:

salt.modules.win_shadow¶

Manage the shadow file IMPORTANT:

salt.modules.win_status¶

Module for returning various status data about a minion. These data can be useful for compiling into stats later, or for problem solving if your minion is having problems. New in version 0.12.0.

salt.modules.win_system¶

Module for managing windows systems.
Support for reboot, shutdown, etc

salt.modules.win_task module¶

Windows Task Scheduler Module A module for working with the Windows Task Scheduler. You can add and edit existing tasks. You can add and clear triggers and actions. You can list all tasks, folders, triggers, and actions.

salt.modules.win_timezone¶

Module for managing timezone on Windows systems.

salt.modules.win_update¶

Module for running windows updates.
New in version 2014.7.0. Set windows updates to run by category. Default behavior is to install all updates that do not require user interaction to complete. Optionally set categories to a category of your choice to only install certain updates. Default is to set to install all available but driver updates. The following example will install all Security and Critical Updates, and download but not install standard updates.
You can also specify a number of features about the update to have a fine grain approach to specific types of updates. These are the following features/states of updates available for configuring:
The following example installs all updates that don't require a reboot:
Once installed Salt will return a similar output:
The number at the beginning of the line is an OperationResultCode from the Windows Update Agent, it's enumeration is described here: https://msdn.microsoft.com/en-us/library/windows/desktop/aa387095(v=vs.85).aspx. The result code is then followed by the update name and its KB identifier.

salt.modules.win_useradd¶

Module for managing Windows Users IMPORTANT:

NOTE:

salt.modules.win_wua¶

Module for managing Windows Updates using the Windows Update Agent. New in version 2015.8.0.









CLI Examples:

salt.modules.x509¶

Manage X509 certificates New in version 2015.8.0.

salt.modules.xapi¶

This module (mostly) uses the XenAPI to manage Xen virtual machines. Big fat warning: the XenAPI used in this file is the one bundled with Xen Source, NOT XenServer nor Xen Cloud Platform. As a matter of fact it will fail under those platforms. From what I've read, little work is needed to adapt this code to XS/XCP, mostly playing with XenAPI version, but as XCP is not taking precedence on Xen Source on many platforms, please keep compatibility in mind. Useful documentation: . http://downloads.xen.org/Wiki/XenAPI/xenapi-1.0.6.pdf

salt.modules.xfs¶

Module for managing XFS file systems.

salt.modules.xmpp¶

Module for Sending Messages via XMPP (a.k.a. Jabber) New in version 2014.1.0.

salt.modules.yumpkg¶

Support for YUM/DNF IMPORTANT:
NOTE:

salt.modules.zabbix module¶

Support for Zabbix

salt.modules.zcbuildout¶

Management of zc.buildout New in version 2014.1.0. This module is inspired by minitage's buildout maker NOTE:

General notes¶

You have those following methods:

salt.modules.zenoss¶

Module for working with the Zenoss API New in version 2016.3.0.

salt.modules.zfs¶

Salt interface to ZFS commands

salt.modules.zk_concurrency¶

Concurrency controls in zookeeper¶

This module allows you to acquire and release a slot. This is primarily useful for ensureing that no more than N hosts take a specific action at once. This can also be used to coordinate between masters.

salt.modules.znc¶

znc - An advanced IRC bouncer New in version 2014.7.0. Provides an interface to basic ZNC functionality

salt.modules.zpool¶

Module for running ZFS zpool command

salt.modules.zypper¶

Package support for openSUSE via the zypper package manager
IMPORTANT:

netapi modules¶

rest_cherrypy¶

A REST API for Salt¶

New in version 2014.7.0.

Authentication¶

Authentication is performed by passing a session token with each request. Tokens are generated via the Login URL. The token may be sent in one of two ways: as a custom header or as a session cookie. The latter is far more convenient for clients that support cookies.
SEE ALSO:

Usage¶

This interface directly exposes Salt's Python API. Everything possible at the CLI is possible through the Python API. Commands are executed on the Salt Master. The root URL ( /) is RPC-like in that it accepts instructions in the request body for what Salt functions to execute, and the response contains the result of those function calls. For example:
The request body must be an array of commands. Use this workflow to build a command:
The client field is a reference to the main Python classes used in Salt's Python API. Read the full client interfaces documentation, but in short:
Most clients have variants like synchronous or asynchronous execution as well as others like batch execution. See the full list of client interfaces. Each client requires different arguments and sometimes has different syntax. For example, LocalClient requires the tgt argument because it forwards the command to Minions and the other client interfaces do not. LocalClient also takes arg (array) and kwarg (dictionary) arguments because these values are sent to the Minions and used to execute the requested function there. RunnerClient and WheelClient are executed directly on the Master and thus do not need or accept those arguments. Read the method signatures in the client documentation linked above, but hopefully an example will help illustrate the concept. This example causes Salt to execute two functions -- the test.arg execution function using LocalClient and the test.arg runner function using RunnerClient; note the different structure for each command. The results for both are combined and returned as one response.
One more example, this time with more commonly used functions:

Content negotiation¶

This REST interface is flexible in what data formats it will accept as well as what formats it will return (e.g., JSON, YAML, urlencoded).
We recommend the JSON format for most HTTP requests. urlencoded data is simple and cannot express complex data structures -- and that is often required for some Salt commands, such as starting a state run that uses Pillar data. Salt's CLI tool can reformat strings passed in at the CLI into complex data structures, and that behavior also works via salt-api, but that can be brittle and since salt-api can accept JSON it is best just to send JSON. Here is an example of sending urlencoded data:

Deployment¶

The rest_cherrypy netapi module is a standard Python WSGI app. It can be deployed one of two ways.

salt-api using the CherryPy server¶

The default configuration is to run this module using salt-api to start the Python-based CherryPy server. This server is lightweight, multi-threaded, encrypted with SSL, and should be considered production-ready.

Using a WSGI-compliant web server¶

This module may be deployed on any WSGI-compliant server such as Apache with mod_wsgi or Nginx with FastCGI, to name just two (there are many). Note, external WSGI servers handle URLs, paths, and SSL certs directly. The rest_cherrypy configuration options are ignored and the salt-api daemon does not need to be running at all. Remember Salt authentication credentials are sent in the clear unless SSL is being enforced! An example Apache virtual host configuration:

REST URI Reference¶

/¶

/login¶

/logout¶

/minions¶

/jobs¶

/run¶

/events¶

/hook¶

/keys¶

/ws¶

/stats¶

rest_tornado¶

A Websockets add-on to saltnado¶

In order to enable saltnado_websockets you must add websockets: True to your saltnado config block.

All Events¶

Exposes all "real-time" events from Salt's event bus on a websocket connection. It should be noted that "Real-time" here means these events are made available to the server as soon as any salt related action (changes to minions, new jobs etc) happens. Clients are however assumed to be able to tolerate any network transport related latencies. Functionality provided by this endpoint is similar to the /events end point. The event bus on the Salt master exposes a large variety of things, notably when executions are started on the master and also when minions ultimately return their results. This URL provides a real-time window into a running Salt infrastructure. Uses websocket as the transport mechanism. Exposes GET method to return websocket connections. All requests should include an auth token. A way to obtain obtain authentication tokens is shown below.
Which results in the response
In this example the token returned is d0ce6c1a37e99dcc0374392f272fe19c0090cca7 and can be included in subsequent websocket requests (as part of the URL). The event stream can be easily consumed via JavaScript:
Or via Python, using the Python module websocket-client for example. Or the tornado client.
Above examples show how to establish a websocket connection to Salt and activating real time updates from Salt's event stream by signaling websocket client ready.

Formatted Events¶

Exposes formatted "real-time" events from Salt's event bus on a websocket connection. It should be noted that "Real-time" here means these events are made available to the server as soon as any salt related action (changes to minions, new jobs etc) happens. Clients are however assumed to be able to tolerate any network transport related latencies. Functionality provided by this endpoint is similar to the /events end point. The event bus on the Salt master exposes a large variety of things, notably when executions are started on the master and also when minions ultimately return their results. This URL provides a real-time window into a running Salt infrastructure. Uses websocket as the transport mechanism. Formatted events parses the raw "real time" event stream and maintains a current view of the following:
A change to the minions (such as addition, removal of keys or connection drops) or jobs is processed and clients are updated. Since we use salt's presence events to track minions, please enable presence_events and set a small value for the loop_interval in the salt master config file. Exposes GET method to return websocket connections. All requests should include an auth token. A way to obtain obtain authentication tokens is shown below.
Which results in the response
In this example the token returned is d0ce6c1a37e99dcc0374392f272fe19c0090cca7 and can be included in subsequent websocket requests (as part of the URL). The event stream can be easily consumed via JavaScript:
Or via Python, using the Python module websocket-client for example. Or the tornado client.
Above examples show how to establish a websocket connection to Salt and activating real time updates from Salt's event stream by signaling websocket client ready.

Example responses¶

Minion information is a dictionary keyed by each connected minion's id ( mid), grains information for each minion is also included. Minion information is sent in response to the following minion events:

Job information is also tracked and delivered. Job information is also a dictionary in which each job's information is keyed by salt's jid.

Setup¶

REST URI Reference¶

/¶

/login¶

/minions¶

/jobs¶

/run¶

/events¶

/hook¶

rest_wsgi¶

A minimalist REST API for Salt¶

This rest_wsgi module provides a no-frills REST interface for sending commands to the Salt master. There are no dependencies. Extra care must be taken when deploying this module into production. Please read this documentation in entirety. All authentication is done through Salt's external auth system.

Usage¶

SEE ALSO:

Deployment¶

The rest_wsgi netapi module is a standard Python WSGI app. It can be deployed one of two ways.

Using a WSGI-compliant web server¶

This module may be run via any WSGI-compliant production server such as Apache with mod_wsgi or Nginx with FastCGI. It is strongly recommended that this app be used with a server that supports HTTPS encryption since raw Salt authentication credentials must be sent with every request. Any apps that access Salt through this interface will need to manually manage authentication credentials (either username and password or a Salt token). Tread carefully.

salt-api using a development-only server¶

If run directly via the salt-api daemon it uses the wsgiref.simple_server() that ships in the Python standard library. This is a single-threaded server that is intended for testing and development. This server does not use encryption; please note that raw Salt authentication credentials must be sent with every HTTP request. Running this module via salt-api is not recommended! In order to start this module via the salt-api daemon the following must be put into the Salt master config:

Usage examples¶

output modules¶

Follow one of the below links for further information and examples

highstate	Outputter for displaying results of state runs
json_out	Display return data in JSON format
key	Display salt-key output
nested	Recursively display nested data
newline_values_only	Display values only, separated by newlines
no_out	Display no output
no_return	Display output for minions that did not return
overstatestage	Display clean output of an overstate stage
pprint_out	Python pretty-print (pprint)
progress	Display return data as a progress bar
raw	Display raw output data structure
txt	Simple text outputter
virt_query	virt.query outputter
yaml_out	Display return data in YAML format

salt.output.highstate¶

Outputter for displaying results of state runs¶

The return data from the Highstate command is a standard data structure which is parsed by the highstate outputter to deliver a clean and readable set of information about the HighState run on minions. Two configurations can be set to modify the highstate outputter. These values can be set in the master config to change the output of the salt command or set in the minion config to change the output of the salt-call command.
Example usage: If state_output: filter is set in the configuration file:
means to exclude no states from the highstate and turn on terse output.
means to exclude states problemstate1 and problemstate2 from the highstate, and use regular output. Example output for the above highstate call when top.sls defines only one other state to apply to minion twd:
Example output with no special settings in configuration files:

salt.output.json_out¶

Display return data in JSON format¶

Salt's outputters operate on a per-minion basis. Each minion return will be output as a single JSON object once it comes in to the master. Some JSON parsers can guess when an object ends and a new one begins but many can not. A good way to differentiate between each minion return is to use the single-line output format and to parse each line individually. Example output (truncated):

salt.output.key¶

Display salt-key output¶

The salt-key command makes use of this outputter to format its output.

salt.output.nested¶

Recursively display nested data¶

This is the default outputter for most execution functions. Example output:

salt.output.newline_values_only¶

Display values only, separated by newlines¶

New in version 2015.5.0. This outputter is designed for Salt CLI return data. It will do the following to the return dict:
This results in a single string of return data containing all the values from the various minions. WARNING:

Example 1¶

Input¶

Output¶

Example 2¶

Input¶

Output¶

salt.output.no_out¶

Display no output¶

No output is produced when this outputter is selected

salt.output.no_return¶

Display output for minions that did not return¶

This outputter is used to display notices about which minions failed to return when a salt function is run with -v or --verbose. It should not be called directly from the CLI. Example output:

salt.output.overstatestage¶

Display clean output of an overstate stage¶

This outputter is used to display OverState stages, and should not be called directly.

salt.output.pprint_out¶

Python pretty-print (pprint)¶

The python pretty-print system was once the default outputter. It simply passes the return data through to pprint.pformat and prints the results. Example output:

salt.output.progress¶

Display return data as a progress bar

salt.output.raw¶

Display raw output data structure¶

This outputter simply displays the output as a python data structure, by printing a string representation of it. It is similar to the pprint outputter, only the data is not nicely formatted/indented. This was the original outputter used by Salt before the outputter system was developed. Example output:

salt.output.txt¶

Simple text outputter¶

The txt outputter has been developed to make the output from shell commands on minions appear as they do when the command is executed on the minion.

salt.output.virt_query¶

virt.query outputter¶

Used to display the output from the virt.query runner.

salt.output.yaml_out¶

Display return data in YAML format¶

This outputter defaults to printing in YAML block mode for better readability. Example output:

pillar modules¶

cmd_json	Execute a command and read the output as JSON.
cmd_yaml	Execute a command and read the output as YAML.
cmd_yamlex	Execute a command and read the output as YAMLEX.
cobbler	A module to pull data from Cobbler via its API into the Pillar dictionary
confidant	An external pillar module for getting credentials from confidant.
consul_pillar	Use Consul K/V as a Pillar source with values parsed as YAML
django_orm	Generate Pillar data from Django models through the Django ORM
ec2_pillar	Retrieve EC2 instance data for minions.
etcd_pillar	Use etcd data as a Pillar source
file_tree	Recursively iterate over directories and add all files as Pillar data
foreman	A module to pull data from Foreman via its API into the Pillar dictionary
git_pillar	Use a git repository as a Pillar source
hg_pillar	Use remote Mercurial repository as a Pillar source.
hiera	Use hiera data as a Pillar source
http_yaml	A module that adds data to the Pillar structure retrieved by an http request
libvirt	Load up the libvirt keys into Pillar for a given minion if said keys have been
mongo	Read Pillar data from a mongodb collection
mysql	Retrieve Pillar data by doing a MySQL query
neutron	Use Openstack Neutron data as a Pillar source.
nodegroups
pepa	Pepa
pillar_ldap	Use LDAP data as a Pillar source
puppet	Execute an unmodified puppet_node_classifier and read the output as YAML.
reclass_adapter	Use the "reclass" database as a Pillar source
redismod	Read pillar data from a Redis backend
s3	Copy pillar data from a bucket in Amazon S3
sql_base	Retrieve Pillar data by doing a SQL query
sqlcipher	Retrieve Pillar data by running a SQLCipher query
sqlite3	Retrieve Pillar data by doing a SQLite3 query
stack	Simple and flexible YAML ext_pillar which can read pillar from within pillar.
svn_pillar	Clone a remote SVN repository and use the filesystem as a Pillar source
varstack_pillar	Use Varstack data as a Pillar source
vault	Vault Pillar Module
virtkey	Accept a key from a hypervisor if the virt runner has already submitted an authorization request

salt.pillar.cmd_json¶

Execute a command and read the output as JSON. The JSON data is then directly overlaid onto the minion's Pillar data.

salt.pillar.cmd_yaml¶

Execute a command and read the output as YAML. The YAML data is then directly overlaid onto the minion's Pillar data

salt.pillar.cmd_yamlex¶

Execute a command and read the output as YAMLEX. The YAMLEX data is then directly overlaid onto the minion's Pillar data

salt.pillar.cobbler¶

A module to pull data from Cobbler via its API into the Pillar dictionary

Configuring the Cobbler ext_pillar¶

The same cobbler.* parameters are used for both the Cobbler tops and Cobbler pillar modules.

Module Documentation¶

salt.pillar.confidant¶

An external pillar module for getting credentials from confidant.

Configuring the Confidant module¶

The module can be configured via ext_pillar in the minion config:

Module Documentation¶

salt.pillar.consul_pillar module¶

Use Consul K/V as a Pillar source with values parsed as YAML
In order to use an consul server, a profile must be created in the master configuration file:
All parameters are optional. The consul.token requires python-consul >= 0.4.7. If you have a multi-datacenter Consul cluster you can map your pillarenv``s to your data centers by providing a dictionary of mappings in ``consul.dc field:
In the example above we specifying static mapping between Pillar environments and data centers: the data for dev and prod Pillar environments will be fetched from us-east-1 and us-west-1 datacenter respectively. In fact when consul.dc is set to dictionary keys are processed as regular expressions (that can capture named parameters) and values are processed as string templates as per PEP 3101.
This example maps all Pillar environments starting with dev- to dev-datacenter whereas Pillar environment like eu-prod will be mapped to prod-datacenter-eu. Before evaluation patterns are sorted by length in descending order. If Pillar environment names correspond to data center names a single pattern can be used:
After the profile is created, configure the external pillar system to use it. Optionally, a root may be specified.
Using these configuration profiles, multiple consul sources may also be used:
Either the minion_id, or the role, or the environment grain may be used in the root path to expose minion-specific information stored in consul.
Minion-specific values may override shared values when the minion-specific root appears after the shared root:
If using the role or environment grain in the consul key path, be sure to define it using /etc/salt/grains, or similar:
It's possible to lock down where the pillar values are shared through minion targeting. Note that double quotes " are required around the target value and cannot be used inside the matching statement. See the section on Compound Matchers for more examples.

salt.pillar.django_orm¶

Generate Pillar data from Django models through the Django ORM

Configuring the django_orm ext_pillar¶

To use this module, your Django project must be on the salt master server with database access. This assumes you are using virtualenv with all the project's requirements installed.
This would return pillar data that would look like
As another example, data from multiple database tables can be fetched using Django's regular lookup syntax. Note, using ManyToManyFields will not currently work since the return from values() changes if a ManyToMany is present.

Module Documentation¶

salt.pillar.ec2_pillar¶

Retrieve EC2 instance data for minions. The minion id must be the instance-id retrieved from AWS. As an option, use_grain can be set to True. This allows the use of an instance-id grain instead of the minion-id. Since this is a potential security risk, the configuration can be further expanded to include a list of minions that are trusted to only allow the alternate id of the instances to specific hosts. There is no glob matching at this time.
This is a very simple pillar that simply retrieves the instance data from AWS. Currently the only portion implemented are EC2 tags, which returns a list of key/value pairs for all of the EC2 tags assigned to the instance.

salt.pillar.etcd_pillar¶

Use etcd data as a Pillar source New in version 2014.7.0.
In order to use an etcd server, a profile must be created in the master configuration file:
After the profile is created, configure the external pillar system to use it. Optionally, a root may be specified.
Using these configuration profiles, multiple etcd sources may also be used:
The minion_id may be used in the root path to expose minion-specific information stored in etcd.
Minion-specific values may override shared values when the minion-specific root appears after the shared root:
Using the configuration above, the following commands could be used to share a key with all minions but override its value for a specific minion:

salt.pillar.file_tree¶

Recursively iterate over directories and add all files as Pillar data New in version 2015.5.0.

Example Configuration¶

The root_dir parameter is required and points to the directory where files for each host are stored. The follow_dir_links parameter is optional and defaults to False. If follow_dir_links is set to True, this external pillar will follow symbolic links to other directories. WARNING:
If keep_newline is set to True, then the pillar values for files ending in newlines will keep that newline. The default behavior is to remove the end-of-file newline. keep_newline should be turned on if the pillar data is intended to be used to deploy a file using contents_pillar with a file.managed state. Changed in version 2015.8.4: The raw_data parameter has been renamed to keep_newline. In earlier releases, raw_data must be used. Also, this parameter can now be a list of globs, allowing for more granular control over which pillar values keep their end-of-file newline. The globs match paths relative to the directories named for minion IDs and nodegroups underneath the root_dir (see the layout examples in the below sections).
NOTE:

Assigning Pillar Data to Individual Hosts¶

To configure pillar data for each host, this external pillar will recursively iterate over root_dir/hosts/id (where id is a minion ID), and compile pillar data with each subdirectory as a dictionary key and each file as a value. For example, the following root_dir tree:
will result in the following pillar tree for minion with ID test-host:
NOTE:

Assigning Pillar Data to Entire Nodegroups¶

To assign Pillar data to all minions in a given nodegroup, this external pillar recursively iterates over root_dir/nodegroups/nodegroup (where nodegroup is the name of a nodegroup), and like for individual hosts, compiles pillar data with each subdirectory as a dictionary key and each file as a value. IMPORTANT:
For example, the following root_dir tree:
will result in the following pillar data for minions in the node group test-group:

salt.pillar.foreman¶

A module to pull data from Foreman via its API into the Pillar dictionary

Configuring the Foreman ext_pillar¶

Set the following Salt config to setup Foreman as external pillar source:
The following options are optional:
An alternative would be to use the Foreman modules integrating Salt features in the Smart Proxy and the webinterface. Further information can be found on GitHub.

Module Documentation¶

salt.pillar.git_pillar¶

Use a git repository as a Pillar source¶

NOTE:
This external pillar allows for a Pillar top file and Pillar SLS files to be sourced from a git repository. However, since git_pillar does not have an equivalent to the pillar_roots parameter, configuration is slightly different. A Pillar top file is required to be in the git repository and must still contain the relevant environment, like so:
The branch/tag which maps to that environment must then be specified along with the repo's URL. Configuration details can be found below. IMPORTANT:

Configuring git_pillar for Salt releases before 2015.8.0¶

For Salt releases earlier than 2015.8.0, GitPython is the only supported provider for git_pillar. Individual repositories can be configured under the ext_pillar configuration parameter like so:
The repository is specified in the format <branch> <repo_url>, with an optional root parameter (added in the 2014.7.0 release) which allows the pillar SLS files to be served up from a subdirectory (similar to gitfs_root in gitfs). To use more than one branch from the same repo, multiple lines must be specified under ext_pillar:
To remap a specific branch to a specific Pillar environment, use the format <branch>:<env>:
In this case, the develop branch would need its own top.sls with a dev section in it, like this:
The master branch would need its own top.sls with a prod section in it:
If __env__ is specified as the branch name, then git_pillar will first look at the minion's environment option. If unset, it will fall back to using branch specified by the master's gitfs_base:
The corresponding Pillar top file would look like this:
NOTE:

Configuring git_pillar for Salt releases 2015.8.0 and later¶

NOTE:
Beginning with Salt version 2015.8.0, pygit2 is now supported in addition to GitPython (Dulwich will not be supported for the foreseeable future). The requirements for GitPython and pygit2 are the same as for gitfs, as described here. IMPORTANT:
Here is an example git_pillar configuration:
The main difference between this and the old way of configuring git_pillar is that multiple remotes can be configured under one git section under ext_pillar. More than one git section can be used, but it is not necessary. Remotes will be evaluated sequentially. Per-remote configuration parameters are supported (similar to gitfs), and global versions of the git_pillar configuration parameters can also be set. To remap a specific branch to a specific Pillar environment, use the env per-remote parameter:
If __env__ is specified as the branch name, then git_pillar will decide which branch to use based on the following criteria:
NOTE:
Here's an example of using __env__ as the git_pillar environment:
The corresponding Pillar top file would look like this:
NOTE:
With the addition of pygit2 support, git_pillar can now interact with authenticated remotes. Authentication works just like in gitfs (as outlined in the Git Fileserver Backend Walkthrough), only with the global authenication parameter names prefixed with git_pillar instead of gitfs (e.g. git_pillar_pubkey, git_pillar_privkey, git_pillar_passphrase, etc.). NOTE:

salt.pillar.hg_pillar¶

Use remote Mercurial repository as a Pillar source. New in version 2015.8.0. The module depends on the hglib python module being available. This is the same requirement as for hgfs_ so should not pose any extra hurdles. This external Pillar source can be configured in the master config file as such:

salt.pillar.hiera¶

Use hiera data as a Pillar source

salt.pillar.http_yaml module¶

A module that adds data to the Pillar structure retrieved by an http request

Configuring the HTTP_YAML ext_pillar¶

Set the following Salt config to setup an http endpoint as the external pillar source:

Module Documentation¶

salt.pillar.libvirt¶

Load up the libvirt keys into Pillar for a given minion if said keys have been generated using the libvirt key runner

salt.pillar.mongo¶

Read Pillar data from a mongodb collection
This module will load a node-specific pillar dictionary from a mongo collection. It uses the node's id for lookups and can load either the whole document, or just a specific field from that document as the pillar dictionary.

Salt Master Mongo Configuration¶

The module shares the same base mongo connection variables as salt.returners.mongo_return. These variables go in your master config file.

Configuring the Mongo ext_pillar¶

The Mongo ext_pillar takes advantage of the fact that the Salt Master configuration file is yaml. It uses a sub-dictionary of values to adjust specific features of the pillar. This is the explicit single-line dictionary notation for yaml. One may be able to get the easier-to-read multi-line dict to work correctly with some experimentation.
In the example above, we've decided to use the vm collection in the database to store the data. Minion ids are stored in the name field on documents in that collection. And, since minion ids are FQDNs in most cases, we'll need to trim the domain name in order to find the minion by hostname in the collection. When we find a minion, return only the customer_id, software, and apache_vhosts fields, as that will contain the data we want for a given node. They will be available directly inside the pillar dict in your SLS templates.

Module Documentation¶

salt.pillar.mysql¶

Retrieve Pillar data by doing a MySQL query MariaDB provides Python support through the MySQL Python package. Therefore, you may use this module with both MySQL or MariaDB. This module is a concrete implementation of the sql_base ext_pillar for MySQL.

Configuring the mysql ext_pillar¶

Use the 'mysql' key under ext_pillar for configuration of queries. MySQL configuration of the MySQL returner is being used (mysql.db, mysql.user, mysql.pass, mysql.port, mysql.host) for database connection info. Required python modules: MySQLdb

Complete example¶

salt.pillar.neutron module¶

Use Openstack Neutron data as a Pillar source. Will list all networks listed inside of Neutron, to all minions. New in version 2015.5.1.
A keystone profile must be used for the pillar to work (no generic keystone configuration here). For example:
After the profile is created, configure the external pillar system to use it.
Using these configuration profiles, multiple neutron sources may also be used:
By default, these networks will be returned as a pillar item called networks. In order to have them returned under a different name, add the name after the Keystone profile name:

salt.pillar.nodegroups¶

Nodegroups Pillar¶

Introspection: to which nodegroups does my minion belong? Provides a pillar with the default name of nodegroups which contains a list of nodegroups which match for a given minion. New in version 2016.11.0.

Command Line¶

Configuring Nodegroups Pillar¶

salt.pillar.pepa¶

Pepa¶

Configuration templating for SaltStack using Hierarchical substitution and Jinja.

Configuring Pepa¶

Pepa can also be used in Master-less SaltStack setup.

Command line¶

Templates¶

Templates is configuration for a host or software, that can use information from Grains or Pillars. These can then be used for hierarchically substitution. Example File: host/input/test_example_com.yaml
As you see in this example you can use Jinja directly inside the template. Example File: host/region/amer.yaml
Each template is named after the value of the key using lowercase and all extended characters are replaced with underscore. Example: osfinger: Fedora-19 Would become: fedora_19.yaml

Nested dictionaries¶

In order to create nested dictionaries as output you can use double dot ".." as a delimiter. You can change this using "pepa_delimiter" we choose double dot since single dot is already used by key names in some modules, and using ":" requires quoting in the YAML. Example:
Would become:

Operators¶

Operators can be used to merge/unset a list/hash or set the key as immutable, so it can't be changed.

Operator	Description
merge()	Merge list or hash
unset()	Unset key
immutable()	Set the key as immutable, so it can't be changed
imerge()	Set immutable and merge
iunset()	Set immutable and unset

Example:

Validation¶

Since it's very hard to test Jinja as is, the best approach is to run all the permutations of input and validate the output, i.e. Unit Testing. To facilitate this in Pepa we use YAML, Jinja and Cerberus < https://github.com/nicolaiarocci/cerberus>.

Schema¶

So this is a validation schema for network configuration, as you see it can be customized with Jinja just as Pepa templates. This was designed to be run as a build job in Jenkins or similar tool. You can provide Grains/Pillar input using either the config file or command line arguments. File Example: host/validation/network.yaml

Links¶

For more examples and information see < https://github.com/mickep76/pepa>.

salt.pillar.pillar_ldap¶

Use LDAP data as a Pillar source This pillar module executes a series of LDAP searches. Data returned by these searches are aggregated, whereby data returned by later searches override data by previous searches with the same key. The final result is merged with existing pillar data. The configuration of this external pillar module is done via an external file which provides the actual configuration for the LDAP searches.

Configuring the LDAP ext_pillar¶

The basic configuration is part of the master configuration.
NOTE:
WARNING:
The only required key in the master configuration is pillar_ldap pointing to a file containing the actual configuration.

Configuring the LDAP searches¶

The file is processed using Salt's Renderers <renderers> which makes it possible to reference grains within the configuration. WARNING:

Map Mode¶

The it-admins configuration below returns the Pillar it-admins by:

List Mode¶

TODO: see also _result_to_dict() documentation

salt.pillar.puppet¶

Execute an unmodified puppet_node_classifier and read the output as YAML. The YAML data is then directly overlaid onto the minion's Pillar data.

salt.pillar.reclass_adapter¶

Use the "reclass" database as a Pillar source This ext_pillar plugin provides access to the reclass database, such that Pillar data for a specific minion are fetched using reclass. You can find more information about reclass at http://reclass.pantsfullofunix.net. To use the plugin, add it to the ext_pillar list in the Salt master config and tell reclass by way of a few options how and where to find the inventory:
This would cause reclass to read the inventory from YAML files in /srv/salt/nodes and /srv/salt/classes. If you are also using reclass as master_tops plugin, and you want to avoid having to specify the same information for both, use YAML anchors (take note of the differing data types for ext_pillar and master_tops):
If you want to run reclass from source, rather than installing it, you can either let the master know via the PYTHONPATH environment variable, or by setting the configuration option, like in the example above.

salt.pillar.redismod¶

Read pillar data from a Redis backend¶

New in version 2014.7.0.

Salt Master Redis Configuration¶

The module shares the same base Redis connection variables as salt.returners.redis_return. These variables go in your master config file.

Configuring the Redis ext_pillar¶

salt.pillar.s3¶

Copy pillar data from a bucket in Amazon S3 The S3 pillar can be configured in the master config file with the following options
The bucket parameter specifies the target S3 bucket. It is required. The keyid parameter specifies the key id to use when access the S3 bucket. If it is not provided, an attempt to fetch it from EC2 instance meta-data will be made. The key parameter specifies the key to use when access the S3 bucket. If it is not provided, an attempt to fetch it from EC2 instance meta-data will be made. The multiple_env defaults to False. It specifies whether the pillar should interpret top level folders as pillar environments (see mode section below). The environment defaults to 'base'. It specifies which environment the bucket represents when in single environments mode (see mode section below). It is ignored if multiple_env is True. The prefix defaults to ''. It specifies a key prefix to use when searching for data in the bucket for the pillar. It works when multiple_env is True or False. Essentially it tells ext_pillar to look for your pillar data in a 'subdirectory' of your S3 bucket The verify_ssl parameter defaults to True. It specifies whether to check for valid S3 SSL certificates. NOTE If you use bucket names with periods, this must be set to False else an invalid certificate error will be thrown (issue #12200). The service_url parameter defaults to 's3.amazonaws.com'. It specifies the base url to use for accessing S3. The kms_keyid parameter is optional. It specifies the ID of the Key Management Service (KMS) master key that was used to encrypt the object. The s3_cache_expire parameter defaults to 30s. It specifies expiration time of S3 metadata cache file. The s3_sync_on_update parameter defaults to True. It specifies if cache is synced on update rather than jit. This pillar can operate in two modes, single environment per bucket or multiple environments per bucket. Single environment mode must have this bucket structure:
Multiple environment mode must have this bucket structure:
If you wish to define your pillar data entirely within S3 it's recommended that you use the prefix= parameter and specify one entry in ext_pillar for each environment rather than specifying multiple_env. This is due to issue #22471 ( https://github.com/saltstack/salt/issues/22471)

salt.pillar.sql_base module¶

Retrieve Pillar data by doing a SQL query This module is not meant to be used directly as an ext_pillar. It is a place to put code common to PEP 249 compliant SQL database adapters. It exposes a python ABC that can be subclassed for new database providers.

Theory of sql_base ext_pillar¶

Ok, here's the theory for how this works...
We do this so that it's backward compatible with older configs. Keyword arguments are sorted before being appended, so that they're predictable, but they will always be applied last so overall it's moot. For each of those items we process, it depends on the object type:
You can retrieve as many fields as you like, how they get used depends on the exact settings.

Configuring a sql_base ext_pillar¶

The sql_base ext_pillar cannot be used directly, but shares query configuration with its implementations. These examples use a fake 'sql_base' adapter, which should be replaced with the name of the adapter you are using. A list of queries can be passed in
Or you can pass in a mapping
The query can be provided as a string as we have just shown, but they can be provided as lists
Or as a mapping
The depth defines how the dicts are constructed. Essentially if you query for fields a,b,c,d for each row you'll get:
Depth greater than 3 wouldn't be different from 3 itself. Depth of 0 translates to the largest depth needed, so 3 in this case. (max depth == key count - 1) Then they are merged in a similar way to plain pillar data, in the order returned by the SQL database. Thus subsequent results overwrite previous ones when they collide. The ignore_null option can be used to change the overwrite behavior so that only non-NULL values in subsequent results will overwrite. This can be used to selectively overwrite default values.
If you specify as_list: True in the mapping expression it will convert collisions to lists. If you specify with_lists: '...' in the mapping expression it will convert the specified depths to list. The string provided is a sequence numbers that are comma separated. The string '1,3' will result in:
These columns define list grouping
The range for with_lists is 1 to number_of_fields, inclusive. Numbers outside this range are ignored. Finally, if you pass the queries in via a mapping, the key will be the first level name where as passing them in as a list will place them in the root. This isolates the query results into their own subtrees. This may be a help or hindrance to your aims and can be used as such. You can basically use any SELECT query that gets you the information, you could even do joins or subqueries in case your minion_id is stored elsewhere. It is capable of handling single rows or multiple rows per minion. Configuration of the connection depends on the adapter in use.

More complete example for MySQL (to also show configuration)¶

salt.pillar.sqlcipher module¶

Retrieve Pillar data by running a SQLCipher query New in version 2016.3.0. Python SQLCipher support is provided by the pysqlcipher Python package. You need this module installed to query Pillar data from a SQLCipher database. This module is a concrete implementation of the sql_base ext_pillar for SQLCipher.

Configuring the sqlcipher ext_pillar¶

Use the 'sqlcipher' key under ext_pillar for configuration of queries. SQLCipher database connection configuration requires the following values configured in the master config:
Example configuration

Complete example¶

salt.pillar.sqlite3 module¶

Retrieve Pillar data by doing a SQLite3 query New in version 2015.8.0. sqlite3 is included in the stdlib since Python 2.5. This module is a concrete implementation of the sql_base ext_pillar for SQLite3.

Configuring the sqlite3 ext_pillar¶

Use the 'sqlite3' key under ext_pillar for configuration of queries. SQLite3 database connection configuration requires the following values configured in the master config: Note, timeout is in seconds.

Legacy Compatibility¶

SQLite3 database connection configuration previously had keys under pillar.
This has been deprecated in 2016.3.0 and will be removed in Salt Nitrogen.

Complete Example¶

salt.pillar.stack¶

Simple and flexible YAML ext_pillar which can read pillar from within pillar. New in version 2016.3.0. PillarStack is a custom saltstack ext_pillar which was inspired by varstack but is heavily based on Jinja2 for maximum flexibility. Any issue should be reported to the upstream project at: https://github.com/bbinet/pillarstack/issues It supports the following features:

Installation¶

PillarStack is already bundled with Salt since 2016.3.0 version so there is nothing to install from version 2016.3.0. If you use an older Salt version or you want to override PillarStack with a more recent one, follow the installation procedure below. Installing the PillarStack ext_pillar is as simple as dropping the stack.py file in the <extension_modules>/pillar directory (no external python module required), given that extension_modules is set in your salt-master configuration, see: http://docs.saltstack.com/en/latest/ref/configuration/master.html#extension-modules

Configuration in Salt¶

Like any other external pillar, its configuration takes place through the ext_pillar key in the master config file. However, you can configure PillarStack in 3 different ways:

Single config file¶

This is the simplest option, you just need to set the path to your single PillarStack config file like below:

List of config files¶

You can also provide a list of config files:

Select config files through grains|pillar|opts matching¶

You can also opt for a much more flexible configuration: PillarStack allows one to select the config files for the current minion based on matching values from either grains, or pillar, or opts objects. Here is an example of such a configuration, which should speak by itself:

PillarStack configuration files¶

The config files that are referenced in the above ext_pillar configuration are jinja2 templates which must render as a simple ordered list of yaml files that will then be merged to build pillar data. The path of these yaml files must be relative to the directory of the PillarStack config file. These paths support unix style pathname pattern expansion through the Python glob module <https://docs.python.org/2/library/glob.html>. The following variables are available in jinja2 templating of PillarStack configuration files:
So you can use all the power of jinja2 to build your list of yaml files that will be merged in pillar data. For example, you could have a PillarStack config file which looks like:
And the whole directory structure could look like:

Overall process¶

In the above PillarStack configuration, given that test-1-dev minion is an amd64 platform running Debian Jessie, and which pillar roles is ["db"], the following yaml files would be merged in order:
Before merging, every files above will be preprocessed as Jinja2 templates. The following variables are available in Jinja2 templating of yaml files:
So you can use all the power of jinja2 to build your pillar data, and even use other pillar values that has already been merged by PillarStack (from previous yaml files in PillarStack configuration) through the stack variable. Once a yaml file has been preprocessed by Jinja2, we obtain a Python dict - let's call it yml_data - then, PillarStack will merge this yml_data dict in the main stack dict (which contains already merged PillarStack pillar data). By default, PillarStack will deeply merge yml_data in stack (similarly to the recurse salt pillar_source_merging_strategy), but 3 merging strategies are currently available for you to choose (see next section). Once every yaml files have been processed, the stack dict will contain your whole own pillar data, merged in order by PillarStack. So PillarStack ext_pillar returns the stack dict, the contents of which Salt takes care to merge in with all of the other pillars and finally return the whole pillar to the minion.

Merging strategies¶

The way the data from a new yaml_data dict is merged with the existing stack data can be controlled by specifying a merging strategy. Right now this strategy can either be merge-last (the default), merge-first, remove, or overwrite. Note that scalar values like strings, integers, booleans, etc. are always evaluated using the overwrite strategy (other strategies don't make sense in that case). The merging strategy can be set by including a dict in the form of:
as the first item of the dict or list. This allows fine grained control over the merging process.

merge-last (default) strategy¶

If the merge-last strategy is selected (the default), then content of dict or list variables is merged recursively with previous definitions of this variable (similarly to the recurse salt pillar_source_merging_strategy). This allows for extending previously defined data.

merge-first strategy¶

If the merge-first strategy is selected, then the content of dict or list variables are swapped between the yaml_data and stack objects before being merged recursively with the merge-last previous strategy.

remove strategy¶

If the remove strategy is selected, then content of dict or list variables in stack are removed only if the corresponding item is present in the yaml_data dict. This allows for removing items from previously defined data.

overwrite strategy¶

If the overwrite strategy is selected, then the content of dict or list variables in stack is overwritten by the content of yaml_data dict. So this allows one to overwrite variables from previous definitions.

Merging examples¶

Let's go through small examples that should clarify what's going on when a yaml_data dict is merged in the stack dict. When you don't specify any strategy, the default merge-last strategy is selected:

stack	yaml_data	stack (after merge)
0.0 3.5 users: tom: uid: 500 roles: - sysadmin root: uid: 0 252u 252u	0.0 3.5 users: tom: uid: 1000 roles: - developer mat: uid: 1001 252u 252u	0.0 3.5 users: tom: uid: 1000 roles: - sysadmin - developer mat: uid: 1001 root: uid: 0 252u 252u

Then you can select a custom merging strategy using the __ key in a dict:

stack	yaml_data	stack (after merge)
0.0 3.5 users: tom: uid: 500 roles: - sysadmin root: uid: 0 252u 252u	0.0 3.5 users: __: merge-last tom: uid: 1000 roles: - developer mat: uid: 1001 252u 252u	0.0 3.5 users: tom: uid: 1000 roles: - sysadmin - developer mat: uid: 1001 root: uid: 0 252u 252u

0.0 3.5 users: tom: uid: 500 roles: - sysadmin root: uid: 0 252u 252u	0.0 3.5 users: __: merge-first tom: uid: 1000 roles: - developer mat: uid: 1001 252u 252u	0.0 3.5 users: tom: uid: 500 roles: - developer - sysadmin mat: uid: 1001 root: uid: 0 252u 252u

0.0 3.5 users: tom: uid: 500 roles: - sysadmin root: uid: 0 252u 252u	0.0 3.5 users: __: remove tom: mat: 252u 252u	0.0 3.5 users: root: uid: 0 252u 252u

0.0 3.5 users: tom: uid: 500 roles: - sysadmin root: uid: 0 252u 252u	0.0 3.5 users: __: overwrite tom: uid: 1000 roles: - developer mat: uid: 1001 252u 252u	0.0 3.5 users: tom: uid: 1000 roles: - developer mat: uid: 1001 252u 252u

You can also select a custom merging strategy using a __ object in a list:

stack	yaml_data	stack (after merge)
0.0 3.5 users: - tom - root 252u 252u	0.0 3.5 users: - __: merge-last - mat 252u 252u	0.0 3.5 users: - tom - root - mat 252u 252u

0.0 3.5 users: - tom - root 252u 252u	0.0 3.5 users: - __: merge-first - mat 252u 252u	0.0 3.5 users: - mat - tom - root 252u 252u

0.0 3.5 users: - tom - root 252u 252u	0.0 3.5 users: - __: remove - mat - tom 252u 252u	0.0 3.5 users: - root 252u 252u

0.0 3.5 users: - tom - root 252u 252u	0.0 3.5 users: - __: overwrite - mat 252u 252u	0.0 3.5 users: - mat 252u 252u

salt.pillar.svn_pillar¶

Clone a remote SVN repository and use the filesystem as a Pillar source This external Pillar source can be configured in the master config file like so:
The root= parameter is optional and used to set the subdirectory from where to look for Pillar files (such as top.sls). Changed in version 2014.7.0: The optional root parameter will be added. Note that this is not the same thing as configuring pillar data using the pillar_roots parameter. The branch referenced in the ext_pillar entry above ( master), would evaluate to the base environment, so this branch needs to contain a top.sls with a base section in it, like this:
To use other environments from the same SVN repo as svn_pillar sources, just add additional lines, like so:
In this case, the dev branch would need its own top.sls with a dev section in it, like this:

salt.pillar.varstack_pillar¶

Use Varstack data as a Pillar source

Configuring Varstack¶

Using varstack in Salt is fairly simple. Just put the following into the config file of your master:
Varstack will then use /etc/varstack.yaml to determine which configuration data to return as pillar information. From there you can take a look at the README of varstack on how this file is evaluated.

salt.pillar.vault module¶

Vault Pillar Module
New in version 2016.11.0. This module allows pillar data to be stored in Hashicorp Vault. The vault module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example:
vault.host refers to the host that is hosting vault and vault.port refers to the port on that host. A vault token is also required. It may be set statically, as above, or as an environment variable:
After the profile is created, configure the external pillar system to use it. A path must also be specified so that vault knows where to look.
Using these configuration profiles, multiple vault sources may also be used:

salt.pillar.virtkey¶

Accept a key from a hypervisor if the virt runner has already submitted an authorization request

proxy modules¶

chronos	Chronos
esxi	Proxy Minion interface module for managing VMware ESXi hosts.
fx2	Dell FX2 chassis
junos	Interface with a Junos device via proxy-minion.
marathon	Marathon
napalm	NAPALM: Network Automation and Programmability Abstraction Layer with Multivendor support
nxos	Proxy Minion for Cisco NX OS Switches
philips_hue	Philips HUE lamps module for proxy.
rest_sample	This is a simple proxy-minion designed to connect to and communicate with
ssh_sample	This is a simple proxy-minion designed to connect to and communicate with a server that exposes functionality via SSH.

salt.proxy.chronos module¶

Chronos¶

Proxy minion for managing a Chronos cluster.

Dependencies¶

Pillar¶

The chronos proxy configuration requires a 'base_url' property that points to the chronos endpoint:
New in version 2015.8.2.

salt.proxy.esxi¶

Proxy Minion interface module for managing VMware ESXi hosts. New in version 2015.8.4. Special Note: SaltStack thanks Adobe Corporation for their support in creating this Proxy Minion integration. This proxy minion enables VMware ESXi (hereafter referred to as simply 'ESXi') hosts to be treated individually like a Salt Minion. Since the ESXi host may not necessarily run on an OS capable of hosting a Python stack, the ESXi host can't run a Salt Minion directly. Salt's "Proxy Minion" functionality enables you to designate another machine to host a minion process that "proxies" communication from the Salt Master. The master does not know nor care that the target is not a "real" Salt Minion. More in-depth conceptual reading on Proxy Minions can be found in the Proxy Minion section of Salt's documentation.

Dependencies¶

pyVmomi¶

PyVmomi can be installed via pip:
NOTE:
Based on the note above, to install an earlier version of pyVmomi than the version currently listed in PyPi, run the following:
The 5.5.0.2014.1.1 is a known stable version that this original ESXi State Module was developed against.

ESXCLI¶

Currently, about a third of the functions used in the vSphere Execution Module require the ESXCLI package be installed on the machine running the Proxy Minion process. The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware provides vCLI package installation instructions for vSphere 5.5 and vSphere 6.0. Once all of the required dependencies are in place and the vCLI package is installed, you can check to see if you can connect to your ESXi host or vCenter server by running the following command:
If the connection was successful, ESXCLI was successfully installed on your system. You should see output related to the ESXi host's syslog configuration.

Configuration¶

To use this integration proxy module, please configure the following:

Pillar¶

Proxy minions get their configuration from Salt's Pillar. Every proxy must have a stanza in Pillar and a reference in the Pillar top-file that matches the ID. At a minimum for communication with the ESXi host, the pillar should look like this:

proxytype¶

The proxytype key and value pair is critical, as it tells Salt which interface to load from the proxy directory in Salt's install hierarchy, or from /srv/salt/_proxy on the Salt Master (if you have created your own proxy module, for example). To use this ESXi Proxy Module, set this to esxi.

host¶

The location, or ip/dns, of the ESXi host. Required.

username¶

The username used to login to the ESXi host, such as root. Required.

passwords¶

A list of passwords to be used to try and login to the ESXi host. At least one password in this list is required. The proxy integration will try the passwords listed in order. It is configured this way so you can have a regular password and the password you may be updating for an ESXi host either via the vsphere.update_host_password execution module function or via the esxi.password_present state function. This way, after the password is changed, you should not need to restart the proxy minion--it should just pick up the the new password provided in the list. You can then change pillar at will to move that password to the front and retire the unused ones. This also allows you to use any number of potential fallback passwords. NOTE:

protocol¶

If the ESXi host is not using the default protocol, set this value to an alternate protocol. Default is https.

port¶

If the ESXi host is not using the default port, set this value to an alternate port. Default is 443.

Salt Proxy¶

After your pillar is in place, you can test the proxy. The proxy can run on any machine that has network connectivity to your Salt Master and to the ESXi host in question. SaltStack recommends that the machine running the salt-proxy process also run a regular minion, though it is not strictly necessary. On the machine that will run the proxy, make sure there is an /etc/salt/proxy file with at least the following in it:
You can then start the salt-proxy process with:
You may want to add -l debug to run the above in the foreground in debug mode just to make sure everything is OK. Next, accept the key for the proxy on your salt-master, just like you would for a regular minion:
You can confirm that the pillar data is in place for the proxy:
And now you should be able to ping the ESXi host to make sure it is responding:
At this point you can execute one-off commands against the host. For example, you can get the ESXi host's system information:
Note that you don't need to provide credentials or an ip/hostname. Salt knows to use the credentials you stored in Pillar. It's important to understand how this particular proxy works. Salt.modules.vsphere is a standard Salt execution module. If you pull up the docs for it you'll see that almost every function in the module takes credentials and a target host. When credentials and a host aren't passed, Salt runs commands through pyVmomi against the local machine. If you wanted, you could run functions from this module on any host where an appropriate version of pyVmomi is installed, and that host would reach out over the network and communicate with the ESXi host. esxi.cmd acts as a "shim" between the execution module and the proxy. Its first parameter is always the function from salt.modules.vsphere. If the function takes more positional or keyword arguments you can append them to the call. It's this shim that speaks to the ESXi host through the proxy, arranging for the credentials and hostname to be pulled from the Pillar section for this Proxy Minion. Because of the presence of the shim, to lookup documentation for what functions you can use to interface with the ESXi host, you'll want to look in salt.modules.vsphere instead of salt.modules.esxi.

States¶

Associated states are thoroughly documented in salt.states.esxi. Look there to find an example structure for Pillar as well as an example .sls file for standing up an ESXi host from scratch.

salt.proxy.fx2¶

Dell FX2 chassis¶

New in version 2015.8.2. Proxy minion interface module for managing Dell FX2 chassis (Dell Chassis Management Controller version 1.2 and above, iDRAC8 version 2.00 and above)

Dependencies¶

Special Note: SaltStack thanks Adobe Corporation for their support in creating this proxy minion integration. This proxy minion enables Dell FX2 and FX2s (hereafter referred to as simply "chassis", "CMC", or "FX2") chassis to be treated individually like a salt-minion. Since the CMC embedded in the chassis does not run an OS capable of hosting a Python stack, the chassis can't run a minion directly. Salt's "Proxy Minion" functionality enables you to designate another machine to host a minion process that "proxies" communication from the salt-master. The master does not know nor care that the target is not a real minion. More in-depth conceptual reading on Proxy Minions can be found in the Proxy Minion section of Salt's documentation. To configure this integration, follow these steps:

Pillar¶

Proxy minions get their configuration from Salt's Pillar. Every proxy must have a stanza in Pillar, and a reference in the Pillar topfile that matches the ID. At a minimum for communication with the chassis the pillar should look like this:
The proxytype line above is critical, it tells Salt which interface to load from the proxy directory in Salt's install hierarchy, or from /srv/salt/_proxy on the salt-master (if you have created your own proxy module, for example). The proxy integration will try the passwords listed in order. It is configured this way so you can have a regular password, a potential fallback password, and the third password can be the one you intend to change the chassis to use. This way, after it is changed, you should not need to restart the proxy minion--it should just pick up the third password in the list. You can then change pillar at will to move that password to the front and retire the unused ones. Beware, many Dell CMC and iDRAC units are configured to lockout IP addresses or users after too many failed password attempts. This can generate user panic in the form of "I no longer know what the password is!!!". To mitigate panic try the web interface from a different IP, or setup a emergency administrator user in the CMC before doing a wholesale password rotation. The automatic lockout can be disabled via Salt with the following:
and then verified with

salt-proxy¶

After your pillar is in place, you can test the proxy. The proxy can run on any machine that has network connectivity to your salt-master and to the chassis in question. SaltStack recommends that this machine also run a regular minion, though it is not strictly necessary. On the machine that will run the proxy, make sure there is an /etc/salt/proxy file with at least the following in it:
You can start the proxy with
You may want to add -l debug to run the above in the foreground in debug mode just to make sure everything is OK. Next, accept the key for the proxy on your salt-master, just like you would for a regular minion:
You can confirm that the pillar data is in place for the proxy:
And now you should be able to ping the chassis to make sure it is responding:
At this point you can execute one-off commands against the chassis. For example, you can get the chassis inventory:
Note that you don't need to provide credentials or an ip/hostname. Salt knows to use the credentials you stored in Pillar. It's important to understand how this particular proxy works. Salt.modules.dracr is a standard Salt execution module. If you pull up the docs for it you'll see that almost every function in the module takes credentials and a target host. When credentials and a host aren't passed, Salt runs racadm against the local machine. If you wanted you could run functions from this module on any host where an appropriate version of racadm is installed, and that host would reach out over the network and communicate with the chassis. Chassis.cmd acts as a "shim" between the execution module and the proxy. It's first parameter is always the function from salt.modules.dracr to execute. If the function takes more positional or keyword arguments you can append them to the call. It's this shim that speaks to the chassis through the proxy, arranging for the credentials and hostname to be pulled from the pillar section for this proxy minion. Because of the presence of the shim, to lookup documentation for what functions you can use to interface with the chassis, you'll want to look in salt.modules.dracr instead of salt.modules.chassis.

States¶

Associated states are thoroughly documented in salt.states.dellchassis. Look there to find an example structure for pillar as well as an example .sls file for standing up a Dell Chassis from scratch.

salt.proxy.junos¶

Interface with a Junos device via proxy-minion.

salt.proxy.marathon module¶

Marathon¶

Proxy minion for managing a Marathon cluster.

Dependencies¶

Pillar¶

The marathon proxy configuration requires a 'base_url' property that points to the marathon endpoint:
New in version 2015.8.2.

salt.proxy.napalm¶

NAPALM: Network Automation and Programmability Abstraction Layer with Multivendor support¶

Proxy minion for managing network devices via NAPALM library.

Dependencies¶

The napalm proxy module requires NAPALM library to be installed: pip install napalm Please check Installation for complete details.

Pillar¶

The napalm proxy configuration requires four mandatory parameters in order to connect to the network device:
Example:
SEE ALSO:
New in version 2016.11.0.

salt.proxy.nxos module¶

Proxy Minion for Cisco NX OS Switches The Cisco NX OS Proxy Minion uses the built in SSHConnection module in salt.utils.vt_helper To configure the proxy minion:

The functions from the proxy minion can be run from the salt commandline using the salt.modules.nxos execution module. NOTE:

salt.proxy.philips_hue module¶

Philips HUE lamps module for proxy. New in version 2015.8.3.

salt.proxy.rest_sample¶

This is a simple proxy-minion designed to connect to and communicate with the bottle-based web service contained in https://github.com/saltstack/salt-contrib/tree/master/proxyminion_rest_example

salt.proxy.ssh_sample¶

This is a simple proxy-minion designed to connect to and communicate with a server that exposes functionality via SSH. This can be used as an option when the device does not provide an api over HTTP and doesn't have the python stack to run a minion.

queue modules¶

pgjsonb_queue	New in version 2016.3.0.
sqlite_queue	New in version 2014.7.0.

salt.queues.pgjsonb_queue module¶

New in version 2016.3.0. This is a queue with postgres as the backend. It uses the jsonb store to store information for queues.
To enable this queue, the following needs to be configured in your master config. These are the defaults:
Use the following Pg database schema:

salt.queues.sqlite_queue module¶

New in version 2014.7.0. This is the default local master event queue built on sqlite. By default, an sqlite3 database file is created in the sqlite_queue_dir which is found at:
It's possible to store the sqlite3 database files by setting sqlite_queue_dir to another location:

roster modules¶

ansible	Read in an Ansible inventory file or script
cache	Use the minion cache on the master to derive IP addresses based on minion ID.
cloud	Use the cloud cache on the master to derive IPv4 addresses based on minion ID.
clustershell	This roster resolves hostname in a pdsh/clustershell style.
flat	Read in the roster from a flat file using the renderer system
range	This roster resolves targets from a range server.
scan	Scan a netmask or ipaddr for open ssh ports

salt.roster.ansible¶

Read in an Ansible inventory file or script Flat inventory files should be in the regular ansible inventory format.
then salt-ssh can be used to hit any of them
There is also the option of specifying a dynamic inventory, and generating it on the fly
This is the format that an inventory script needs to output to work with ansible, and thus here.
Any of the [groups] or direct hostnames will return. The 'all' is special, and returns everything.

salt.roster.cache¶

Use the minion cache on the master to derive IP addresses based on minion ID. Currently only contains logic to return an IPv4 address; does not handle IPv6, or authentication (passwords, keys, etc). It is possible to configure this roster to prefer a particular type of IP over another. To configure the order, set the roster_order in the master config file. The default for this is:

salt.roster.cloud¶

Use the cloud cache on the master to derive IPv4 addresses based on minion ID. This roster requires that the minion in question was created using at least the 2015.5.0 version of Salt Cloud. Starting with the 2015.5.0 release, Salt Cloud maintains an index of minions that it creates and deletes. This index tracks the provider and profile configuration used to provision the minion, including authentication information. So long as this configuration remains current, it can be used by Salt SSH to log into any minion in the index. To connect as a user other than root, modify the cloud configuration file usually located at /etc/salt/cloud. For example, add the following:

salt.roster.clustershell¶

This roster resolves hostname in a pdsh/clustershell style.
When you want to use host globs for target matching, use --roster clustershell. For example:

salt.roster.flat¶

Read in the roster from a flat file using the renderer system

salt.roster.range module¶

This roster resolves targets from a range server.
When you want to use a range query for target matching, use --roster range. For example:

salt.roster.scan¶

Scan a netmask or ipaddr for open ssh ports

runner modules¶

asam	Novell ASAM Runner
cache	Return cached data from minions
cloud	The Salt Cloud Runner
ddns	Dynamic DNS Runner
doc	A runner module to collect and display the inline documentation from the
drac	Manage Dell DRAC from the Master
error	Error generator to enable integration testing of salt runner error handling
f5	Runner to provide F5 Load Balancer functionality
fileserver	Directly manage the Salt fileserver plugins
git_pillar	Runner module to directly manage the git external pillar
http	Module for making various web calls.
jobs	A convenience system to manage jobs, both active and already run
launchd	Manage launchd plist files
lxc	Control Linux Containers via Salt
manage	General management functions for salt, tools like seeing what hosts are up
mine	A runner to access data from the salt mine
nacl	This runner helps create encrypted passwords that can be included in pillars.
network	Network tools to run from the Master
pagerduty	Runner Module for Firing Events via PagerDuty
pillar	Functions to interact with the pillar compiler on the master
pkg	Package helper functions using salt.modules.pkg
queue	General management and processing of queues.
reactor	A convenience system to manage reactors
salt	New in version 2016.11.0.
saltutil	Sync custom types to the Master
sdb	Runner for setting and querying data via the sdb API on the master
search	Runner frontend to search system
spacewalk	Spacewalk Runner
ssh	A Runner module interface on top of the salt-ssh Python API.
state	Execute orchestration functions
survey	A general map/reduce style salt runner for aggregating results returned by several different minions.
test	This runner is used only for test purposes and servers no production purpose
thin	The thin runner is used to manage the salt thin systems.
virt	Control virtual machines via Salt
winrepo	Runner to manage Windows software repo

salt.runners.asam¶

Novell ASAM Runner¶

New in version Beryllium. Runner to interact with Novell ASAM Fan-Out Driver
To use this runner, set up the Novell Fan-Out Driver URL, username and password in the master configuration at /etc/salt/master or /etc/salt/master.d/asam.conf:
NOTE:

salt.runners.cache¶

Return cached data from minions

salt.runners.cloud¶

The Salt Cloud Runner¶

This runner wraps the functionality of salt cloud making salt cloud routines available to all internal apis via the runner system

salt.runners.ddns¶

Dynamic DNS Runner¶

New in version Beryllium. Runner to interact with DNS server and create/delete/update DNS records

salt.runners.doc¶

A runner module to collect and display the inline documentation from the various module types

salt.runners.drac¶

Manage Dell DRAC from the Master The login credentials need to be configured in the Salt master configuration file.

salt.runners.error¶

Error generator to enable integration testing of salt runner error handling

salt.runners.f5¶

Runner to provide F5 Load Balancer functionality

salt.runners.fileserver¶

Directly manage the Salt fileserver plugins

salt.runners.git_pillar¶

Runner module to directly manage the git external pillar

salt.runners.http¶

Module for making various web calls. Primarily designed for webhooks and the like, but also useful for basic http testing. New in version 2015.5.0.

salt.runners.jobs¶

A convenience system to manage jobs, both active and already run

salt.runners.launchd¶

Manage launchd plist files

salt.runners.lxc¶

Control Linux Containers via Salt

salt.runners.manage¶

General management functions for salt, tools like seeing what hosts are up and what hosts are down

salt.runners.mine¶

A runner to access data from the salt mine

salt.runners.nacl¶

This runner helps create encrypted passwords that can be included in pillars.
This is often useful if you wish to store your pillars in source control or share your pillar data with others that you trust. I don't advise making your pillars public regardless if they are encrypted or not. The following configurations can be defined in the master config so your users can create encrypted passwords using the runner nacl:
Now with the config in the master you can use the runner nacl like:

salt.runners.network¶

Network tools to run from the Master

salt.runners.pagerduty¶

Runner Module for Firing Events via PagerDuty New in version 2014.1.0.

salt.runners.pillar¶

Functions to interact with the pillar compiler on the master

salt.runners.pkg¶

Package helper functions using salt.modules.pkg New in version 2015.8.0.

salt.runners.queue¶

General management and processing of queues. This runner facilitates interacting with various queue backends such as the included sqlite3 queue or the planned AWS SQS and Redis queues The queue functions such as insert, delete, and pop can be used for typical management of the queue. The process_queue function pops the requested number of items from the queue and creates a Salt Event that can then be processed by a Reactor. The process_queue function can be called manually, or can be configured to run on a schedule with the Salt Scheduler or regular system cron. It is also possible to use the peer system to allow a minion to call the runner. This runner, as well as the Queues system, is not api stable at this time. There are many things that could potentially be done with queues within Salt. For the time being the focus will be on queueing infrastructure actions on specific minions. The queues generally will be populated with minion IDs. When the process_queue runner function is called events are created on the Salt Event bus that indicate the queue and a list of one or more minion IDs. The reactor is set up to match on event tags for a specific queue and then take infrastructure actions on those minion IDs. These actions might be to delete the minion's key from the master, use salt-cloud to destroy the vm, or some other custom action.

salt.runners.reactor¶

A convenience system to manage reactors

salt.runners.salt¶

New in version 2016.11.0. This runner makes Salt's execution modules available on the salt master. Salt's execution modules are normally available on the salt minion. Use this runner to call execution modules on the salt master. Salt execution modules are the functions called by the salt command. Execution modules can be called with salt-run:
Execution modules are also available to salt runners:

salt.runners.saltutil¶

Sync custom types to the Master New in version 2016.3.0.

salt.runners.sdb¶

Runner for setting and querying data via the sdb API on the master

salt.runners.search¶

Runner frontend to search system

salt.runners.spacewalk¶

Spacewalk Runner¶

New in version 2016.3.0. Runner to interact with Spacewalk using Spacewalk API
To use this runner, set up the Spacewalk URL, username and password in the master configuration at /etc/salt/master or /etc/salt/master.d/spacewalk.conf:
NOTE:

salt.runners.ssh¶

A Runner module interface on top of the salt-ssh Python API. This allows for programmatic use from salt-api, the Reactor, Orchestrate, etc.

salt.runners.state¶

Execute orchestration functions

salt.runners.survey¶

A general map/reduce style salt runner for aggregating results returned by several different minions. New in version 2014.7.0. Aggregated results are sorted by the size of the minion pools which returned matching results. Useful for playing the game: "some of these things are not like the others..." when identifying discrepancies in a large infrastructure managed by salt.

salt.runners.test¶

This runner is used only for test purposes and servers no production purpose

salt.runners.thin¶

The thin runner is used to manage the salt thin systems. Salt Thin is a transport-less version of Salt that can be used to run routines in a standalone way. This runner has tools which generate the standalone salt system for easy consumption.

salt.runners.virt¶

Control virtual machines via Salt

salt.runners.winrepo¶

Runner to manage Windows software repo

sdb modules¶

confidant	An SDB module for getting credentials from confidant.
consul	Consul sdb Module
couchdb	CouchDB sdb Module
etcd_db	etcd Database Module
keyring_db	Keyring Database Module
memcached	Memcached sdb Module
rest	Generic REST API SDB Module
sqlite3	SQLite sdb Module
vault	Vault SDB Module

salt.sdb.confidant¶

An SDB module for getting credentials from confidant.

Configuring the Confidant module¶

The module can be configured via sdb in the minion config:

Module Documentation¶

salt.sdb.consul module¶

Consul sdb Module
This module allows access to Consul using an sdb:// URI Like all sdb modules, the Consul module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. For example: The driver refers to the Consul module, all other options are optional. For option details see: https://python-consul.readthedocs.io/en/latest/#consul

salt.sdb.couchdb¶

CouchDB sdb Module
This allow interaction between Salt and a CouchDB [couchdb.apache.org] database. It uses salt's sdb system to allow for inserts and retrevals using the sdb:// prefix in salt configuration files. To use the couchbase sdb module, it must first be configured in the salt master or minion config. The following arguments are required:
One could then query the CouchDB instance via an sdb:// URI such as the following:
To use this interface, you must track IDs on your own or have another source to do the map-reduce logic necessary to calculate the ID you wish to fetch. Additional contributions to build true map-reduce functionality into this module would be welcome.

salt.sdb.etcd_db¶

etcd Database Module
New in version 2015.5.0. This module allows access to the etcd database using an sdb:// URI. This package is located at https://pypi.python.org/pypi/python-etcd. Like all sdb modules, the etcd module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example:
The driver refers to the etcd module, etcd.host refers to the host that is hosting the etcd database and etcd.port refers to the port on that host.

salt.sdb.keyring_db¶

Keyring Database Module
This module allows access to the keyring package using an sdb:// URI. This package is located at https://pypi.python.org/pypi/keyring. Care must be taken when using keyring. Not all keyend backends are supported on all operating systems. Also, many backends require an agent to be running in order to work. For instance, the "Secret Service" backend requires a compatible agent such as gnome-keyring-daemon or kwallet to be running. The keyczar backend does not seem to enjoy the benefits of an agent, and so using it will require either that the password is typed in manually (which is unreasonable for the salt-minion and salt-master daemons, especially in production) or an agent is written for it. Like all sdb modules, the keyring module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example:
The driver refers to the keyring module, service refers to the service that will be used inside of keyring (which may be likened unto a database table) and mykeyring refers to the name that will appear in the URI:
The underlying backend configuration must be configured via keyring itself. For examples and documentation, see keyring: https://pypi.python.org/pypi/keyring New in version 2014.1.4.

salt.sdb.memcached¶

Memcached sdb Module
This module allows access to memcached using an sdb:// URI. This package is located at https://pypi.python.org/pypi/python-memcached. Like all sdb modules, the memcached module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example:
The driver refers to the memcached module, host and port the memcached server to connect to (defaults to localhost and 11211, and mymemcached refers to the name that will appear in the URI:

salt.sdb.rest module¶

Generic REST API SDB Module
New in version 2015.8.0. This module allows access to a REST interface using an sdb:// URI. Like all REST modules, the REST module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example:
The driver refers to the REST module, and must be set to rest in order to use this driver. Each of the other items inside this block refers to a separate set of HTTP items, including a URL and any options associated with it. The options used here should match the options available in salt.utils.http.query(). In order to call the urls item in the example, the following reference can be made inside a configuration file:
Key/Value pairs may also be used with this driver, and merged into the URL using the configured renderer ( jinja, by default). For instance, in order to use the keys item in the example, the following reference can be made:
This will cause the following URL to actually be called:
Key/Value pairs will NOT be passed through as GET data. If GET data needs to be sent to the URL, then it should be configured in the SDB configuration block. For instance:

salt.sdb.sqlite3¶

SQLite sdb Module
This module allows access to sqlite3 using an sdb:// URI Like all sdb modules, the sqlite3 module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. For example:
The driver refers to the sqlite3 module, database refers to the sqlite3 database file. table is the table within the db that will hold keys and values (defaults to sdb). The database and table will be created if they do not exist.

Advanced Usage:¶

Instead of a table name, it is possible to provide custom SQL statements to create the table(s) and get and set values.

salt.sdb.vault module¶

Vault SDB Module
New in version 2016.11.0. This module allows access to Hashicorp Vault using an sdb:// URI. Like all sdb modules, the vault module requires a configuration profile to be configured in either the minion or master configuration file. This profile requires very little. In the example:
The driver refers to the vault module, vault.host refers to the host that is hosting vault and vault.port refers to the port on that host. A vault token is also required. It may be set statically, as above, or as an environment variable:
Once configured you can access data using a URL such as:
In this URL, myvault refers to the configuration profile, secret/passwords is the path where the data resides, and mypassword is the key of the data to return. The above URI is analogous to running the following vault command:

serializer modules¶

configparser	salt.serializers.configparser
json	salt.serializers.json
msgpack	salt.serializers.msgpack
python	salt.serializers.python
yaml	salt.serializers.yaml
yamlex	salt.serializers.yamlex

salt.serializers.configparser module¶

salt.serializers.configparser¶

New in version 2016.3.0. Implements a configparser serializer.

salt.serializers.json¶

salt.serializers.json¶

Implements JSON serializer. It's just a wrapper around json (or simplejson if available).

salt.serializers.msgpack¶

salt.serializers.msgpack¶

Implements MsgPack serializer.

salt.serializers.python module¶

salt.serializers.python¶

New in version 2016.3.0. Implements a Python serializer (via pprint.format)

salt.serializers.yaml¶

salt.serializers.yaml¶

Implements YAML serializer. Underneath, it is based on pyyaml and use the safe dumper and loader. It also use C bindings if they are available.

salt.serializers.yamlex¶

salt.serializers.yamlex¶

YAMLEX is a format that allows for things like sls files to be more intuitive. It's an extension of YAML that implements all the salt magic: - it implies omap for any dict like. - it implies that string like data are str, not unicode - ... For example, the file states.sls has this contents:
The file can be parsed into Python like this
Check that obj is an OrderedDict
yamlex __repr__ and __str__ objects' methods render YAML understandable string. It means that they are template friendly.
returns:
and they are still valid YAML:
yamlex implements also custom tags: !aggregate
!reset
Document is defacto an aggregate mapping.

state modules¶

acme	ACME / Let's Encrypt certificate management state
alias	Configuration of email aliases
alternatives	Configuration of the alternatives system
apache	Apache state
apache_conf	Manage Apache Confs
apache_module	Manage Apache Modules
apache_site	Manage Apache Sites
aptpkg	Package management operations specific to APT- and DEB-based systems
archive	Extract an archive
artifactory	This state downloads artifacts from artifactory.
at	Configuration disposable regularly scheduled tasks for at.
augeas	Configuration management using Augeas
aws_sqs	Manage SQS Queues
beacon	Management of the Salt beacons
bigip	A state module designed to enforce load-balancing configurations for F5 Big-IP entities.
blockdev	Management of Block Devices
boto_apigateway	Manage Apigateway Rest APIs
boto_asg	Manage Autoscale Groups
boto_cfn	Connection module for Amazon Cloud Formation
boto_cloudtrail	Manage CloudTrail Objects
boto_cloudwatch_alarm	Manage Cloudwatch alarms
boto_cognitoidentity	Manage CognitoIdentity Functions
boto_datapipeline	Manage Data Pipelines
boto_dynamodb	Manage DynamoDB Tables
boto_ec2	Manage EC2
boto_elasticache	Manage Elasticache
boto_elasticsearch_domain	Manage Elasticsearch Domains
boto_elb	Manage ELBs
boto_iam	Manage IAM objects
boto_iam_role	Manage IAM roles
boto_iot	Manage IoT Objects
boto_kms	Manage KMS keys, key policies and grants.
boto_lambda	Manage Lambda Functions
boto_lc	Manage Launch Configurations
boto_rds	Manage RDSs
boto_route53	Manage Route53 records
boto_s3_bucket	Manage S3 Buckets
boto_secgroup	Manage Security Groups
boto_sns	Manage SNS Topics
boto_sqs	Manage SQS Queues
boto_vpc	Manage VPCs
bower	Installation of Bower Packages
cabal	Installation of Cabal Packages
chef	Execute Chef client runs
chocolatey	Manage Chocolatey package installs ..
chronos_job	Configure Chronos jobs via a salt proxy.
cloud	Using states instead of maps to deploy clouds
cmd	Execution of arbitrary commands
composer	Installation of Composer Packages
cron	Management of cron, the Unix command scheduler
cyg	Installation of Cygwin packages.
ddns	Dynamic DNS updates
debconfmod	Management of debconf selections
dellchassis	Manage chassis via Salt Proxies.
disk	Disk monitoring state
dockerio	Manage Docker containers
dockerng	Management of Docker containers
drac	Management of Dell DRAC
elasticsearch_index	State module to manage Elasticsearch indices
elasticsearch_index_template	State module to manage Elasticsearch index templates
environ	Support for getting and setting the environment variables of the current salt process.
eselect	Management of Gentoo configuration using eselect
etcd_mod	Manage etcd Keys
esxi	Manage VMware ESXi Hosts.
event	Send events through Salt's event system during state runs
file	Operations on regular files, special files, directories, and symlinks
firewall	State to check firewall configurations ..
firewalld	Management of firewalld
gem	Installation of Ruby modules packaged as gems
git	States to manage git repositories and git configuration
github	Github User State Module
glance	Managing Images in OpenStack Glance
glusterfs	Manage GlusterFS pool.
gnomedesktop	Configuration of the GNOME desktop
gpg	Management of the GPG keychains
grafana	Manage Grafana Dashboards
grafana_dashboard	Manage Grafana v2.0 Dashboards
grafana_datasource	Manage Grafana v2.0 data sources
grains	Manage grains on the minion
group	Management of user groups
hg	Interaction with Mercurial repositories
hipchat	Send a message to Hipchat
host	Management of addresses and names in hosts file
htpasswd	Support for htpasswd module.
http	HTTP monitoring states
ifttt	Trigger an event in IFTTT
incron	Management of incron, the inotify cron
influxdb_database	Management of Influxdb databases
influxdb_user	Management of InfluxDB users
infoblox	states for infoblox stuff
ini_manage	Manage ini files
ipmi	Manage IPMI devices over LAN
ipset	Management of ipsets
iptables	Management of iptables
jboss7	Manage JBoss 7 Application Server via CLI interface
jenkins	Management of Jenkins
junos	State modules to interact with Junos devices.
k8s	Manage Kubernetes
kapacitor	Kapacitor state module.
keyboard	Management of keyboard layouts
keystone	Management of Keystone users
kmod	Loading and unloading of kernel modules
layman	Management of Gentoo Overlays using layman
ldap	Manage entries in an LDAP database
linux_acl	Linux File Access Control Lists
locale	Management of languages/locales
lvm	Management of Linux logical volumes
lvs_server	Management of LVS (Linux Virtual Server) Real Server
lvs_service	Management of LVS (Linux Virtual Server) Service
lxc	Manage Linux Containers
mac_assistive	Allows you to manage assistive access on macOS minions with 10.9+
mac_defaults	Writing/reading defaults from a macOS minion
mac_keychain	Installing of certificates to the keychain
mac_package	Installing of mac pkg files
mac_xattr	Allows you to manage extended attributes on files or directories
makeconf	Management of Gentoo make.conf
marathon_app	Configure Marathon apps via a salt proxy.
mdadm	Managing software RAID with mdadm
memcached	States for Management of Memcached Keys
modjk	State to control Apache modjk
modjk_worker	Manage modjk workers
module	Execution of Salt modules from within states
mongodb_database	Management of Mongodb databases
mongodb_user	Management of Mongodb users
monit	Monit state
mount	Mounting of filesystems
mysql_database	Management of MySQL databases (schemas)
mysql_grants	Management of MySQL grants (user permissions)
mysql_query	Execution of MySQL queries
mysql_user	Management of MySQL users
netntp	Network NTP
netsnmp	Network SNMP
netusers	Network Users
network	Configuration of network interfaces
nftables	Management of nftables
npm	Installation of NPM Packages
ntp	Management of NTP servers
nxos	State module for Cisco NX OS Switches Proxy minions
openstack_config	Manage OpenStack configuration file settings.
openvswitch_bridge	Management of Open vSwitch bridges.
openvswitch_port	Management of Open vSwitch ports.
pagerduty	Create an Event in PagerDuty
pagerduty_escalation_policy	Manage PagerDuty escalation policies.
pagerduty_schedule	Manage PagerDuty schedules.
pagerduty_service	Manage PagerDuty services
pagerduty_user	Manage PagerDuty users.
pcs	Management of Pacemaker/Corosync clusters with PCS
pecl	Installation of PHP Extensions Using pecl
pip_state	Installation of Python Packages Using pip
pkg	Installation of packages using OS package managers such as yum or apt-get
pkgbuild	The pkgbuild state is the front of Salt package building backend.
pkgng	Manage package remote repo using FreeBSD pkgng
pkgrepo	Management of APT/YUM package repos
portage_config	Management of Portage package configuration on Gentoo
ports	Manage software from FreeBSD ports
postgres_cluster	Management of PostgreSQL clusters
postgres_database	Management of PostgreSQL databases
postgres_extension	Management of PostgreSQL extensions
postgres_group	Management of PostgreSQL groups (roles)
postgres_initdb	Initialization of PostgreSQL data directory
postgres_language	Management of PostgreSQL languages
postgres_privileges	Management of PostgreSQL Privileges
postgres_schema	Management of PostgreSQL schemas
postgres_tablespace	Management of PostgreSQL tablespace
postgres_user	Management of PostgreSQL users (roles)
powerpath	Powerpath configuration support
probes	Network Probes
process	Process Management
pushover	Send a message to PushOver
pyenv	Managing python installations with pyenv
pyrax_queues	Manage Rackspace Queues
quota	Management of POSIX Quotas
rabbitmq_cluster	Manage RabbitMQ Clusters
rabbitmq_plugin	Manage RabbitMQ Plugins
rabbitmq_policy	Manage RabbitMQ Policies
rabbitmq_user	Manage RabbitMQ Users
rabbitmq_vhost	Manage RabbitMQ Virtual Hosts
rbenv	Managing Ruby installations with rbenv
rdp	Manage RDP Service on Windows servers
redismod	Management of Redis server
reg
rsync	State to synchronize files and directories with rsync.
rvm	Managing Ruby installations and gemsets with Ruby Version Manager (RVM)
salt_proxy	Salt proxy state
saltmod	Control the Salt command interface
schedule	Management of the Salt scheduler
selinux	Management of SELinux rules
serverdensity_device	Monitor Server with Server Density
service	Starting or restarting of services and daemons
slack	Send a message to Slack
smartos	Management of SmartOS Standalone Compute Nodes
smtp	Sending Messages via SMTP
snapper	Managing implicit state and baselines using snapshots
splunk	Splunk User State Module
splunk_search	Splunk Search State Module
sqlite3	Management of SQLite3 databases
ssh_auth	Control of entries in SSH authorized_key files
ssh_known_hosts	Control of SSH known_hosts entries
stateconf	Stateconf System
status	Minion status monitoring
stormpath_account	Support for Stormpath.
supervisord	Interaction with the Supervisor daemon
svn	Manage SVN repositories
sysctl	Configuration of the Linux kernel using sysctl
syslog_ng	State module for syslog_ng
sysrc
telemetry_alert	New in version 2016.3.0..
test	Test States
timezone	Management of timezones
tls	Enforce state for SSL/TLS
tomcat	Manage Apache Tomcat web applications
trafficserver	Control Apache Traffic Server
tuned	Interface to Red Hat tuned-adm module
uptime	Monitor Web Server with Uptime
user	Management of user accounts
vbox_guest	VirtualBox Guest Additions installer state
victorops	Create an Event in VictorOps
virt	Manage virt
virtualenv_mod	Setup of Python virtualenv sandboxes.
win_certutil	Installing of certificates to the Windows Certificate Manager
win_dacl	Windows Object Access Control Lists
win_dism	Installing of Windows features using DISM
win_dns_client	Module for configuring DNS Client on Windows systems
win_firewall	State for configuring Windows Firewall
win_iis	Microsoft IIS site management
win_license	Installation and activation of windows licenses
win_network	Configuration of network interfaces on Windows hosts
win_path	Manage the Windows System PATH
win_powercfg	This module allows you to control the power settings of a windows minion via powercfg.
win_servermanager	Manage Windows features via the ServerManager powershell module
win_smtp_server	Module for managing IIS SMTP server configuration on Windows servers.
win_system	Management of Windows system information
win_update	Management of the windows update agent
winrepo	Manage Windows Package Repository
x509	Manage X509 Certificates
xmpp	Sending Messages over XMPP
zabbix_host	Management of Zabbix hosts.
zabbix_hostgroup	Management of Zabbix host groups.
zabbix_user	Management of Zabbix users.
zabbix_usergroup	Management of Zabbix user groups.
zcbuildout	Management of zc.buildout
zenoss	State to manage monitoring in Zenoss.
zk_concurrency	Control concurrency of steps within state execution using zookeeper
zfs	Management zfs datasets
zpool	Management zpool

salt.states.acme module¶

ACME / Let's Encrypt certificate management state¶

See also the module documentation

salt.states.alias¶

Configuration of email aliases The mail aliases file can be managed to contain definitions for specific email aliases:

The default alias file is set to /etc/aliases, as defined in Salt's config execution module. To change the alias file from the default location, set the following in your minion config:

salt.states.alternatives¶

Configuration of the alternatives system Control the alternatives system

salt.states.apache¶

Apache state New in version 2014.7.0. Allows for inputting a yaml dictionary into a file for apache configuration files. The variable this is special and signifies what should be included with the above word between angle brackets (<>).

salt.states.apache_conf module¶

Manage Apache Confs New in version 2016.3.0. Enable and disable apache confs.

salt.states.apache_module¶

Manage Apache Modules New in version 2014.7.0. Enable and disable apache modules.

salt.states.apache_site module¶

Manage Apache Sites New in version 2016.3.0. Enable and disable apache sites.

salt.states.aptpkg¶

Package management operations specific to APT- and DEB-based systems¶

salt.states.archive¶

Extract an archive New in version 2014.1.0.

salt.states.artifactory¶

This state downloads artifacts from artifactory.

salt.states.at¶

Configuration disposable regularly scheduled tasks for at.¶

The at state can be add disposable regularly scheduled tasks for your system.

salt.states.augeas¶

Configuration management using Augeas New in version 0.17.0. This state requires the augeas Python module. Augeas can be used to manage configuration files. WARNING:

salt.states.aws_sqs¶

Manage SQS Queues Create and destroy SQS queues. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses the awscli tool provided by Amazon. This can be downloaded from pip. Also check the documentation for awscli for configuration information.

salt.states.beacon¶

Management of the Salt beacons¶

New in version 2015.8.0.

salt.states.bigip¶

salt.states.blockdev¶

Management of Block Devices A state module to manage blockdevices
New in version 2014.7.0.

salt.states.boto_apigateway module¶

Manage Apigateway Rest APIs¶

New in version 2016.11.0. Create and destroy rest apis depending on a swagger version 2 definition file. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto3, which can be installed via package, or pip. This module accepts explicit vpc credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_asg¶

Manage Autoscale Groups¶

New in version 2014.7.0. Create and destroy autoscale groups. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit autoscale credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at:
If IAM roles are not used you need to specify them either in a pillar or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config:

It's possible to specify cloudwatch alarms that will be setup along with the ASG. Note the alarm name will be the name attribute defined, plus the ASG resource name.
You can also use alarms from pillars, and override values from the pillar alarms by setting overrides on the resource. Note that 'boto_asg_alarms' will be used as a default value for all resources, if defined and can be used to ensure alarms are always set for an ASG resource. Setting the alarms in a pillar:
Overriding the alarm values on the resource:

salt.states.boto_cfn¶

Connection module for Amazon Cloud Formation New in version 2015.8.0.

salt.states.boto_cloudtrail module¶

Manage CloudTrail Objects¶

New in version 2016.3.0. Create and destroy CloudTrail objects. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto3, which can be installed via package, or pip. This module accepts explicit vpc credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_cloudwatch_alarm¶

Manage Cloudwatch alarms New in version 2014.7.0. Create and destroy cloudwatch alarms. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html If IAM roles are not used you need to specify them either in a pillar or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config:

salt.states.boto_cognitoidentity module¶

Manage CognitoIdentity Functions¶

New in version 2016.11.0. Create and destroy CognitoIdentity identity pools. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto3, which can be installed via package, or pip. This module accepts explicit vpc credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_datapipeline module¶

Manage Data Pipelines New in version 2016.3.0. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto3, which can be installed via package, or pip. This module accepts explicit AWS credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_dynamodb¶

Manage DynamoDB Tables¶

New in version 2015.5.0. Create and destroy DynamoDB tables. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit DynamoDB credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

It's possible to specify cloudwatch alarms that will be setup along with the DynamoDB table. Note the alarm name will be defined by the name attribute provided, plus the DynamoDB resource name.
You can also use alarms from pillars, and override values from the pillar alarms by setting overrides on the resource. Note that 'boto_dynamodb_alarms' will be used as a default value for all resources, if defined and can be used to ensure alarms are always set for a resource. Setting the alarms in a pillar:

salt.states.boto_ec2¶

Manage EC2 New in version 2015.8.0. This module provides an interface to the Elastic Compute Cloud (EC2) service from AWS. The below code creates a key pair:

You can also use salt:// in order to define the public key.
The below code deletes a key pair:

salt.states.boto_elasticache¶

Manage Elasticache¶

New in version 2014.7.0. Create, destroy and update Elasticache clusters. Be aware that this interacts with Amazon's services, and so may incur charges. Note: This module currently only supports creation and deletion of elasticache resources and will not modify clusters when their configuration changes in your state files. This module uses boto, which can be installed via package, or pip. This module accepts explicit elasticache credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_elasticsearch_domain module¶

Manage Elasticsearch Domains¶

New in version 2016.11.0. Create and destroy Elasticsearch domains. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto3, which can be installed via package, or pip. This module accepts explicit vpc credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_elb¶

Manage ELBs New in version 2014.7.0. Create and destroy ELBs. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit elb credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

It's possible to specify attributes from pillars by specifying a pillar. You can override the values defined in the pillard by setting the attributes on the resource. The module will use the default pillar key 'boto_elb_attributes', which allows you to set default attributes for all ELB resources. Setting the attributes pillar:
Overriding the attribute values on the resource:
It's possible to specify cloudwatch alarms that will be setup along with the ELB. Note the alarm name will be defined by the name attribute provided, plus the ELB resource name.
You can also use alarms from pillars, and override values from the pillar alarms by setting overrides on the resource. Note that 'boto_elb_alarms' will be used as a default value for all resources, if defined and can be used to ensure alarms are always set for a resource. Setting the alarms in a pillar:
Overriding the alarm values on the resource:
Tags can also be set: New in version 2016.3.0.

salt.states.boto_iam¶

Manage IAM objects¶

New in version 2015.8.0. This module uses boto, which can be installed via package, or pip. This module accepts explicit IAM credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_iam_role¶

Manage IAM roles¶

New in version 2014.7.0. This module uses boto, which can be installed via package, or pip. This module accepts explicit IAM credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:
Creating a role will automatically create an instance profile and associate it with the role. This is the default behavior of the AWS console.
If delete_policies: False is specified, existing policies that are not in the given list of policies will not be deleted. This allows manual modifications on the IAM role to be persistent. This functionality was added in 2015.8.0. NOTE:

salt.states.boto_iot module¶

Manage IoT Objects¶

New in version 2016.3.0. Create and destroy IoT objects. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto3, which can be installed via package, or pip. This module accepts explicit vpc credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_kms¶

Manage KMS keys, key policies and grants. New in version 2015.8.0. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit kms credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_lambda module¶

Manage Lambda Functions¶

New in version 2016.3.0. Create and destroy Lambda Functions. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto3, which can be installed via package, or pip. This module accepts explicit vpc credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_lc¶

Manage Launch Configurations New in version 2014.7.0. Create and destroy Launch Configurations. Be aware that this interacts with Amazon's services, and so may incur charges. A limitation of this module is that you can not modify launch configurations once they have been created. If a launch configuration with the specified name exists, this module will always report success, even if the specified configuration doesn't match. This is due to a limitation in Amazon's launch configuration API, as it only allows launch configurations to be created and deleted. Also note that a launch configuration that's in use by an autoscale group can not be deleted until the autoscale group is no longer using it. This may affect the way in which you want to order your states. This module uses boto, which can be installed via package, or pip. This module accepts explicit autoscale credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:
Credential information is shared with autoscale groups as launch configurations and autoscale groups are completely dependent on each other.

salt.states.boto_rds¶

Manage RDSs¶

New in version 2015.8.0. Create and destroy RDS instances. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit rds credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_route53¶

Manage Route53 records New in version 2014.7.0. Create and delete Route53 records. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit route53 credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_s3_bucket module¶

Manage S3 Buckets¶

New in version 2016.3.0. Create and destroy S3 buckets. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto3, which can be installed via package, or pip. This module accepts explicit vpc credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_secgroup¶

Manage Security Groups¶

New in version 2014.7.0. Create and destroy Security Groups. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit EC2 credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

NOTE:

salt.states.boto_sns¶

Manage SNS Topics Create and destroy SNS topics. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit AWS credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_sqs¶

Manage SQS Queues New in version 2014.7.0. Create and destroy SQS queues. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit SQS credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

salt.states.boto_vpc¶

Manage VPCs¶

New in version 2015.8.0. Create and destroy VPCs. Be aware that this interacts with Amazon's services, and so may incur charges. This module uses boto, which can be installed via package, or pip. This module accepts explicit vpc credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here. If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:
It's also possible to specify key, keyid and region via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:


New in version 2016.11.0. Request, accept and delete VPC peering connections. VPC peering connections can be named allowing the name to be used throughout the state file. Following example shows how to request and accept a VPC peering connection.
VPC peering connections need not be named. In this case the VPC peering connection ID should be used in the state file.
VPC peering connections can be deleted, as shown below.
Delete also accepts a VPC peering connection id.

salt.states.bower¶

Installation of Bower Packages¶

These states manage the installed packages using Bower. Note that npm, git and bower must be installed for these states to be available, so bower states should include requisites to pkg.installed states for the packages which provide npm and git (simply npm and git in most cases), and npm.installed state for the package which provides bower. Example:

salt.states.cabal¶

Installation of Cabal Packages¶

New in version 2015.8.0. These states manage the installed packages for Haskell using cabal. Note that cabal-install must be installed for these states to be available, so cabal states should include a requisite to a pkg.installed state for the package which provides cabal ( cabal-install in case of Debian based distributions). Example:

salt.states.chef¶

Execute Chef client runs¶

Run chef-client or chef-solo

salt.states.chocolatey module¶

Manage Chocolatey package installs

salt.states.chronos_job module¶

Configure Chronos jobs via a salt proxy.
New in version 2015.8.2.

salt.states.cloud¶

Using states instead of maps to deploy clouds¶

New in version 2014.1.0. Use this minion to spin up a cloud instance:

salt.states.cmd¶

Execution of arbitrary commands¶

The cmd state module manages the enforcement of executed commands, this state can tell a command to run under certain circumstances. A simple example to execute a command:
Only run if another execution failed, in this case truncate syslog if there is no disk space:
Only run if the file specified by creates does not exist, in this case touch /tmp/foo if it does not exist:
creates also accepts a list of files:
NOTE:
Salt determines whether the cmd state is successfully enforced based on the exit code returned by the command. If the command returns a zero exit code, then salt determines that the state was successfully enforced. If the script returns a non-zero exit code, then salt determines that it failed to successfully enforce the state. If a command returns a non-zero exit code but you wish to treat this as a success, then you must place the command in a script and explicitly set the exit code of the script to zero. Please note that the success or failure of the state is not affected by whether a state change occurred nor the stateful argument. When executing a command or script, the state (i.e., changed or not) of the command is unknown to Salt's state system. Therefore, by default, the cmd state assumes that any command execution results in a changed state. This means that if a cmd state is watched by another state then the state that's watching will always be executed due to the changed state in the cmd state.

Using the Stateful Argument¶

Many state functions in this module now also accept a stateful argument. If stateful is specified to be true then it is assumed that the command or script will determine its own state and communicate it back by following a simple protocol described below:

Should I use cmd.run or cmd.wait?¶

NOTE:
These two states are often confused. The important thing to remember about them is that cmd.run states are run each time the SLS file that contains them is applied. If it is more desirable to have a command that only runs after some other state changes, then cmd.wait does just that. cmd.wait is designed to watch other states, and is executed when the state it is watching changes. Example:
cmd.wait itself does not do anything; all functionality is inside its mod_watch function, which is called by watch on changes. cmd.wait will be deprecated in future due to the confusion it causes. The preferred format is using the onchanges Requisite, which works on cmd.run as well as on any other state. The example would then look as follows:

How do I create an environment from a pillar map?¶

The map that comes from a pillar can be directly consumed by the env option! To use it, one may pass it like this. Example:

salt.states.composer¶

Installation of Composer Packages¶

These states manage the installed packages for composer for PHP. Note that either composer is installed and accessible via a bin directory or you can pass the location of composer in the state.

salt.states.cron¶

Management of cron, the Unix command scheduler¶

Cron declarations require a number of parameters. The following are the parameters used by Salt to define the various timing values for a cron job:
WARNING:
A long time ago (before 2014.2), when making changes to an existing cron job, the name declaration is the parameter used to uniquely identify the job, so if an existing cron that looks like this:
Is changed to this:
Then the existing cron will be updated, but if the cron command is changed, then a new cron job will be added to the user's crontab. The current behavior is still relying on that mechanism, but you can also specify an identifier to identify your crontabs:
New in version 2014.1.2. And, some months later, you modify it:
New in version 2014.1.2. The old date > /tmp/crontest will be replaced by superscript > /tmp/crontest. Additionally, Salt also supports running a cron every x minutes very similarly to the Unix convention of using */5 to have a job run every five minutes. In Salt, this looks like:
The job will now run every 5 minutes. Additionally, the temporal parameters (minute, hour, etc.) can be randomized by using random instead of using a specific value. For example, by using the random keyword in the minute parameter of a cron state, the same cron job can be pushed to hundreds or thousands of hosts, and they would each use a randomly-generated minute. This can be helpful when the cron job accesses a network resource, and it is not desirable for all hosts to run the job concurrently.
New in version 0.16.0. Since Salt assumes a value of * for unspecified temporal parameters, adding a parameter to the state and setting it to random will change that value from * to a randomized numeric value. However, if that field in the cron entry on the minion already contains a numeric value, then using the random keyword will not modify it. Added the opportunity to set a job with a special keyword like '@reboot' or '@hourly'.
The script will be executed every reboot if cron daemon support this option.
This counter part definition will ensure than a job with a special keyword is not set.

salt.states.cyg¶

Installation of Cygwin packages. A state module to manage cygwin packages. Packages can be installed or removed.

salt.states.ddns¶

Dynamic DNS updates¶

Ensure a DNS record is present or absent utilizing RFC 2136 type dynamic updates.
NOTE:
Example:

salt.states.debconfmod¶

Management of debconf selections¶

The debconfmod state module manages the enforcement of debconf selections, this state can set those selections prior to package installation.

Available Functions¶

The debconfmod state has two functions, the set and set_file functions

NOTE:

salt.states.dellchassis¶

Manage chassis via Salt Proxies. New in version 2015.8.2. Below is an example state that sets basic parameters:
However, it is possible to place the entire set of chassis configuration data in pillar. Here's an example pillar structure:
And to go with it, here's an example state that pulls the data from the pillar stated above:
NOTE:
NOTE:

salt.states.disk¶

Disk monitoring state Monitor the state of disk resources. The disk.status function can be used to report that the used space of a filesystem is within the specified limits.
It can be used with an onfail requisite, for example, to take additional action in response to or in preparation for other states.
To use kilobytes (KB) for minimum and maximum rather than percents, specify the absolute flag:

salt.states.dockerio¶

Manage Docker containers¶

Deprecated since version 2015.8.0: Future feature development will be done only in dockerng. See the documentation for this module for information on the deprecation path. Docker is a lightweight, portable, self-sufficient software container wrapper. The base supported wrapper type is LXC, cgroups, and the Linux Kernel. NOTE:

Available Functions¶

Use Cases¶

NOTE:

salt.states.dockerng¶

Management of Docker containers New in version 2015.8.0. This is the state module to accompany the dockerng execution module.

Why Make a Second Docker State Module?¶

We have received a lot of feedback on our Docker support. In the process of implementing recommended improvements, it became obvious that major changes needed to be made to the functions and return data. In the end, a complete rewrite was done. The changes being too significant, it was decided that making a separate execution module and state module (called dockerng) would be the best option. This will give users a couple release cycles to modify their scripts, SLS files, etc. to use the new functionality, rather than forcing users to change everything immediately. In the Nitrogen release of Salt (due in 2017), this execution module will take the place of the default Docker execution module, and backwards-compatible naming will be maintained for a couple releases after that to allow users time to replace references to dockerng with docker. NOTE:

salt.states.drac¶

Management of Dell DRAC The DRAC module is used to create and manage DRAC cards on Dell servers Ensure the user damian is present
Ensure the user damian does not exist
Ensure DRAC network is in a consistent state

salt.states.elasticsearch_index¶

State module to manage Elasticsearch indices New in version 2015.8.0.

salt.states.elasticsearch_index_template¶

State module to manage Elasticsearch index templates New in version 2015.8.0.

salt.states.environ¶

Support for getting and setting the environment variables of the current salt process.

salt.states.eselect¶

Management of Gentoo configuration using eselect¶

A state module to manage Gentoo configuration via eselect

salt.states.etcd_mod¶

Manage etcd Keys¶

New in version 2015.8.0.
This state module supports setting and removing keys from etcd.

Configuration¶

To work with an etcd server you must configure an etcd profile. The etcd config can be set in either the Salt Minion configuration file or in pillar:
It is technically possible to configure etcd without using a profile, but this is not considered to be a best practice, especially when multiple etcd servers or clusters are available.
NOTE:

Available Functions¶

salt.states.esxi¶

Manage VMware ESXi Hosts. New in version 2015.8.4.

Dependencies¶

pyVmomi¶

PyVmomi can be installed via pip:
NOTE:
Based on the note above, to install an earlier version of pyVmomi than the version currently listed in PyPi, run the following:
The 5.5.0.2014.1.1 is a known stable version that this original ESXi State Module was developed against.

ESXCLI¶

Currently, about a third of the functions used in the vSphere Execution Module require the ESXCLI package be installed on the machine running the Proxy Minion process. The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware provides vCLI package installation instructions for vSphere 5.5 and vSphere 6.0. Once all of the required dependencies are in place and the vCLI package is installed, you can check to see if you can connect to your ESXi host or vCenter server by running the following command:
If the connection was successful, ESXCLI was successfully installed on your system. You should see output related to the ESXi host's syslog configuration. NOTE:

About¶

This state module was written to be used in conjunction with Salt's ESXi Proxy Minion. For a tutorial on how to use Salt's ESXi Proxy Minion, please refer to the ESXi Proxy Minion Tutorial for configuration examples, dependency installation instructions, how to run remote execution functions against ESXi hosts via a Salt Proxy Minion, and a larger state example.

salt.states.event¶

Send events through Salt's event system during state runs

salt.states.file¶

Operations on regular files, special files, directories, and symlinks¶

Salt States can aggressively manipulate files on a system. There are a number of ways in which files can be managed. Regular files can be enforced with the file.managed state. This state downloads files from the salt master and places them on the target system. Managed files can be rendered as a jinja, mako, or wempy template, adding a dynamic component to file management. An example of file.managed which makes use of the jinja templating system would look like this:
It is also possible to use the py renderer as a templating option. The template would be a Python script which would need to contain a function called run(), which returns a string. All arguments to the state will be made available to the Python script as globals. The returned string will be the contents of the managed file. For example:
NOTE:
If using a template, any user-defined template variables in the file defined in source must be passed in using the defaults and/or context arguments. The general best practice is to place default values in defaults, with conditional overrides going into context, as seen above. The template will receive a variable custom_var, which would be accessed in the template using {{ custom_var }}. If the operating system is Ubuntu, the value of the variable custom_var would be override, otherwise it is the default default value The source parameter can be specified as a list. If this is done, then the first file to be matched will be the one that is used. This allows you to have a default file on which to fall back if the desired file does not exist on the salt fileserver. Here's an example:
NOTE:
The source parameter can also specify a file in another Salt environment. In this example foo.conf in the dev environment will be used instead.
WARNING:
The names parameter, which is part of the state compiler, can be used to expand the contents of a single state declaration into multiple, single state declarations. Each item in the names list receives its own individual state name and is converted into its own low-data structure. This is a convenient way to manage several files with similar attributes. There is more documentation about this feature in the Names declaration section of the
Special files can be managed via the mknod function. This function will create and enforce the permissions on a special file. The function supports the creation of character devices, block devices, and FIFO pipes. The function will create the directory structure up to the special file if it is needed on the minion. The function will not overwrite or operate on (change major/minor numbers) existing special files with the exception of user, group, and permissions. In most cases the creation of some special files require root permissions on the minion. This would require that the minion to be run as the root user. Here is an example of a character device:
Here is an example of a block device:
Here is an example of a fifo pipe:
Directories can be managed via the directory function. This function can create and enforce the permissions on a directory. A directory statement will look like this:
If you need to enforce user and/or group ownership or permissions recursively on the directory's contents, you can do so by adding a recurse directive:
As a default, mode will resolve to dir_mode and file_mode, to specify both directory and file permissions, use this form:
Symlinks can be easily created; the symlink function is very simple and only takes a few arguments:
Recursive directory management can also be set via the recurse function. Recursive directory management allows for a directory on the salt master to be recursively copied down to the minion. This is a great tool for deploying large code and configuration systems. A state using recurse would look something like this:
A more complex recurse example:
Retention scheduling can be applied to manage contents of backup directories. For example:

salt.states.firewall module¶

State to check firewall configurations

salt.states.firewalld¶

Management of firewalld New in version 2015.8.0. The following example applies changes to the public zone, blocks echo-reply and echo-request packets, does not set the zone to be the default, enables masquerading, and allows ports 22/tcp and 25/tcp. It will be applied permanently and directly before restart/reload.
The following example applies changes to the public zone, enables masquerading and configures port forwarding TCP traffic from port 22 to 2222, and forwards TCP traffic from port 80 to 443 at 192.168.0.1.
The following example binds the public zone to interface eth0 and to all packets coming from the 192.168.1.0/24 subnet. It also removes the zone from all other interfaces or sources.
Here, we define a new service that encompasses TCP ports 4505 4506:
To make this new service available in a zone, the following can be used, which would allow access to the salt master from the 10.0.0.0/8 subnet:

salt.states.gem¶

Installation of Ruby modules packaged as gems¶

A state module to manage rubygems. Gems can be set up to be installed or removed. This module will use RVM or rbenv if they are installed. In that case, you can specify what ruby version and gemset to target.

salt.states.git¶

States to manage git repositories and git configuration IMPORTANT:
Changed in version 2015.8.8: This state module now requires git 1.6.5 (released 10 October 2009) or newer.

salt.states.github module¶

Github User State Module New in version 2016.3.0.. This state is used to ensure presence of users in the Organization.

salt.states.glance¶

Managing Images in OpenStack Glance¶

salt.states.glusterfs¶

Manage GlusterFS pool.

salt.states.gnomedesktop¶

Configuration of the GNOME desktop¶

Control the GNOME settings

salt.states.gpg module¶

Management of the GPG keychains¶

New in version 2016.3.0.

salt.states.grafana¶

Manage Grafana Dashboards This module uses elasticsearch, which can be installed via package, or pip. You can specify elasticsearch hosts directly to the module, or you can use an elasticsearch profile via pillars:

The behavior of this module is to create dashboards if they do not exist, to add rows if they do not exist in existing dashboards, and to update rows if they exist in dashboards. The module will not manage rows that are not defined, allowing users to manage their own custom rows.

salt.states.grafana_dashboard module¶

Manage Grafana v2.0 Dashboards New in version 2016.3.0.

The behavior of this module is to create dashboards if they do not exist, to add rows if they do not exist in existing dashboards, and to update rows if they exist in dashboards. The module will not manage rows that are not defined, allowing users to manage their own custom rows.

salt.states.grafana_datasource module¶

Manage Grafana v2.0 data sources New in version 2016.3.0.

salt.states.grains¶

Manage grains on the minion¶

This state allows for grains to be set. Grains set or altered this way are stored in the 'grains' file on the minions, by default at: /etc/salt/grains Note: This does NOT override any grains set in the minion file.

salt.states.group¶

Management of user groups¶

The group module is used to create and manage unix group settings, groups can be either present or absent:

salt.states.hg¶

Interaction with Mercurial repositories¶

Before using hg over ssh, make sure the remote host fingerprint already exists in ~/.ssh/known_hosts, and the remote host has this host's public key.

salt.states.hipchat¶

Send a message to Hipchat¶

This state is useful for sending messages to Hipchat during state runs. The property api_url is optional. By defaul will use the public HipChat API at https://api.hipchat.com New in version 2015.5.0.
The api key can be specified in the master or minion configuration like below:

salt.states.host¶

Management of addresses and names in hosts file¶

The /etc/hosts file can be managed to contain definitions for specific hosts:
Or using the names directive, you can put several names for the same IP. (Do not try one name with space-separated values).
NOTE:

You can replace all existing names for a particular IP address:
Or delete all existing names for an address:

salt.states.htpasswd¶

Support for htpasswd module. Requires the apache2-utils package for Debian-based distros. New in version 2014.7.0.

salt.states.http¶

HTTP monitoring states Perform an HTTP query and statefully return the result New in version 2015.5.0.

salt.states.ifttt¶

Trigger an event in IFTTT¶

This state is useful for trigging events in IFTTT. New in version 2015.8.0.
The api key can be specified in the master or minion configuration like below:

salt.states.incron¶

Management of incron, the inotify cron¶

The incron state module allows for user incrontabs to be cleanly managed. Incron declarations require a number of parameters. The parameters needed to be declared: path, mask, and cmd. The user whose incrontab is to be edited also needs to be defined. When making changes to an existing incron job, the path declaration is the unique factor, so if an existing cron that looks like this:
Is changed to this:
Then the existing cron will be updated, but if the cron command is changed, then a new cron job will be added to the user's crontab. New in version 0.17.0.

salt.states.influxdb_database¶

Management of Influxdb databases¶

(compatible with InfluxDB version 0.9+)

salt.states.influxdb_user¶

Management of InfluxDB users¶

(compatible with InfluxDB version 0.9+)

salt.states.infoblox module¶

states for infoblox stuff ensures a record is either present or absent in an Infoblox DNS system New in version 2016.3.0.

salt.states.ini_manage¶

Manage ini files¶

salt.states.ipmi¶

Manage IPMI devices over LAN¶

The following configuration defaults can be defined in the minion, master config or pillar:
Every call can override the config defaults:

salt.states.ipset¶

Management of ipsets¶

This is an ipset-specific module designed to manage IPSets for use in IPTables Firewalls.

salt.states.iptables¶

Management of iptables¶

This is an iptables-specific module designed to manage Linux firewalls. It is expected that this state module, and other system-specific firewall states, may at some point be deprecated in favor of a more generic firewall state.
NOTE:

salt.states.jboss7¶

Manage JBoss 7 Application Server via CLI interface New in version 2015.5.0. This state uses the jboss-cli.sh script from a JBoss or Wildfly installation and parses its output to determine the execution result. In order to run each state, a jboss_config dictionary with the following properties must be passed:
If the controller doesn't require a password, then the cli_user and cli_password parameters are optional. Since same dictionary with configuration will be used in all the states, it may be more convenient to move JBoss configuration and other properties to the pillar. Example of application deployment from local filesystem:
For the sake of brevity, examples for each state assume that jboss_config is contained in the pillar.

salt.states.jenkins module¶

Management of Jenkins¶

New in version 2016.3.0.

salt.states.junos module¶

State modules to interact with Junos devices.¶

These modules call the corresponding execution modules. Refer to junos for further information.

salt.states.k8s¶

Manage Kubernetes New in version 2016.3.0.

salt.states.kapacitor module¶

Kapacitor state module.
New in version 2016.11.0.

salt.states.keyboard¶

Management of keyboard layouts¶

The keyboard layout can be managed for the system:
Or it can be managed for XOrg:

salt.states.keystone¶

Management of Keystone users¶

salt.states.kmod¶

Loading and unloading of kernel modules¶

The Kernel modules on a system can be managed cleanly with the kmod state module:
Multiple modules can be specified for both kmod.present and kmod.absent.

salt.states.layman¶

Management of Gentoo Overlays using layman¶

A state module to manage Gentoo package overlays via layman

salt.states.ldap¶

Manage entries in an LDAP database¶

New in version 2016.3.0. The states.ldap state module allows you to manage LDAP entries and their attributes.

salt.states.linux_acl¶

Linux File Access Control Lists Ensure a Linux ACL is present
Ensure a Linux ACL does not exist

salt.states.locale¶

Management of languages/locales¶

Manage the available locales and the system default:

salt.states.lvm¶

Management of Linux logical volumes¶

A state module to manage LVMs

salt.states.lvs_server¶

Management of LVS (Linux Virtual Server) Real Server¶

salt.states.lvs_service¶

Management of LVS (Linux Virtual Server) Service¶

salt.states.lxc¶

Manage Linux Containers¶

Container Creation Arguments
options

salt.states.mac_assistive module¶

Allows you to manage assistive access on macOS minions with 10.9+¶

Install, enable and disable assistive access on macOS minions

salt.states.mac_defaults module¶

Writing/reading defaults from a macOS minion¶

salt.states.mac_keychain module¶

Installing of certificates to the keychain¶

Install certificats to the macOS keychain

salt.states.mac_package module¶

Installing of mac pkg files¶

Install any kind of pkg, dmg or app file on macOS:
.*7B91b

salt.states.mac_xattr module¶

Allows you to manage extended attributes on files or directories¶

Install, enable and disable assistive access on macOS minions

salt.states.makeconf¶

Management of Gentoo make.conf¶

A state module to manage Gentoo's make.conf file

salt.states.marathon_app module¶

Configure Marathon apps via a salt proxy.
New in version 2015.8.2.

salt.states.mdadm¶

Managing software RAID with mdadm¶

A state module for creating or destroying software RAID devices.

salt.states.memcached¶

States for Management of Memcached Keys¶

New in version 2014.1.0.

salt.states.modjk¶

State to control Apache modjk

salt.states.modjk_worker¶

Manage modjk workers¶

Send commands to a modjk load balancer via the peer system. This module can be used with the prereq requisite to remove/add the worker from the load balancer before deploying/restarting service. Mandatory Settings:

salt.states.module¶

Execution of Salt modules from within states¶

These states allow individual execution module calls to be made via states. To call a single module function use a module.run state:
Note that this example is probably unnecessary to use in practice, since the mine_functions and mine_interval config parameters can be used to schedule updates for the mine (see here for more info). It is sometimes desirable to trigger a function call after a state is executed, for this the module.wait state can be used:
All arguments that the module state does not consume are passed through to the execution module function being executed:
Due to how the state system works, if a module function accepts an argument called, name, then m_name must be used to specify that argument, to avoid a collision with the name argument. Here is a list of keywords hidden by the state system, which must be prefixed with m_:
For example:
Note that some modules read all or some of the arguments from a list of keyword arguments. For example:

salt.states.mongodb_database¶

Management of Mongodb databases Only deletion is supported, creation doesn't make sense and can be done using mongodb_user.present

salt.states.mongodb_user¶

Management of Mongodb users¶

NOTE:

salt.states.monit¶

Monit state¶

Manage monit states

NOTE:

salt.states.mount¶

Mounting of filesystems¶

Mount any type of mountable filesystem with the mounted function:

salt.states.mysql_database¶

Management of MySQL databases (schemas)¶

The mysql_database module is used to create and manage MySQL databases. Databases can be set as either absent or present.

salt.states.mysql_grants¶

Management of MySQL grants (user permissions)¶

The mysql_grants module is used to grant and revoke MySQL permissions. The name you pass in purely symbolic and does not have anything to do with the grant itself. The database parameter needs to specify a 'priv_level' in the same specification as defined in the MySQL documentation:
This state is not able to set password for the permission from the specified host. See salt.states.mysql_user for further instructions.

salt.states.mysql_query¶

Execution of MySQL queries¶

New in version 2014.7.0.
The mysql_query module is used to execute queries on MySQL databases. Its output may be stored in a file or in a grain.

salt.states.mysql_user¶

Management of MySQL users¶

New in version 0.16.2: Authentication overrides have been added. The MySQL authentication information specified in the minion config file can be overridden in states using the following arguments: connection_host, connection_port, connection_user, connection_pass, connection_db, connection_unix_socket, connection_default_file and connection_charset.
This state is not able to grant permissions for the user. See salt.states.mysql_grants for further instructions.

salt.states.netntp¶

Network NTP¶

Manage the configuration of NTP peers and servers on the network devices through the NAPALM proxy.

Dependencies¶

(in case the user does not configure the peers/servers using their IP addresses) - NAPALM proxy minion - NTP operational and configuration management module

salt.states.netsnmp module¶

Network SNMP¶

Manage the SNMP configuration on network devices.

Dependencies¶

salt.states.netusers module¶

Network Users¶

Manage the users configuration on network devices via the NAPALM proxy.

Dependencies¶

New in version 2016.11.0.

salt.states.network¶

Configuration of network interfaces¶

The network module is used to create and manage network settings, interfaces can be set as either managed or ignored. By default all interfaces are ignored unless specified. NOTE:

NOTE:

salt.states.nftables¶

Management of nftables¶

This is an nftables-specific module designed to manage Linux firewalls. It is expected that this state module, and other system-specific firewall states, may at some point be deprecated in favor of a more generic firewall state.

salt.states.npm¶

Installation of NPM Packages¶

These states manage the installed packages for node.js using the Node Package Manager (npm). Note that npm must be installed for these states to be available, so npm states should include a requisite to a pkg.installed state for the package which provides npm (simply npm in most cases). Example:

salt.states.ntp¶

Management of NTP servers¶

New in version 2014.1.0. This state is used to manage NTP servers. Currently only Windows is supported.

salt.states.nxos module¶

State module for Cisco NX OS Switches Proxy minions For documentation on setting up the nxos proxy minion look in the documentation for salt.proxy.nxos.

salt.states.openstack_config¶

Manage OpenStack configuration file settings.

salt.states.openvswitch_bridge module¶

Management of Open vSwitch bridges.

salt.states.openvswitch_port module¶

Management of Open vSwitch ports.

salt.states.pagerduty¶

Create an Event in PagerDuty¶

New in version 2014.1.0. This state is useful for creating events on the PagerDuty service during state runs.

salt.states.pagerduty_escalation_policy¶

Manage PagerDuty escalation policies. Schedules and users can be referenced by pagerduty ID, or by name, or by email address. For example:

salt.states.pagerduty_schedule¶

Manage PagerDuty schedules. Example.INDENT 0.0

salt.states.pagerduty_service¶

Manage PagerDuty services Escalation policies can be referenced by pagerduty ID or by namea. For example:

salt.states.pagerduty_user¶

Manage PagerDuty users. Example.INDENT 0.0

salt.states.pcs module¶

Management of Pacemaker/Corosync clusters with PCS¶

A state module to manage Pacemaker/Corosync clusters with the Pacemaker/Corosync configuration system(PCS) New in version 2016.110.
Walkthrough of a complete pcs cluster setup:
At first the cibfile must be created:
Then the cibfile can be modified by creating resources (creating only 1 resource for demonstration, see also 7.):
After modifying the cibfile it can be pushed to the live CIB in the cluster:
Create a cluster from scratch:
New in version 2016.3.0.

salt.states.pecl¶

Installation of PHP Extensions Using pecl¶

These states manage the installed pecl extensions. Note that php-pear must be installed for these states to be available, so pecl states should include a requisite to a pkg.installed state for the package which provides pecl ( php-pear in most cases). Example:

salt.states.pip_state¶

Installation of Python Packages Using pip¶

These states manage system installed python packages. Note that pip must be installed for these states to be available, so pip states should include a requisite to a pkg.installed state for the package which provides pip ( python-pip in most cases). Example:

salt.states.pkg¶

Installation of packages using OS package managers such as yum or apt-get¶

NOTE:
Salt can manage software packages via the pkg state module, packages can be set up to be installed, latest, removed and purged. Package management declarations are typically rather simple:
A more involved example involves pulling from a custom repository.
Multiple packages can also be installed with the use of the pkgs state module
WARNING:

salt.states.pkgbuild¶

The pkgbuild state is the front of Salt package building backend. It automatically builds DEB and RPM packages from specified sources New in version 2015.8.0.

salt.states.pkgng¶

Manage package remote repo using FreeBSD pkgng¶

Salt can manage the URL pkgng pulls packages from. ATM the state and module are small so use cases are typically rather simple:

salt.states.pkgrepo¶

Management of APT/YUM package repos¶

Package repositories for APT-based and YUM-based distros can be managed with these states. Here is some example SLS:




NOTE:

salt.states.portage_config¶

Management of Portage package configuration on Gentoo¶

A state module to manage Portage configuration on Gentoo

salt.states.ports¶

Manage software from FreeBSD ports New in version 2014.1.0. NOTE:

salt.states.postgres_cluster module¶

Management of PostgreSQL clusters¶

The postgres_cluster state module is used to manage PostgreSQL clusters. Clusters can be set as either absent or present

salt.states.postgres_database¶

Management of PostgreSQL databases¶

The postgres_database module is used to create and manage Postgres databases. Databases can be set as either absent or present

salt.states.postgres_extension¶

Management of PostgreSQL extensions¶

A module used to install and manage PostgreSQL extensions.
New in version 2014.7.0.

salt.states.postgres_group¶

Management of PostgreSQL groups (roles)¶

The postgres_group module is used to create and manage Postgres groups.

salt.states.postgres_initdb¶

Initialization of PostgreSQL data directory¶

The postgres_initdb module is used to initialize the postgresql data directory. New in version 2016.3.0.

salt.states.postgres_language¶

Management of PostgreSQL languages¶

The postgres_language module is used to create and manage Postgres languages. Languages can be set as either absent or present New in version 2016.3.0.

salt.states.postgres_privileges¶

Management of PostgreSQL Privileges¶

The postgres_privileges module is used to manage Postgres privileges. Privileges can be set as either absent or present. Privileges can be set on the following database object types:
Setting the grant option is supported as well. New in version 2016.3.0.

salt.states.postgres_schema¶

Management of PostgreSQL schemas¶

The postgres_schemas module is used to create and manage Postgres schemas.

salt.states.postgres_tablespace¶

Management of PostgreSQL tablespace¶

A module used to create and manage PostgreSQL tablespaces.
New in version 2015.8.0.

salt.states.postgres_user¶

Management of PostgreSQL users (roles)¶

The postgres_users module is used to create and manage Postgres users.

salt.states.powerpath¶

Powerpath configuration support¶

Allows configuration of EMC Powerpath. Currently only addition/deletion of licenses is supported.

salt.states.probes¶

Network Probes¶

Configure RPM (JunOS)/SLA (Cisco) probes on the device via NAPALM proxy.

Dependencies¶

salt.states.process¶

Process Management¶

Ensure a process matching a given pattern is absent.

salt.states.pushover¶

Send a message to PushOver¶

This state is useful for sending messages to PushOver during state runs. New in version 2015.5.0.
The api key can be specified in the master or minion configuration like below:

salt.states.pyenv¶

Managing python installations with pyenv¶

This module is used to install and manage python installations with pyenv. Different versions of python can be installed, and uninstalled. pyenv will be installed automatically the first time it is needed and can be updated later. This module will not automatically install packages which pyenv will need to compile the versions of python. If pyenv is run as the root user then it will be installed to /usr/local/pyenv, otherwise it will be installed to the users ~/.pyenv directory. To make pyenv available in the shell you may need to add the pyenv/shims and pyenv/bin directories to the users PATH. If you are installing as root and want other users to be able to access pyenv then you will need to add pyenv_ROOT to their environment. This is how a state configuration could look like:
NOTE:

salt.states.pyrax_queues¶

Manage Rackspace Queues¶

New in version 2015.5.0. Create and destroy Rackspace queues. Be aware that this interacts with Rackspace's services, and so may incur charges. This module uses pyrax, which can be installed via package, or pip. This module is greatly inspired by boto_* modules from SaltStack code source.

salt.states.quota¶

Management of POSIX Quotas¶

The quota can be managed for the system:

salt.states.rabbitmq_cluster¶

Manage RabbitMQ Clusters¶

Example:

salt.states.rabbitmq_plugin¶

Manage RabbitMQ Plugins¶

New in version 2014.1.0. Example:

salt.states.rabbitmq_policy¶

Manage RabbitMQ Policies¶

Example:

salt.states.rabbitmq_user¶

Manage RabbitMQ Users¶

Example:

salt.states.rabbitmq_vhost¶

Manage RabbitMQ Virtual Hosts¶

Example:

salt.states.rbenv¶

Managing Ruby installations with rbenv¶

This module is used to install and manage ruby installations with rbenv and the ruby-build plugin. Different versions of ruby can be installed, and uninstalled. Rbenv will be installed automatically the first time it is needed and can be updated later. This module will not automatically install packages which rbenv will need to compile the versions of ruby. If your version of ruby fails to install, refer to the ruby-build documentation to verify you are not missing any dependencies: https://github.com/sstephenson/ruby-build/wiki If rbenv is run as the root user then it will be installed to /usr/local/rbenv, otherwise it will be installed to the users ~/.rbenv directory. To make rbenv available in the shell you may need to add the rbenv/shims and rbenv/bin directories to the users PATH. If you are installing as root and want other users to be able to access rbenv then you will need to add RBENV_ROOT to their environment. The following state configuration demonstrates how to install Ruby 1.9.x and 2.x using rbenv on Ubuntu/Debian:

salt.states.rdp¶

Manage RDP Service on Windows servers

salt.states.redismod¶

Management of Redis server¶

New in version 2014.7.0.

The redis server information specified in the minion config file can be overridden in states using the following arguments: host, post, db, password.

salt.states.reg¶

Manage the Windows registry¶

Many python developers think of registry keys as if they were python keys in a dictionary which is not the case. The windows registry is broken down into the following components:

Hives¶

This is the top level of the registry. They all begin with HKEY. - HKEY_CLASSES_ROOT (HKCR) - HKEY_CURRENT_USER(HKCU) - HKEY_LOCAL MACHINE (HKLM) - HKEY_USER (HKU) - HKEY_CURRENT_CONFIG

Keys¶

Hives contain keys. These are basically the folders beneath the hives. They can contain any number of subkeys.

Values or Entries¶

Values or Entries are the name/data pairs beneath the keys and subkeys. All keys have a default name/data pair. It is usually "(Default)"="(value not set)". The actual value for the name and the date is Null. The registry editor will display "(Default)" and "(value not set)". The following example is taken from the windows startup portion of the registry: ` [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run] "RTHDVCPL"="\"C:\\Program Files\\Realtek\\Audio\\HDA\\RtkNGUI64.exe\" -s" "NvBackend"="\"C:\\Program Files (x86)\\NVIDIA Corporation\\Update Core\\NvBackend.exe\"" "BTMTrayAgent"="rundll32.exe \"C:\\Program Files (x86)\\Intel\\Bluetooth\\btmshellex.dll\",TrayApp" ` In this example these are the values for each: Hive: HKEY_LOCAL_MACHINE Key and subkeys: SOFTWAREMicrosoftWindowsCurrentVersionRun

salt.states.rsync¶

State to synchronize files and directories with rsync. New in version 2016.3.0.

salt.states.rvm¶

Managing Ruby installations and gemsets with Ruby Version Manager (RVM)¶

This module is used to install and manage ruby installations and gemsets with RVM, the Ruby Version Manager. Different versions of ruby can be installed and gemsets created. RVM itself will be installed automatically if it's not present. This module will not automatically install packages that RVM depends on or ones that are needed to build ruby. If you want to run RVM as an unprivileged user (recommended) you will have to create this user yourself. This is how a state configuration could look like:

salt.states.salt_proxy module¶

Salt proxy state New in version 2015.8.2. State to deploy and run salt-proxy processes on a minion. Set up pillar data for your proxies per the documentation. Run the state as below ..code-block:: yaml
This state will configure the salt proxy settings within /etc/salt/proxy (if /etc/salt/proxy doesn't exists) and start the salt-proxy process (default true), if it isn't already running.

salt.states.saltmod¶

Control the Salt command interface¶

This state is intended for use from the Salt Master. It provides access to sending commands down to minions as well as access to executing master-side modules. These state functions wrap Salt's Python API.
SEE ALSO:

salt.states.schedule¶

Management of the Salt scheduler¶

salt.states.selinux¶

Management of SELinux rules¶

If SELinux is available for the running system, the mode can be managed and booleans can be set.
NOTE:

salt.states.serverdensity_device¶

Monitor Server with Server Density¶

New in version 2014.7.0. Server Density Is a hosted monitoring service. WARNING:
NOTE:
NOTE:
Example:

salt.states.service¶

Starting or restarting of services and daemons¶

Services are defined as system daemons typically started with system init or rc scripts. The service state uses whichever service module that is loaded on the minion with the virtualname of service. Services can be defined as running or dead. If you need to know if your init system is supported, see the list of supported service modules for your desired init system (systemd, sysvinit, launchctl, etc.). Note that Salt's service execution module, and therefore this service state, uses OS grains to ascertain which service module should be loaded and used to execute service functions. As existing distributions change init systems or new distributions are created, OS detection can sometimes be incomplete. If your service states are running into trouble with init system detection, please see the Overriding Virtual Module Providers section of Salt's module documentation to work around possible errors. NOTE:

The service can also be set to be started at runtime via the enable option:
By default if a service is triggered to refresh due to a watch statement the service is by default restarted. If the desired behavior is to reload the service, then set the reload value to True:
NOTE:

salt.states.slack¶

Send a message to Slack¶

This state is useful for sending messages to Slack during state runs. New in version 2015.5.0.
The api key can be specified in the master or minion configuration like below:

salt.states.smartos¶

Management of SmartOS Standalone Compute Nodes
New in version 2016.3.0.
NOTE:

salt.states.smtp¶

Sending Messages via SMTP¶

New in version 2014.7.0. This state is useful for firing messages during state runs, using the SMTP protocol

salt.states.snapper module¶

Managing implicit state and baselines using snapshots¶

New in version 2016.11.0. Salt can manage state against explicitly defined state, for example if your minion state is defined by:
If someone modifies this file, the next application of the highstate will allow the admin to correct this deviation and the file will be corrected. Now, what happens if somebody creates a file /etc/new_config_file and deletes /etc/important_config_file? Unless you have a explicit rule, this change will go unnoticed. The snapper state module allows you to manage state implicitly, in addition to explicit rules, in order to define a baseline and iterate with explicit rules as they show that they work in production. The workflow is: once you have a working and audited system, you would create your baseline snapshot (eg. with salt tgt snapper.create_snapshot) and define in your state this baseline using the identifier of the snapshot (in this case: 20):
Baseline snapshots can be also referenced by tag. Most recent baseline snapshot is used in case of multiple snapshots with the same tag:
If you have this state, and you haven't done changes to the system since the snapshot, and you add a user, the state will show you the changes (including full diffs) to /etc/passwd, /etc/shadow, etc if you call it with test=True and will undo all changes if you call it without. This allows you to add more explicit state knowing that you are starting from a very well defined state, and that you can audit any change that is not part of your explicit configuration. So after you made this your state, you decided to introduce a change in your configuration:
The change in /etc/hosts will be done after any other change that deviates from the specified snapshot are reverted. This could be for example, modifications to the /etc/passwd file or changes in the /etc/hosts that could render your the hosts_entry rule void or dangerous. Once you take a new snapshot and you update the baseline snapshot number to include the change in /etc/hosts the hosts_entry rule will basically do nothing. You are free to leave it there for documentation, to ensure that the change is made in case the snapshot is wrong, but if you remove anything that comes after the snapper.baseline_snapshot as it will have no effect; by the moment the state is evaluated, the baseline state was already applied and include this change. WARNING:
WARNING:

salt.states.splunk¶

Splunk User State Module New in version 2016.3.0.. This state is used to ensure presence of users in splunk.

salt.states.splunk_search¶

Splunk Search State Module New in version 2015.5.0. This state is used to ensure presence of splunk searches.

salt.states.sqlite3¶

Management of SQLite3 databases¶

New in version 2016.3.0. The sqlite3 module is used to create and manage sqlite3 databases and execute queries Here is an example of creating a table using sql statements:
Here is an example of creating a table using yaml/jinja instead of sql:
Here is an example of making sure a table is absent:
Sometimes you would to have specific data in tables to be used by other services Here is an example of making sure rows with specific data exist:
Here is an example of removing a row from a table:

salt.states.ssh_auth¶

Control of entries in SSH authorized_key files¶

The information stored in a user's SSH authorized key file can be easily controlled via the ssh_auth state. Defaults can be set by the enc, options, and comment keys. These defaults can be overridden by including them in the name. Since the YAML specification limits the length of simple keys to 1024 characters, and since SSH keys are often longer than that, you may have to use a YAML 'explicit key', as demonstrated in the second example below.

salt.states.ssh_known_hosts¶

Control of SSH known_hosts entries¶

Manage the information stored in the known_hosts files.

salt.states.stateconf¶

Stateconf System¶

The stateconf system is intended for use only with the stateconf renderer. This State module presents the set function. This function does not execute any functionality, but is used to interact with the stateconf renderer.

salt.states.status¶

Minion status monitoring Maps to the status execution module.

salt.states.stormpath_account¶

Support for Stormpath. New in version 2015.8.0.

salt.states.supervisord¶

Interaction with the Supervisor daemon¶

salt.states.svn¶

Manage SVN repositories¶

Manage repository checkouts via the svn vcs system. Note that subversion must be installed for these states to be available, so svn states should include a requisite to a pkg.installed state for the package which provides subversion ( subversion in most cases). Example:

salt.states.sysctl¶

Configuration of the Linux kernel using sysctl¶

Control the kernel sysctl system.

salt.states.syslog_ng¶

State module for syslog_ng¶

Details¶

The service module is not available on all system, so this module includes syslog_ng.reloaded, syslog_ng.stopped, and syslog_ng.started functions. If the service module is available on the computers, users should use that. Users can generate syslog-ng configuration with syslog_ng.config function. For more information see syslog-ng state usage.

Syslog-ng configuration file format¶

The syntax of a configuration snippet in syslog-ng.conf:
These constructions are also called statements. There are options inside of them:
You can find more information about syslog-ng's configuration syntax in the Syslog-ng Admin guide: http://www.balabit.com/sites/default/files/documents/syslog-ng-ose-3.5-guides/en/syslog-ng-ose-v3.5-guide-admin/html-single/index.html#syslog-ng.conf.5

salt.states.sysrc¶

salt.states.telemetry_alert¶

New in version 2016.3.0..

Manage Telemetry alert configurations¶

Create, Update and destroy Mongo Telemetry alert configurations. This module uses requests, which can be installed via package, or pip. This module accepts explicit credential (telemetry api key) or can also read api key credentials from a pillar. Example:

salt.states.test¶

Test States¶

salt.states.timezone¶

Management of timezones¶

The timezone can be managed for the system:
The system and the hardware clock are not necessarily set to the same time. By default, the hardware clock is set to localtime, meaning it is set to the same time as the system clock. If utc is set to True, then the hardware clock will be set to UTC, and the system clock will be an offset of that.
The Ubuntu community documentation contains an explanation of this setting, as it applies to systems that dual-boot with Windows. This is explained in greater detail here.

salt.states.tls¶

Enforce state for SSL/TLS¶

salt.states.tomcat¶

Manage Apache Tomcat web applications¶

NOTE:
The following grains/pillars must be set for communication with Tomcat Manager to work:

Configuring Tomcat Manager¶

To manage webapps via the Tomcat Manager, you'll need to configure a valid user in the file conf/tomcat-users.xml. conf/tomcat-users.xml.INDENT 0.0

Notes.INDENT 0.0

•

Using multiple versions (aka. parallel deployments) on the same context path is not supported.

•

More information about the Tomcat Manager: http://tomcat.apache.org/tomcat-7.0-doc/manager-howto.html

•

If you use only this module for deployments you might want to restrict access to the manager so it's only accessible via localhost. For more info: http://tomcat.apache.org/tomcat-7.0-doc/manager-howto.html#Configuring_Manager_Application_Access

•

salt.states.trafficserver¶

Control Apache Traffic Server¶

New in version 2015.8.0.

salt.states.tuned¶

Interface to Red Hat tuned-adm module

salt.states.uptime¶

Monitor Web Server with Uptime¶

Uptime is an open source remote monitoring application using Node.js, MongoDB, and Twitter Bootstrap. WARNING:
NOTE:
Example:

salt.states.user¶

Management of user accounts¶

The user module is used to create and manage user settings, users can be set as either absent or present

salt.states.vbox_guest¶

VirtualBox Guest Additions installer state

salt.states.victorops¶

Create an Event in VictorOps¶

New in version 2015.8.0. This state is useful for creating events on the VictorOps service during state runs.

salt.states.virt module¶

Manage virt¶

For the key certificate this state uses the external pillar in the master to call for the generation and signing of certificates for systems running libvirt:

salt.states.virtualenv¶

Setup of Python virtualenv sandboxes. New in version 0.17.0.

salt.states.win_certutil module¶

Installing of certificates to the Windows Certificate Manager¶

Install certificates to the Windows Certificate Manager

salt.states.win_dacl¶

Windows Object Access Control Lists

salt.states.win_dism module¶

Installing of Windows features using DISM¶

Install windows features/capabilties with DISM

salt.states.win_dns_client¶

Module for configuring DNS Client on Windows systems

salt.states.win_firewall¶

State for configuring Windows Firewall

salt.states.win_iis module¶

Microsoft IIS site management This module provides the ability to add/remove websites and application pools from Microsoft IIS. New in version 2016.3.0.

salt.states.win_license module¶

Installation and activation of windows licenses¶

Install and activate windows licenses

salt.states.win_network¶

Configuration of network interfaces on Windows hosts¶

New in version 2014.1.0. This module provides the network state(s) on Windows hosts. DNS servers, IP addresses and default gateways can currently be managed. Below is an example of the configuration for an interface that uses DHCP for both DNS servers and IP addresses:
NOTE:
Static DNS and IP addresses can be configured like so:
NOTE:
Optionally, if you are setting a static IP address, you can also specify the default gateway using the gateway parameter:

salt.states.win_path¶

Manage the Windows System PATH

salt.states.win_powercfg¶

This module allows you to control the power settings of a windows minion via powercfg. New in version 2015.8.0.

salt.states.win_servermanager¶

Manage Windows features via the ServerManager powershell module

salt.states.win_smtp_server module¶

Module for managing IIS SMTP server configuration on Windows servers.

salt.states.win_system¶

Management of Windows system information¶

New in version 2014.1.0. This state is used to manage system information such as the computer name and description.

salt.states.win_update¶

Management of the windows update agent¶

New in version 2014.7.0. Set windows updates to run by category. Default behavior is to install all updates that do not require user interaction to complete. Optionally set category to a category of your choice to only install certain updates. Default is to set to install all available updates. The following example will install all Security and Critical Updates, and download but not install standard updates.
You can also specify a number of features about the update to have a fine grain approach to specific types of updates. These are the following features/states of updates available for configuring:
The following example installs all driver updates that don't require a reboot:
To just update your windows machine, add this your sls:

salt.states.winrepo¶

Manage Windows Package Repository

salt.states.x509¶

Manage X509 Certificates New in version 2015.8.0.
This module can enable managing a complete PKI infrastructure including creating private keys, CA's, certificates and CRLs. It includes the ability to generate a private key on a server, and have the corresponding public key sent to a remote CA to create a CA signed certificate. This can be done in a secure manner, where private keys are always generated locally and never moved across the network. Here is a simple example scenario. In this example ca is the ca server, and www is a web server that needs a certificate signed by ca. For remote signing, peers must be permitted to remotely call the sign_remote_certificate function. /etc/salt/master.d/peer.conf
/srv/salt/top.sls
This state creates the CA key, certificate and signing policy. It also publishes the certificate to the mine where it can be easily retrieved by other minions. /srv/salt/ca.sls
The signing policy defines properties that override any property requested or included in a CRL. It also can define a restricted list of minons which are allowed to remotely invoke this signing policy. /srv/salt/signing_policies.conf
This state will instruct all minions to trust certificates signed by our new CA. Using jinja to strip newlines from the text avoids dealing with newlines in the rendered yaml, and the sign_remote_certificate state will handle properly formatting the text before writing the output. /srv/salt/cert.sls
This state creates a private key then requests a certificate signed by ca according to the www policy. /srv/salt/www.sls

salt.states.xmpp¶

Sending Messages over XMPP¶

New in version 2014.1.0. This state is useful for firing messages during state runs, using the XMPP protocol

salt.states.zabbix_host module¶

Management of Zabbix hosts.

salt.states.zabbix_hostgroup module¶

Management of Zabbix host groups.

salt.states.zabbix_user module¶

Management of Zabbix users.

salt.states.zabbix_usergroup module¶

Management of Zabbix user groups.

salt.states.zcbuildout¶

Management of zc.buildout¶

This module is inspired from minitage's buildout maker ( https://github.com/minitage/minitage/blob/master/src/minitage/core/makers/buildout.py) New in version 2016.3.0. NOTE:

Available Functions¶

salt.states.zenoss¶

State to manage monitoring in Zenoss. New in version 2016.3.0. This state module depends on the 'zenoss' Salt execution module. Allows for setting a state of minions in Zenoss using the Zenoss API. Currently Zenoss 4.x is supported.

salt.states.zk_concurrency¶

Control concurrency of steps within state execution using zookeeper¶

This module allows you to "wrap" a state's execution with concurrency control. This is useful to protect against all hosts executing highstate simultaneously if your services don't all HUP restart. The common way of protecting against this is to run in batch mode, but that doesn't protect from another person running the same batch command (and thereby having 2x the number of nodes deploying at once). This module will bock while acquiring a slot, meaning that however the command gets called it will coordinate with zookeeper to ensure that no more than max_concurrency steps are executing with a single path.
This example would allow the file state to change, but would limit the concurrency of the trafficserver service restart to 4.

salt.states.zfs¶

Management zfs datasets
New in version 2016.3.0.

salt.states.zpool¶

Management zpool
New in version 2016.3.0.
WARNING:

thorium modules¶

check	The check Thorium state is used to create gateways to commands, the checks make it easy to make states that watch registers for changes and then just succeed or fail based on the state of the register, this creates the pattern of having a command execution get gated by a check state via a requisite.
file	Writes matches to disk to verify activity, helpful when testing
local	Run remote execution commands via the local client
reg	Used to manage the thorium register.
timer	Allow for flow based timers.

salt.thorium.check module¶

The check Thorium state is used to create gateways to commands, the checks make it easy to make states that watch registers for changes and then just succeed or fail based on the state of the register, this creates the pattern of having a command execution get gated by a check state via a requisite.

salt.thorium.file module¶

Writes matches to disk to verify activity, helpful when testing Normally this is used by giving the name of the file (without a path) that the data will be saved to. If for instance you use foo as the name: Then the file will be saved to: You may also provide an absolute path for the file to be saved to:
Files will be saved in JSON format. However, JSON does not support set()``s. If you are saving a register entry that contains a ``set(), then it will fail to save to JSON format. However, you may pass data through a filter which makes it JSON compliant:
Be warned that if you do this, then the file will be saved, but not in a format that can be re-imported into Python.

salt.thorium.local module¶

Run remote execution commands via the local client

salt.thorium.reg module¶

Used to manage the thorium register. The thorium register is where compound values are stored and computed, such as averages etc.

salt.thorium.timer module¶

Allow for flow based timers. These timers allow for a sleep to exist across multiple runs of the flow

master tops modules¶

cobbler	Cobbler Tops
ext_nodes	External Nodes Classifier
mongo	Read tops data from a mongodb collection
reclass_adapter	Read tops data from a reclass database
varstack	Use Varstack <https://github.com/conversis/varstack> to provide tops data

salt.tops.cobbler¶

Cobbler Tops¶

Cobbler Tops is a master tops subsystem used to look up mapping information from Cobbler via its API. The same cobbler.* parameters are used for both the Cobbler tops and Cobbler pillar modules.

Module Documentation¶

salt.tops.ext_nodes¶

External Nodes Classifier¶

The External Nodes Classifier is a master tops subsystem that retrieves mapping information from major configuration management systems. One of the most common external nodes classifiers system is provided by Cobbler and is called cobbler-ext-nodes. The cobbler-ext-nodes command can be used with this configuration:
It is noteworthy that the Salt system does not directly ingest the data sent from the cobbler-ext-nodes command, but converts the data into information that is used by a Salt top file. Any command can replace the call to 'cobbler-ext-nodes' above, but currently the data must be formatted in the same way that the standard 'cobbler-ext-nodes' does. See (admittedly degenerate and probably not complete) example:
The above essentially is the same as a top.sls containing the following:

salt.tops.mongo¶

Read tops data from a mongodb collection This module will load tops data from a mongo collection. It uses the node's id for lookups.

Salt Master Mongo Configuration¶

The module shares the same base mongo connection variables as salt.returners.mongo_return. These variables go in your master config file.

Configuring the Mongo Tops Subsystem¶

Module Documentation¶

salt.tops.reclass_adapter¶

Read tops data from a reclass database This master_tops plugin provides access to the reclass database, such that state information (top data) are retrieved from reclass. You can find more information about reclass at http://reclass.pantsfullofunix.net. To use the plugin, add it to the master_tops list in the Salt master config and tell reclass by way of a few options how and where to find the inventory:
This would cause reclass to read the inventory from YAML files in /srv/salt/nodes and /srv/salt/classes. If you are also using reclass as ext_pillar plugin, and you want to avoid having to specify the same information for both, use YAML anchors (take note of the differing data types for ext_pillar and master_tops):
If you want to run reclass from source, rather than installing it, you can either let the master know via the PYTHONPATH environment variable, or by setting the configuration option, like in the example above.

salt.tops.varstack¶

Use Varstack <https://github.com/conversis/varstack> to provide tops data This master_tops plugin provides access to the varstack hierarchical yaml files, so you can user varstack as a full external node classifier and store state information (top data) in it.

Configuring Varstack¶

To use varstack as a master top external node classifier, install varstack as documented. Then, add to your master's configuration:
Varstack will then use /path/to/the/config/file/varstack.yaml (usually /etc/varstack.yaml) to determine which configuration data to return as adapter information. From there you can take a look at the README <https://github.com/conversis/varstack/blob/master/README.md> of varstack to learn how this file is evaluated. The ENC part will just return the 'states' dictionary for the node. Ie, if my.fqdn.yaml file contains:
these will be returned as {'base': ['sudo', 'openssh', 'apache', 'salt.minion']} and managed by salt as if given from a top.sls file.

wheel modules¶

config	Manage the master configuration file
error	Error generator to enable integration testing of salt wheel error handling
file_roots	Read in files from the file_root and save files to the file root
key	Wheel system wrapper for the Salt key system to be used in interactions with the Salt Master programmatically.
minions	Wheel system wrapper for connected minions
pillar_roots	The pillar_roots wheel module is used to manage files under the pillar roots directories on the master server.

salt.wheel.config¶

Manage the master configuration file

salt.wheel.error¶

Error generator to enable integration testing of salt wheel error handling

salt.wheel.file_roots¶

Read in files from the file_root and save files to the file root

salt.wheel.key¶

Wheel system wrapper for the Salt key system to be used in interactions with the Salt Master programmatically. The key module for the wheel system is meant to provide an internal interface for other Salt systems to interact with the Salt Master. The following usage examples assume that a WheelClient is available:
Note that importing and using the WheelClient must be performed on the same machine as the Salt Master and as the same user that runs the Salt Master, unless external_auth is configured and the user is authorized to execute wheel functions. The function documentation starts with the wheel reference from the code sample above and use the WheelClient functions to show how they can be called from a Python interpreter. The wheel key functions can also be called via a salt command at the CLI using the saltutil execution module.

salt.wheel.minions¶

Wheel system wrapper for connected minions

salt.wheel.pillar_roots¶

The pillar_roots wheel module is used to manage files under the pillar roots directories on the master server.

APIS¶

Python client API¶

Salt provides several entry points for interfacing with Python applications. These entry points are often referred to as *Client() APIs. Each client accesses different parts of Salt, either from the master or from a minion. Each client is detailed below. SEE ALSO:

Salt's opts dictionary¶

Some clients require access to Salt's opts dictionary. (The dictionary representation of the master or minion config files.) A common pattern for fetching the opts dictionary is to defer to environment variables if they exist or otherwise fetch the config from the default location.

Salt's Loader Interface¶

Modules in the Salt ecosystem are loaded into memory using a custom loader system. This allows modules to have conditional requirements (OS, OS version, installed libraries, etc) and allows Salt to inject special variables ( __salt__, __opts__, etc). Most modules can be manually loaded. This is often useful in third-party Python apps or when writing tests. However some modules require and expect a full, running Salt system underneath. Notably modules that facilitate master-to-minion communication such as the mine, publish, and peer execution modules. The error KeyError: 'master_uri' is a likely indicator for this situation. In those instances use the Caller class to execute those modules instead. Each module type has a corresponding loader function.

Salt's Client Interfaces¶

LocalClient¶

Salt Caller¶

RunnerClient¶

WheelClient¶

CloudClient¶

SSHClient¶

netapi modules¶

Introduction to netapi modules¶

netapi modules provide API-centric access to Salt. Usually externally-facing services such as REST or WebSockets, XMPP, XMLRPC, etc. In general netapi modules bind to a port and start a service. They are purposefully open-ended. A single module can be configured to run as well as multiple modules simultaneously. netapi modules are enabled by adding configuration to your Salt Master config file and then starting the salt-api daemon. Check the docs for each module to see external requirements and configuration settings. Communication with Salt and Salt satellite projects is done using Salt's own Python API. A list of available client interfaces is below.
SEE ALSO:

Client interfaces¶

Salt's client interfaces expose executing functions by crafting a dictionary of values that are mapped to function arguments. This allows calling functions simply by creating a data structure. (And this is exactly how much of Salt's own internals work!)

HTTP Modules¶

This tutorial demonstrates using the various HTTP modules available in Salt. These modules wrap the Python tornado, urllib2, and requests libraries, extending them in a manner that is more consistent with Salt workflows.

The salt.utils.http Library¶

This library forms the core of the HTTP modules. Since it is designed to be used from the minion as an execution module, in addition to the master as a runner, it was abstracted into this multi-use library. This library can also be imported by 3rd-party programs wishing to take advantage of its extended functionality. Core functionality of the execution, state, and runner modules is derived from this library, so common usages between them are described here. Documentation specific to each module is described below. This library can be imported with:

Configuring Libraries¶

This library can make use of either tornado, which is required by Salt, urllib2, which ships with Python, or requests, which can be installed separately. By default, tornado will be used. In order to switch to urllib2, set the following variable:
In order to switch to requests, set the following variable:
This can be set in the master or minion configuration file, or passed as an option directly to any http.query() functions.

salt.utils.http.query()¶

This function forms a basic query, but with some add-ons not present in the tornado, urllib2, and requests libraries. Not all functionality currently available in these libraries has been added, but can be in future iterations.

HTTPS Request Methods¶

A basic query can be performed by calling this function with no more than a single URL:
By default the query will be performed with a GET method. The method can be overridden with the method argument:
When using the POST method (and others, such as PUT), extra data is usually sent as well. This data can be sent directly, in whatever format is required by the remote server (XML, JSON, plain text, etc).

Data Formatting and Templating¶

Bear in mind that the data must be sent pre-formatted; this function will not format it for you. However, a templated file stored on the local system may be passed through, along with variables to populate it with. To pass through only the file (untemplated):
To pass through a file that contains jinja + yaml templating (the default):
To pass through a file that contains mako templating:
Because this function uses Salt's own rendering system, any Salt renderer can be used. Because Salt's renderer requires __opts__ to be set, an opts dictionary should be passed in. If it is not, then the default __opts__ values for the node type (master or minion) will be used. Because this library is intended primarily for use by minions, the default node type is minion. However, this can be changed to master if necessary.

Headers¶

Headers may also be passed through, either as a header_list, a header_dict, or as a header_file. As with the data_file, the header_file may also be templated. Take note that because HTTP headers are normally syntactically-correct YAML, they will automatically be imported as an a Python dict.
Because much of the data that would be templated between headers and data may be the same, the template_data is the same for both. Correcting possible variable name collisions is up to the user.

Authentication¶

The query() function supports basic HTTP authentication. A username and password may be passed in as username and password, respectively.

Cookies and Sessions¶

Cookies are also supported, using Python's built-in cookielib. However, they are turned off by default. To turn cookies on, set cookies to True.
By default cookies are stored in Salt's cache directory, normally /var/cache/salt, as a file called cookies.txt. However, this location may be changed with the cookie_jar argument:
By default, the format of the cookie jar is LWP (aka, lib-www-perl). This default was chosen because it is a human-readable text file. If desired, the format of the cookie jar can be set to Mozilla:
Because Salt commands are normally one-off commands that are piped together, this library cannot normally behave as a normal browser, with session cookies that persist across multiple HTTP requests. However, the session can be persisted in a separate cookie jar. The default filename for this file, inside Salt's cache directory, is cookies.session.p. This can also be changed.
The format of this file is msgpack, which is consistent with much of the rest of Salt's internal structure. Historically, the extension for this file is .p. There are no current plans to make this configurable.

Proxy¶

If the tornado backend is used (tornado is the default), proxy information configured in proxy_host, proxy_port, proxy_username, and proxy_password from the __opts__ dictionary will be used. Normally these are set in the minion configuration file.

Return Data¶

NOTE:
Because Salt's http library was designed to be used with REST interfaces, query() will attempt to decode the data received from the remote server when decode is set to True. First it will check the Content-type header to try and find references to XML. If it does not find any, it will look for references to JSON. If it does not find any, it will fall back to plain text, which will not be decoded. JSON data is translated into a dict using Python's built-in json library. XML is translated using salt.utils.xml_util, which will use Python's built-in XML libraries to attempt to convert the XML into a dict. In order to force either JSON or XML decoding, the decode_type may be set:
Once translated, the return dict from query() will include a dict called dict. If the data is not to be translated using one of these methods, decoding may be turned off.
If decoding is turned on, and references to JSON or XML cannot be found, then this module will default to plain text, and return the undecoded data as text (even if text is set to False; see below). The query() function can return the HTTP status code, headers, and/or text as required. However, each must individually be turned on.
The return from these will be found in the return dict as status, headers and text, respectively.

Writing Return Data to Files¶

It is possible to write either the return data or headers to files, as soon as the response is received from the server, but specifying file locations via the text_out or headers_out arguments. text and headers do not need to be returned to the user in order to do this.

SSL Verification¶

By default, this function will verify SSL certificates. However, for testing or debugging purposes, SSL verification can be turned off.

CA Bundles¶

The requests library has its own method of detecting which CA (certificate authority) bundle file to use. Usually this is implemented by the packager for the specific operating system distribution that you are using. However, urllib2 requires a little more work under the hood. By default, Salt will try to auto-detect the location of this file. However, if it is not in an expected location, or a different path needs to be specified, it may be done so using the ca_bundle variable.
The update_ca_bundle() function can be used to update the bundle file at a specified location. If the target location is not specified, then it will attempt to auto-detect the location of the bundle file. If the URL to download the bundle from does not exist, a bundle will be downloaded from the cURL website. CAUTION: The target and the source should always be specified! Failure to specify the target may result in the file being written to the wrong location on the local system. Failure to specify the source may cause the upstream URL to receive excess unnecessary traffic, and may cause a file to be download which is hazardous or does not meet the needs of the user.
The opts parameter should also always be specified. If it is, then the target and the source may be specified in the relevant configuration file (master or minion) as ca_bundle and ca_bundle_url, respectively.
If Salt is unable to auto-detect the location of the CA bundle, it will raise an error. The update_ca_bundle() function can also be passed a string or a list of strings which represent files on the local system, which should be appended (in the specified order) to the end of the CA bundle file. This is useful in environments where private certs need to be made available, and are not otherwise reasonable to add to the bundle file.

Test Mode¶

This function may be run in test mode. This mode will perform all work up until the actual HTTP request. By default, instead of performing the request, an empty dict will be returned. Using this function with TRACE logging turned on will reveal the contents of the headers and POST data to be sent. Rather than returning an empty dict, an alternate test_url may be passed in. If this is detected, then test mode will replace the url with the test_url, set test to True in the return data, and perform the rest of the requested operations as usual. This allows a custom, non-destructive URL to be used for testing when necessary.

Execution Module¶

The http execution module is a very thin wrapper around the salt.utils.http library. The opts can be passed through as well, but if they are not specified, the minion defaults will be used as necessary. Because passing complete data structures from the command line can be tricky at best and dangerous (in terms of execution injection attacks) at worse, the data_file, and header_file are likely to see more use here. All methods for the library are available in the execution module, as kwargs.

Runner Module¶

Like the execution module, the http runner module is a very thin wrapper around the salt.utils.http library. The only significant difference is that because runners execute on the master instead of a minion, a target is not required, and default opts will be derived from the master config, rather than the minion config. All methods for the library are available in the runner module, as kwargs.

State Module¶

The state module is a wrapper around the runner module, which applies stateful logic to a query. All kwargs as listed above are specified as usual in state files, but two more kwargs are available to apply stateful logic. A required parameter is match, which specifies a pattern to look for in the return text. By default, this will perform a string comparison of looking for the value of match in the return text. In Python terms this looks like:
If more complex pattern matching is required, a regular expression can be used by specifying a match_type. By default this is set to string, but it can be manually set to pcre instead. Please note that despite the name, this will use Python's re.search() rather than re.match(). Therefore, the following states are valid:
In addition to, or instead of a match pattern, the status code for a URL can be checked. This is done using the status argument:
If both are specified, both will be checked, but if only one is True and the other is False, then False will be returned. In this case, the comments in the return data will contain information for troubleshooting. Because this is a monitoring state, it will return extra data to code that expects it. This data will always include text and status. Optionally, headers and dict may also be requested by setting the headers and decode arguments to True, respectively.

Writing netapi modules¶

netapi modules, put simply, bind a port and start a service. They are purposefully open-ended and can be used to present a variety of external interfaces to Salt, and even present multiple interfaces at once. SEE ALSO:

Configuration¶

All netapi configuration is done in the Salt master config and takes a form similar to the following:

The __virtual__ function¶

Like all module types in Salt, netapi modules go through Salt's loader interface to determine if they should be loaded into memory and then executed. The __virtual__ function in the module makes this determination and should return False or a string that will serve as the name of the module. If the module raises an ImportError or any other errors, it will not be loaded.

The start function¶

The start() function will be called for each netapi module that is loaded. This function should contain the server loop that actually starts the service. This is started in a multiprocess.

Multiple instances¶

New in version 2016.11.0. rest_cherrypy and rest_tornado support running multiple instances by copying and renaming entire directory of those. To start the copied multiple netapi modules, add configuration blocks for the copied netapi modules in the Salt Master config. The name of each added configuration block must match with the name of each directory of the copied netapi module.

Inline documentation¶

As with the rest of Salt, it is a best-practice to include liberal inline documentation in the form of a module docstring and docstrings on any classes, methods, and functions in your netapi module.

Loader “magic” methods¶

The loader makes the __opts__ data structure available to any function in a netapi module.

ARCHITECTURE¶

If you are used to configuration management tools that require you to plan down to the last detail before you install anything, you are probably wondering why this section doesn't appear before the installation instructions. With Salt, you can switch to a high availability architecture at any time, and add additional components to scale your deployment as you go. Since a single Salt master can manage thousands of systems, we usually recommend that you start by deploying a single Salt master, and then modifying your deployment as needed for redundancy, geographical distribution, and scale.

High Availability Features in Salt¶

Salt supports several features for high availability and fault tolerance. Brief documentation for these features is listed alongside their configuration parameters in Configuration file examples.

Multimaster¶

Salt minions can connect to multiple masters at one time by configuring the master configuration parameter as a YAML list of all the available masters. By default, all masters are "hot", meaning that any master can direct commands to the Salt infrastructure. In a multimaster configuration, each master must have the same cryptographic keys, and minion keys must be accepted on all masters separately. The contents of file_roots and pillar_roots need to be kept in sync with processes external to Salt as well A tutorial on setting up multimaster with "hot" masters is here: Multimaster Tutorial

Multimaster with Failover¶

Changing the master_type parameter from str to failover will cause minions to connect to the first responding master in the list of masters. Every master_alive_interval seconds the minions will check to make sure the current master is still responding. If the master does not respond, the minion will attempt to connect to the next master in the list. If the minion runs out of masters, the list will be recycled in case dead masters have been restored. Note that master_alive_interval must be present in the minion configuration, or else the recurring job to check master status will not get scheduled. Failover can be combined with PKI-style encrypted keys, but PKI is NOT REQUIRED to use failover. Multimaster with PKI and Failover is discussed in this tutorial master_type: failover can be combined with master_shuffle: True to spread minion connections across all masters (one master per minion, not each minion connecting to all masters). Adding Salt Syndics into the mix makes it possible to create a load-balanced Salt infrastructure. If a master fails, minions will notice and select another master from the available list.

Syndic¶

Salt's Syndic feature is a way to create differing infrastructure topologies. It is not strictly an HA feature, but can be treated as such. With the syndic, a Salt infrastructure can be partitioned in such a way that certain masters control certain segments of the infrastructure, and "Master of Masters" nodes can control multiple segments underneath them. Syndics are covered in depth in Salt Syndic.

Syndic with Multimaster¶

New in version 2015.5.0. Syndic with Multimaster lets you connect a syndic to multiple masters to provide an additional layer of redundancy in a syndic configuration. Syndics are covered in depth in Salt Syndic.

Salt Syndic¶

The most basic or typical Salt topology consists of a single Master node controlling a group of Minion nodes. An intermediate node type, called Syndic, when used offers greater structural flexibility and scalability in the construction of Salt topologies than topologies constructed only out of Master and Minion node types. A Syndic node can be thought of as a special passthrough Minion node. A Syndic node consists of a salt-syndic daemon and a salt-master daemon running on the same system. The salt-master daemon running on the Syndic node controls a group of lower level Minion nodes and the salt-syndic daemon connects higher level Master node, sometimes called a Master of Masters. The salt-syndic daemon relays publications and events between the Master node and the local salt-master daemon. This gives the Master node control over the Minion nodes attached to the salt-master daemon running on the Syndic node.

Configuring the Syndic¶

To setup a Salt Syndic you need to tell the Syndic node and its Master node about each other. If your Master node is located at 10.10.0.1, then your configurations would be: On the Syndic node:

On the Master node:
The syndic_master option tells the Syndic node where to find the Master node in the same way that the master option tells a Minion node where to find a Master node. The id option is used by the salt-syndic daemon to identify with the Master node and if unset will default to the hostname or IP address of the Syndic just as with a Minion. The order_masters option configures the Master node to send extra information with its publications that is needed by Syndic nodes connected directly to it. NOTE:

Configuring the Syndic with Multimaster¶

New in version 2015.5.0. Syndic with Multimaster lets you connect a syndic to multiple masters to provide an additional layer of redundancy in a syndic configuration. Higher level masters should first be configured in a multimaster configuration. See Multimaster Tutorial. On the syndic, the syndic_master option is populated with a list of the higher level masters. Since each syndic is connected to each master, jobs sent from any master are forwarded to minions that are connected to each syndic. If the master_id value is set in the master config on the higher level masters, job results are returned to the master that originated the request in a best effort fashion. Events/jobs without a master_id are returned to any available master.

Running the Syndic¶

The salt-syndic daemon is a separate process that needs to be started in addition to the salt-master daemon running on the Syndic node. Starting the salt-syndic daemon is the same as starting the other Salt daemons. The Master node in many ways sees the Syndic as an ordinary Minion node. In particular, the Master will need to accept the Syndic's Minion key as it would for any other Minion. On the Syndic node:
On the Master node:
The Master node will now be able to control the Minion nodes connected to the Syndic. Only the Syndic key will be listed in the Master node's key registry but this also means that key activity between the Syndic's Minions and the Syndic does not encumber the Master node. In this way, the Syndic's key on the Master node can be thought of as a placeholder for the keys of all the Minion and Syndic nodes beneath it, giving the Master node a clear, high level structural view on the Salt cluster. On the Master node:

Topology¶

A Master node (a node which is itself not a Syndic to another higher level Master node) must run a salt-master daemon and optionally a salt-minion daemon. A Syndic node must run salt-syndic and salt-master daemons and optionally a salt-minion daemon. A Minion node must run a salt-minion daemon. When a salt-master daemon issues a command, it will be received by the Syndic and Minion nodes directly connected to it. A Minion node will process the command in the way it ordinarily would. On a Syndic node, the salt-syndic daemon will relay the command to the salt-master daemon running on the Syndic node, which then propagates the command to to the Minions and Syndics connected to it. When events and job return data are generated by salt-minion daemons, they are aggregated by the salt-master daemon they are connected to, which salt-master daemon then relays the data back through its salt-syndic daemon until the data reaches the Master or Syndic node that issued the command.

Syndic wait¶

syndic_wait is a master configuration file setting that specifies the number of seconds the Salt client should wait for additional syndics to check in with their lists of expected minions before giving up. This value defaults to 5 seconds. The syndic_wait setting is necessary because the higher-level master does not have a way of knowing which minions are below the syndics. The higher-level master has its own list of expected minions and the masters below them have their own lists as well, so the Salt client does not how long to wait for all returns. The syndic_wait option allows time for all minions to return to the Salt client. NOTE:
While it is possible to run a Syndic without a Minion installed on the same system, it is recommended, for a faster CLI response time, to do so. Without a Minion installed on the Syndic node, the timeout value of syndic_wait increases significantly - about three-fold. With a Minion installed on the Syndic, the CLI timeout resides at the value defined in syndic_wait. NOTE:
In order for a Master or Syndic node to return information from Minions that are below their Syndics, the CLI requires a short wait time in order to allow the Syndics to gather responses from their Minions. This value is defined in the syndic_wait config option and has a default of five seconds.

Syndic config options¶

These are the options that can be used to configure a Syndic node. Note that other than id, Syndic config options are placed in the Master config on the Syndic node.

Using Salt at scale¶

The focus of this tutorial will be building a Salt infrastructure for handling large numbers of minions. This will include tuning, topology, and best practices. For how to install the Salt Master please go here: Installing saltstack NOTE:

The Master¶

The most common problems on the Salt Master are:
The first three are all "thundering herd" problems. To mitigate these issues we must configure the minions to back-off appropriately when the Master is under heavy load. The fourth is caused by masters with little hardware resources in combination with a possible bug in ZeroMQ. At least that's what it looks like till today ( Issue 118651, Issue 5948, Mail thread) To fully understand each problem, it is important to understand, how Salt works. Very briefly, the Salt Master offers two services to the minions.
All minions are always connected to the publisher on port 4505 and only connect to the open return port 4506 if necessary. On an idle Master, there will only be connections on port 4505.

Too many minions authing¶

When the Minion service is first started up, it will connect to its Master's publisher on port 4505. If too many minions are started at once, this can cause a "thundering herd". This can be avoided by not starting too many minions at once. The connection itself usually isn't the culprit, the more likely cause of master-side issues is the authentication that the Minion must do with the Master. If the Master is too heavily loaded to handle the auth request it will time it out. The Minion will then wait acceptance_wait_time to retry. If acceptance_wait_time_max is set then the Minion will increase its wait time by the acceptance_wait_time each subsequent retry until reaching acceptance_wait_time_max.

Too many minions re-authing¶

This is most likely to happen in the testing phase of a Salt deployment, when all Minion keys have already been accepted, but the framework is being tested and parameters are frequently changed in the Salt Master's configuration file(s). The Salt Master generates a new AES key to encrypt its publications at certain events such as a Master restart or the removal of a Minion key. If you are encountering this problem of too many minions re-authing against the Master, you will need to recalibrate your setup to reduce the rate of events like a Master restart or Minion key removal ( salt-key -d). When the Master generates a new AES key, the minions aren't notified of this but will discover it on the next pub job they receive. When the Minion receives such a job it will then re-auth with the Master. Since Salt does minion-side filtering this means that all the minions will re-auth on the next command published on the master-- causing another "thundering herd". This can be avoided by setting the
in the minions configuration file to a higher value and stagger the amount of re-auth attempts. Increasing this value will of course increase the time it takes until all minions are reachable via Salt commands.

Too many minions re-connecting¶

By default the zmq socket will re-connect every 100ms which for some larger installations may be too quick. This will control how quickly the TCP session is re-established, but has no bearing on the auth load. To tune the minions sockets reconnect attempts, there are a few values in the sample configuration file (default values)

To tune this values to an existing environment, a few decision have to be made.
These questions can not be answered generally. Their answers depend on the hardware and the administrators requirements. Here is an example scenario with the goal, to have all minions reconnect within a 60 second time-frame on a Salt Master service restart.
Each Minion will have a randomized reconnect value between 'recon_default' and 'recon_default + recon_max', which in this example means between 1000ms and 60000ms (or between 1 and 60 seconds). The generated random-value will be doubled after each attempt to reconnect (ZeroMQ default behavior). Lets say the generated random value is 11 seconds (or 11000ms).
With a thousand minions this will mean
round about 16 connection attempts a second. These values should be altered to values that match your environment. Keep in mind though, that it may grow over time and that more minions might raise the problem again.

Too many minions returning at once¶

This can also happen during the testing phase, if all minions are addressed at once with
it may cause thousands of minions trying to return their data to the Salt Master open port 4506. Also causing a flood of syn-flood if the Master can't handle that many returns at once. This can be easily avoided with Salt's batch mode:
This will only address 50 minions at once while looping through all addressed minions.

Too few resources¶

The masters resources always have to match the environment. There is no way to give good advise without knowing the environment the Master is supposed to run in. But here are some general tuning tips for different situations:

The Master is CPU bound¶

Salt uses RSA-Key-Pairs on the masters and minions end. Both generate 4096 bit key-pairs on first start. While the key-size for the Master is currently not configurable, the minions keysize can be configured with different key-sizes. For example with a 2048 bit key:
With thousands of decryptions, the amount of time that can be saved on the masters end should not be neglected. See here for reference: Pull Request 9235 how much influence the key-size can have. Downsizing the Salt Master's key is not that important, because the minions do not encrypt as many messages as the Master does. In installations with large or with complex pillar files, it is possible for the master to exhibit poor performance as a result of having to render many pillar files at once. This exhibit itself in a number of ways, both as high load on the master and on minions which block on waiting for their pillar to be delivered to them. To reduce pillar rendering times, it is possible to cache pillars on the master. To do this, see the set of master configuration options which are prefixed with pillar_cache. NOTE:

The Master is disk IO bound¶

By default, the Master saves every Minion's return for every job in its job-cache. The cache can then be used later, to lookup results for previous jobs. The default directory for this is:
and then in the /proc directory. Each job return for every Minion is saved in a single file. Over time this directory can grow quite large, depending on the number of published jobs. The amount of files and directories will scale with the number of jobs published and the retention time defined by

If no job history is needed, the job cache can be disabled:
If the job cache is necessary there are (currently) 2 options:
If a master has many accepted keys, it may take a long time to publish a job because the master much first determine the matching minions and deliver that information back to the waiting client before the job can be published. To mitigate this, a key cache may be enabled. This will reduce the load on the master to a single file open instead of thousands or tens of thousands. This cache is updated by the maintanence process, however, which means that minions with keys that are accepted may not be targeted by the master for up to sixty seconds by default. To enable the master key cache, set key_cache: 'sched' in the master configuration file.

Multi Master Tutorial¶

As of Salt 0.16.0, the ability to connect minions to multiple masters has been made available. The multi-master system allows for redundancy of Salt masters and facilitates multiple points of communication out to minions. When using a multi-master setup, all masters are running hot, and any active master can be used to send commands out to the minions. NOTE:
In 0.16.0, the masters do not share any information, keys need to be accepted on both masters, and shared files need to be shared manually or use tools like the git fileserver backend to ensure that the file_roots are kept consistent.

Summary of Steps¶

Prepping a Redundant Master¶

The first task is to prepare the redundant master. If the redundant master is already running, stop it. There is only one requirement when preparing a redundant master, which is that masters share the same private key. When the first master was created, the master's identifying key pair was generated and placed in the master's pki_dir. The default location of the master's key pair is /etc/salt/pki/master/. Take the private key, master.pem, and copy it to the same location on the redundant master. Do the same for the master's public key, master.pub. Assuming that no minions have yet been connected to the new redundant master, it is safe to delete any existing key in this location and replace it. NOTE:
Once the new key is in place, the redundant master can be safely started.

Configure Minions¶

Since minions need to be master-aware, the new master needs to be added to the minion configurations. Simply update the minion configurations to list all connected masters:
Now the minion can be safely restarted. NOTE:
Now the minions will check into the original master and also check into the new redundant master. Both masters are first-class and have rights to the minions. NOTE:

Sharing Files Between Masters¶

Salt does not automatically share files between multiple masters. A number of files should be shared or sharing of these files should be strongly considered.

Minion Keys¶

Minion keys can be accepted the normal way using salt-key on both masters. Keys accepted, deleted, or rejected on one master will NOT be automatically managed on redundant masters; this needs to be taken care of by running salt-key on both masters or sharing the /etc/salt/pki/master/{minions,minions_pre,minions_rejected} directories between masters. NOTE:

File_Roots¶

The file_roots contents should be kept consistent between masters. Otherwise state runs will not always be consistent on minions since instructions managed by one master will not agree with other masters. The recommended way to sync these is to use a fileserver backend like gitfs or to keep these files on shared storage. IMPORTANT:

Pillar_Roots¶

Pillar roots should be given the same considerations as file_roots.

Master Configurations¶

While reasons may exist to maintain separate master configurations, it is wise to remember that each master maintains independent control over minions. Therefore, access controls should be in sync between masters unless a valid reason otherwise exists to keep them inconsistent. These access control options include but are not limited to:

Multi-Master-PKI Tutorial With Failover¶

This tutorial will explain, how to run a salt-environment where a single minion can have multiple masters and fail-over between them if its current master fails. The individual steps are

Motivation¶

The default behaviour of a salt-minion is to connect to a master and accept the masters public key. With each publication, the master sends his public-key for the minion to check and if this public-key ever changes, the minion complains and exits. Practically this means, that there can only be a single master at any given time. Would it not be much nicer, if the minion could have any number of masters (1:n) and jump to the next master if its current master died because of a network or hardware failure? NOTE:
It is also desirable, to add some sort of authenticity-check to the very first public key a minion receives from a master. Currently a minions takes the first masters public key for granted.

The Goal¶

Setup the master to sign the public key it sends to the minions and enable the minions to verify this signature for authenticity.

Prepping the master to sign its public key¶

For signing to work, both master and minion must have the signing and/or verification settings enabled. If the master signs the public key but the minion does not verify it, the minion will complain and exit. The same happens, when the master does not sign but the minion tries to verify. The easiest way to have the master sign its public key is to set
After restarting the salt-master service, the master will automatically generate a new key-pair
A custom name can be set for the signing key-pair by setting
The master will then generate that key-pair upon restart and use it for creating the public keys signature attached to the auth-reply. The computation is done for every auth-request of a minion. If many minions auth very often, it is advised to use conf_master: master_pubkey_signature and conf_master: master_use_pubkey_signature settings described below. If multiple masters are in use and should sign their auth-replies, the signing key-pair master_sign.* has to be copied to each master. Otherwise a minion will fail to verify the masters public when connecting to a different master than it did initially. That is because the public keys signature was created with a different signing key-pair.

Prepping the minion to verify received public keys¶

The minion must have the public key (and only that one!) available to be able to verify a signature it receives. That public key (defaults to master_sign.pub) must be copied from the master to the minions pki-directory.
When that is done, enable the signature checking in the minions configuration
and restart the minion. For the first try, the minion should be run in manual debug mode.
Upon connecting to the master, the following lines should appear on the output:
If the signature verification fails, something went wrong and it will look like this
In a case like this, it should be checked, that the verification pubkey (master_sign.pub) on the minion is the same as the one on the master. Once the verification is successful, the minion can be started in daemon mode again. For the paranoid among us, its also possible to verify the publication whenever it is received from the master. That is, for every single auth-attempt which can be quite frequent. For example just the start of the minion will force the signature to be checked 6 times for various things like auth, mine, highstate, etc. If that is desired, enable the setting

Multiple Masters For A Minion¶

Configuring multiple masters on a minion is done by specifying two settings:


This tells the minion that all the master above are available for it to connect to. When started with this configuration, it will try the master in the order they are defined. To randomize that order, set
The master-list will then be shuffled before the first connection attempt. The first master that accepts the minion, is used by the minion. If the master does not yet know the minion, that counts as accepted and the minion stays on that master. For the minion to be able to detect if its still connected to its current master enable the check for it
If the loss of the connection is detected, the minion will temporarily remove the failed master from the list and try one of the other masters defined (again shuffled if that is enabled).

Testing the setup¶

At least two running masters are needed to test the failover setup. Both masters should be running and the minion should be running on the command line in debug mode
The minion will connect to the first master from its master list
A test.ping on the master the minion is currently connected to should be run to test connectivity. If successful, that master should be turned off. A firewall-rule denying the minions packets will also do the trick. Depending on the configured conf_minion: master_alive_interval, the minion will notice the loss of the connection and log it to its logfile.
The minion will then remove the current master from the list and try connecting to the next master
If everything is configured correctly, the new masters public key will be verified successfully
the authentication with the new master is successful
and the minion can be pinged again from its new master.

Performance Tuning¶

With the setup described above, the master computes a signature for every auth-request of a minion. With many minions and many auth-requests, that can chew up quite a bit of CPU-Power. To avoid that, the master can use a pre-created signature of its public-key. The signature is saved as a base64 encoded string which the master reads once when starting and attaches only that string to auth-replies. Enabling this also gives paranoid users the possibility, to have the signing key-pair on a different system than the actual salt-master and create the public keys signature there. Probably on a system with more restrictive firewall rules, without internet access, less users, etc. That signature can be created with
This will create a default signature file in the master pki-directory
It is a simple text-file with the binary-signature converted to base64. If no signing-pair is present yet, this will auto-create the signing pair and the signature file in one call
Telling the master to use the pre-created signature is done with
That requires the file 'master_pubkey_signature' to be present in the masters pki-directory with the correct signature. If the signature file is named differently, its name can be set with
With many masters and many public-keys (default and signing), it is advised to use the salt-masters hostname for the signature-files name. Signatures can be easily confused because they do not provide any information about the key the signature was created from. Verifying that everything works is done the same way as above.

How the signing and verification works¶

The default key-pair of the salt-master is
To be able to create a signature of a message (in this case a public-key), another key-pair has to be added to the setup. Its default name is:
The combination of the master.* and master_sign.* key-pairs give the possibility of generating signatures. The signature of a given message is unique and can be verified, if the public-key of the signing-key-pair is available to the recipient (the minion). The signature of the masters public-key in master.pub is computed with
This results in a binary signature which is converted to base64 and attached to the auth-reply send to the minion. With the signing-pairs public-key available to the minion, the attached signature can be verified with
When running multiple masters, either the signing key-pair has to be present on all of them, or the master_pubkey_signature has to be pre-computed for each master individually (because they all have different public-keys).

WINDOWS¶

This section contains details on the Windows Package Manager, and specific information you need to use Salt on Windows.

Windows Software Repository¶

NOTE:
The SaltStack Windows Software Repository provides a package manager and software repository similar to what is provided by yum and apt on Linux. This repository enables the installation of software using the installers on remote Windows systems. In many senses, the operation is similar to that of the other package managers salt is aware of:
High level differences to yum and apt are:
Requirements:

Configuration¶

Populate the Repository¶

The SLS files used to install Windows packages are not distributed by default with Salt. Run the following command to initialize the repository on your Salt master:

Sync Repo to Windows Minions¶

Run pkg.refresh_db on each of your Windows minions to synchronize the package repository.

Install Windows Software¶

After completing the configuration steps, you are ready to manage software on your Windows minions.

Show Installed Packages¶

Install a Package¶

You can query the available version of a package using the Salt pkg module.
As you can see, there are three versions of Firefox available for installation. You can refer a software package by its name or its full_name surround by single quotes.
The above line will install the latest version of Firefox.
The above line will install version 16.0.2 of Firefox. If a different version of the package is already installed it will be replaced with the version in the winrepo (only if the package itself supports live updating). You can also specify the full name:

Uninstall Windows Software¶

Uninstall software using the pkg module:
NOTE:

Repository Location¶

Salt maintains a repository of SLS files to install a large number of Windows packages:
By default, these repositories are mirrored to /srv/salt/win/repo_ng and /srv/salt/win/repo. This location can be changed in the master config file by setting the winrepo_dir_ng and winrepo_dir options.

Maintaining Windows Repo Definitions in Git Repositories¶

Windows software package definitions can be hosted in one or more Git repositories. The default repositories are hosted on GitHub by SaltStack. These include software definition files for various open source software projects. These software definition files are .sls files. There are two default repositories: salt-winrepo and salt-winrepo-ng. salt-winrepo contains software definition files for older minions (older than 2015.8.0). salt-winrepo-ng is for newer minions (2015.8.0 and newer). Each software definition file contains all the information salt needs to install that software on a minion including the HTTP or FTP locations of the installer files, required command-line switches for silent install, etc. Anyone is welcome to send a pull request to this repo to add new package definitions. The repos can be browsed here: salt-winrepo salt-winrepo-ng NOTE:
Configure which git repositories the master can search for package definitions by modifying or extending the winrepo_remotes and winrepo_remotes_ng options. IMPORTANT:
Package definitions are pulled down from the online repository by running the winrepo.update_git_repos runner. This command is run on the master:
This will pull down the software definition files for older minions ( salt-winrepo) and new minions ( salt-winrepo-ng). They are stored in the file_roots under win/repo/salt-winrepo and win/repo-ng/salt-winrepo-ng respectively. IMPORTANT:
The next step (if you have older minions) is to create the msgpack file for the repo ( winrepo.p). This is done by running the winrepo.genrepo runner. This is also run on the master:
NOTE:
Finally, you need to refresh the minion database by running the pkg.refresh_db command. This is run on the master as well:
On older minions (older than 2015.8.0) this will copy the winrepo.p file down to the minion. On newer minions (2015.8.0 and newer) this will copy all the software definition files (.sls) down to the minion and then create the msgpack file ( winrepo.p) locally. The reason this is done locally is because the jinja needs to be parsed using the minion's grains. IMPORTANT:
NOTE:
To disable one of the repos, set it to an empty list [] in the master config. For example, to disable winrepo_remotes set the following in the master config file:

Creating a Package Definition SLS File¶

The package definition file is a yaml file that contains all the information needed to install a piece of software using salt. It defines information about the package to include version, full name, flags required for the installer and uninstaller, whether or not to use the windows task scheduler to install the package, where to find the installation package, etc. Take a look at this example for Firefox:
Each software definition file begins with a package name for the software. As in the example above firefox. The next line is indented two spaces and contains the version to be defined. As in the example above, a software definition file can define multiple versions for the same piece of software. The lines following the version are indented two more spaces and contain all the information needed to install that package. WARNING:
The version line is the version for the package to be installed. It is used when you need to install a specific version of a piece of software. WARNING:
NOTE:

Available parameters are as follows:

Notice the Full Name for Firefox: Mozilla Firefox 17.0.0 (x86 en-US). That's exactly what's in the full_name parameter in the software definition file. If any of the software insalled on the machine matches one of the software definition files in the repository the full_name will be automatically renamed to the package name. The example below shows the pkg.list_pkgs for a machine that already has Mozilla Firefox 17.0.1 installed.
IMPORTANT:
NOTE:

Salt will not return if the installer is waiting for user input so these are important.
Salt will not return if the uninstaller is waiting for user input so these are important. Here are some examples of installer and uninstaller settings:
Alternatively the uninstaller can also simply repeat the URL of the msi file.

NOTE:
Here's an example for a software package that has dependent files:

to the provided hash sum before execution. The value can be formatted as hash_algorithm=hash_sum, or it can be a URI to a file containing the hash sum. For a list of supported algorithms, see the hashlib documentation. Here's an example of source_hash usage:

Examples can be found at https://github.com/saltstack/salt-winrepo-ng

Managing Windows Software on a Standalone Windows Minion¶

The Windows Package Repository functions similar in a standalone environment, with a few differences in the configuration. To replace the winrepo runner that is used on the Salt master, an execution module exists to provide the same functionality to standalone minions. The functions are named the same as the ones in the runner, and are used in the same way; the only difference is that salt-call is used instead of salt-run:
After executing the previous commands the repository on the standalone system is ready to use.

Custom Location for Repository SLS Files¶

If file_roots has not been modified in the minion configuration, then no additional configuration needs to be added to the minion configuration. The winrepo.genrepo function from the winrepo execution module will by default look for the filename specified by winrepo_cachefile within C:\salt\srv\salt\win\repo. If the file_roots parameter has been modified, then winrepo_dir must be modified to fall within that path, at the proper relative path. For example, if the base environment in file_roots points to D:\foo, and winrepo_source_dir is salt://win/repo, then winrepo_dir must be set to D:\foo\win\repo to ensure that winrepo.genrepo puts the cachefile into right location.

Config Options for Minions 2015.8.0 and Later¶

The winrepo_source_dir config parameter (default: salt://win/repo) controls where pkg.refresh_db looks for the cachefile (default: winrepo.p). This means that the default location for the winrepo cachefile would be salt://win/repo/winrepo.p. Both winrepo_source_dir and winrepo_cachefile can be adjusted to match the actual location of this file on the Salt fileserver.

Config Options for Minions Before 2015.8.0¶

If connected to a master, the minion will by default look for the winrepo cachefile (the file generated by the winrepo.genrepo runner) at salt://win/repo/winrepo.p. If the cachefile is in a different path on the salt fileserver, then win_repo_cachefile will need to be updated to reflect the proper location.

Changes in Version 2015.8.0¶

Git repository management for the Windows Software Repository has changed in version 2015.8.0, and several master/minion config parameters have been renamed to make their naming more consistent with each other. For a list of the winrepo config options, see here for master config options, and here for configuration options for masterless Windows minions. On the master, the winrepo.update_git_repos runner has been updated to use either pygit2 or GitPython to checkout the git repositories containing repo data. If pygit2 or GitPython is installed, existing winrepo git checkouts should be removed after upgrading to 2015.8.0, to allow them to be checked out again by running winrepo.update_git_repos. If neither GitPython nor pygit2 are installed, then Salt will fall back to the pre-existing behavior for winrepo.update_git_repos, and a warning will be logged in the master log. NOTE:

Config Parameters Renamed¶

Many of the legacy winrepo configuration parameters have changed in version 2015.8.0 to make the naming more consistent. The old parameter names will still work, but a warning will be logged indicating that the old name is deprecated. Below are the parameters which have changed for version 2015.8.0:

Master Config¶

Old Name	New Name
win_repo	winrepo_dir
win_repo_mastercachefile	winrepo_cachefile
win_gitrepos	winrepo_remotes

NOTE:
See here for detailed information on all master config options for the Windows Repo.

Minion Config¶

Old Name	New Name
win_repo	winrepo_dir
win_repo_cachefile	winrepo_cachefile
win_gitrepos	winrepo_remotes

See here for detailed information on all minion config options for the Windows Repo.

pygit2/GitPython Support for Maintaining Git Repos¶

The winrepo.update_git_repos runner (and the corresponding remote execution function for standalone minions) now makes use of the same underlying code used by the Git Fileserver Backend and Git External Pillar to maintain and update its local clones of git repositories. If a compatible version of either pygit2 (0.20.3 and later) or GitPython (0.3.0 or later) is installed, then Salt will use it instead of the old method (which invokes the git.latest state). NOTE:
To minimize potential issues, it is a good idea to remove any winrepo git repositories that were checked out by the old (pre-2015.8.0) winrepo code when upgrading the master to 2015.8.0 or later, and run winrepo.update_git_repos to clone them anew after the master is started. Additional added features include the ability to access authenticated git repositories ( NOTE: pygit2 only), and to set per-remote config settings. An example of this would be the following:
NOTE:
There are a couple other changes in how Salt manages git repos using pygit2/ GitPython. First of all, a clean argument has been added to the winrepo.update_git_repos runner, which (if set to True) will tell the runner to dispose of directories under the winrepo_dir which are not explicitly configured. This prevents the need to manually remove these directories when a repo is removed from the config file. To clean these old directories, just pass clean=True, like so:
However, if a mix of git and non-git Windows Repo definition files are being used, then this should not be used, as it will remove the directories containing non-git definitions. The other major change is that collisions between repo names are now detected, and the winrepo.update_git_repos runner will not proceed if any are detected. Consider the following configuration:
The winrepo.update_git_repos runner will refuse to update repos here, as all three of these repos would be checked out to the same directory. To work around this, a per-remote parameter called name can be used to resolve these conflicts:

Troubleshooting¶

Incorrect name/version¶

If the package seems to install properly, but salt reports a failure then it is likely you have a version or full_name mismatch. Check the exact full_name and version used by the package. Use pkg.list_pkgs to check that the names and version exactly match what is installed.

Changes to sls files not being picked up¶

Ensure you have (re)generated the repository cache file (for older minions) and then updated the repository cache on the relevant minions:

Packages management under Windows 2003¶

On Windows server 2003, you need to install optional Windows component "wmi windows installer provider" to have full list of installed packages. If you don't have this, salt-minion can't report some installed software.

How Success and Failure are Reported¶

The install state/module function of the Windows package manager works roughly as follows:
If there are any problems in using the package manager it is likely due to the data in your sls files not matching the difference between the pre and post pkg.list_pkgs results.

Windows-specific Behaviour¶

Salt is capable of managing Windows systems, however due to various differences between the operating systems, there are some things you need to keep in mind. This document will contain any quirks that apply across Salt or generally across multiple module functions. Any Windows-specific behavior for particular module functions will be documented in the module function documentation. Therefore this document should be read in conjunction with the module function documentation.

Group parameter for files¶

Salt was originally written for managing Unix-based systems, and therefore the file module functions were designed around that security model. Rather than trying to shoehorn that model on to Windows, Salt ignores these parameters and makes non-applicable module functions unavailable instead. One of the commonly ignored parameters is the group parameter for managing files. Under Windows, while files do have a 'primary group' property, this is rarely used. It generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services). Because of this, any file module functions that typically require a group, do not under Windows. Attempts to directly use file module functions that operate on the group (e.g. file.chgrp) will return a pseudo-value and cause a log message to appear. No group parameters will be acted on. If you do want to access and change the 'primary group' property and understand the implications, use the file.get_pgid or file.get_pgroup functions or the pgroup parameter on the file.chown module function.

Dealing with case-insensitive but case-preserving names¶

Windows is case-insensitive, but however preserves the case of names and it is this preserved form that is returned from system functions. This causes some issues with Salt because it assumes case-sensitive names. These issues generally occur in the state functions and can cause bizarre looking errors. To avoid such issues, always pretend Windows is case-sensitive and use the right case for names, e.g. specify user=Administrator instead of user=administrator. Follow issue 11801 for any changes to this behavior.

Dealing with various username forms¶

Salt does not understand the various forms that Windows usernames can come in, e.g. username, mydomain\username, username@mydomain.tld can all refer to the same user. In fact, Salt generally only considers the raw username value, i.e. the username without the domain or host information. Using these alternative forms will likely confuse Salt and cause odd errors to happen. Use only the raw username value in the correct case to avoid problems. Follow issue 11801 for any changes to this behavior.

Specifying the None group¶

Each Windows system has built-in _None_ group. This is the default 'primary group' for files for users not on a domain environment. Unfortunately, the word _None_ has special meaning in Python - it is a special value indicating 'nothing', similar to null or nil in other languages. To specify the None group, it must be specified in quotes, e.g. ./salt '*' file.chpgrp C:\path\to\file "'None'".

Symbolic link loops¶

Under Windows, if any symbolic link loops are detected or if there are too many levels of symlinks (defaults to 64), an error is always raised. For some functions, this behavior is different to the behavior on Unix platforms. In general, avoid symlink loops on either platform.

Modifying security properties (ACLs) on files¶

There is no support in Salt for modifying ACLs, and therefore no support for changing file permissions, besides modifying the owner/user.

DEVELOPING SALT¶

Overview¶

In its most typical use, Salt is a software application in which clients, called "minions" can be commanded and controlled from a central command server called a "master". Commands are normally issued to the minions (via the master) by calling a client script simply called, 'salt'. Salt features a pluggable transport system to issue commands from a master to minions. The default transport is ZeroMQ.

Salt Client¶

Overview¶

The salt client is run on the same machine as the Salt Master and communicates with the salt-master to issue commands and to receive the results and display them to the user. The primary abstraction for the salt client is called 'LocalClient'. When LocalClient wants to publish a command to minions, it connects to the master by issuing a request to the master's ReqServer (TCP: 4506) The LocalClient system listens to responses for its requests by listening to the master event bus publisher (master_event_pub.ipc).

Salt Master¶

Overview¶

The salt-master daemon runs on the designated Salt master and performs functions such as authenticating minions, sending, and receiving requests from connected minions and sending and receiving requests and replies to the 'salt' CLI.

Moving Pieces¶

When a Salt master starts up, a number of processes are started, all of which are called 'salt-master' in a process-list but have various role categories. Among those categories are:

Publisher¶

The Publisher process is responsible for sending commands over the designated transport to connected minions. The Publisher is bound to the following:
Each salt minion establishes a connection to the master Publisher.

EventPublisher¶

The EventPublisher publishes events onto the event bus. It is bound to the following:

MWorker¶

Worker processes manage the back-end operations for the Salt Master. The number of workers is equivalent to the number of 'worker_threads' specified in the master configuration and is always at least one. Workers are bound to the following:

ReqServer¶

The Salt request server takes requests and distributes them to available MWorker processes for processing. It also receives replies back from minions.
Each salt minion establishes a connection to the master ReqServer.

Job Flow¶

The Salt master works by always publishing commands to all connected minions and the minions decide if the command is meant for them by checking themselves against the command target. The typical lifecycle of a salt job from the perspective of the master might be as follows:
2) The 'salt' command uses LocalClient to generate a request to the salt master by connecting to the ReqServer on TCP:4506 and issuing the job. 3) The salt-master ReqServer sees the request and passes it to an available MWorker over workers.ipc. 4) A worker picks up the request and handles it. First, it checks to ensure that the requested user has permissions to issue the command. Then, it sends the publish command to all connected minions. For the curious, this happens in ClearFuncs.publish(). 5) The worker announces on the master event bus that it is about to publish a job to connected minions. This happens by placing the event on the master event bus (master_event_pull.ipc) where the EventPublisher picks it up and distributes it to all connected event listeners on master_event_pub.ipc. 6) The message to the minions is encrypted and sent to the Publisher via IPC on publish_pull.ipc. 7) Connected minions have a TCP session established with the Publisher on TCP port 4505 where they await commands. When the Publisher receives the job over publish_pull, it sends the jobs across the wire to the minions for processing. 8) After the minions receive the request, they decrypt it and perform any requested work, if they determine that they are targeted to do so. 9) When the minion is ready to respond, it publishes the result of its job back to the master by sending the encrypted result back to the master on TCP 4506 where it is again picked up by the ReqServer and forwarded to an available MWorker for processing. (Again, this happens by passing this message across workers.ipc to an available worker.) 10) When the MWorker receives the job it decrypts it and fires an event onto the master event bus (master_event_pull.ipc). (Again for the curious, this happens in AESFuncs._return(). 11) The EventPublisher sees this event and re-publishes it on the bus to all connected listeners of the master event bus (on master_event_pub.ipc). This is where the LocalClient has been waiting, listening to the event bus for minion replies. It gathers the job and stores the result. 12) When all targeted minions have replied or the timeout has been exceeded, the salt client displays the results of the job to the user on the CLI.

Salt Minion¶

Overview¶

The salt-minion is a single process that sits on machines to be managed by Salt. It can either operate as a stand-alone daemon which accepts commands locally via 'salt-call' or it can connect back to a master and receive commands remotely. When starting up, salt minions connect _back_ to a master defined in the minion config file. The connect to two ports on the master:

Event System¶

Similar to the master, a salt-minion has its own event system that operates over IPC by default. The minion event system operates on a push/pull system with IPC files at minion_event_<unique_id>_pub.ipc and minion_event_<unique_id>_pull.ipc. The astute reader might ask why have an event bus at all with a single-process daemon. The answer is that the salt-minion may fork other processes as required to do the work without blocking the main salt-minion process and this necessitates a mechanism by which those processes can communicate with each other. Secondarily, this provides a bus by which any user with sufficient permissions can read or write to the bus as a common interface with the salt minion.

Job Flow¶

When a salt minion starts up, it attempts to connect to the Publisher and the ReqServer on the salt master. It then attempts to authenticate and once the minion has successfully authenticated, it simply listens for jobs. Jobs normally come either come from the 'salt-call' script run by a local user on the salt minion or they can come directly from a master.

Master Job Flow¶

1) A master publishes a job that is received by a minion as outlined by the master's job flow above. 2) The minion is polling its receive socket that's connected to the master Publisher (TCP 4505 on master). When it detects an incoming message, it picks it up from the socket and decrypts it. 3) A new minion process or thread is created and provided with the contents of the decrypted message. The _thread_return() method is provided with the contents of the received message. 4) The new minion thread is created. The _thread_return() function starts up and actually calls out to the requested function contained in the job.
6) The result of the function that's run is encrypted and returned to the master's ReqServer (TCP 4506 on master). [Still in thread.] 7) Thread exits. Because the main thread was only blocked for the time that it took to initialize the worker thread, many other requests could have been received and processed during this time.

A Note on ClearFuncs vs. AESFuncs¶

A common source of confusion is determining when messages are passed in the clear and when they are passed using encryption. There are two rules governing this behaviour: 1) ClearFuncs is used for intra-master communication and during the initial authentication handshake between a minion and master during the key exhange.

Contributing¶

There is a great need for contributions to Salt and patches are welcome! The goal here is to make contributions clear, make sure there is a trail for where the code has come from, and most importantly, to give credit where credit is due! There are a number of ways to contribute to Salt development. For details on how to contribute documentation improvements please review Writing Salt Documentation.

Salt Coding Style¶

SaltStack has its own coding style guide that informs contributors on various coding approaches. Please review the Salt Coding Style documentation for information about Salt's particular coding patterns. Within the Salt Coding Style documentation, there is a section about running Salt's .pylintrc file. SaltStack recommends running the .pylintrc file on any files you are changing with your code contribution before submitting a pull request to Salt's repository. Please see the Linting documentation for more information.

Sending a GitHub pull request¶

Sending pull requests on GitHub is the preferred method for receiving contributions. The workflow advice below mirrors GitHub's own guide and is well worth reading.
NOTE:

Which Salt branch?¶

GitHub will open pull requests against Salt's main branch, develop, by default. Ideally, features should go into develop and bug fixes and documentation changes should go into the oldest supported release branch affected by the bug or documentation update. See Sending a GitHub pull request. If you have a bug fix or doc change and have already forked your working branch from develop and do not know how to rebase your commits against another branch, then submit it to develop anyway and we'll be sure to back-port it to the correct place.

The current release branch¶

The current release branch is the most recent stable release. Pull requests containing bug fixes should be made against the release branch. The branch name will be a date-based name such as 2016.3. Bug fixes are made on this branch so that minor releases can be cut from this branch without introducing surprises and new features. This approach maximizes stability. The Salt development team will "merge-forward" any fixes made on the release branch to the develop branch once the pull request has been accepted. This keeps the fix in isolation on the release branch and also keeps the develop branch up-to-date. NOTE:

The develop branch¶

The develop branch is unstable and bleeding-edge. Pull requests containing feature additions or non-bug-fix changes should be made against the develop branch. The Salt development team will back-port bug fixes made to develop to the current release branch if the contributor cannot create the pull request against that branch.

Keeping Salt Forks in Sync¶

Salt is advancing quickly. It is therefore critical to pull upstream changes from upstream into your fork on a regular basis. Nothing is worse than putting hard work into a pull request only to see bunches of merge conflicts because it has diverged too far from upstream. SEE ALSO:
The following assumes origin is the name of your fork and upstream is the name of the main saltstack/salt repository.

Posting patches to the mailing list¶

Patches will also be accepted by email. Format patches using git format-patch and send them to the salt-users mailing list. The contributor will then get credit for the patch, and the Salt community will have an archive of the patch and a place for discussion.

Backporting Pull Requests¶

If a bug is fixed on develop and the bug is also present on a currently-supported release branch it will need to be back-ported to all applicable branches. NOTE:
It is often easiest to fix a bug on the oldest supported release branch and then merge that branch forward into develop (as described earlier in this document). When that is not possible the fix must be back-ported, or copied, into any other affected branches. These steps assume a pull request #1234 has been merged into develop. And upstream is the name of the remote pointing to the main Salt repo.

Issue and Pull Request Labeling System¶

SaltStack uses several labeling schemes to help facilitate code contributions and bug resolution. See the Labels and Milestones documentation for more information.

Deprecating Code¶

Salt should remain backwards compatible, though sometimes, this backwards compatibility needs to be broken because a specific feature and/or solution is no longer necessary or required. At first one might think, let me change this code, it seems that it's not used anywhere else so it should be safe to remove. Then, once there's a new release, users complain about functionality which was removed and they where using it, etc. This should, at all costs, be avoided, and, in these cases, that specific code should be deprecated. In order to give users enough time to migrate from the old code behavior to the new behavior, the deprecation time frame should be carefully determined based on the significance and complexity of the changes required by the user. Salt feature releases are based on the Periodic Table. Any new features going into the develop branch will be named after the next element in the Periodic Table. For example, Beryllium was the feature release name of the develop branch before the 2015.8 branch was tagged. At that point in time, any new features going into the develop branch after 2015.8 was branched were part of the Boron feature release. A deprecation warning should be in place for at least two major releases before the deprecated code and its accompanying deprecation warning are removed. More time should be given for more complex changes. For example, if the current release under development is Sodium, the deprecated code and associated warnings should remain in place and warn for at least Aluminum. To help in this deprecation task, salt provides salt.utils.warn_until. The idea behind this helper function is to show the deprecation warning to the user until salt reaches the provided version. Once that provided version is equaled salt.utils.warn_until will raise a RuntimeError making salt stop its execution. This stoppage is unpleasant and will remind the developer that the deprecation limit has been reached and that the code can then be safely removed. Consider the following example:
Development begins on the Aluminum release when the Magnesium branch is forked from the develop branch. Once this occurs, all uses of the warn_until function targeting Aluminum, along with the code they are warning about should be removed from the code.

Dunder Dictionaries¶

Salt provides several special "dunder" dictionaries as a convenience for Salt development. These include __opts__, __context__, __salt__, and others. This document will describe each dictionary and detail where they exist and what information and/or functionality they provide.

__opts__¶

Available in¶

The __opts__ dictionary contains all of the options passed in the configuration file for the master or minion. NOTE:
The configuration file data made available in the __opts__ dictionary is the configuration data relative to the running daemon. If the modules are loaded and executed by the master, then the master configuration data is available, if the modules are executed by the minion, then the minion configuration is available. Any additional information passed into the respective configuration files is made available

__salt__¶

Available in¶

__salt__ contains the execution module functions. This allows for all functions to be called as they have been set up by the salt loader.
NOTE:

__grains__¶

Available in¶

The __grains__ dictionary contains the grains data generated by the minion that is currently being worked with. In execution modules, state modules and returners this is the grains of the minion running the calls, when generating the external pillar the __grains__ is the grains data from the minion that the pillar is being generated for.

__pillar__¶

Available in¶

The __pillar__ dictionary contains the pillar for the respective minion.

__context__¶

__context__ exists in state modules and execution modules. During a state run the __context__ dictionary persists across all states that are run and then is destroyed when the state ends. When running an execution module __context__ persists across all module executions until the modules are refreshed; such as when saltutil.sync_all or state.apply are executed. A great place to see how to use __context__ is in the cp.py module in salt/modules/cp.py. The fileclient authenticates with the master when it is instantiated and then is used to copy files to the minion. Rather than create a new fileclient for each file that is to be copied down, one instance of the fileclient is instantiated in the __context__ dictionary and is reused for each file. Here is an example from salt/modules/cp.py:
NOTE:

External Pillars¶

Salt provides a mechanism for generating pillar data by calling external pillar interfaces. This document will describe an outline of an ext_pillar module.

Location¶

Salt expects to find your ext_pillar module in the same location where it looks for other python modules. If the extension_modules option in your Salt master configuration is set, Salt will look for a pillar directory under there and load all the modules it finds. Otherwise, it will look in your Python site-packages salt/pillar directory.

Configuration¶

The external pillars that are called when a minion refreshes its pillars is controlled by the ext_pillar option in the Salt master configuration. You can pass a single argument, a list of arguments or a dictionary of arguments to your pillar:

The Module¶

Imports and Logging¶

Import modules your external pillar module needs. You should first include generic modules that come with stock Python:
And then start logging. This is an idiomatic way of setting up logging in Salt:
Finally, load modules that are specific to what you are doing. You should catch import errors and set a flag that the __virtual__ function can use later.

Options¶

If you define an __opts__ dictionary, it will be merged into the __opts__ dictionary handed to the ext_pillar function later. This is a good place to put default configuration items. The convention is to name things modulename.option.

Initialization¶

If you define an __init__ function, it will be called with the following signature:
Note: The __init__ function is ran every time a particular minion causes the external pillar to be called, so don't put heavy initialization code here. The __init__ functionality is a side-effect of the Salt loader, so it may not be as useful in pillars as it is in other Salt items.

__virtual__¶

If you define a __virtual__ function, you can control whether or not this module is visible. If it returns False then Salt ignores this module. If it returns a string, then that string will be how Salt identifies this external pillar in its ext_pillar configuration. If you're not renaming the module, simply return True in the __virtual__ function, which is the same as if this function did not exist, then, the name Salt's ext_pillar will use to identify this module is its conventional name in Python. This is useful to write modules that can be installed on all Salt masters, but will only be visible if a particular piece of software your module requires is installed.

ext_pillar¶

This is where the real work of an external pillar is done. If this module is active and has a function called ext_pillar, whenever a minion updates its pillar this function is called. How it is called depends on how it is configured in the Salt master configuration. The first argument is always the current pillar dictionary, this contains pillar items that have already been added, starting with the data from pillar_roots, and then from any already-ran external pillars. Using our example above:
In the example_a case, pillar will contain the items from the pillar_roots, in example_b pillar will contain that plus the items added by example_a, and in example_c pillar will contain that plus the items added by example_b. In all three cases, id will contain the ID of the minion making the pillar request. This function should return a dictionary, the contents of which are merged in with all of the other pillars and returned to the minion. Note: this function is called once for each minion that fetches its pillar data.
You can call pillar with the dictionary's top name to retrieve its data. From above example, 'external_pillar' is the top dictionary name. Therefore:
You shouldn't just add items to pillar and return that, since that will cause Salt to merge data that already exists. Rather, just return the items you are adding or changing. You could, however, use pillar in your module to make some decision based on pillar data that already exists. This function has access to some useful globals:

Example configuration¶

As an example, if you wanted to add external pillar via the cmd_json external pillar, add something like this to your master config:

Reminder¶

Just as with traditional pillars, external pillars must be refreshed in order for minions to see any fresh data:

Installing Salt for development¶

Clone the repository using:
NOTE:
Create a new virtualenv:
Avoid making your virtualenv path too long. On Arch Linux, where Python 3 is the default installation of Python, use the virtualenv2 command instead of virtualenv. On Gentoo you must use --system-site-packages to enable pkg and portage_config functionality NOTE:
NOTE:
Activate the virtualenv:
Install Salt (and dependencies) into the virtualenv:
NOTE:
NOTE:
NOTE:
WARNING:

Running a self-contained development version¶

During development it is easiest to be able to run the Salt master and minion that are installed in the virtualenv you created above, and also to have all the configuration, log, and cache files contained in the virtualenv as well. Copy the master and minion config files into your virtualenv:
Edit the master config file:
Edit the minion config file:
NOTE:
Start the master and minion, accept the minion's key, and verify your local Salt installation is working:
Running the master and minion in debug mode can be helpful when developing. To do this, add -l debug to the calls to salt-master and salt-minion. If you would like to log to the console instead of to the log file, remove the -d. NOTE:
NOTE:

Changing Default Paths¶

Instead of updating your configuration files to point to the new root directory and having to pass the new configuration directory path to all of Salt's CLI tools, you can explicitly tweak the default system paths that Salt expects:
You can now call all of Salt's CLI tools without explicitly passing the configuration directory.

Additional Options¶

In case you want to distribute your virtualenv, you probably don't want to include Salt's clone .git/ directory, and, without it, Salt won't report the accurate version. You can tell setup.py to generate the hardcoded version information which is distributable:
Instead of passing those two environmental variables, you can just pass a single one which will trigger the other two:
This last one will grant you an editable salt installation with hardcoded system paths and version information.

Installing Salt from the Python Package Index¶

If you are installing using easy_install, you will need to define a USE_SETUPTOOLS environment variable, otherwise dependencies will not be installed:

Editing and previewing the documentation¶

You need sphinx-build command to build the docs. In Debian/Ubuntu this is provided in the python-sphinx package. Sphinx can also be installed to a virtualenv using pip:
Change to salt documentation directory, then:




Once you've updated the documentation, you can run the following command to launch a simple Python HTTP server to see your changes:

Running unit and integration tests¶

Run the test suite with following command:
See here for more information regarding the test suite.

Issue and Pull Request Labeling System¶

SaltStack uses several labeling schemes to help facilitate code contributions and bug resolution. See the Labels and Milestones documentation for more information.

GitHub Labels and Milestones¶

SaltStack uses several label categories, as well as milestones, to triage incoming issues and pull requests in the GitHub issue tracker. Labels are used to sort issues by type, priority, severity, status, functional area, functional group, and targeted release and pull requests by status, functional area, functional group, type of change, and test status. Milestones are used to indicate whether an issue is fully triaged or is scheduled to be fixed by SaltStack in an upcoming sprint.

Milestones¶

All issues are assigned to a milestone, whereas pull requests are almost never assigned to a milestone as the mean lifetime of pull requests is short enough that there is no need to track them temporally. SaltStack uses milestones to indicate which issues are blocked on submitter or upstream actions, are approved, or are scheduled to be fixed or implemented in an upcoming sprint. If an issue is not attached to a sprint milestone, you are welcome to work on it at your own desire and convenience. If it is attached to a sprint milestone and you have already begun working on it or have a solution in mind or have other ideas related to the issue, you are encouraged to coordinate with the assignee via the GitHub issue tracker to create the best possible solution or implementation.

Labels¶

Labels are used to sort and describe issues and pull requests. Some labels are usually reserved for one or the other, though most labels may be applied to both. New issues will receive at least one label and a milestone, and new pull requests will receive at least one label. Except for the functional area and functional group label categories, issues will generally receive only up to one label per category.

Type¶

Issues are categorized into one of several types. Type labels are almost never used for pull requests. GitHub treats pull requests like issues in many ways, so a pull request could be considered an issue with an implicit Pull Request type label applied.

Priority¶

An issue's priority is relative to its functional area. If a bug report, for example, about gitfs indicates that all users of gitfs will encounter this bug, then a P1 label will be applied, even though users who are not using gitfs will not encounter the bug. If a feature is requested by many users, it may be given a high priority.

Severity¶

Severity labels are almost always only applied to issues labeled Bug.

Functional Area¶

Many major components of Salt have corresponding GitHub labels. These labels are applied to all issues and pull requests as is reasonably appropriate. They are useful in organizing issues and pull requests according to the source code relevant to issues or the source code changed by pull requests.

Functional Group¶

These labels sort issues and pull requests according to the internal SaltStack engineering teams.

Status¶

Status labels are used to define and track the state of issues and pull requests. Not all potential statuses correspond to a label, but some statuses are common enough that labels have been created for them. If an issue has not been moved beyond the Blocked milestone, it is very likely that it will only have a status label.

Type of Change¶

Every pull request should receive a change label. These labels measure the quantity of change as well as the significance of the change. The amount of change and the importance of the code area changed are considered, but often the depth of secondary code review required and the potential repercussions of the change may also advise the label choice. Core code areas include: state compiler, crypto engine, master and minion and syndic daemons, transport, pillar rendering, loader, transport layer, event system, salt.utils, client, cli, logging, netapi, runner engine, templating engine, top file compilation, file client, file server, mine, salt-ssh, test runner, etc. Non-core code usually constitutes the specific set of plugins for each of the several plugin layers of Salt: execution modules, states, runners, returners, clouds, etc.

Test Status¶

These labels relate to the status of the automated tests that run on pull requests. If the tests on a pull request fail and are not overridden by one of these labels, the pull request submitter needs to update the code and/or tests so that the tests pass and the pull request can be merged.

Other¶

These labels indicate miscellaneous issue types or statuses that are common or important enough to be tracked and sorted with labels.

Logging Internals¶

TODO

Modular Systems¶

When first working with Salt, it is not always clear where all of the modular components are and what they do. Salt comes loaded with more modular systems than many users are aware of, making Salt very easy to extend in many places. The most commonly used modular systems are execution modules and states. But the modular systems extend well beyond the more easily exposed components and are often added to Salt to make the complete system more flexible.

Execution Modules¶

Execution modules make up the core of the functionality used by Salt to interact with client systems. The execution modules create the core system management library used by all Salt systems, including states, which interact with minion systems. Execution modules are completely open ended in their execution. They can be used to do anything required on a minion, from installing packages to detecting information about the system. The only restraint in execution modules is that the defined functions always return a JSON serializable object. For a list of all built in execution modules, click here For information on writing execution modules, see this page.

Interactive Debugging¶

Sometimes debugging with print() and extra logs sprinkled everywhere is not the best strategy. IPython is a helpful debug tool that has an interactive python environment which can be embedded in python programs. First the system will require IPython to be installed.
Now, in the troubling python module, add the following line at a location where the debugger should be started:
After running a Salt command that hits that line, the following will show up in the log file:
Now on the system that invoked embed_kernel, run the following command from a shell:
This provides a console that has access to all the vars and functions, and even supports tab-completion.
To exit IPython and continue running Salt, press Ctrl-d to logout.

State Modules¶

State modules are used to define the state interfaces used by Salt States. These modules are restrictive in that they must follow a number of rules to function properly. NOTE:

Auth¶

The auth module system allows for external authentication routines to be easily added into Salt. The auth function needs to be implemented to satisfy the requirements of an auth module. Use the pam module as an example.

Fileserver¶

The fileserver module system is used to create fileserver backends used by the Salt Master. These modules need to implement the functions used in the fileserver subsystem. Use the gitfs module as an example.

Grains¶

Grain modules define extra routines to populate grains data. All defined public functions will be executed and MUST return a Python dict object. The dict keys will be added to the grains made available to the minion.

Output¶

The output modules supply the outputter system with routines to display data in the terminal. These modules are very simple and only require the output function to execute. The default system outputter is the nested module.

Pillar¶

Used to define optional external pillar systems. The pillar generated via the filesystem pillar is passed into external pillars. This is commonly used as a bridge to database data for pillar, but is also the backend to the libvirt state used to generate and sign libvirt certificates on the fly.

Renderers¶

Renderers are the system used to render sls files into salt highdata for the state compiler. They can be as simple as the py renderer and as complex as stateconf and pydsl.

Returners¶

Returners are used to send data from minions to external sources, commonly databases. A full returner will implement all routines to be supported as an external job cache. Use the redis returner as an example.

Runners¶

Runners are purely master-side execution sequences.

Tops¶

Tops modules are used to convert external data sources into top file data for the state system.

Wheel¶

The wheel system is used to manage master side management routines. These routines are primarily intended for the API to enable master configuration.

Package Providers¶

This page contains guidelines for writing package providers.

Package Functions¶

One of the most important features of Salt is package management. There is no shortage of package managers, so in the interest of providing a consistent experience in pkg states, there are certain functions that should be present in a package provider. Note that these are subject to change as new features are added or existing features are enhanced.

list_pkgs¶

This function should declare an empty dict, and then add packages to it by calling pkg_resource.add_pkg, like so:
The last thing that should be done before returning is to execute pkg_resource.sort_pkglist. This function does not presently do anything to the return dict, but will be used in future versions of Salt.
list_pkgs returns a dictionary of installed packages, with the keys being the package names and the values being the version installed. Example return data:

latest_version¶

Accepts an arbitrary number of arguments. Each argument is a package name. The return value for a package will be an empty string if the package is not found or if the package is up-to-date. The only case in which a non-empty string is returned is if the package is available for new installation (i.e. not already installed) or if there is an upgrade available. If only one argument was passed, this function return a string, otherwise a dict of name/version pairs is returned. This function must also accept **kwargs, in order to receive the fromrepo and repo keyword arguments from pkg states. Where supported, these arguments should be used to find the install/upgrade candidate in the specified repository. The fromrepo kwarg takes precedence over repo, so if both of those kwargs are present, the repository specified in fromrepo should be used. However, if repo is used instead of fromrepo, it should still work, to preserve backwards compatibility with older versions of Salt.

version¶

Like latest_version, accepts an arbitrary number of arguments and returns a string if a single package name was passed, or a dict of name/value pairs if more than one was passed. The only difference is that the return values are the currently-installed versions of whatever packages are passed. If the package is not installed, an empty string is returned for that package.

upgrade_available¶

Deprecated and destined to be removed. For now, should just do the following:

install¶

The following arguments are required and should default to None:
The first thing that this function should do is call pkg_resource.parse_targets (see below). This function will convert the SLS input into a more easily parsed data structure. pkg_resource.parse_targets may need to be modified to support your new package provider, as it does things like parsing package metadata which cannot be done for every package management system.
Two values will be returned to the install function. The first of them will be a dictionary. The keys of this dictionary will be package names, though the values will differ depending on what kind of installation is being done:
The second return value will be a string with two possible values: repository or file. The install function can use this value (if necessary) to build the proper command to install the targeted package(s). Both before and after the installing the target(s), you should run list_pkgs to obtain a list of the installed packages. You should then return the output of salt.utils.compare_dicts()

remove¶

Removes the passed package and return a list of the packages removed.

Package Repo Functions¶

There are some functions provided by pkg which are specific to package repositories, and not to packages themselves. When writing modules for new package managers, these functions should be made available as stated below, in order to provide compatibility with the pkgrepo state. All repo functions should accept a basedir option, which defines which directory repository configuration should be found in. The default for this is dictated by the repo manager that is being used, and rarely needs to be changed.

list_repos¶

Lists the repositories that are currently configured on this system.
Returns a dictionary, in the following format:

get_repo¶

Displays all local configuration for a specific repository.
The information is formatted in much the same way as list_repos, but is specific to only one repo.

del_repo¶

Removes the local configuration for a specific repository. Requires a repo argument, which must match the locally configured name. This function returns a string, which informs the user as to whether or not the operation was a success.

mod_repo¶

Modify the local configuration for one or more option for a configured repo. This is also the way to create new repository configuration on the local system; if a repo is specified which does not yet exist, it will be created. The options specified for this function are specific to the system; please refer to the documentation for your specific repo manager for specifics.

Low-Package Functions¶

In general, the standard package functions as describes above will meet your needs. These functions use the system's native repo manager (for instance, yum or the apt tools). In most cases, the repo manager is actually separate from the package manager. For instance, yum is usually a front-end for rpm, and apt is usually a front-end for dpkg. When possible, the package functions that use those package managers directly should do so through the low package functions. It is normal and sane for pkg to make calls to lowpkgs, but lowpkg must never make calls to pkg. This is affects functions which are required by both pkg and lowpkg, but the technique in pkg is more performant than what is available to lowpkg. When this is the case, the lowpkg function that requires that technique must still use the lowpkg version.

list_pkgs¶

Returns a dict of packages installed, including the package name and version. Can accept a list of packages; if none are specified, then all installed packages will be listed.
Example output:

verify¶

Many (but not all) package management systems provide a way to verify that the files installed by the package manager have or have not changed. This function accepts a list of packages; if none are specified, all packages will be included.
Example output:

file_list¶

Lists all of the files installed by all packages specified. If not packages are specified, then all files for all known packages are returned.
This function does not return which files belong to which packages; all files are returned as one giant list (hence the file_list function name. However, This information is still returned inside of a dict, so that it can provide any errors to the user in a sane manner.

file_dict¶

Lists all of the files installed by all packages specified. If not packages are specified, then all files for all known packages are returned.
Unlike file_list, this function will break down which files belong to which packages. It will also return errors in the same manner as file_list.

Reporting Bugs¶

Salt uses GitHub to track open issues and feature requests. To file a bug, please navigate to the new issue page for the Salt project. In an issue report, please include the following information:

Salt Topology¶

Salt is based on a powerful, asynchronous, network topology using ZeroMQ. Many ZeroMQ systems are in place to enable communication. The central idea is to have the fastest communication possible.

Servers¶

The Salt Master runs 2 network services. First is the ZeroMQ PUB system. This service by default runs on port 4505 and can be configured via the publish_port option in the master configuration. Second is the ZeroMQ REP system. This is a separate interface used for all bi-directional communication with minions. By default this system binds to port 4506 and can be configured via the ret_port option in the master.

PUB/SUB¶

The commands sent out via the salt client are broadcast out to the minions via ZeroMQ PUB/SUB. This is done by allowing the minions to maintain a connection back to the Salt Master and then all connections are informed to download the command data at once. The command data is kept extremely small (usually less than 1K) so it is not a burden on the network.

Return¶

The PUB/SUB system is a one way communication, so once a publish is sent out the PUB interface on the master has no further communication with the minion. The minion, after running the command, then sends the command's return data back to the master via the ret_port.

Translating Documentation¶

If you wish to help translate the Salt documentation to your language, please head over to the Transifex website and signup for an account. Once registered, head over to the Salt Translation Project, and either click on Request Language if you can't find yours, or, select the language for which you wish to contribute and click Join Team. Transifex provides some useful reading resources on their support domain, namely, some useful articles directed to translators.

Building A Localized Version of the Documentation¶

While you're working on your translation on Transifex, you might want to have a look at how it's rendering.

Install The Transifex Client¶

To interact with the Transifex web service you will need to install the transifex-client:

Configure The Transifex Client¶

Once installed, you will need to set it up on your computer. We created a script to help you with that:

Download Remote Translations¶

There's a little script which simplifies the download process of the translations(which isn't that complicated in the first place). So, let's assume you're translating pt_PT, Portuguese(Portugal). To download the translations, execute from the doc/ directory of your Salt checkout:
To download pt_PT, Portuguese(Portugal), and nl, Dutch, you can use the helper script directly:

Build Localized Documentation¶

After the download process finishes, which might take a while, the next step is to build a localized version of the documentation. Following the pt_PT example above:

View Localized Documentation¶

Open your browser, point it to the local documentation path and check the localized output you've just build.

Developing Salt Tutorial¶

This tutorial assumes you have:

Fork¶

In your browser, navigate to the saltstack/salt GitHub repository. Click on Fork (https://github.com/saltstack/salt/#fork-destination-box). NOTE:

Clone¶

In your CLI, navigate to the directory into which you want clone the Salt codebase and submit the following command:
where <my_account> is the name of your GitHub account. After the clone has completed, add SaltStack as a second remote and fetch any changes from upstream.
For this tutorial, we will be working off from the develop branch, which is the default branch for the SaltStack GitHub project. This branch needs to track upstream/develop so that we will get all upstream changes when they happen.

Fetch¶

Fetch any upstream changes on the develop branch and sync them to your local copy of the branch with a single command:
NOTE:

Branch¶

Now we are ready to get to work. Consult the sprint beginner bug list and select an execution module whose __virtual__ function needs to be updated. I'll select the alternatives module. Create a new branch off from develop. Be sure to name it something short and descriptive.

Edit¶

Edit the file you have selected, and verify that the changes are correct.

Commit¶

Stage and commit the changes. Write a descriptive commit summary, but try to keep it less than 50 characters. Review your commit.
NOTE:

Push¶

Push your branch to your GitHub account. You will likely need to enter your GitHub username and password.
NOTE:

Merge¶

In your browser, navigate to the new pull request page on the saltstack/salt GitHub repository and click on compare across forks. Select <my_account> from the list of head forks and the branch you are wanting to merge into develop (virt_ret in this case). When you have finished reviewing the changes, click Create pull request. If your pull request contains only a single commit, the title and comment will be taken from that commit's summary and message, otherwise the branch name is used for the title. Edit these fields as necessary and click Create pull request. NOTE:

Resources¶

GitHub offers many great tutorials on various aspects of the git- and GitHub-centric development workflow: https://help.github.com/ There are many topics covered by the Salt Developer documentation: https://docs.saltstack.com/en/latest/topics/development/index.html The contributing documentation presents more details on specific contributing topics: https://docs.saltstack.com/en/latest/topics/development/contributing.html

Salt Extend¶

salt-extend is a templating tool for extending SaltStack. If you're looking to add a module to SaltStack, then the salt-extend utility can guide you through the process. You can use Salt Extend to quickly create templated modules for adding new behaviours to some of the module subsystems within Salt. Salt Extend takes a template directory and merges it into a SaltStack source code directory.

Command line usage¶

See salt-extend

Choosing a template¶

The following templates are available:

module¶

Creates a new execution module within salt/modules/{{module_name}}.py

module_unit¶

Creates a new execution module unit test suite within tests/unit/modules/{{module_name}}_test.py

state¶

Creates a new state module within salt/states/{{module_name}}.py

state_unit¶

Creates a new state module unit test suite within tests/unit/states/{{module_name}}_test.py

Adding templates¶

Example template.yml¶

NOTE:

Example file in the template directory¶

Default context properties¶

The default context provides the following properties
As well as any additional properties entered from the questions section of template.yml

API¶

SaltStack Extend¶

A templating tool for extending SaltStack. Takes a template directory and merges it into a SaltStack source code directory. This tool uses Jinja2 for templating. This tool is accessed using salt-extend

Salt's Test Suite¶

Salt comes with a powerful integration and unit test suite allowing for the fully automated run of integration and/or unit tests from a single interface. To learn the basics of how Salt's test suite works, be sure to check out the Salt's Test Suite: An Introduction tutorial.

Test Directory Structure¶

Salt's test suite is located in the tests directory in the root of Salt's codebase. The test suite is divided into two main groups:
Within each of these groups, the directory structure roughly mirrors the structure of Salt's own codebase. Notice that there are directories for states, modules, runners, output, and more in each testing group. The files that are housed in the modules directory of either the unit or the integration testing factions contain respective integration or unit test files for Salt execution modules.

Integration Tests¶

The Integration section of Salt's test suite start up a number of Salt daemons to test functionality in a live environment. These daemons include two Salt Masters, one Syndic, and two Minions. This allows the Syndic interface to be tested and Master/Minion communication to be verified. All of the integration tests are executed as live Salt commands sent through the started daemons. Integration tests are particularly good at testing modules, states, and shell commands, among other segments of Salt's ecosystem. By utilizing the integration test daemons, integration tests are easy to write. They are also SaltStack's generally preferred method of adding new tests. The discussion in the Integration vs. Unit section of the testing tutorial is beneficial in learning why you might want to write integration tests vs. unit tests. Both testing arenas add value to Salt's test suite and you should consider adding both types of tests if possible and appropriate when contributing to Salt.

Unit Tests¶

Unit tests do not spin up any Salt daemons, but instead find their value in testing singular implementations of individual functions. Instead of testing against specific interactions, unit tests should be used to test a function's logic as well as any return or raises statements. Unit tests also rely heavily on mocking external resources. The discussion in the Integration vs. Unit section of the testing tutorial is useful in determining when you should consider writing unit tests instead of, or in addition to, integration tests when contributing to Salt.

Running The Tests¶

There are requirements, in addition to Salt's requirements, which need to be installed in order to run the test suite. Install one of the lines below, depending on the relevant Python version:
To be able to run integration tests which utilizes ZeroMQ transport, you also need to install additional requirements for it. Make sure you have installed the C/C++ compiler and development libraries and header files needed for your Python version. This is an example for RedHat-based operating systems:
On Debian, Ubuntu or their derivatives run the following commands:
This will install the latest pycrypto and pyzmq (with bundled libzmq) Python modules required for running integration tests suite. Once all requirements are installed, use runtests.py script to run all of the tests included in Salt's test suite:
For more information about options you can pass the test runner, see the --help option:
An alternative way of invoking the test suite is available in setup.py:

Running Test Subsections¶

Instead of running the entire test suite all at once, which can take a long time, there are several ways to run only specific groups of tests or individual tests:
For more specific examples of how to run various test subsections or individual tests, please see the Test Selection Options documentation or the Running Specific Tests section of the Salt's Test Suite: An Introduction tutorial.

Running Unit Tests Without Integration Test Daemons¶

Since the unit tests do not require a master or minion to execute, it is often useful to be able to run unit tests individually, or as a whole group, without having to start up the integration testing daemons. Starting up the master, minion, and syndic daemons takes a lot of time before the tests can even start running and is unnecessary to run unit tests. To run unit tests without invoking the integration test daemons, simply run the runtests.py script with --unit argument:
All of the other options to run individual tests, entire classes of tests, or entire test modules still apply.

Running Destructive Integration Tests¶

Salt is used to change the settings and behavior of systems. In order to effectively test Salt's functionality, some integration tests are written to make actual changes to the underlying system. These tests are referred to as "destructive tests". Some examples of destructive tests are changes may be testing the addition of a user or installing packages. By default, destructive tests are disabled and will be skipped. Generally, destructive tests should clean up after themselves by attempting to restore the system to its original state. For instance, if a new user is created during a test, the user should be deleted after the related test(s) have completed. However, no guarantees are made that test clean-up will complete successfully. Therefore, running destructive tests should be done with caution. NOTE:
To run tests marked as destructive, set the --run-destructive flag:

Running Cloud Provider Tests¶

Salt's testing suite also includes integration tests to assess the successful creation and deletion of cloud instances using Salt-Cloud for providers supported by Salt-Cloud. The cloud provider tests are off by default and run on sample configuration files provided in tests/integration/files/conf/cloud.providers.d/. In order to run the cloud provider tests, valid credentials, which differ per provider, must be supplied. Each credential item that must be supplied is indicated by an empty string value and should be edited by the user before running the tests. For example, DigitalOcean requires a client key and an api key to operate. Therefore, the default cloud provider configuration file for DigitalOcean looks like this:
As indicated by the empty string values, the client_key and the api_key must be provided:
NOTE:
Once all of the valid credentials for the cloud provider have been supplied, the cloud provider tests can be run by setting the --cloud-provider-tests flag:

Running The Tests In A Docker Container¶

The test suite can be executed under a docker container using the --docked option flag. The docker container must be properly configured on the system invoking the tests and the container must have access to the internet. Here's a simple usage example:
The full docker container repository can also be provided:
The SaltStack team is creating some containers which will have the necessary dependencies pre-installed. Running the test suite on a container allows destructive tests to run without making changes to the main system. It also enables the test suite to run under a different distribution than the one the main system is currently using. The current list of test suite images is on Salt's docker repository. Custom docker containers can be provided by submitting a pull request against Salt's docker Salt test containers repository.

Automated Test Runs¶

SaltStack maintains a Jenkins server to allow for the execution of tests across supported platforms. The tests executed from Salt's Jenkins server create fresh virtual machines for each test run, then execute destructive tests on the new, clean virtual machine. SaltStack's Jenkins server continuously runs the entire test suite, including destructive tests, on an array of various supported operating systems throughout the day. Each actively supported branch of Salt's repository runs the tests located in the respective branch's code. Each set of branch tests also includes a pylint run. These branch tests help ensure the viability of Salt code at any given point in time as pull requests are merged into branches throughout the day. In addition to branch tests, SaltStack's Jenkins server also runs tests on pull requests. These pull request tests include a smaller set of virtual machines that run on the branch tests. The pull request tests, like the branch tests, include a pylint test as well. When a pull request is submitted to Salt's repository on GitHub, the suite of pull request tests are started by Jenkins. These tests are used to gauge the pull request's viability to merge into Salt's codebase. If these initial tests pass, the pull request can then merged into the Salt branch by one of Salt's core developers, pending their discretion. If the initial tests fail, core developers may request changes to the pull request. If the failure is unrelated to the changes in question, core developers may merge the pull request despite the initial failure. As soon as the pull request is merged, the changes will be added to the next branch test run on Jenkins. For a full list of currently running test environments, go to http://jenkins.saltstack.com.

Using Salt-Cloud on Jenkins¶

For testing Salt on Jenkins, SaltStack uses Salt-Cloud to spin up virtual machines. The script using Salt-Cloud to accomplish this is open source and can be found here: https://github.com/saltstack/salt/blob/develop/tests/jenkins.py

Writing Tests¶

The salt testing infrastructure is divided into two classes of tests, integration tests and unit tests. These terms may be defined differently in other contexts, but for Salt they are defined this way:
Salt testing uses unittest2 from the python standard library and MagicMock.

Naming Conventions¶

Any function in either integration test files or unit test files that is doing the actual testing, such as functions containing assertions, must start with test_:
When functions in test files are not prepended with test_, the function acts as a normal, helper function and is not run as a test by the test suite.

Submitting New Tests¶

Which branch of the Salt codebase should new tests be written against? The location of where new tests should be submitted depends largely on the reason you're writing the tests.

Tests for New Features¶

If you are adding new functionality to Salt, please write the tests for this new feature in the same pull request as the new feature. New features should always be submitted to the develop branch. If you have already submitted the new feature, but did not write tests in the original pull request that has already been merged, please feel free to submit a new pull request containing tests. If the feature was recently added to Salt's develop branch, then the tests should be added there as well. However, if the feature was added to develop some time ago and is already present in one or more release branches, please refer to the Tests for Entire Files or Functions section below for more details about where to submit tests for functions or files that do not already have tests.

Tests to Accompany a Bugfix¶

If you are writing tests for code that fixes a bug in Salt, please write the test in the same pull request as the bugfix. If you're unsure of where to submit your bugfix and accompanying test, please review the Which Salt Branch? documentation in Salt's Contributing guide.

Tests for Entire Files or Functions¶

Sometimes entire files in Salt are completely untested. If you are writing tests for a file that doesn't have any tests written for it, write your test against the earliest supported release branch that contains the file or function you're testing. Once your tests are submitted in a pull request and is merged into the branch in question, the tests you wrote will be merged-forward by SaltStack core engineers and the new tests will propagate to the newer release branches. That way the tests you wrote will apply to all current and relevant release branches, and not just the develop branch, for example. This methodology will help protect against regressions on older files in Salt's codebase. There may be times when the tests you write against an older branch fail in the merge-forward process because functionality has changed in newer release branches. In these cases, a Salt core developer may reach out to you for advice on the tests in question if the path forward is unclear. NOTE:

raet¶

# RAET # Reliable Asynchronous Event Transport Protocol SEE ALSO:

Protocol¶

Layering: OSI Layers 7: Application: Format: Data (Stack to Application interface buffering etc) 6: Presentation: Format: Data (Encrypt-Decrypt convert to machine independent format) 5: Session: Format: Data (Interhost communications. Authentication. Groups) 4: Transport: Format: Segments (Reliable delivery of Message, Transactions, Segmentation, Error checking) 3: Network: Format: Packets/Datagrams (Addressing Routing) 2: Link: Format: Frames ( Reliable per frame communications connection, Media access controller ) 1: Physical: Bits (Transceiver communication connection not reliable) Link is hidden from Raet Network is IP host address and Udp Port Transport is Raet transactions, service kind, tail error checking, Could include header signing as part of transport reliable delivery serialization of header Session is session id key exchange for signing. Grouping is Road (like 852 channel) Presentation is Encrypt Decrypt body Serialize Deserialize Body Application is body data dictionary Header signing spans both the Transport and Session layers.

Header¶

JSON Header (Tradeoff some processing speed for extensibility, ease of use, readability) Body initially JSON but support for "packed" binary body

Packet¶

Header ASCII Safe JSON Header termination: Empty line given by double pair of carriage return linefeed /r/n/r/n 10 13 10 13 ADAD 1010 1101 1010 1101 In json carriage return and newline characters cannot appear in a json encoded string unless they are escaped with backslash, so the 4 byte combination is illegal in valid json that does not have multi-byte unicode characters. These means the header must be ascii safe so no multibyte utf-8 strings allowed in header. Following Header Terminator is variable length signature block. This is binary and the length is provided in the header. Following the signature block is the packet body or data. This may either be JSON or packed binary. The format is given in the json header Finally is an optional tail block for error checking or encryption details

Header Fields¶

In UDP header sh = source host sp = source port dh = destination host dp = destination port In RAET Header hk = header kind hl = header length vn = version number sd = Source Device ID dd = Destination Device ID cf = Corresponder Flag mf = Multicast Flag si = Session ID ti = Transaction ID sk = Service Kind pk = Packet Kind bf = Burst Flag (Send all Segments or Ordered packets without interleaved acks) oi = Order Index dt = DateTime Stamp sn = Segment Number sc = Segment Count pf = Pending Segment Flag af = All Flag (Resent all Segments not just one) nk = Auth header kind nl = Auth header length bk = body kind bl = body length tk = tail kind tl = tail length

Session Bootstrap¶

Minion sends packet with SID of Zero with public key of minions Public Private Key pair Master acks packet with SID of Zero to let minion know it received the request Some time later Master sends packet with SID of zero that accepts the Minion Minion

Session¶

Session is important for security. Want one session opened and then multiple transactions within session. Session ID SID sid GUID hash to guarantee uniqueness since no guarantee of nonvolatile storage or require file storage to keep last session ID used.

Service Types or Modular Services¶

Four Service Types
Initially unicast messaging Eventually support for Multicast The use case for C) is to fragment large packets as once a UDP packet exceeds the frame size its reliability goes way down So its more reliable to fragment large packets. Better approach might be to have more modularity. Services Levels
Service Features
Always include transaction id since multiple transactions on same port So get duplicate detection for free if keep transaction alive but if use A) Maybe one or more B1) At Least One B2) Exactly One C) One of sequence D) End to End A) Sender creates transaction id for number of repeats but receiver does not keep transaction alive B1) Sender creates transaction id keeps it for retries. Receiver keeps it to send ack then kills so retry could be duplicate not detected B2) Sender creates transaction id keeps for retries Receiver keeps tid for acks on any retires so no duplicates. C) Sender creates TID and Sequence Number. Receiver checks for out of order sequence and can request retry. D) Application layer sends response. So question is do we keep transaction open or have response be new transaction. No because then we need a rep-req ID so might as well use the same transaction id. Just keep alive until get response. Little advantage to B1 vs B2 not having duplicates. So 4 service types
Also multicast or unicast Modular Transaction Table

SaltStack Git Policy¶

The SaltStack team follows a git policy to maintain stability and consistency with the repository. The git policy has been developed to encourage contributions and make contributing to Salt as easy as possible. Code contributors to SaltStack projects DO NOT NEED TO READ THIS DOCUMENT, because all contributions come into SaltStack via a single gateway to make it as easy as possible for contributors to give us code. The primary rule of git management in SaltStack is to make life easy on contributors and developers to send in code. Simplicity is always a goal!

New Code Entry¶

All new SaltStack code should be submitted against either the develop branch or a point release branch, depending on the nature of the submission. Please see the Which Salt Branch? section of Salt's Contributing documentation or the Release Branching section section below for more information.

Release Branching¶

SaltStack maintains two types of releases, Feature Releases and Point Releases (also commonly referred to as Bugfix Releases. A feature release is managed by incrementing the first or second release point number, so 2015.5.5 -> 2015.8.0 signifies a feature release and 2015.8.0 -> 2015.8.1 signifies a point release.

Feature Release Branching¶

Each feature release is maintained in a dedicated git branch derived from the last applicable release commit on develop. All file changes relevant to the feature release will be completed in the develop branch prior to the creation of the feature release branch. The feature release branch will be named after the relevant numbers to the feature release, which constitute the first two numbers. This means that the release branch for the 2015.8.0 series is named 2015.8. A feature release branch is created with the following command:

Point Releases¶

Each point release is derived from its parent release branch. Constructing point releases is a critical aspect of Salt development and is managed by members of the core development team. Point releases comprise bug and security fixes. Bug fixes can be made against a point release branch in one of two ways: the bug fix can be submitted directly against the point release branch, or an attempt can be made to back-port the fix to the point release branch. Bug fixes should be made against the earliest supported release branch on which the bug is present. The Salt development team regularly merges older point release branches forward into newer point release branches. That way, the bug fixes that are submitted to older release branches can cascade up through all related release branches. For more information, please see the Which Salt Branch? section of Salt's Contributing documentation. Determining when a point release is going to be made is up to the project leader (Thomas Hatch). Generally point releases are made every 2-4 weeks or if there is a security fix they can be made sooner. The point release is only designated by tagging the commit on the release branch with a release number using the existing convention (version 2015.8.1 is tagged with v2015.8.1). From the tag point a new source tarball is generated and published to PyPI, and a release announcement is made.

Salt Conventions¶

Writing Salt Documentation¶

Salt's documentation is built using the Sphinx documentation system. It can be built in a large variety of output formats including HTML, PDF, ePub, and manpage. All the documentation is contained in the main Salt repository. Speaking broadly, most of the narrative documentation is contained within the https://github.com/saltstack/salt/blob/develop/doc subdirectory and most of the reference and API documentation is written inline with Salt's Python code and extracted using a Sphinx extension.

Style¶

The Salt project recommends the IEEE style guide as a general reference for writing guidelines. Those guidelines are not strictly enforced but rather serve as an excellent resource for technical writing questions. The NCBI style guide is another very approachable resource.

Point-of-view¶

Use third-person perspective and avoid "I", "we", "you" forms of address. Identify the addressee specifically e.g., "users should", "the compiler does", etc.

Active voice¶

Use active voice and present-tense. Avoid filler words.

Title capitalization¶

Document titles and section titles within a page should follow normal sentence capitalization rules. Words that are capitalized as part of a regular sentence should be capitalized in a title and otherwise left as lowercase. Punctuation can be omitted unless it aids the intent of the title (e.g., exclamation points or question marks). For example:

Serial Commas¶

According to Wikipedia: In English punctuation, a serial comma or series comma (also called Oxford comma and Harvard comma) is a comma placed immediately before the coordinating conjunction (usually "and", "or", or "nor") in a series of three or more terms. For example, a list of three countries might be punctuated either as "France, Italy, and Spain" (with the serial comma), or as "France, Italy and Spain" (without the serial comma)." When writing a list that includes three or more items, the serial comma should always be used.

Documenting modules¶

Documentation for Salt's various module types is inline in the code. During the documentation build process it is extracted and formatted into the final HTML, PDF, etc format.

Inline documentation¶

Python has special multi-line strings called docstrings as the first element in a function or class. These strings allow documentation to live alongside the code and can contain special formatting. For example:

Specify a release for additions or changes¶

New functions or changes to existing functions should include a marker that denotes what Salt release will be affected. For example:
For changes to a function:

Adding module documentation to the index¶

Each module type has an index listing all modules of that type. For example: all-salt.modules, all-salt.states, all-salt.renderers. New modules must be added to the index manually.

Cross-references¶

The Sphinx documentation system contains a wide variety of cross-referencing capabilities.

Glossary entries¶

Link to glossary entries using the term role. A cross-reference should be added the first time a Salt-specific term is used in a document.

Index entries¶

Sphinx automatically generates many kinds of index entries, but it is occasionally useful to manually add items to the index. One method is to use the index directive above the document or section that should appear in the index.
Another method is to use the index role inline with the text that should appear in the index. The index entry is created and the target text is left otherwise intact.

Documents and sections¶

Each document should contain a unique top-level label of the form:
Unique labels can be linked using the ref role. This allows cross-references to survive document renames or movement.
Note, the :doc: role should not be used to link documents together.

Modules¶

Cross-references to Salt modules can be added using Sphinx's Python domain roles. For example, to create a link to the test.ping function:
Salt modules can be referenced as well:
The same syntax works for all modules types:

Settings¶

Individual settings in the Salt Master or Salt Minion configuration files are cross-referenced using two custom roles, conf_master, and conf_minion.

Documentation Changes and Fixes¶

Documentation changes and fixes should be made against the earliest supported release branch that the update applies to. The practice of updating a release branch instead of making all documentation changes against Salt's main, default branch, develop, is necessary in order for the docs to be as up-to-date as possible when the docs are built. The workflow mentioned above is also in line with the recommendations outlined in Salt's contributing page. You can read more about how to choose where to submit documentation fixes by reading the which-salt-branch section. For an explanation of how to submit changes against various branches, see the github-pull-request section. Specifically, see the section describing how to Create a new branch and the steps that follow.

Building the documentation¶

Salt Formulas¶

Formulas are pre-written Salt States. They are as open-ended as Salt States themselves and can be used for tasks such as installing a package, configuring, and starting a service, setting up users or permissions, and many other common tasks. All official Salt Formulas are found as separate Git repositories in the "saltstack-formulas" organization on GitHub: https://github.com/saltstack-formulas As a simple example, to install the popular Apache web server (using the normal defaults for the underlying distro) simply include the apache-formula from a top file:

Installation¶

Each Salt Formula is an individual Git repository designed as a drop-in addition to an existing Salt State tree. Formulas can be installed in the following ways.

Adding a Formula as a GitFS remote¶

One design goal of Salt's GitFS fileserver backend was to facilitate reusable States. GitFS is a quick and natural way to use Formulas.

Adding a Formula directory manually¶

Formulas are simply directories that can be copied onto the local file system by using Git to clone the repository or by downloading and expanding a tarball or zip file of the repository. The directory structure is designed to work with file_roots in the Salt master configuration.

Usage¶

Each Formula is intended to be immediately usable with sane defaults without any additional configuration. Many formulas are also configurable by including data in Pillar; see the pillar.example file in each Formula repository for available options.

Including a Formula in an existing State tree¶

Formula may be included in an existing sls file. This is often useful when a state you are writing needs to require or extend a state defined in the formula. Here is an example of a state that uses the epel-formula in a require declaration which directs Salt to not install the python26 package until after the EPEL repository has also been installed:

Including a Formula from a Top File¶

Some Formula perform completely standalone installations that are not referenced from other state files. It is usually cleanest to include these Formula directly from a Top File. For example the easiest way to set up an OpenStack deployment on a single machine is to include the openstack-standalone-formula directly from a top.sls file:
Quickly deploying OpenStack across several dedicated machines could also be done directly from a Top File and may look something like this:

Configuring Formula using Pillar¶

Salt Formulas are designed to work out of the box with no additional configuration. However, many Formula support additional configuration and customization through Pillar. Examples of available options can be found in a file named pillar.example in the root directory of each Formula repository.

Using Formula with your own states¶

Remember that Formula are regular Salt States and can be used with all Salt's normal state mechanisms. Formula can be required from other States with requisites-require declarations, they can be modified using extend, they can made to watch other states with requisites-watch-in. The following example uses the stock apache-formula alongside a custom state to create a vhost on a Debian/Ubuntu system and to reload the Apache service whenever the vhost is changed.
Don't be shy to read through the source for each Formula!

Reporting problems & making additions¶

Each Formula is a separate repository on GitHub. If you encounter a bug with a Formula please file an issue in the respective repository! Send fixes and additions as a pull request. Add tips and tricks to the repository wiki.

Writing Formulas¶

Each Formula is a separate repository in the saltstack-formulas organization on GitHub. NOTE:

Style¶

Maintainability, readability, and reusability are all marks of a good Salt sls file. This section contains several suggestions and examples.

Use a descriptive State ID¶

The ID of a state is used as a unique identifier that may be referenced via other states in requisites. It must be unique across the whole state tree (it is a key in a dictionary, after all). In addition a state ID should be descriptive and serve as a high-level hint of what it will do, or manage, or change. For example, deploy_webapp, or apache, or reload_firewall.

Use module.function notation¶

So-called "short-declaration" notation is preferred for referencing state modules and state functions. It provides a consistent pattern of module.function shared between Salt States, the Reactor, Salt Mine, the Scheduler, as well as with the CLI.
Salt's state compiler will transform "short-decs" into the longer format when compiling the human-friendly highstate structure into the machine-friendly lowstate structure.

Specify the name parameter¶

Use a unique and permanent identifier for the state ID and reserve name for data with variability. The name declaration is a required parameter for all state functions. The state ID will implicitly be used as name if it is not explicitly set in the state. In many state functions the name parameter is used for data that varies such as OS-specific package names, OS-specific file system paths, repository addresses, etc. Any time the ID of a state changes all references to that ID must also be changed. Use a permanent ID when writing a state the first time to future-proof that state and allow for easier refactors down the road.

Comment state files¶

YAML allows comments at varying indentation levels. It is a good practice to comment state files. Use vertical whitespace to visually separate different concepts or actions.
Be careful to use Jinja comments for commenting Jinja code and YAML comments for commenting YAML code.

Easy on the Jinja!¶

Jinja templating provides vast flexibility and power when building Salt sls files. It can also create an unmaintainable tangle of logic and data. Speaking broadly, Jinja is best used when kept apart from the states (as much as is possible). Below are guidelines and examples of how Jinja can be used effectively.

Know the evaluation and execution order¶

High-level knowledge of how Salt states are compiled and run is useful when writing states. The default renderer setting in Salt is Jinja piped to YAML. Each is a separate step. Each step is not aware of the previous or following step. Jinja is not YAML aware, YAML is not Jinja aware; they cannot share variables or interact.
The full evaluation and execution order:

Avoid changing the underlying system with Jinja¶

Avoid calling commands from Jinja that change the underlying system. Commands run via Jinja do not respect Salt's dry-run mode ( test=True)! This is usually in conflict with the idempotent nature of Salt states unless the command being run is also idempotent.

Inspect the local system¶

A common use for Jinja in Salt states is to gather information about the underlying system. The grains dictionary available in the Jinja context is a great example of common data points that Salt itself has already gathered. Less common values are often found by running commands. For example:
This is usually best done with a variable assignment in order to separate the data from the state that will make use of the data.

Gather external data¶

One of the most common uses for Jinja is to pull external data into the state file. External data can come from anywhere like API calls or database queries, but it most commonly comes from flat files on the file system or Pillar data from the Salt Master. For example:
This is usually best done with a variable assignment in order to separate the data from the state that will make use of the data.

Light conditionals and looping¶

Jinja is extremely powerful for programmatically generating Salt states. It is also easy to overuse. As a rule of thumb, if it is hard to read it will be hard to maintain! Separate Jinja control-flow statements from the states as much as is possible to create readable states. Limit Jinja within states to simple variable lookups. Below is a simple example of a readable loop:
Avoid putting a Jinja conditionals within Salt states where possible. Readability suffers and the correct YAML indentation is difficult to see in the surrounding visual noise. Parametrization (discussed below) and variables are both useful techniques to avoid this. For example:
Dictionaries are useful to effectively "namespace" a collection of variables. This is useful with parametrization (discussed below). Dictionaries are also easily combined and merged. And they can be directly serialized into YAML which is often easier than trying to create valid YAML through templating. For example:
There is still room for improvement in the above example. For example, extracting into an external file or replacing the if-elif conditional with a function call to filter the correct data more succinctly. However, the state itself is simple and legible, the data is separate and also simple and legible. And those suggested improvements can be made at some future date without altering the state at all!

Avoid heavy logic and programming¶

Jinja is not Python. It was made by Python programmers and shares many semantics and some syntax but it does not allow for abitrary Python function calls or Python imports. Jinja is a fast and efficient templating language but the syntax can be verbose and visually noisy. Once Jinja use within an sls file becomes slightly complicated -- long chains of if-elif-elif-else statements, nested conditionals, complicated dictionary merges, wanting to use sets -- instead consider using a different Salt renderer, such as the Python renderer. As a rule of thumb, if it is hard to read it will be hard to maintain -- switch to a format that is easier to read. Using alternate renderers is very simple to do using Salt's "she-bang" syntax at the top of the file. The Python renderer must simply return the correct highstate data structure. The following example is a state tree of two sls files, one simple and one complicated. /srv/salt/top.sls:
/srv/salt/common_configuration.sls:
/srv/salt/roles_configuration:

Jinja Macros¶

In Salt sls files Jinja macros are useful for one thing and one thing only: creating mini templates that can be reused and rendered on demand. Do not fall into the trap of thinking of macros as functions; Jinja is not Python (see above). Macros are useful for creating reusable, parameterized states. For example:
Macros are also useful for creating one-off "serializers" that can accept a data structure and write that out as a domain-specific configuration file. For example, the following macro could be used to write a php.ini config file: /srv/salt/php.sls:
/srv/pillar/php.sls:
/srv/salt/php.ini.tmpl:

Abstracting static defaults into a lookup table¶

Separate data that a state uses from the state itself to increases the flexibility and reusability of a state. An obvious and common example of this is platform-specific package names and file system paths. Another example is sane defaults for an application, or common settings within a company or organization. Organizing such data as a dictionary (aka hash map, lookup table, associative array) often provides a lightweight namespacing and allows for quick and easy lookups. In addition, using a dictionary allows for easily merging and overriding static values within a lookup table with dynamic values fetched from Pillar. A strong convention in Salt Formulas is to place platform-specific data, such as package names and file system paths, into a file named map.jinja that is placed alongside the state files. The following is an example from the MySQL Formula. The grains.filter_by function performs a lookup on that table using the os_family grain (by default). The result is that the mysql variable is assigned to a subset of the lookup table for the current platform. This allows states to reference, for example, the name of a package without worrying about the underlying OS. The syntax for referencing a value is a normal dictionary lookup in Jinja, such as {{ mysql['service'] }} or the shorthand {{ mysql.service }}. map.jinja:
Values defined in the map file can be fetched for the current platform in any state file using the following syntax:

Organizing Pillar data¶

It is considered a best practice to make formulas expect all formula-related parameters to be placed under second-level lookup key, within a main namespace designated for holding data for particular service/software/etc, managed by the formula:

Collecting common values¶

Common values can be collected into a base dictionary. This minimizes repetition of identical values in each of the lookup_dict sub-dictionaries. Now only the values that are different from the base must be specified by the alternates: map.jinja:

Overriding values in the lookup table¶

Allow static values within lookup tables to be overridden. This is a simple pattern which once again increases flexibility and reusability for state files. The merge argument in filter_by specifies the location of a dictionary in Pillar that can be used to override values returned from the lookup table. If the value exists in Pillar it will take precedence. This is useful when software or configuration files is installed to non-standard locations or on unsupported platforms. For example, the following Pillar would replace the config value from the call above.
NOTE:
The filter_by function performs a simple dictionary lookup but also allows for fetching data from Pillar and overriding data stored in the lookup table. That same workflow can be easily performed without using filter_by; other dictionaries besides data from Pillar can also be used.

When to use lookup tables¶

The map.jinja file is only a convention within Salt Formulas. This greater pattern is useful for a wide variety of data in a wide variety of workflows. This pattern is not limited to pulling data from a single file or data source. This pattern is useful in States, Pillar and the Reactor, for example. Working with a data structure instead of, say, a config file allows the data to be cobbled together from multiple sources (local files, remote Pillar, database queries, etc), combined, overridden, and searched. Below are a few examples of what lookup tables may be useful for and how they may be used and represented.

Platform-specific information¶

An obvious pattern and one used heavily in Salt Formulas is extracting platform-specific information such as package names and file system paths in a file named map.jinja. The pattern is explained in detail above.

Sane defaults¶

Application settings can be a good fit for this pattern. Store default settings along with the states themselves and keep overrides and sensitive settings in Pillar. Combine both into a single dictionary and then write the application config or settings file. The example below stores most of the Apache Tomcat server.xml file alongside the Tomcat states and then allows values to be updated or augmented via Pillar. (This example uses the BadgerFish format for transforming JSON to XML.) /srv/salt/tomcat/defaults.yaml:
/srv/pillar/tomcat.sls:
/srv/salt/tomcat/server_xml.sls:
The file.serialize state can provide a shorthand for creating some files from data structures. There are also many examples within Salt Formulas of creating one-off "serializers" (often as Jinja macros) that reformat a data structure to a specific config file format. For example,

`Nginx vhosts`__

or the

`php.ini`__

__: https://github.com/saltstack-formulas/nginx-formula/blob/5cad4512/nginx/ng/vhosts_config.sls __: https://github.com/saltstack-formulas/php-formula/blob/82e2cd3a/php/ng/files/php.ini

Environment specific information¶

A single state can be reused when it is parameterized as described in the section below, by separating the data the state will use from the state that performs the work. This can be the difference between deploying Application X and Application Y, or the difference between production and development. For example: /srv/salt/app/deploy.sls:
/srv/salt/app/defaults.yaml:

Single-purpose SLS files¶

Each sls file in a Formula should strive to do a single thing. This increases the reusability of this file by keeping unrelated tasks from getting coupled together. As an example, the base Apache formula should only install the Apache httpd server and start the httpd service. This is the basic, expected behavior when installing Apache. It should not perform additional changes such as set the Apache configuration file or create vhosts. If a formula is single-purpose as in the example above, other formulas, and also other states can include and use that formula with requisites without also including undesirable or unintended side-effects. The following is a best-practice example for a reusable Apache formula. (This skips platform-specific options for brevity. See the full apache-formula for more.)
To illustrate a bad example, say the above Apache formula installed Apache and also created a default vhost. The mod_wsgi state would not be able to include the Apache formula to create that dependency tree without also installing the unneeded default vhost. Formulas should be reusable. Avoid coupling unrelated actions together.

Parameterization¶

Parameterization is a key feature of Salt Formulas and also for Salt States. Parameterization allows a single Formula to be reused across many operating systems; to be reused across production, development, or staging environments; and to be reused by many people all with varying goals. Writing states, specifying ordering and dependencies is the part that takes the longest to write and to test. Filling those states out with data such as users or package names or file locations is the easy part. How many users, what those users are named, or where the files live are all implementation details that should be parameterized. This separation between a state and the data that populates a state creates a reusable formula. In the example below the data that populates the state can come from anywhere -- it can be hard-coded at the top of the state, it can come from an external file, it can come from Pillar, it can come from an execution function call, or it can come from a database query. The state itself doesn't change regardless of where the data comes from. Production data will vary from development data will vary from data from one company to another, however the state itself stays the same.

Configuration¶

Formulas should strive to use the defaults of the underlying platform, followed by defaults from the upstream project, followed by sane defaults for the formula itself. As an example, a formula to install Apache should not change the default Apache configuration file installed by the OS package. However, the Apache formula should include a state to change or override the default configuration file.

Pillar overrides¶

Pillar lookups must use the safe get() and must provide a default value. Create local variables using the Jinja set construct to increase redability and to avoid potentially hundreds or thousands of function calls across a large state tree.
Any default values used in the Formula must also be documented in the pillar.example file in the root of the repository. Comments should be used liberally to explain the intent of each configuration value. In addition, users should be able copy-and-paste the contents of this file into their own Pillar to make any desired changes.

Scripting¶

Remember that both State files and Pillar files can easily call out to Salt execution modules and have access to all the system grains as well.
Jinja macros to encapsulate logic or conditionals are discouraged in favor of writing custom execution modules in Python.

Repository structure¶

A basic Formula repository should have the following layout:
SEE ALSO:

README.rst¶

The README should detail each available .sls file by explaining what it does, whether it has any dependencies on other formulas, whether it has a target platform, and any other installation or usage instructions or tips. A sample skeleton for the README.rst file:

CHANGELOG.rst¶

The CHANGELOG.rst file should detail the individual versions, their release date and a set of bullet points for each version highlighting the overall changes in a given version of the formula. A sample skeleton for the CHANGELOG.rst file: CHANGELOG.rst:

Versioning¶

Formula are versioned according to Semantic Versioning, http://semver.org/. NOTE:
Formula versions are tracked using Git tags as well as the VERSION file in the formula repository. The VERSION file should contain the currently released version of the particular formula.

Testing Formulas¶

A smoke-test for invalid Jinja, invalid YAML, or an invalid Salt state structure can be performed by with the state.show_sls function:
Salt Formulas can then be tested by running each .sls file via state.apply and checking the output for the success or failure of each state in the Formula. This should be done for each supported platform.

SaltStack Packaging Guide¶

Since Salt provides a powerful toolkit for system management and automation, the package can be spit into a number of sub-tools. While packaging Salt as a single package containing all components is perfectly acceptable, the split packages should follow this convention.

Patching Salt For Distributions¶

The occasion may arise where Salt source and default configurations may need to be patched. It is preferable if Salt is only patched to include platform specific additions or to fix release time bugs. It is preferable that configuration settings and operations remain in the default state, as changes here lowers the user experience for users moving across distributions. In the event where a packager finds a need to change the default configuration it is advised to add the files to the master.d or minion.d directories.

Source Files¶

Release packages should always be built from the source tarball distributed via pypi. Release packages should NEVER use a git checkout as the source for distribution.

Single Package¶

Shipping Salt as a single package, where the minion, master, and all tools are together is perfectly acceptable and practiced by distributions such as FreeBSD.

Split Package¶

Salt Should always be split in a standard way, with standard dependencies, this lowers cross distribution confusion about what components are going to be shipped with specific packages. These packages can be defined from the Salt Source as of Salt 2014.1.0:

Salt Common¶

The salt-common or salt package should contain the files provided by the salt python package, or all files distributed from the salt/ directory in the source distribution packages. The documentation contained under the doc/ directory can be a part of this package but splitting out a doc package is preferred. Since salt-call is the entry point to utilize the libs and is useful for all salt packages it is included in the salt-common package.

Name¶

Files¶

Depends¶

Salt Master¶

The salt-master package contains the applicable scripts, related man pages and init information for the given platform.

Name¶

Files¶

Depends¶

Salt Syndic¶

The Salt Syndic package can be rolled completely into the Salt Master package. Platforms which start services as part of the package deployment need to maintain a separate salt-syndic package (primarily Debian based platforms). The Syndic may optionally not depend on the anything more than the Salt Master since the master will bring in all needed dependencies, but fall back to the platform specific packaging guidelines.

Name¶

Files¶

Depends¶

Salt Minion¶

The Minion is a standalone package and should not be split beyond the salt-minion and salt-common packages.

Name¶

Files¶

Depends¶

Salt SSH¶

Since Salt SSH does not require the same dependencies as the minion and master, it should be split out.

Name¶

Files¶

Depends¶

Salt Cloud¶

As of Salt 2014.1.0 Salt Cloud is included in the same repo as Salt. This can be split out into a separate package or it can be included in the salt-master package.

Name¶

Files¶

Depends¶

Salt Doc¶

The documentation package is very distribution optional. A completely split package will split out the documentation, but some platform conventions do not prefer this. If the documentation is not split out, it should be included with the Salt Common package.

Name¶

Files¶

Optional Depends¶

Salt Release Process¶

The goal for Salt projects is to cut a new feature release every four to six months. This document outlines the process for these releases, and the subsequent bug fix releases which follow.

Feature Release Process¶

When a new release is ready to be cut, the person responsible for cutting the release will follow the following steps (written using the 0.16 release as an example):

Maintenance and Bugfix Releases¶

Once a feature release branch has been cut from develop, the branch moves into a "feature freeze" state. The new release branch enters the merge-forward chain and only bugfixes should be applied against the new branch. Once major bugs have been fixed, a bugfix release can be cut:
For more information about the difference between the develop branch and bugfix release branches, please refer to the Which Salt Branch? section of Salt's Contributing documentation.

Salt Coding Style¶

Salt is developed with a certain coding style, while the style is dominantly PEP 8 it is not completely PEP 8. It is also noteworthy that a few development techniques are also employed which should be adhered to. In the end, the code is made to be "Salty". Most importantly though, we will accept code that violates the coding style and KINDLY ask the contributor to fix it, or go ahead and fix the code on behalf of the contributor. Coding style is NEVER grounds to reject code contributions, and is never grounds to talk down to another member of the community (There are no grounds to treat others without respect, especially people working to improve Salt)!!

Linting¶

Most Salt style conventions are codified in Salt's .pylintrc file. Salt's pylint file has two dependencies: pylint and saltpylint. You can install these dependencies with pip:
The .pylintrc file is found in the root of the Salt project and can be passed as an argument to the pylint program as follows:

Variables¶

Variables should be a minimum of three characters and should provide an easy-to-understand name of the object being represented. When keys and values are iterated over, descriptive names should be used to represent the temporary variables. Multi-word variables should be separated by an underscore. Variables which are two-letter words should have an underscore appended to them to pad them to three characters.

Strings¶

Salt follows a few rules when formatting strings:

Single Quotes¶

In Salt, all strings use single quotes unless there is a good reason not to. This means that docstrings use single quotes, standard strings use single quotes etc.:

Formatting Strings¶

All strings which require formatting should use the .format string method:
Make sure to use indices or identifiers in the format brackets, since empty brackets are not supported by python 2.6. Please do NOT use printf formatting.

Docstring Conventions¶

Docstrings should always add a newline, docutils takes care of the new line and it makes the code cleaner and more vertical: GOOD:
BAD:
When adding a new function or state, where possible try to use a versionadded directive to denote when the function or state was added.
If you are uncertain what version should be used, either consult a core developer in IRC or bring this up when opening your pull request and a core developer will add the proper version once your pull request has been merged. Bugfixes will be available in a bugfix release (i.e. 0.17.1, the first bugfix release for 0.17.0), while new features are held for feature releases, and this will affect what version number should be used in the versionadded directive. Similar to the above, when an existing function or state is modified (for example, when an argument is added), then under the explanation of that new argument a versionadded directive should be used to note the version in which the new argument was added. If an argument's function changes significantly, the versionchanged directive can be used to clarify this:

Dictionaries¶

Dictionaries should be initialized using {} instead of dict(). See here for an in-depth discussion of this topic.

Imports¶

Salt code prefers importing modules and not explicit functions. This is both a style and functional preference. The functional preference originates around the fact that the module import system used by pluggable modules will include callable objects (functions) that exist in the direct module namespace. This is not only messy, but may unintentionally expose code python libs to the Salt interface and pose a security problem. To say this more directly with an example, this is GOOD:
This on the other hand is DISCOURAGED:
The time when this is changed is for importing exceptions, generally directly importing exceptions is preferred: This is a good way to import exceptions:

Absolute Imports¶

Although absolute imports seems like an awesome idea, please do not use it. Extra care would be necessary all over salt's code in order for absolute imports to work as supposed. Believe it, it has been tried before and, as a tried example, by renaming salt.modules.sysmod to salt.modules.sys, all other salt modules which needed to import sys would have to also import absolute_import, which should be avoided. NOTE:

Vertical is Better¶

When writing Salt code, vertical code is generally preferred. This is not a hard rule but more of a guideline. As PEP 8 specifies, Salt code should not exceed 79 characters on a line, but it is preferred to separate code out into more newlines in some cases for better readability:
Where there are more line breaks, this is also apparent when constructing a function with many arguments, something very common in state functions for instance:
NOTE:

Line Length¶

For function definitions and function calls, Salt adheres to the PEP-8 specification of at most 80 characters per line. Non function definitions or function calls, please adopt a soft limit of 120 characters per line. If breaking the line reduces the code readability, don't break it. Still, try to avoid passing that 120 characters limit and remember, vertical is better... unless it isn't

Indenting¶

Some confusion exists in the python world about indenting things like function calls, the above examples use 8 spaces when indenting comma-delimited constructs. The confusion arises because the pep8 program INCORRECTLY flags this as wrong, where PEP 8, the document, cites only using 4 spaces here as wrong, as it doesn't differentiate from a new indent level. Right:
WRONG:
Lining up the indent is also correct:
This also applies to function calls and other hanging indents. pep8 and Flake8 (and, by extension, the vim plugin Syntastic) will complain about the double indent for hanging indents. This is a known conflict between pep8 (the script) and the actual PEP 8 standard. It is recommended that this particular warning be ignored with the following lines in ~/.config/flake8:
Make sure your Flake8/pep8 are up to date. The first three errors are ignored by default and are present here to keep the behavior the same. This will also work for pep8 without the Flake8 wrapper -- just replace all instances of 'flake8' with 'pep8', including the filename.

Code Churn¶

Many pull requests have been submitted that only churn code in the name of PEP 8. Code churn is a leading source of bugs and is strongly discouraged. While style fixes are encouraged they should be isolated to a single file per commit, and the changes should be legitimate, if there are any questions about whether a style change is legitimate please reference this document and the official PEP 8 ( http://legacy.python.org/dev/peps/pep-0008/) document before changing code. Many claims that a change is PEP 8 have been invalid, please double check before committing fixes.

Salt code and internals¶

Reference documentation on Salt's internal code.

Contents¶

salt.aggregation¶

salt.utils.aggregation¶

This library makes it possible to introspect dataset and aggregate nodes when it is instructed. NOTE:

How to instructs merging¶

This yaml document has duplicate keys:
but tagged values instruct Salt that overlapping values they can be merged together:

Default merge strategy is keep untouched¶

For example, this yaml document still has duplicate keys, but does not instruct aggregation:
So the late found values prevail:

Limitations¶

Aggregation is permitted between tagged objects that share the same type. If not, the default merge strategy prevails. For example, these examples:
are interpreted like this:

Introspection¶

TODO: write this part

Exceptions¶

Salt-specific exceptions should be thrown as often as possible so the various interfaces to Salt (CLI, API, etc) can handle those errors appropriately and display error messages appropriately.

salt.exceptions	This module is a central location for all salt exceptions

salt.exceptions¶

This module is a central location for all salt exceptions

Salt opts dictionary¶

It is very common in the Salt codebase to see opts referred to in a number of contexts. For example, it can be seen as __opts__ in certain cases, or simply as opts as an argument to a function in others. Simply put, this data structure is a dictionary of Salt's runtime configuration information that's passed around in order for functions to know how Salt is configured. When writing Python code to use specific parts of Salt, it may become necessary to initialize a copy of opts from scratch in order to have it available for a given function. To do so, use the utility functions available in salt.config. As an example, here is how one might generate and print an options dictionary for a minion instance:
To generate and display opts for a master, the process is similar:

Unicode in Salt¶

Though Unicode handling in large projects can often be complex, Salt adheres to several basic rules to help developers handle Unicode correctly. (For a basic introduction to this problem, see Ned Batchelder's excellent intoroduction to the topic <http://nedbatchelder.com/text/unipain/unipain.html>. Salt's basic workflow for Unicode handling is as follows: 1) Salt should convert whatever data is passed on CLI/API to Unicode. Internally, everything that Salt does should be Unicode unless it is printing to the screen or writing to storage.
4) When Salt delivers the data to an outputter or a returner, it is the job of the outputter or returner to encode the Unicode before displaying it on the console or writing it to storage.

Salt Community Projects¶

This page contains links to Salt-related projects created by community members. If you come across a useful project please add it to the list!

Hubblestack¶

Hubble is a modular, open-source security compliance framework built on top of SaltStack. The project provides on-demand profile-based auditing, real-time security event notifications, automated remediation, alerting and reporting. http://hubblestack.io/

alkali¶

alkali is a collections of SaltStack states and pillar data that provide just the basics for provisioning Linux instances that may be built upon. alkali is a starter kit of sorts, to help new users to SaltStack get up-and-running quickly with the most commonly used, core packages. https://github.com/zulily/alkali

buoyant¶

buoyant leverages docker to provide an alternative to VM-centric SaltStack development environments. buoyant containers may be spun up nearly instantly, once an initial docker image has been built. https://github.com/zulily/buoyant

Salt Sandbox¶

Salt Sandbox is a multi-VM Vagrant-based Salt development environment used for creating and testing new Salt state modules outside of your production environment. It's also a great way to learn firsthand about Salt and its remote execution capabilities. https://github.com/elasticdog/salt-sandbox

Salt Vagrant Demo¶

A Salt Demo using Vagrant. https://github.com/UtahDave/salt-vagrant-demo

Salt's Test Suite: An Introduction¶

NOTE:
Salt comes with a powerful integration and unit test suite. The test suite allows for the fully automated run of integration and/or unit tests from a single interface. Salt's test suite is located under the tests directory in the root of Salt's code base and is divided into two main types of tests: unit tests and integration tests. The unit and integration sub-test-suites are located in the tests directory, which is where the majority of Salt's test cases are housed.

Getting Set Up For Tests¶

There are a couple of requirements, in addition to Salt's requirements, that need to be installed in order to run Salt's test suite. You can install these additional requirements using the files located in the salt/requirements directory, depending on your relevant version of Python:
To be able to run integration tests which utilizes ZeroMQ transport, you also need to install additional requirements for it. Make sure you have installed the C/C++ compiler and development libraries and header files needed for your Python version. This is an example for RedHat-based operating systems:
On Debian, Ubuntu or their derivatives run the following commands:
This will install the latest pycrypto and pyzmq (with bundled libzmq) Python modules required for running integration tests suite.

Test Directory Structure¶

As noted in the introduction to this tutorial, Salt's test suite is located in the tests directory in the root of Salt's code base. From there, the tests are divided into two groups integration and unit. Within each of these directories, the directory structure roughly mirrors the directory structure of Salt's own codebase. For example, the files inside tests/integration/modules contains tests for the files located within salt/modules. NOTE:

Integration vs. Unit¶

Given that Salt's test suite contains two powerful, though very different, testing approaches, when should you write integration tests and when should you write unit tests? Integration tests use Salt masters, minions, and a syndic to test salt functionality directly and focus on testing the interaction of these components. Salt's integration test runner includes functionality to run Salt execution modules, runners, states, shell commands, salt-ssh commands, salt-api commands, and more. This provides a tremendous ability to use Salt to test itself and makes writing such tests a breeze. Integration tests are the preferred method of testing Salt functionality when possible. Unit tests do not spin up any Salt daemons, but instead find their value in testing singular implementations of individual functions. Instead of testing against specific interactions, unit tests should be used to test a function's logic. Unit tests should be used to test a function's exit point(s) such as any return or raises statements. Unit tests are also useful in cases where writing an integration test might not be possible. While the integration test suite is extremely powerful, unfortunately at this time, it does not cover all functional areas of Salt's ecosystem. For example, at the time of this writing, there is not a way to write integration tests for Proxy Minions. Since the test runner will need to be adjusted to account for Proxy Minion processes, unit tests can still provide some testing support in the interim by testing the logic contained inside Proxy Minion functions.

Running the Test Suite¶

Once all of the requirements are installed, the runtests.py file in the salt/tests directory is used to instantiate Salt's test suite:
The command above, if executed without any options, will run the entire suite of integration and unit tests. Some tests require certain flags to run, such as destructive tests. If these flags are not included, then the test suite will only perform the tests that don't require special attention. At the end of the test run, you will see a summary output of the tests that passed, failed, or were skipped. The test runner also includes a --help option that lists all of the various command line options:
You can also call the test runner as an executable:

Running Integration Tests¶

Salt's set of integration tests use Salt to test itself. The integration portion of the test suite includes some built-in Salt daemons that will spin up in preparation of the test run. This list of Salt daemon processes includes:
These various daemons are used to execute Salt commands and functionality within the test suite, allowing you to write tests to assert against expected or unexpected behaviors. A simple example of a test utilizing a typical master/minion execution module command is the test for the test_ping function in the tests/integration/modules/test.py file:
The test above is a very simple example where the test.ping function is executed by Salt's test suite runner and is asserting that the minion returned with a True response.

Test Selection Options¶

If you look in the output of the --help command of the test runner, you will see a section called Tests Selection Options. The options under this section contain various subsections of the integration test suite such as --modules, --ssh, or --states. By selecting any one of these options, the test daemons will spin up and the integration tests in the named subsection will run.
NOTE:

Running Unit Tests¶

While ./tests/runtests.py executes the entire test suite (barring any tests requiring special flags), the --unit flag can be used to run only Salt's unit tests. Salt's unit tests include the tests located in the tests/unit directory. The unit tests do not spin up any Salt testing daemons as the integration tests do and execute very quickly compared to the integration tests.

Running Specific Tests¶

There are times when a specific test file, test class, or even a single, individual test need to be executed, such as when writing new tests. In these situations, the --name option should be used. For running a single test file, such as the pillar module test file in the integration test directory, you must provide the file path using . instead of / as separators and no file extension:
Some test files contain only one test class while other test files contain multiple test classes. To run a specific test class within the file, append the name of the test class to the end of the file path:
To run a single test within a file, append both the name of the test class the individual test belongs to, as well as the name of the test itself:
The --name and -n options can be used for unit tests as well as integration tests. The following command is an example of how to execute a single test found in the tests/unit/modules/cp_test.py file:

Writing Tests for Salt¶

Once you're comfortable running tests, you can now start writing them! Be sure to review the Integration vs. Unit section of this tutorial to determine what type of test makes the most sense for the code you're testing. NOTE:

Writing Integration Tests¶

Since integration tests validate against a running environment, as explained in the Running Integration Tests section of this tutorial, integration tests are very easy to write and are generally the preferred method of writing Salt tests. The following integration test is an example taken from the test.py file in the tests/integration/modules directory. This test uses the run_function method to test the functionality of a traditional execution module command. The run_function method uses the integration test daemons to execute a module.function command as you would with Salt. The minion runs the function and returns. The test also uses Python's Assert Functions to test that the minion's return is expected.
Args can be passed in to the run_function method as well:
The next example is taken from the tests/integration/modules/aliases.py file and demonstrates how to pass kwargs to the run_function call. Also note that this test uses another salt function to ensure the correct data is present (via the aliases.set_target call) before attempting to assert what the aliases.get_target call should return.
Using multiple Salt commands in this manor provides two useful benefits. The first is that it provides some additional coverage for the aliases.set_target function. The second benefit is the call to aliases.get_target is not dependent on the presence of any aliases set outside of this test. Tests should not be dependent on the previous execution, success, or failure of other tests. They should be isolated from other tests as much as possible. While it might be tempting to build out a test file where tests depend on one another before running, this should be avoided. SaltStack recommends that each test should test a single functionality and not rely on other tests. Therefore, when possible, individual tests should also be broken up into singular pieces. These are not hard-and-fast rules, but serve more as recommendations to keep the test suite simple. This helps with debugging code and related tests when failures occur and problems are exposed. There may be instances where large tests use many asserts to set up a use case that protects against potential regressions. NOTE:

Destructive vs Non-destructive Tests¶

Since Salt is used to change the settings and behavior of systems, often, the best approach to run tests is to make actual changes to an underlying system. This is where the concept of destructive integration tests comes into play. Tests can be written to alter the system they are running on. This capability is what fills in the gap needed to properly test aspects of system management like package installation. To write a destructive test, import and use the destructiveTest decorator for the test method:

Writing Unit Tests¶

As explained in the Integration vs. Unit section above, unit tests should be written to test the logic of a function. This includes focusing on testing return and raises statements. Substantial effort should be made to mock external resources that are used in the code being tested. External resources that should be mocked include, but are not limited to, APIs, function calls, external data either globally available or passed in through function arguments, file data, etc. This practice helps to isolate unit tests to test Salt logic. One handy way to think about writing unit tests is to "block all of the exits". More information about how to properly mock external resources can be found in Salt's Unit Test documentation. Salt's unit tests utilize Python's mock class as well as MagicMock. The @patch decorator is also heavily used when "blocking all the exits". A simple example of a unit test currently in use in Salt is the test_get_file_not_found test in the tests/unit/modules/cp_test.py file. This test uses the @patch decorator and MagicMock to mock the return of the call to Salt's cp.hash_file execution module function. This ensures that we're testing the cp.get_file function directly, instead of inadvertently testing the call to cp.hash_file, which is used in cp.get_file.
Note that Salt's cp module is imported at the top of the file, along with all of the other necessary testing imports. The get_file function is then called directed in the testing function, instead of using the run_function method as the integration test examples do above. The call to cp.get_file returns an empty string when a hash_file isn't found. Therefore, the example above is a good illustration of a unit test "blocking the exits" via the @patch decorator, as well as testing logic via asserting against the return statement in the if clause. There are more examples of writing unit tests of varying complexities available in the following docs:
NOTE:

Checking for Log Messages¶

To test to see if a given log message has been emitted, the following pattern can be used

Automated Test Runs¶

SaltStack maintains a Jenkins server which can be viewed at https://jenkins.saltstack.com. The tests executed from this Jenkins server create fresh virtual machines for each test run, then execute the destructive tests on the new, clean virtual machine. This allows for the execution of tests across supported platforms.

Additional Testing Documentation¶

In addition to this tutorial, there are some other helpful resources and documentation that go into more depth on Salt's test runner, writing tests for Salt code, and general Python testing documentation. Please see the follow references for more information:

RELEASE NOTES¶

See the version numbers page for more information about the version numbering scheme.

Latest Branch Release¶

Release Candidate

Previous Releases¶

Salt 2016.11.0 Release Notes - Codename Carbon¶

New Features¶

Docker Introspection and Configuration¶

Major additions have been made to the Docker support in 2016.11.0. The new addition allows Salt to be executed within a Docker container without a minion running or installed in the container. This allows states to be run inside a container, but also all of Salt's remote execution commands to be run inside docker containers as well. This makes container introspection simple and powerful. See the tutorial on using this new feature here: See Salt in Docker Containers.

Advanced Ceph Control¶

Our friends over at SUSE have delivered a powerful new tool to make the deployment of Ceph storage systems using Salt very easy. These new Ceph tools allow for a storage system to be easily defined using the new ceph.quorum state.

Thorium Additions and Improvements¶

The Thorium advanced reactor has undergone extensive testing and updates. These updates include many more Thorium states, a system for automating key management, the ability to use Thorium to easily replace old reactors and a great deal of stability and bug fixes.

State Rollback Using Snapper¶

Rollback has been one of the most prevalent requests for Salt. We have researched it extensively and concluded that the only way to accomplish truly reliable rollback would be to execute it at the filesystem layer. To accomplish this we have introduced Snapper integration into Salt States. Snapper is a tool which allows for simple and reliable snapshots of the filesystem to be made. With the new snapper_states option set to True in the minion config a snapshot will be made before and after every Salt State run. These snapshots can be viewed, managed and rolled back to via the snapper execution module.

Preserve File Perms in File States¶

This feature has been requested for years, the ability to set a flag and use the same file permissions for files deployed to a minion as the permissions set to the file on the master. Just set the keep_mode option on any file management state to True.

Ponies!¶

We all agreed that cowsay was just not good enough, install the ponysay command and the new pony outputter will work. Fun for the whole family!

Additional Features¶

New Top File Merging Strategy for States¶

A new strategy called merge_all has been added to provide a new way of merging top file matches when executing a highstate. See the top_file_merging_strategy documentation for further information. In addition, the same merging strategy was not functioning as documented. This has now been corrected. While this is technically a bugfix, we decided to hold a change in top file merging until a feature release to minimize user impact.

Improved Archive Extraction Support¶

The archive.extracted state has been overhauled. Notable changes include the following:
A number of new arguments were also added. See the docs py:func: docs for the archive.extracted state <salt.states.archive.extracted> for more information. Additionally, the following changes have been made to the archive execution module:

Improved Checksum Handling in file.managed, archive.extracted States¶

When the source_hash argument for these states refers to a file containing checksums, Salt now looks for checksums matching the name of the source URI, as well as the file being managed. Prior releases only looked for checksums matching the filename being managed. Additionally, a new argument ( source_hash_name) has been added, which allows the user to disambiguate ambiguous matches when more than one matching checksum is found in the source_hash file. A more detailed explanation of this functionality can be found in the file.managed documentation, in the section for the new source_hash_name argument. NOTE:

Config Changes¶

The following default config values were changed:

Grains Changes¶

Beacons Changes¶

Runner Changes¶

Pillar Changes¶

Network Automation: NAPALM¶

Beginning with 2016.11.0, network automation is inclued by default in the core of Salt. It is based on a the NAPALM library and provides facilities to manage the configuration and retrieve data from network devices running widely used operating systems such: JunOS, IOS-XR, eOS, IOS, NX-OS etc. - see the complete list of supported devices. The connection is established via the NAPALM proxy. In the current release, the following modules were included:

Junos Module Changes¶

Returner Changes¶

Renderer Changes¶

Added the ability to restrict allowed renderers. Two new config parameters, renderer_whitelist and renderer_blacklist are introduced for this purpose.

eAuth Changes¶

External Module Packaging¶

Modules may now be packaged via entry-points in setuptools. See external module packaging tutorial for more information.

Functionality Changes¶

New Azure ARM Cloud Driver¶

A new cloud driver has been added for Azure ARM, aka, the Azure Resource Manager. The older Azure driver is still required to work with the older Azure API. This new driver works with the newer ARM API, which is managed via the newer Azure Portal website.

New Modules¶

Beacons¶

Clouds¶

Engines¶

Modules¶

Outputters¶

Pillar¶

Returners¶

Runners¶

SDB¶

States¶

Thorium¶

Deprecations¶

General Deprecations¶

Cloud Deprecations¶

Execution Module Deprecations¶

Outputter Module Deprecations¶

Runner Module Deprecations¶

State Module Deprecations¶

Utils Module Deprecations¶

Salt 2016.11.1 Release Notes¶

Version 2016.11.1 is a bugfix release for 2016.11.0.

Changes for v2016.11.0..v2016.11.1¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-12-09T21:54:17Z Statistics:
Changes:

Salt 2016.11.2 Release Notes¶

Version 2016.11.2 is a bugfix release for 2016.11.0.

Changes for v2016.11.1..v2016.11.2¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2017-01-20T21:19:44Z Statistics:
Changes:

Salt 2016.3.0 Release Notes - Codename Boron¶

Known Issues¶

WARNING:

Backwards-incompatible Changes¶

Core Changes¶

External Module Packaging¶

Modules may now be packaged via entry-points in setuptools. See external module packaging tutorial for more information.

Cloud Changes¶

Platform Changes¶

Package Support¶

Proxy Minion Changes¶

The deprecated config option enumerate_proxy_minions has been removed. As mentioned in earlier documentation, the add_proxymodule_to_opts configuration variable defaults to False in this release. This means if you have proxymodules or other code looking in __opts__['proxymodule'] you will need to set this variable in your /etc/salt/proxy file, or modify your code to use the __proxy__ injected variable. The __proxyenabled__ directive now only applies to grains and proxy modules themselves. Standard execution modules and state modules are not prevented from loading for proxy minions. Support has been added to Salt's loader allowing custom proxymodules to be placed in salt://_proxy. Proxy minions that need these modules will need to be restarted to pick up any changes. A corresponding utility function, saltutil.sync_proxymodules, has been added to sync these modules to minions. Enhancements in grains processing have made the __proxyenabled__ directive somewhat redundant in dynamic grains code. It is still required, but best practices for the __virtual__ function in grains files have changed. It is now recommended that the __virtual__ functions check to make sure they are being loaded for the correct proxytype, example below:
The try/except block above exists because grains are processed very early in the proxy minion startup process, sometimes earlier than the proxy key in the __opts__ dictionary is populated. Grains are loaded so early in startup that no dunder dictionaries are present, so __proxy__, __salt__, etc. are not available. Custom grains located in /srv/salt/_grains and in the salt install grains directory can now take a single argument, proxy, that is identical to __proxy__. This enables patterns like
Then the grain ip will contain the result of calling the get_ip() function in the proxymodule called proxymodulename. Proxy modules now benefit from including a function called initialized(). This function should return True if the proxy's init() function has been successfully called. This is needed to make grains processing easier. Finally, if there is a function called grains in the proxymodule, it will be executed on proxy-minion startup and its contents will be merged with the rest of the proxy's grains. Since older proxy-minions might have used other methods to call such a function and add its results to grains, this is config-gated by a new proxy configuration option called proxy_merge_grains_in_module. This defaults to False in this release. It will default to True in the release after next. The next release is codenamed Carbon, the following is Nitrogen. The example proxy minions rest_sample and ssh_sample have been updated to reflect these changes.

Syndic Updates¶

A major performance and management issue was found and fixed in the syndic. This makes the Salt Syndic substantially more reliable and performant. Please make sure that the syndic and the master of masters which syndics attach to are updated, otherwise the syndic fixes alone can cause minor performance issues with older master of masters. Please update masters first, then syndics. Minions do not need to be updated for this fix to work.

Module Changes¶

New Features¶

Thorium - Provisional New Reactor¶

The 2016.3 release introduces the new Thorium Reactor. This reactor is an experimental new feature that implements a flow programming interface using the salt state system as the engine. This means that the Thorium reactor uses a classic state tree approach to create a reactor that can aggregate event data from multiple sources and make aggregate decisions about executing reactions. This feature is both experimental and provisional, it may be removed and APIs may be changed. This system should be considered as ambitious as the Salt State System in that the scope of adding a programmable logic engine of this scale into the event systems is non trivial. See Thorium Complex Reactor.

Improved Mac OS Support¶

Improved Solaris Support¶

A lot of work was done to improve support for SmartOS. This work also resulted in improvements for Solaris and illumos as SmartOS.

Tornado Transport¶

IMPORTANT:

Windows DSC Integration (Experiemental)¶

Dimension Data Cloud Support¶

A SaltStack Cloud driver for Dimension Data Public Cloud, provides the driver functionality to service automation for any of the Dimension Data Public Cloud locations:
Documentation of the Dimension Data SaltStack integration is found on developer.dimensiondata.com

Minion Blackout¶

During a blackout, minions will not execute any remote execution commands, except for saltutil.refresh_pillar. Blackouts are enabled using a special pillar key, minion_blackout set to True. See Minion Blackout.

Splunk Returner¶

A Splunk Returner that uses HTTP Event Collector is now available ( PR 30718).

SQLCipher Pillar Module¶

Support was added for retrieving pillar data via queries to SQLCiper databases ( PR 29782).

New Modules¶

The following list contains a link to the new modules added in this release.

Beacons¶

Engines¶

Execution Modules¶

Pillar¶

Proxy¶

Roster¶

States¶

Salt 2016.3.1 Release Notes¶

Version 2016.3.1 is a bugfix release for 2016.3.0. Final Release of Debian 7 Packages Regular security support for Debian 7 ended on April 25th 2016. As a result, 2016.3.1 and 2015.8.10 will be the last Salt releases for which Debian 7 packages are created.

Changes for v2016.3.0..v2016.3.1¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-06-08T22:43:50Z Total Merges: 87 Changes:

Salt 2016.3.2 Release Notes¶

Version 2016.3.2 is a bugfix release for 2016.3.0.

Returner Changes¶

Changes for v2016.3.1..2016.3.2¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-07-27T15:47:45Z Statistics:
Changes:

Salt 2016.3.3 Release Notes¶

Version 2016.3.3 is a bugfix release for 2016.3.0.

Known Issues¶

issue 36055: Salt Cloud events (salt/cloud) are not generated on the master event bus when provisioning cloud systems. Bootstrap Issue #973: python-futures is not installed when installing from a git tag on RedHat-based distributions. Python futures is needed when running Salt with the TCP transport. This is fixed on the develop branch of the salt-bootstrap repo and the fix will be included in the upcoming release of salt-bootstrap, but is a bug in the bootstrap release that ships with this version of Salt. Please see the salt-bootstrap repo for more information on how to update your bootstrap version.

Changes for v2016.3.2..2016.3.3¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-08-19T16:17:34Z Total Merges: 134 Changes:

Salt 2016.3.4 Release Notes¶

Version 2016.3.4 is a bugfix release for 2016.3.0.

Known Issues¶

The Salt Minion does not clean up files in /tmp when rendering templates. This potentially results in either running out of disk space or running out of inodes. Please see Issue #37541 for more information. This bug was fixed with Pull Request #37540, which will be available in the 2016.3.5 release of Salt. The release of the bootstrap-salt.sh script that is included with 2016.3.4 release has a bug in it that fails to install salt correctly for git installs using tags in the 2015.5 branch. This bug has not been fixed in the salt-bootstrap repository yet, but the previous bootstrap release (v2016.08.16) does not contain this bug.

Changes¶

Changes for v2016.3.3..v2016.3.4¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-10-27T16:10:53Z Total Merges: 274 Changes:

Salt 2016.3.5 Release Notes¶

Version 2016.3.5 is a bugfix release for 2016.3.0.

Improved Checksum Handling in file.managed, archive.extracted States¶

When the source_hash argument for these states refers to a file containing checksums, Salt now looks for checksums matching the name of the source URI, as well as the file being managed. Prior releases only looked for checksums matching the filename being managed. Additionally, a new argument ( source_hash_name) has been added, which allows the user to disambiguate ambiguous matches when more than one matching checksum is found in the source_hash file. A more detailed explanation of this functionality can be found in the file.managed documentation, in the section for the new source_hash_name argument.

Salt 2015.8.0 Release Notes - Codename Beryllium¶

2015.8.0 Detailed Change List¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs) Generated at: 2015-09-09T18:15:43Z This list includes all pull requests merged into the 2015.8 branch between the forking of the branch from develop and the release of 2015.8.0. Statistics:
Pull Requests:
The 2015.8.0 feature release of Salt contains several major new features. As usual the release notes are not exhaustive and primarily include the most notable additions and improvements. Hundreds of bugs have been fixed and many modules have been substantially updated and added.

New SaltStack Installation Repositories¶

SaltStack now provides installation repositories for several platforms, with more to come. See the following links for instructions:

Send Event on State Completion¶

A fire_event global state keyword argument was added that allows any state to send an event upon completion. Useful for custom progress bars and checking in on long state runs. See fire_event.

ZeroMQ socket monitoring¶

If zmq_monitor is enabled, log all ZMQ events for socket monitoring purposes. Verbose, but useful.

SPM (Salt Package Manager)¶

Allows Salt formulas to be packaged for ease of deployment. See spm. NOTE:

Specify a Single Environment for Top Files¶

A new default_top option was added to load the state top file from a single, specific environment, rather than merging top data across all environments. Additionally, new top_file_merge_strategy and env_order options were added for more control over top file merging. See The Top File.

Tornado TCP Transport¶

Implemented a pure-TCP transport, in addition to ZeroMQ and RAET. The new transport uses Tornado, which allows Salt to use a standardized set of libraries for asynchronous behavior, which should greatly improve reliability and performance. NOTE:

Proxy Minion Enhancements¶

Proxy Minions have undergone a significant overhaul in 2015.8, see Proxy Minion Enhancements.

Engines¶

Salt engines are long-running, external processes that leverage Salt. See Salt Engines.

Core Changes¶

Git Pillar¶

The git external pillar has been rewritten to bring it up to feature parity with gitfs. Support for

pygit2_

has been added, bringing with it the ability to access authenticated repositories. Using the new features will require updates to the git ext_pillar configuration, further details can be found in the pillar.git_pillar docs.

Salt Cloud Improvements¶

Salt Cloud Changes¶

State and Execution Module Improvements¶

Git State and Execution Modules Rewritten¶

The git state and execution modules have gone through an extensive overhaul.

Changes in the git.latest State¶

git.config_unset state added¶

This state allows for configuration values (or entire keys) to be unset. See here for more information and example SLS.

git.config State Renamed to git.config_set¶

To reduce confusion after the addition of git.config_unset, the git.config state has been renamed to git.config_set. The old config.get name will still work for a couple releases, allowing time for SLS files to be updated. In addition, this state now supports managing multivar git configuration values. See here for more information and example SLS.

Initial Support for Git Worktrees in Execution Module¶

Several functions have been added to the execution module to manage worktrees (a feature new to Git 2.5.0). State support does not exist yet, but will follow soon.

New Functions in Git Execution Module¶

Changes to Functions in Git Execution Module¶

git.add¶

git.archive¶

git.checkout¶

git.clone¶

git.config_get¶

git.config_set¶

git.fetch¶

git.ls_remote¶

git.merge¶

git.status¶

git.submodule¶

Windows Improvements¶

Windows Software Repo Changes¶

A next-generation (ng) windows software repo is available for 2015.8.0 and later minions. When using this new repository, the repo cache is compiled on the Salt Minion, which enables pillar, grains and other things to be available during compilation time. See the Windows Software Repository documentation for more information.

Changes to legacy Windows repository¶

If you have pre 2015.8 Windows minions connecting to your 2015.8 Salt master, you can continue to use the legacy Windows repository for these Salt minions. If you were previously using this repository and have customized settings, be aware that several config options have been renamed to make their naming more consistent. See the Windows Software Repository documentation for more information.

Win System Module¶

The unit of the timeout parameter in the system.halt, system.poweroff, system.reboot, and system.shutdown functions has been changed from seconds to minutes in order to be consistent with the linux timeout setting. ( issue 24411) Optionally, the unit can be reverted to seconds by specifying in_seconds=True.

Other Improvements¶

Deprecations¶

Security Fixes¶

CVE-2015-6918 - Git modules leaking HTTPS auth credentials to debug log Updated the Git state and execution modules to no longer display HTTPS basic authentication credentials in loglevel debug output on the Salt master. These credentials are now replaced with REDACTED in the debug output. Thanks to Andreas Stieger < asteiger@suse.com> for bringing this to our attention.

Major Bug Fixes¶

Salt 2015.8.1 Release Notes¶

Version 2015.8.1 is a bugfix release for 2015.8.0.

Security Fixes¶

CVE-2015-6941 - win_useradd module and salt-cloud display passwords in debug log Updated the win_useradd module return data to no longer include the password of the newly created user. The password is now replaced with the string XXX-REDACTED-XXX. Updated the Salt Cloud debug output to no longer display win_password and sudo_password authentication credentials. Also updated the Linode driver to no longer display authentication credentials in debug logs. These credentials are now replaced with REDACTED in the debug output. CVE-2015-6918 - Git modules leaking HTTPS auth credentials to debug log Updated the Git state and execution modules to no longer display HTTPS basic authentication credentials in loglevel debug output on the Salt master. These credentials are now replaced with REDACTED in the debug output. Thanks to Andreas Stieger < asteiger@suse.com> for bringing this to our attention.

Major Bug Fixes¶

Known Issues:

Changes for v2015.8.0..v2015.8.1¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2015-10-01T04:45:02Z Total Merges: 200 Changes:

Salt 2015.8.10 Release Notes¶

Version 2015.8.10 is a bugfix release for 2015.8.0. Final Release of Debian 7 Packages Regular security support for Debian 7 ended on April 25th 2016. As a result, 2016.3.1 and 2015.8.10 will be the last Salt releases for which Debian 7 packages are created.

Changes for v2015.8.9..v2015.8.10¶

Salt 2015.8.10 includes fixes for the following known issues in 2015.8.9:
Since 2015.8.10 includes only two fixes, the 2015.8.9 changes list is included below for convenience: ---- Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-05-17T17:09:39Z Total Merges: 145 Changes:

Salt 2015.8.11 Release Notes¶

Version 2015.8.11 is a bugfix release for 2015.8.0.

Returner Changes¶

New Configuration Parameter: rotate_aes_key¶

Ubuntu 16.04 Packages¶

SaltStack is now providing official Salt 2015.8 packages for Ubuntu 16.04.

Changes for v2015.8.10..v2015.8.11¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-07-14T21:16:18Z Total Merges: 122 Changes:

Salt 2015.8.12 Release Notes¶

Version 2015.8.12 is a bugfix release for 2015.8.0.

Changes for v2015.8.11..v2015.8.12¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-08-19T16:06:27Z Total Merges: 57 Changes:

Salt 2015.8.13 Release Notes¶

Version 2015.8.13 is a bugfix release for 2015.8.0.

Changes for v2015.8.12..v2015.8.13¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2017-01-09T21:17:06Z Statistics:
Changes:

Salt 2015.8.2 Release Notes¶

NOTE:
Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2015-11-13T17:24:04Z Total Merges: 378 Changes:

Salt 2015.8.3 Release Notes¶

Security Fix¶

CVE-2015-8034: Saving state.sls cache data to disk with insecure permissions This affects users of the state.sls function. The state run cache on the minion was being created with incorrect permissions. This file could potentially contain sensitive data that was inserted via jinja into the state SLS files. The permissions for this file are now being set correctly. Thanks to @zmalone for bringing this issue to our attention.

Changes¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2015-11-25T00:03:40Z Merges: 452 Changes:

Salt 2015.8.4 Release Notes¶

Known Issues¶

in_ requisites (issue 30820) This issue affects all users targeting an explicit - name: <name> with a _in requisite (such as watch_in or require_in). If you are not using explicit - name: <name> arguments, are targeting with the state ID instead of the name, or are not using _in requisites, then you should be safe to upgrade to 2015.8.4. This issue is resolved in the 2015.8.5 release.

Security Fix¶

CVE-2016-1866: Improper handling of clear messages on the minion, which could result in executing commands not sent by the master. This issue affects only the 2015.8.x releases of Salt. In order for an attacker to use this attack vector, they would have to execute a successful attack on an existing TCP connection between minion and master on the pub port. It does not allow an external attacker to obtain the shared secret or decrypt any encrypted traffic between minion and master. Thank you to Sebastian Krahmer < krahmer@suse.com> for bringing this issue to our attention. We recommend everyone upgrade to 2015.8.4 as soon as possible.

Core Changes¶

Changes for v2015.8.3..v2015.8.4¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-01-25T17:48:35Z Total Merges: 320 Changes:

Salt 2015.8.5 Release Notes¶

Known Issue in boto_* execution modules¶

This release contains an issue that causes the boto_* execution modules to display a __salt__ not defined error (issue 30300). This issue will be fixed in an upcoming release, but can be manually resolved by completing the following:
---- 2015.8.4 Release Notes

Security Fix¶

CVE-2016-1866: Improper handling of clear messages on the minion, which could result in executing commands not sent by the master. This issue affects only the 2015.8.x releases of Salt. In order for an attacker to use this attack vector, they would have to execute a successful attack on an existing TCP connection between minion and master on the pub port. It does not allow an external attacker to obtain the shared secret or decrypt any encrypted traffic between minion and master. Thank you to Sebastian Krahmer < krahmer@suse.com> for bringing this issue to our attention. We recommend everyone upgrade to 2015.8.4 as soon as possible.

Core Changes¶

Changes for v2015.8.3..v2015.8.4¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-01-25T17:48:35Z Total Merges: 320 Changes:

Salt 2015.8.7 Release Notes¶

NOTE:

Changes for v2015.8.4..v2015.8.7¶

For pkg.installed states, on Linux distributions which use yum/dnf, packages which have a non-zero epoch in the version number now require this epoch to be included when specifying an exact version for a package. For example:
The pkg.latest_version and pkg.list_repo_pkgs functions can be used to get the correct version string to use, as they will now contain the epoch when it is non-zero. Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-02-11T22:13:51Z Statistics:
Changes:
----

Security Fix¶

CVE-2016-1866: Improper handling of clear messages on the minion, which could result in executing commands not sent by the master. This issue affects only the 2015.8.x releases of Salt. In order for an attacker to use this attack vector, they would have to execute a successful attack on an existing TCP connection between minion and master on the pub port. It does not allow an external attacker to obtain the shared secret or decrypt any encrypted traffic between minion and master. Thank you to Sebastian Krahmer < krahmer@suse.com> for bringing this issue to our attention. We recommend everyone upgrade to 2015.8.4 as soon as possible.

Core Changes¶

Changes for v2015.8.3..v2015.8.4¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-01-25T17:48:35Z Total Merges: 320 Changes:

Salt 2015.8.8 Release Notes¶

IMPORTANT:

Salt 2015.8.8.2¶

Salt 2015.8.8.2 includes fixes for the following known issues in 2015.8.8:
IMPORTANT:

Salt 2015.8.8¶

Security Fix¶

CVE-2016-3176: Insecure configuration of PAM external authentication service This issue affects all Salt versions prior to 2015.8.8/2015.5.10 when PAM external authentication is enabled. This issue involves passing an alternative PAM authentication service with a command that is sent to LocalClient, enabling the attacker to bypass the configured authentication service. Thank you to Dylan Frese < dmfrese@gmail.com> for bringing this issue to our attention. This update defines the PAM eAuth service that users authenticate against in the Salt Master configuration.

Read Before Upgrading Debian 7 (Wheezy) from 2015.8.7 to 2015.8.8¶

Before you upgrade from 2015.8.7 on Debian 7, you must run the following commands to remove previous packages:
Note that python-pycrypto will likely remove python-apache-libcloud, so the second command might not be necessary. These have been replaced by python-crypto and python-libcloud with ~bpo70+1 moniker.

Read Before Upgrading Debian 8 (Jessie) from Salt Versions Earlier than 2015.8.4¶

Salt systemd service files are missing the following statement in these versions:
This statement must be added to successfully upgrade on these earlier versions of Salt.

Changes for v2015.8.7..v2015.8.8¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-03-17T21:03:44Z Total Merges: 312 Changes:

Salt 2015.8.9 Release Notes¶

Version 2015.8.9 is a bugfix release for 2015.8.0.

Changes for v2015.8.8..v2015.8.9¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-05-17T17:09:39Z Total Merges: 145 Changes:

Salt 2015.5.0 Release Notes - Codename Lithium¶

The 2015.5.0 feature release of Salt is focused on hardening Salt and mostly on improving existing systems. A few major additions are present, primarily the new Beacon system. Most enhancements have been focused around improving existing features and interfaces. As usual the release notes are not exhaustive and primarily include the most notable additions and improvements. Hundreds of bugs have been fixed and many modules have been substantially updated and added. WARNING:
NOTE:

Beacons¶

The beacon system allows the minion to hook into system processes and continually translate external events into the salt event bus. The primary example of this is the inotify beacon. This beacon uses inotify to watch configured files or directories on the minion for changes, creation, deletion etc. This allows for the changes to be sent up to the master where the reactor can respond to changes.

Sudo Minion Settings¶

It is now possible to run the minion as a non-root user and for the minion to execute commands via sudo. Simply add sudo_user: root to the minion config, run the minion as a non-root user and grant that user sudo rights to execute salt-call.

Lazy Loader¶

The Lazy Loader is a significant overhaul of Salt's module loader system. The Lazy Loader will lazily load modules on access instead of all on start. In addition to a major performance improvement, this "sandboxes" modules so a bad/broken import of a single module will only affect jobs that require accessing the broken module. (:issue: 20274)

Enhanced Active Directory Support¶

The eauth system for LDAP has been extended to support Microsoft Active Directory out of the box. This includes Active Directory and LDAP group support for eauth.

Salt LXC Enhancements¶

The LXC systems have been overhauled to be more consistent and to fix many bugs. This overhaul makes using LXC with Salt much easier and substantially improves the underlying capabilities of Salt's LXC integration.

Salt SSH¶

New Windows Installer¶

The new Windows installer changes how Salt is installed on Windows. The old installer used bbfreeze to create an isolated python environment to execute in. This made adding modules and python libraries difficult. The new installer sets up a more flexible python environment making it easy to manage the python install and add python modules. Instead of frozen packages, a full python implementation resides in the bin directory ( C:\salt\bin). By executing pip or easy_install from within the Scripts directory ( C:\salt\bin\Scripts) you can install any additional python modules you may need for your custom environment. The .exe's that once resided at the root of the salt directory ( C:\salt) have been replaced by .bat files and should function the same way as the .exe's in previous versions. The new Windows Installer will not replace the minion config file and key if they already exist on the target system. Only the salt program files will be replaced. C:\salt\conf and C:\salt\var will remain unchanged.

Removed Requests Dependency¶

The hard dependency on the requests library has been removed. Requests is still required by a number of cloud modules but is no longer required for normal Salt operations. This removal fixes issues that were introduced with requests and salt-ssh, as well as issues users experienced from the many different packaging methods used by requests package maintainers.

Python 3 Updates¶

While Salt does not YET run on Python 3 it has been updated to INSTALL on Python 3, taking us one step closer. What remains is getting the test suite to the point where it can run on Python 3 so that we can verify compatibility.

RAET Additions¶

The RAET support continues to improve. RAET now supports multi-master and many bugs and performance issues have been fixed. RAET is much closer to being a first class citizen.

Modified File Detection¶

A number of functions have been added to the RPM-based package managers to detect and diff files that are modified from the original package installs. This can be found in the new pkg.modified functions.

Reactor Update¶

Fix an infinite recursion problem for runner/wheel reactor jobs by passing a "user" (Reactor) to all jobs that the reactor starts. The reactor skips all events created by that username -- thereby only reacting to events not caused by itself. Because of this, runner and wheel executions from the runner will have user "Reactor" in the job cache.

Misc Fixes/Additions¶

Deprecations¶

Known Issues¶

Salt 2015.5.1 Release Notes¶

Version 2015.5.1 is a bugfix release for 2015.5.0. Changes:
Extended Changelog Courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs):

Salt 2015.5.10 Release Notes¶

Security Fix¶

CVE-2016-3176: Insecure configuration of PAM external authentication service This issue affects all Salt versions prior to 2015.8.8/2015.5.10 when PAM external authentication is enabled. This issue involves passing an alternative PAM authentication service with a command that is sent to LocalClient, enabling the attacker to bypass the configured authentication service. Thank you to Dylan Frese < dmfrese@gmail.com> for bringing this issue to our attention. This update defines the PAM eAuth service that users authenticate against in the Salt Master configuration. (No additional fixes are contained in this release).

Read Before Upgrading Debian 8 (Jessie) from Salt Versions Earlier than 2015.5.9¶

Salt systemd service files are missing the following statement in these versions:
This statement must be added to successfully upgrade on these earlier versions of Salt.

Salt 2015.5.11 Release Notes¶

Version 2015.5.11 is a bugfix release for 2015.5.0.

Changes for v2015.5.10..v2015.5.11¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-05-20T21:02:38Z Total Merges: 101 Changes:

Salt 2015.5.2 Release Notes¶

Version 2015.5.2 is a bugfix release for 2015.5.0. Extended Changelog Courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs):

Salt 2015.5.3 Release Notes¶

Extended Changelog Courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2015-07-01T19:40:52Z Statistics:
Changes:

Salt 2015.5.4 Release Notes¶

Version 2015.5.4 is a bugfix release for 2015.5.0. Changes:

Changes for v2015.5.3..v2015.5.4¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2015-08-13T20:23:30Z Statistics:
Changes:

Salt 2015.5.5 Release Notes¶

Version 2015.5.5 is a bugfix release for 2015.5.0. Changes:

Changes for v2015.5.3..v2015.5.5¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2015-08-20T17:02:37Z Statistics:
Changes:

Salt 2015.5.6 Release Notes¶

Version 2015.5.6 is a bugfix release for 2015.5.0.

Security Fixes¶

CVE-2015-6941 - win_useradd module and salt-cloud display passwords in debug log Updated the win_useradd module return data to no longer include the password of the newly created user. The password is now replaced with the string XXX-REDACTED-XXX. Updated the Salt Cloud debug output to no longer display win_password and sudo_password authentication credentials. CVE-2015-6918 - Git modules leaking HTTPS auth credentials to debug log Updated the Git state and execution modules to no longer display HTTPS basic authentication credentials in loglevel debug output on the Salt master. These credentials are now replaced with REDACTED in the debug output. Thanks to Andreas Stieger < asteiger@suse.com> for bringing this to our attention.

Changes for v2015.5.5..v2015.5.6¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2015-09-30T22:22:43Z Total Merges: 144 Changes:

Salt 2015.5.7 Release Notes¶

NOTE:
Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2015-11-13T17:11:14Z Total Merges: 102 Changes:

Salt 2015.5.8 Release Notes¶

Security Fix¶

CVE-2015-8034: Saving state.sls cache data to disk with insecure permissions This affects users of the state.sls function. The state run cache on the minion was being created with incorrect permissions. This file could potentially contain sensitive data that was inserted via jinja into the state SLS files. The permissions for this file are now being set correctly. Thanks to @zmalone for bringing this issue to our attention.

Changes¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2015-11-23T23:16:23Z Total Merges: 118 Changes:

Salt 2015.5.9 Release Notes¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-01-08T23:02:31Z Total Merges: 44 Changes:

Salt 2014.7.0 Release Notes - Codename Helium¶

This release is the largest Salt release ever, with more features and commits then any previous release of Salt. Everything from the new RAET transport to major updates in Salt Cloud and the merging of Salt API into the main project. IMPORTANT:
IMPORTANT:

New Transport!¶

RAET Transport Option¶

This has been a HUGE amount of work, but the beta release of Salt with RAET is ready to go. RAET is a reliable queuing transport system that has been developed in partnership with a number of large enterprises to give Salt an alternative to ZeroMQ and a way to get Salt to scale well beyond tens of thousands of servers. Unlike ZeroMQ, RAET is completely asynchronous in every aspect of its operation and has been developed using the flow programming paradigm. This allows for many new capabilities to be added to Salt in the upcoming releases. Please keep in mind that this is a beta release of RAET and we hope for bugs to be worked out, performance to be better realized and more in the 2015.5.0 release. Simply stated, users running Salt with RAET should expect some hiccups as we hammer out the update. This is a BETA release of Salt RAET. For information about how to use Salt with RAET please see the tutorial.

Salt SSH Enhancements¶

Salt SSH has just entered a new league, with substantial updates and improvements to make salt-ssh more reliable and easier then ever! From new features like the ansible roster and fileserver backends to the new pypi salt-ssh installer to lowered deps and a swath of bugfixes, salt-ssh is basically reborn!

Install salt-ssh Using pip¶

Salt-ssh is now pip-installable! https://pypi.python.org/pypi/salt-ssh/ Pip will bring in all of the required deps, and while some deps are compiled, they all include pure python implementations, meaning that any compile errors which may be seen can be safely ignored.

Fileserver Backends¶

Salt-ssh can now use the salt fileserver backend system. This allows for the gitfs, hgfs, s3, and many more ways to centrally store states to be easily used with salt-ssh. This also allows for a distributed team to easily use a centralized source.

Saltfile Support¶

The new saltfile system makes it easy to have a user specific custom extended configuration.

Ext Pillar¶

Salt-ssh can now use the external pillar system. Making it easier then ever to use salt-ssh with teams.

No More sshpass¶

Thanks to the enhancements in the salt vt system, salt-ssh no longer requires sshpass to send passwords to ssh. This also makes the manipulation of ssh calls substantially more flexible, allowing for intercepting ssh calls in a much more fluid way.

Pure Python Shim¶

The salt-ssh call originally used a shell script to discover what version of python to execute with and determine the state of the ssh code deployment. This shell script has been replaced with a pure python version making it easy to increase the capability of the code deployment without causing platform inconsistency issues with different shell interpreters.

Custom Module Delivery¶

Custom modules are now seamlessly delivered. This makes the deployment of custom grains, states, execution modules and returners a seamless process.

CP Module Support¶

Salt-ssh now makes simple file transfers easier then ever! The cp module allows for files to be conveniently sent from the salt fileserver system down to systems.

More Thin Directory Options¶

Salt ssh functions by copying a subset of the salt code, or salt thin down to the target system. In the past this was always transferred to /tmp/.salt and cached there for subsequent commands. Now, salt thin can be sent to a random directory and removed when the call is complete with the -W option. The new -W option still uses a static location but will clean up that location when finished. The default salt thin location is now user defined, allowing multiple users to cleanly access the same systems.

State System Enhancements¶

New Imperative State Keyword Listen¶

The new listen and listen_in keywords allow for completely imperative states by calling the mod_watch() routine after all states have run instead of re-ordering the states.

Mod Aggregate Runtime Manipulator¶

The new mod_aggregate system allows for the state system to rewrite the state data during execution. This allows for state definitions to be aggregated dynamically at runtime. The best example is found in the pkg state. If mod_aggregate is turned on, then when the first pkg state is reached, the state system will scan all of the other running states for pkg states and take all other packages set for install and install them all at once in the first pkg state. These runtime modifications make it easy to run groups of states together. In future versions, we hope to fill out the mod_aggregate system to build in more and more optimizations. For more documentation on mod_aggregate, see the documentation.

New Requisites: onchanges and onfail¶

The new onchanges and onchanges_in requisites make a state apply only if there are changes in the required state. This is useful to execute post hooks after changes occur on a system. The other new requisites, onfail, and onfail_in, allow for a state to run in reaction to the failure of another state. For more information about these new requisites, see the requisites documentation.

Global onlyif and unless¶

The onlyif and unless options can now be used for any state declaration.

Use names to expand and override values¶

The names declaration in Salt's state system can now override or add values to the expanded data structure. For example:

Major Features¶

Scheduler Additions¶

The Salt scheduler system has received MAJOR enhancements, allowing for cron-like scheduling and much more granular timing routines. See here for more info.

Red Hat 7 Family Support¶

All the needed additions have been made to run Salt on RHEL 7 and derived OSes like CentOS and Scientific.

Fileserver Backends in salt-call¶

Fileserver backends like gitfs can now be used without a salt master! Just add the fileserver backend configuration to the minion config and execute salt-call. This has been a much-requested feature and we are happy to finally bring it to our users.

Amazon Execution Modules¶

An entire family of execution modules further enhancing Salt's Amazon Cloud support. They include the following:

LXC Runner Enhancements¶

BETA The Salt LXC management system has received a number of enhancements which make running an LXC cloud entirely from Salt an easy proposition.

Next Gen Docker Management¶

The Docker support in Salt has been increased at least ten fold. The Docker API is now completely exposed and Salt ships with Docker data tracking systems which make automating Docker deployments very easy.

Peer System Performance Improvements¶

The peer system communication routines have been refined to make the peer system substantially faster.

SDB¶

Encryption at rest for configs

GPG Renderer¶

Encrypted pillar at rest

OpenStack Expansion¶

Lots of new OpenStack stuff

Queues System¶

Ran change external queue systems into Salt events

Multi Master Failover Additions¶

Connecting to multiple masters is more dynamic then ever

Chef Execution Module¶

Managing Chef with Salt just got even easier!

salt-api Project Merge¶

The salt-api project has been merged into Salt core and is now available as part of the regular salt-master package install. No API changes were made, the salt-api script and init scripts remain intact. salt-api has always provided Yet Another Pluggable Interface to Salt (TM) in the form of "netapi" modules. These are modules that bind to a port and start a service. Like many of Salt's other module types, netapi modules often have library and configuration dependencies. See the documentation for each module for instructions. SEE ALSO:

Synchronous and Asynchronous Execution of Runner and Wheel Modules¶

salt.runner.RunnerClient and salt.wheel.WheelClient have both gained complimentary cmd_sync and cmd_async methods allowing for synchronous and asynchronous execution of any Runner or Wheel module function, all protected using Salt's external authentication system. salt-api benefits from this addition as well.

rest_cherrypy Additions¶

The rest_cherrypy netapi module provides the main REST API for Salt.

Web Hooks¶

This release of course includes the Web Hook additions from the most recent salt-api release, which allows external services to signal actions within a Salt infrastructure. External services such as Amazon SNS, Travis-CI, or GitHub, as well as internal services that cannot or should not run a Salt minion daemon can be used as first-class components in Salt's rich orchestration capabilities. The raw HTTP request body is now available in the event data. This is sometimes required information for checking an HMAC signature in order to verify a HTTP request. As an example, Amazon or GitHub requests are signed this way.

Generating and Accepting Minion Keys¶

The /key convenience URL generates a public and private key for a minion, automatically pre-accepts the public key on the Salt Master, and returns both keys as a tarball for download. This allows for easily bootstrapping the key on a new minion with a single HTTP call, such as with a Kickstart script, all using regular shell tools.

Fileserver Backend Enhancements¶

All of the fileserver backends have been overhauled to be faster, lighter, and more reliable. The VCS backends ( gitfs, hgfs, and svnfs) have also received a lot of new features. Additionally, most config parameters for the VCS backends can now be configured on a per-remote basis, allowing for global config parameters to be overridden for a specific gitfs/hgfs/svnfs remote.

New gitfs Features¶

Pygit2 and Dulwich¶

In addition to supporting GitPython, support for pygit2 (0.20.3 and newer) and dulwich have been added. Provided a compatible version of pygit2 is installed, it will now be the default provider. The config parameter gitfs_provider has been added to allow one to choose a specific provider for gitfs.

Mountpoints¶

Prior to this release, to serve a file from gitfs at a salt fileserver URL of salt://foo/bar/baz.txt, it was necessary to ensure that the parent directories existed in the repository. A new config parameter gitfs_mountpoint allows gitfs remotes to be exposed starting at a user-defined salt:// URL.

Environment Whitelisting/Blacklisting¶

By default, gitfs will expose all branches and tags as Salt fileserver environments. Two new config parameters, gitfs_env_whitelist, and gitfs_env_blacklist, allow more control over which branches and tags are exposed. More detailed information on how these two options work can be found in the Gitfs Walkthrough.

Expanded Authentication Support¶

As of pygit2 0.20.3, both http(s) and SSH key authentication are supported, and Salt now also supports both authentication methods when using pygit2. Keep in mind that pygit2 0.20.3 is not yet available on many platforms, so those who had been using authenticated git repositories with a passphraseless key should stick to GitPython if a new enough pygit2 is not yet available for the platform on which the master is running. A full explanation of how to use authentication can be found in the Gitfs Walkthrough.

New hgfs Features¶

Mountpoints¶

This feature works exactly like its gitfs counterpart. The new config parameter is called hgfs_mountpoint.

Environment Whitelisting/Blacklisting¶

This feature works exactly like its gitfs counterpart. The new config parameters are called hgfs_env_whitelist and hgfs_env_blacklist.

New svnfs Features¶

Mountpoints¶

This feature works exactly like its gitfs counterpart. The new config parameter is called svnfs_mountpoint.

Environment Whitelisting/Blacklisting¶

This feature works exactly like its gitfs counterpart. The new config parameters are called svnfs_env_whitelist and svnfs_env_blacklist.

Configurable Trunk/Branches/Tags Paths¶

Prior to this release, the paths where trunk, branches, and tags were located could only be in directories named "trunk", "branches", and "tags" directly under the root of the repository. Three new config parameters ( svnfs_trunk, svnfs_branches, and svnfs_tags) allow SVN repositories which are laid out differently to be used with svnfs.

New minionfs Features¶

Mountpoint¶

This feature works exactly like its gitfs counterpart. The new config parameter is called minionfs_mountpoint. The one major difference is that, as minionfs doesn't use multiple remotes (it just serves up files pushed to the master using cp.push) there is no such thing as a per-remote configuration for minionfs_mountpoint.

Changing the Saltenv from Which Files are Served¶

A new config parameter ( minionfs_env) allows minionfs files to be served from a Salt fileserver environment other than base.

Minion Whitelisting/Blacklisting¶

By default, minionfs will expose the pushed files from all minions. Two new config parameters, minionfs_whitelist, and minionfs_blacklist, allow minionfs to be restricted to serve files from only the desired minions.

Pyobjects Renderer¶

Salt now ships with with the Pyobjects Renderer that allows for construction of States using pure Python with an idiomatic object interface.

New Modules¶

In addition to the Amazon modules mentioned above, there are also several other new execution modules:

New Runners¶

New External Pillars¶

New Salt-Cloud Providers¶

Salt Call Change¶

When used with a returner, salt-call now contacts a master if --local is not specicified.

Deprecations¶

salt.modules.virtualenv_mod¶

Salt 2014.7.1 Release Notes¶

Version 2014.7.1 is a bugfix release for 2014.7.0. The changes include:

Salt 2014.7.2 Release Notes¶

Version 2014.7.2 is a bugfix release for 2014.7.0. The changes include:

Salt 2014.7.3 Release Notes¶

Version 2014.7.3 is a bugfix release for 2014.7.0. Changes:
Known issues:

Salt 2014.7.4 Release Notes¶

Version 2014.7.4 is a bugfix release for 2014.7.0. This is a security release. The security issues fixed have only been present since 2014.7.0, and only users of the two listed modules are vulnerable. The following CVEs have been resolved:
Changes:
Known issues:

Salt 2014.7.5 Release Notes¶

Version 2014.7.5 is a bugfix release for 2014.7.0. Changes:
Known issues:

Salt 2014.7.6 Release Notes¶

Version 2014.7.6 is a bugfix release for 2014.7.0. This release is a security release. A minor issue was found, as cited below:
Only users of the Aliyun or Proxmox cloud modules are at risk. The vulnerability does not exist in the latest 2015.5.0 release of Salt. Changes:
Extended Changelog Courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs):

Salt 2014.7.8 Release Notes¶

Changes for v2014.7.7..v2014.7.8¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-03-11T21:18:48Z Statistics:
Changes:

Salt 2014.7.9 Release Notes¶

Changes for v2014.7.8..v2014.7.9¶

Extended changelog courtesy of Todd Stansell ( https://github.com/tjstansell/salt-changelogs): Generated at: 2016-03-11T20:58:58Z Statistics:
Changes:

Salt 2014.1.0 Release Notes - Codename Hydrogen¶

NOTE:
NOTE:

The 2014.1.0 release of Salt is a major release which not only increases stability but also brings new capabilities in virtualization, cloud integration, and more. This release brings a great focus on the expansion of testing making roughly double the coverage in the Salt tests, and comes with many new features. 2014.1.0 is the first release to follow the new date-based release naming system. See the version numbers page for more details.

Major Features¶

Salt Cloud Merged into Salt¶

Salt Cloud is a tool for provisioning salted minions across various cloud providers. Prior to this release, Salt Cloud was a separate project but this marks its full integration with the Salt distribution. A Getting Started guide and additional documentation for Salt Cloud can be found here:

Google Compute Engine¶

Alongside Salt Cloud comes new support for the Google Compute Engine. Salt Stack can now deploy and control GCE virtual machines and the application stacks that they run. For more information on Salt Stack and GCE, please see this blog post. Documentation for Salt and GCE can be found here.

Salt Virt¶

Salt Virt is a cloud controller that supports virtual machine deployment, inspection, migration, and integration with many aspects of Salt. Salt Virt has undergone a major overhaul with this release and now supports many more features and includes a number of critical improvements.

Docker Integration¶

Salt now ships with states and an execution module to manage Docker containers.

Substantial Testing Expansion¶

Salt continues to increase its unit/regression test coverage. This release includes over 300 new tests.

BSD Package Management¶

BSD package management has been entirely rewritten. FreeBSD 9 and older now default to using pkg_add, while FreeBSD 10 and newer will use pkgng. FreeBSD 9 can be forced to use pkgng, however, by specifying the following option in the minion config file:
In addition, support for installing software from the ports tree has been added. See the documentation for the ports state and execution module for more information.

Network Management for Debian/Ubuntu¶

Initial support for management of network interfaces on Debian-based distros has been added. See the documentation for the network state and the debian_ip for more information.

IPv6 Support for iptables State/Module¶

The iptables state and module now have IPv6 support. A new parameter family has been added to the states and execution functions, to distinguish between IPv4 and IPv6. The default value for this parameter is ipv4, specifying ipv6 will use ip6tables to manage firewall rules.

GitFS Improvements¶

Several performance improvements have been made to the Git fileserver backend. Additionally, file states can now use any any SHA1 commit hash as a fileserver environment:
This applies to the functions in the cp module as well:

MinionFS¶

This new fileserver backend allows files which have been pushed from the minion to the master (using cp.push) to be served up from the salt fileserver. The path for these files takes the following format:
minion-id is the id of the "source" minion, the one from which the files were pushed to the master. /path/to/file is the full path of the file. The MinionFS Walkthrough contains a more thorough example of how to use this backend.

saltenv¶

To distinguish between fileserver environments and execution functions which deal with environment variables, fileserver environments are now specified using the saltenv parameter. env will continue to work, but is deprecated and will be removed in a future release.

Grains Caching¶

A caching layer has been added to the Grains system, which can help speed up minion startup. Disabled by default, it can be enabled by setting the minion config option grains_cache:
If set to True, the grains loader will read from/write to a msgpack-serialized file containing the grains data. Additional command-line parameters have been added to salt-call, mainly for testing purposes:

Improved Command Logging Control¶

When using the cmd module, either on the CLI or when developing Salt execution modules, a new keyword argument output_loglevel allows for greater control over how (or even if) the command and its output are logged. For example:
The package management modules ( apt, yumpkg, etc.) have been updated to log the copious output generated from these commands at loglevel debug. NOTE:

PagerDuty Support¶

Initial support for firing events via PagerDuty has been added. See the documentation for the pagerduty module.

Virtual Terminal¶

Sometimes the subprocess module is not good enough, and, in fact, not even askpass is. This virtual terminal is still in it's infant childhood, needs quite some love, and was originally created to replace askpass, but, while developing it, it immediately proved that it could do so much more. It's currently used by salt-cloud when bootstrapping salt on clouds which require the use of a password.

Proxy Minions¶

Initial basic support for Proxy Minions is in this release. Documentation can be found here. Proxy minions are a developing feature in Salt that enables control of devices that cannot run a minion. Examples include network gear like switches and routers that run a proprietary OS but offer an API, or "dumb" devices that just don't have the horsepower or ability to handle a Python VM. Proxy minions can be difficult to write, so a simple REST-based example proxy is included. A Python bottle-based webserver can be found at https://github.com/cro/salt-proxy-rest as an endpoint for this proxy. This is an ALPHA-quality feature. There are a number of issues with it currently, mostly centering around process control, logging, and inability to work in a masterless configuration.

Additional Bugfixes (Release Candidate Period)¶

Below are many of the fixes that were implemented in salt during the release candidate phase.

Salt 2014.1.1 Release Notes¶

Version 2014.1.1 is a bugfix release for 2014.1.0. The changes include:

Salt 2014.1.10 Release Notes¶

NOTE:
Version 2014.1.10 is another bugfix release for 2014.1.0. Changes include:
Salt 2014.1.10 fixes security issues documented by CVE-2014-3563: "Insecure tmp-file creation in seed.py, salt-ssh, and salt-cloud." Upgrading is recommended.

Salt 2014.1.11 Release Notes¶

Version 2014.1.11 is another bugfix release for 2014.1.0. Changes include:

Salt 2014.1.12 Release Notes¶

Version 2014.1.12 is another bugfix release for 2014.1.0. Changes include:

Salt 2014.1.13 Release Notes¶

Version 2014.1.13 is another bugfix release for 2014.1.0. Changes include:

Salt 2014.1.2 Release Notes¶

Version 2014.1.2 is another bugfix release for 2014.1.0. The changes include:

Salt 2014.1.3 Release Notes¶

Version 2014.1.3 is another bugfix release for 2014.1.0. It was created as a hotfix for a regression found in 2014.1.2, which was not distributed. The only change made was as follows:
Changes in the not-distributed 2014.1.2, also included in 2014.1.3:

Salt 2014.1.4 Release Notes¶

Version 2014.1.4 is another bugfix release for 2014.1.0. Changes include:

Salt 2014.1.5 Release Notes¶

Version 2014.1.5 is another bugfix release for 2014.1.0. Changes include:

Salt 2014.1.6 Release Notes¶

Version 2014.1.6 is another bugfix release for 2014.1.0. Changes include:

Salt 2014.1.7 Release Notes¶

Version 2014.1.7 is another bugfix release for 2014.1.0. Changes include:
This release was a hotfix release for the regression listed above which was present in the 2014.1.6 release. The changes included in 2014.1.6 are listed below:

Salt 2014.1.8 Release Notes¶

NOTE:
Version 2014.1.8 is another bugfix release for 2014.1.0. Changes include:

Salt 2014.1.9 Release Notes¶

NOTE:
NOTE:
Version 2014.1.9 is another bugfix release for 2014.1.0. Changes include:

Salt 0.10.0 Release Notes¶

0.10.0 has arrived! This release comes with MANY bug fixes, and new capabilities which greatly enhance performance and reliability. This release is primarily a bug fix release with many new tests and many repaired bugs. This release also introduces a few new key features which were brought in primarily to repair bugs and some limitations found in some of the components of the original architecture.

Major Features¶

Event System¶

The Salt Master now comes equipped with a new event system. This event system has replaced some of the back end of the Salt client and offers the beginning of a system which will make plugging external applications into Salt. The event system relies on a local ZeroMQ publish socket and other processes can connect to this socket and listen for events. The new events can be easily managed via Salt's event library.

Unprivileged User Updates¶

Some enhancements have been added to Salt for running as a user other than root. These new additions should make switching the user that the Salt Master is running as very painless, simply change the user option in the master configuration and restart the master, Salt will take care of all of the particulars for you.

Peer Runner Execution¶

Salt has long had the peer communication system used to allow minions to send commands via the salt master. 0.10.0 adds a new capability here, now the master can be configured to allow for minions to execute Salt runners via the peer_run option in the salt master configuration.

YAML Parsing Updates¶

In the past the YAML parser for sls files would return the incorrect numbers when the file mode was set with a preceding 0. The YAML parser used in Salt has been modified to no longer convert these number into octal but to keep them as the correct value so that sls files can be a little cleaner to write.

State Call Data Files¶

It was requested that the minion keep a local cache of the most recent executed state run. This has been added and now with state runs the data is stored in a msgpack file in the minion's cachedir.

Turning Off the Job Cache¶

A new option has been added to the master configuration file. In previous releases the Salt client would look over the Salt job cache to read in the minion return data. With the addition of the event system the Salt client can now watch for events directly from the master worker processes. This means that the job cache is no longer a hard requirement. Keep in mind though, that turning off the job cache means that historic job execution data cannot be retrieved.

Test Updates¶

Minion Swarms Are Faster¶

To continue our efforts with testing Salt's ability to scale the minionswarm script has been updated. The minionswarm can now start up minions much faster than it could before and comes with a new feature allowing modules to be disabled, thus lowering the minion's footprint when making a swarm. These new updates have allows us to test

Many Fixes¶

To get a good idea for the number of bugfixes this release offers take a look at the closed tickets for 0.10.0, this is a very substantial update: https://github.com/saltstack/salt/issues?milestone=12&state=closed

Master and Minion Stability Fixes¶

As Salt deployments grow new ways to break Salt are discovered. 0.10.0 comes with a number of fixes for the minions and master greatly improving Salt stability.

Salt 0.10.1 Release Notes¶

Salt 0.10.2 Release Notes¶

0.10.2 is out! This release comes with enhancements to the pillar interface, cleaner ways to access the salt-call capabilities in the API, minion data caching and the event system has been added to salt minions. There have also been updates to the ZeroMQ functions, many more tests (thanks to sponsors, the code sprint and many contributors) and a swath of bug fixes.

Major Features¶

Ext Pillar Modules¶

The ranks of available Salt modules directories sees a new member in 0.10.2. With the popularity of pillar a higher demand has arisen for ext_pillar interfaces to be more like regular Salt module additions. Now ext_pillar interfaces can be added in the same way as other modules, just drop it into the pillar directory in the salt source.

Minion Events¶

In 0.10.0 an event system was added to the Salt master. 0.10.2 adds the event system to the minions as well. Now event can be published on a local minion as well. The minions can also send events back up to the master. This means that Salt is able to communicate individual events from the minions back up to the Master which are not associated with command.

Minion Data Caching¶

When pillar was introduced the landscape for available data was greatly enhanced. The minion's began sending grain data back to the master on a regular basis. The new config option on the master called minion_data_cache instructs the Salt master to maintain a cache of the minion's grains and pillar data in the cachedir. This option is turned off by default to avoid hitting the disk more, but when enabled the cache is used to make grain matching from the salt command more powerful, since the minions that will match can be predetermined.

Backup Files¶

By default all files replaced by the file.managed and file.recurse states we simply deleted. 0.10.2 adds a new option. By setting the backup option to minion the files are backed up before they are replaced. The backed up files are located in the cachedir under the file_backup directory. On a default system this will be at: /var/cache/salt/file_backup

Configuration files¶

salt-master and salt-minion automatically load additional configuration files from master.d/*.conf respective minion.d/*.conf where master.d/minion.d is a directory in the same directory as the main configuration file.

Salt Key Verification¶

A number of users complained that they had inadvertently deleted the wrong salt authentication keys. 0.10.2 now displays what keys are going to be deleted and verifies that they are the keys that are intended for deletion.

Key auto-signing¶

If autosign_file is specified in the configuration file incoming keys will be compared to the list of keynames in autosign_file. Regular expressions as well as globbing is supported. The file must only be writable by the user otherwise the file will be ignored. To relax the permission and allow group write access set the permissive_pki_access option.

Module changes¶

Improved OpenBSD support¶

New modules for managing services and packages were provided by Joshua Elsasser to further improve the support for OpenBSD. Existing modules like the disk module were also improved to support OpenBSD.

SQL Modules¶

The MySQL and PostgreSQL modules have both received a number of additions thanks to the work of Avi Marcus and Roman Imankulov.

ZFS Support on FreeBSD¶

A new ZFS module has been added by Kurtis Velarde for FreeBSD supporting various ZFS operations like creating, extending or removing zpools.

Augeas¶

A new Augeas module by Ulrich Dangel for editing and verifying config files.

Native Debian Service module¶

The support for the Debian was further improved with an new service module for Debian by Ahmad Khayyat supporting disable and enable.

Cassandra¶

Cassandra support has been added by Adam Garside. Currently only status and diagnostic information are supported.

Networking¶

The networking support for RHEL has been improved and supports bonding support as well as zeroconf configuration.

Monit¶

Basic monit support by Kurtis Velarde to control services via monit.

nzbget¶

Basic support for controlling nzbget by Joseph Hall

Bluetooth¶

Baisc bluez support for managing and controlling Bluetooth devices. Supports scanning as well as pairing/unpairing by Joseph Hall.

Test Updates¶

Consistency Testing¶

Another testing script has been added. A bug was found in pillar when many minions generated pillar data at the same time. The new consist.py script is the tests directory was created to reproduce bugs where data should always be consistent.

Many Fixes¶

To get a good idea for the number of bugfixes this release offers take a look at the closed tickets for 0.10.2, this is a very substantial update: https://github.com/saltstack/salt/issues?milestone=24&page=1&state=closed

Master and Minion Stability Fixes¶

As Salt deployments grow new ways to break Salt are discovered. 0.10.2 comes with a number of fixes for the minions and master greatly improving Salt stability.

Salt 0.10.3 Release Notes¶

The latest taste of Salt has come, this release has many fixes and feature additions. Modifications have been made to make ZeroMQ connections more reliable, the beginning of the ACL system is in place, a new command line parsing system has been added, dynamic module distribution has become more environment aware, the new master_finger option and many more!

Major Features¶

ACL System¶

The new ACL system has been introduced. The ACL system allows for system users other than root to execute salt commands. Users can be allowed to execute specific commands in the same way that minions are opened up to the peer system. The configuration value to open up the ACL system is called client_acl and is configured like so:
Where fred is allowed access to functions in the test module and to the pkg.list_pkgs function.

Master Finger Option¶

The master_finger option has been added to improve the security of minion provisioning. The master_finger option allows for the fingerprint of the master public key to be set in the configuration file to double verify that the master is valid. This option was added in response to a motivation to pre-authenticate the master when provisioning new minions to help prevent man in the middle attacks in some situations.

Salt Key Fingerprint Generation¶

The ability to generate fingerprints of keys used by Salt has been added to salt-key. The new option finger accepts the name of the key to generate and display a fingerprint for.
Will display the fingerprints for the master public and private keys.

Parsing System¶

Pedro Algavio, aka s0undt3ch, has added a substantial update to the command line parsing system that makes the help message output much cleaner and easier to search through. Salt parsers now have --versions-report besides usual --version info which you can provide when reporting any issues found.

Key Generation¶

We have reduced the requirements needed for salt-key to generate minion keys. You're no longer required to have salt configured and it's common directories created just to generate keys. This might prove useful if you're batch creating keys to pre-load on minions.

Startup States¶

A few configuration options have been added which allow for states to be run when the minion daemon starts. This can be a great advantage when deploying with Salt because the minion can apply states right when it first runs. To use startup states set the startup_states configuration option on the minion to highstate.

New Exclude Declaration¶

Some users have asked about adding the ability to ensure that other sls files or ids are excluded from a state run. The exclude statement will delete all of the data loaded from the specified sls file or will delete the specified id:

Max Open Files¶

While we're currently unable to properly handle ZeroMQ's abort signals when the max open files is reached, due to the way that's handled on ZeroMQ's, we have minimized the chances of this happening without at least warning the user.

More State Output Options¶

Some major changes have been made to the state output system. In the past state return data was printed in a very verbose fashion and only states that failed or made changes were printed by default. Now two options can be passed to the master and minion configuration files to change the behavior of the state output. State output can be set to verbose (default) or non-verbose with the state_verbose option:
It is noteworthy that the state_verbose option used to be set to False by default but has been changed to True by default in 0.10.3 due to many requests for the change. Te next option to be aware of new and called state_output. This option allows for the state output to be set to full (default) or terse. The full output is the standard state output, but the new terse output will print only one line per state making the output much easier to follow when executing a large state system.

state.file.append Improvements¶

The salt state file.append() tries not to append existing text. Previously the matching check was being made line by line. While this kind of check might be enough for most cases, if the text being appended was multi-line, the check would not work properly. This issue is now properly handled, the match is done as a whole ignoring any white space addition or removal except inside commas. For those thinking that, in order to properly match over multiple lines, salt will load the whole file into memory, that's not true. For most cases this is not important but an erroneous order to read a 4GB file, if not properly handled, like salt does, could make salt chew that amount of memory. Salt has a buffered file reader which will keep in memory a maximum of 256KB and iterates over the file in chunks of 32KB to test for the match, more than enough, if not, explain your usage on a ticket. With this change, also salt.modules.file.contains(), salt.modules.file.contains_regex(), salt.modules.file.contains_glob() and salt.utils.find now do the searching and/or matching using the buffered chunks approach explained above. Two new keyword arguments were also added, makedirs, and source. The first, makedirs will create the necessary directories in order to append to the specified file, of course, it only applies if we're trying to append to a non-existing file on a non-existing directory:
The second, source, allows one to append the contents of a file instead of specifying the text.

Security Fix¶

A timing vulnerability was uncovered in the code which decrypts the AES messages sent over the network. This has been fixed and upgrading is strongly recommended.

Salt 0.10.4 Release Notes¶

Salt 0.10.4 is a monumental release for the Salt team, with two new module systems, many additions to allow granular access to Salt, improved platform support and much more. This release is also exciting because we have been able to shorten the release cycle back to under a month. We are working hard to keep up the aggressive pace and look forward to having releases happen more frequently! This release also includes a serious security fix and all users are very strongly recommended to upgrade. As usual, upgrade the master first, and then the minion to ensure that the process is smooth.

Major Features¶

External Authentication System¶

The new external authentication system allows for Salt to pass through authentication to any authentication system to determine if a user has permission to execute a Salt command. The Unix PAM system is the first supported system with more to come! The external authentication system allows for specific users to be granted access to execute specific functions on specific minions. Access is configured in the master configuration file, and uses the new access control system:
The configuration above allows the user thatch to execute functions in the test and network modules on minions that match the web* target.

Access Control System¶

All Salt systems can now be configured to grant access to non-administrative users in a granular way. The old configuration continues to work. Specific functions can be opened up to specific minions from specific users in the case of external auth and client ACLs, and for specific minions in the case of the peer system. Access controls are configured like this:

Target by Network¶

A new matcher has been added to the system which allows for minions to be targeted by network. This new matcher can be called with the -S flag on the command line and is available in all places that the matcher system is available. Using it is simple:

Nodegroup Nesting¶

Previously a nodegroup was limited by not being able to include another nodegroup, this restraint has been lifted and now nodegroups will be expanded within other nodegroups with the N@ classifier.

Salt Key Delete by Glob¶

The ability to delete minion keys by glob has been added to salt-key. To delete all minion keys whose minion name starts with 'web':

Master Tops System¶

The external_nodes system has been upgraded to allow for modular subsystems to be used to generate the top file data for a highstate run. The external_nodes option still works but will be deprecated in the future in favor of the new master_tops option. Example of using master_tops:

Next Level Solaris Support¶

A lot of work has been put into improved Solaris support by Romeo Theriault. Packaging modules (pkgadd/pkgrm and pkgutil) and states, cron support and user and group management have all been added and improved upon. These additions along with SMF (Service Management Facility) service support and improved Solaris grain detection in 0.10.3 add up to Salt becoming a great tool to manage Solaris servers with.

Security¶

A vulnerability in the security handshake was found and has been repaired, old minions should be able to connect to a new master, so as usual, the master should be updated first and then the minions.

Pillar Updates¶

The pillar communication has been updated to add some extra levels of verification so that the intended minion is the only one allowed to gather the data. Once all minions and the master are updated to salt 0.10.4 please activate pillar 2 by changing the pillar_version in the master config to 2. This will be set to 2 by default in a future release.

Salt 0.10.5 Release Notes¶

Salt 0.10.5 is ready, and comes with some great new features. A few more interfaces have been modularized, like the outputter system. The job cache system has been made more powerful and can now store and retrieve jobs archived in external databases. The returner system has been extended to allow minions to easily retrieve data from a returner interface. As usual, this is an exciting release, with many noteworthy additions!

Major Features¶

External Job Cache¶

The external job cache is a system which allows for a returner interface to also act as a job cache. This system is intended to allow users to store job information in a central location for longer periods of time and to make the act of looking up information from jobs executed on other minions easier. Currently the external job cache is supported via the mongo and redis returners:
Once the external job cache is turned on the new ret module can be used on the minions to retrieve return information from the job cache. This can be a great way for minions to respond and react to other minions.

OpenStack Additions¶

OpenStack integration with Salt has been moving forward at a blistering pace. The new nova, glance, and keystone modules represent the beginning of ongoing OpenStack integration. The Salt team has had many conversations with core OpenStack developers and is working on linking to OpenStack in powerful new ways.

Wheel System¶

A new API was added to the Salt Master which allows the master to be managed via an external API. This new system allows Salt API to easily hook into the Salt Master and manage configs, modify the state tree, manage the pillar and more. The main motivation for the wheel system is to enable features needed in the upcoming web UI so users can manage the master just as easily as they manage minions. The wheel system has also been hooked into the external auth system. This allows specific users to have granular access to manage components of the Salt Master.

Render Pipes¶

Jack Kuan has added a substantial new feature. The render pipes system allows Salt to treat the render system like unix pipes. This new system enables sls files to be passed through specific render engines. While the default renderer is still recommended, different engines can now be more easily merged. So to pipe the output of Mako used in YAML use this shebang line: #!mako|yaml

Salt Key Overhaul¶

The Salt Key system was originally developed as only a CLI interface, but as time went on it was pressed into becoming a clumsy API. This release marks a complete overhaul of Salt Key. Salt Key has been rewritten to function purely from an API and to use the outputter system. The benefit here is that the outputter system works much more cleanly with Salt Key now, and the internals of Salt Key can be used much more cleanly.

Modular Outputters¶

The outputter system is now loaded in a modular way. This means that output systems can be more easily added by dropping a python file down on the master that contains the function output.

Gzip from Fileserver¶

Gzip compression has been added as an option to the cp.get_file and cp.get_dir commands. This will make file transfers more efficient and faster, especially over slower network links.

Unified Module Configuration¶

In past releases of Salt, the minions needed to be configured for certain modules to function. This was difficult because it required pre-configuring the minions. 0.10.5 changes this by making all module configs on minions search the master config file for values. Now if a single database server is needed, then it can be defined in the master config and all minions will become aware of the configuration value.

Salt Call Enhancements¶

The salt-call command has been updated in a few ways. Now, salt-call can take the --return option to send the data to a returner. Also, salt-call now reports executions in the minion proc system, this allows the master to be aware of the operation salt-call is running.

Death to pub_refresh and sub_timeout¶

The old configuration values pub_refresh and sub_timeout have been removed. These options were in place to alleviate problems found in earlier versions of ZeroMQ which have since been fixed. The continued use of these options has proven to cause problems with message passing and have been completely removed.

Git Revision Versions¶

When running Salt directly from git (for testing or development, of course) it has been difficult to know exactly what code is being executed. The new versioning system will detect the git revision when building and how many commits have been made since the last release. A release from git will look like this: 0.10.4-736-gec74d69

Svn Module Addition¶

Anthony Cornehl (twinshadow) contributed a module that adds Subversion support to Salt. This great addition helps round out Salt's VCS support.

Noteworthy Changes¶

Arch Linux Defaults to Systemd¶

Arch Linux recently changed to use systemd by default and discontinued support for init scripts. Salt has followed suit and defaults to systemd now for managing services in Arch.

Salt, Salt Cloud and Openstack¶

With the releases of Salt 0.10.5 and Salt Cloud 0.8.2, OpenStack becomes the first (non-OS) piece of software to include support both on the user level (with Salt Cloud) and the admin level (with Salt). We are excited to continue to extend support of other platforms at this level.

Salt 0.11.0 Release Notes¶

Salt 0.11.0 is here, with some highly sought after and exciting features. These features include the new overstate system, the reactor system, a new state run scope component called __context__, the beginning of the search system (still needs a great deal of work), multiple package states, the MySQL returner and a better system to arbitrarily reference outputters. It is also noteworthy that we are changing how we mark release numbers. For the life of the project we have been pushing every release with features and fixes as point releases. We will now be releasing point releases for only bug fixes on a more regular basis and major feature releases on a slightly less regular basis. This means that the next release will be a bugfix only release with a version number of 0.11.1. The next feature release will be named 0.12.0 and will mark the end of life for the 0.11 series.

Major Features¶

OverState¶

The overstate system is a simple way to manage rolling state executions across many minions. The overstate allows for a state to depend on the successful completion of another state.

Reactor System¶

The new reactor system allows for a reactive logic engine to be created which can respond to events within a salted environment. The reactor system uses sls files to match events fired on the master with actions, enabling Salt to react to problems in an infrastructure. Your load-balanced group of webservers is under extra load? Spin up a new VM and add it to the group. Your fileserver is filling up? Send a notification to your sysadmin on call. The possibilities are endless!

Module Context¶

A new component has been added to the module loader system. The module context is a data structure that can hold objects for a given scope within the module. This allows for components that are initialized to be stored in a persistent context which can greatly speed up ongoing connections. Right now the best example can be found in the cp execution module.

Multiple Package Management¶

A long desired feature has been added to package management. By definition Salt States have always installed packages one at a time. On most platforms this is not the fastest way to install packages. Erik Johnson, aka terminalmage, has modified the package modules for many providers and added new capabilities to install groups of packages. These package groups can be defined as a list of packages available in repository servers:
or specify based on the location of specific packages:

Search System¶

The bones to the search system have been added. This is a very basic interface that allows for search backends to be added as search modules. The first supported search module is the whoosh search backend. Right now only the basic paths for the search system are in place, making this very experimental. Further development will involve improving the search routines and index routines for whoosh and other search backends. The search system has been made to allow for searching through all of the state and pillar files, configuration files and all return data from minion executions.

Notable Changes¶

All previous versions of Salt have shared many directories between the master and minion. The default locations for keys, cached data and sockets has been shared by master and minion. This has created serious problems with running a master and a minion on the same systems. 0.11.0 changes the defaults to be separate directories. Salt will also attempt to migrate all of the old key data into the correct new directories, but if it is not successful it may need to be done manually. If your keys exhibit issues after updating make sure that they have been moved from /etc/salt/pki to /etc/salt/pki/{master,minion}. The old setup will look like this:
With the accepted minion keys in /etc/salt/pki/minions, the new setup places the accepted minion keys in /etc/salt/pki/master/minions.

Salt 0.11.1 Release Notes¶

Salt 0.12.0 Release Notes¶

Another feature release of Salt is here! Some exciting additions are included with more ways to make salt modular and even easier management of the salt file server.

Major Features¶

Modular Fileserver Backend¶

The new modular fileserver backend allows for any external system to be used as a salt file server. The main benefit here is that it is now possible to tell the master to directly use a git remote location, or many git remote locations, automatically mapping git branches and tags to salt environments.

Windows is First Class!¶

A new Salt Windows installer is now available! Much work has been put in to improve Windows support. With this much easier method of getting Salt on your Windows machines, we hope even more development and progress will occur. Please file bug reports on the Salt GitHub repo issue tracker so we can continue improving. One thing that is missing on Windows that Salt uses extensively is a software package manager and a software package repository. The Salt pkg state allows sys admins to install software across their infrastructure and across operating systems. Software on Windows can now be managed in the same way. The SaltStack team built a package manager that interfaces with the standard Salt pkg module to allow for installing and removing software on Windows. In addition, a software package repository has been built on top of the Salt fileserver. A small YAML file provides the information necessary for the package manager to install and remove software. An interesting feature of the new Salt Windows software package repository is that one or more remote git repositories can supplement the master's local repository. The repository can point to software on the master's fileserver or on an HTTP, HTTPS, or ftp server.

New Default Outputter¶

Salt displays data to the terminal via the outputter system. For a long time the default outputter for Salt has been the python pretty print library. While this has been a generally reasonable outputter, it did have many failings. The new default outputter is called "nested", it recursively scans return data structures and prints them out cleanly. If the result of the new nested outputter is not desired any other outputter can be used via the --out option, or the output option can be set in the master and minion configs to change the default outputter.

Internal Scheduler¶

The internal Salt scheduler is a new capability which allows for functions to be executed at given intervals on the minion, and for runners to be executed at given intervals on the master. The scheduler allows for sequences such as executing state runs (locally on the minion or remotely via an overstate) or continually gathering system data to be run at given intervals. The configuration is simple, add the schedule option to the master or minion config and specify jobs to run, this in the master config will execute the state.over runner every 60 minutes:
This example for the minion configuration will execute a highstate every 30 minutes:

Optional DSL for SLS Formulas¶

Jack Kuan, our renderer expert, has created something that is astonishing. Salt, now comes with an optional Python based DSL, this is a very powerful interface that makes writing SLS files in pure python easier than it was with the raw py renderer. As usual this can be used with the renderer shebang line, so a single sls can be written with the DSL if pure python power is needed while keeping other sls files simple with YAML.

Set Grains Remotely¶

A new execution function and state module have been added that allows for grains to be set on the minion. Now grains can be set via a remote execution or via states. Use the grains.present state or the grains.setval execution functions.

Gentoo Additions¶

Major additions to Gentoo specific components have been made. The encompasses executions modules and states ranging from supporting the make.conf file to tools like layman.

Salt 0.12.1 Release Notes¶

Salt 0.13.0 Release Notes¶

The lucky number 13 has turned the corner! From CLI notifications when quitting a salt command, to substantial improvements on Windows, Salt 0.13.0 has arrived!

Major Features¶

Improved file.recurse Performance¶

The file.recurse system has been deployed and used in a vast array of situations. Fixes to the file state and module have led towards opening up new ways of running file.recurse to make it faster. Now the file.recurse state will download fewer files and will run substantially faster.

Windows Improvements¶

Minion stability on Windows has improved. Many file operations, including file.recurse, have been fixed and improved. The network module works better, to include network.interfaces. Both 32bit and 64bit installers are now available.

Nodegroup Targeting in Peer System¶

In the past, nodegroups were not available for targeting via the peer system. This has been fixed, allowing the new nodegroup expr_form argument for the publish.publish function:

Blacklist Additions¶

Additions allowing more granular blacklisting are available in 0.13.0. The ability to blacklist users and functions in client_acl have been added, as well as the ability to exclude state formulas from the command line.

Command Line Pillar Embedding¶

Pillar data can now be embedded on the command line when calling state.sls and state.highstate. This allows for on the fly changes or settings to pillar and makes parameterizing state formulas even easier. This is done via the keyword argument:
The above example will extend the existing pillar to hold the cheese key with a value of spam. If the cheese key is already specified in the minion's pillar then it will be overwritten.

CLI Notifications¶

In the past hitting ctrl-C and quitting from the salt command would just drop to a shell prompt, this caused confusion with users who expected the remote executions to also quit. Now a message is displayed showing what command can be used to track the execution and what the job id is for the execution.

Version Specification in Multiple-Package States¶

Versions can now be specified within multiple-package pkg.installed states. An example can be found below:

Noteworthy Changes¶

The configuration subsystem in Salt has been overhauled to make the opts dict used by Salt applications more portable, the problem is that this is an incompatible change with salt-cloud, and salt-cloud will need to be updated to the latest git to work with Salt 0.13.0. Salt Cloud 0.8.5 will also require Salt 0.13.0 or later to function. The SaltStack team is sorry for the inconvenience here, we work hard to make sure these sorts of things do not happen, but sometimes hard changes get in.

Salt 0.13.1 Release Notes¶

Salt 0.13.2 Release Notes¶

Salt 0.13.3 Release Notes¶

Salt 0.14.0 Release Notes¶

Salt 0.14.0 is here! This release was held up primarily by PyCon, Scale, and illness, but has arrived! 0.14.0 comes with many new features and is breaking ground for Salt in the area of cloud management with the introduction of Salt providing basic cloud controller functionality.

Major Features¶

Salt - As a Cloud Controller¶

This is the first primitive inroad to using Salt as a cloud controller is available in 0.14.0. Be advised that this is alpha, only tested in a few very small environments. The cloud controller is built using kvm and libvirt for the hypervisors. Hypervisors are autodetected as minions and only need to have libvirt running and kvm installed to function. The features of the Salt cloud controller are as follows:
It is noteworthy that this feature is still Alpha, meaning that all rights are reserved to change the interface if needs be in future releases!

Libvirt State¶

One of the problems with libvirt is management of certificates needed for live migration and cross communication between hypervisors. The new libvirt state makes the Salt Master hold a CA and manage the signing and distribution of keys onto hypervisors, just add a call to the libvirt state in the sls formulas used to set up a hypervisor:

New get Functions¶

An easier way to manage data has been introduced. The pillar, grains, and config execution modules have been extended with the new get function. This function works much in the same way as the get method in a python dict, but with an enhancement, nested dict components can be extracted using a : delimiter. If a structure like this is in pillar:
Extracting it from the raw pillar in an sls formula or file template is done this way:
Now with the new get function the data can be safely gathered and a default can be set allowing the template to fall back if the value is not available:
This makes handling nested structures much easier, and defaults can be cleanly set. This new function is being used extensively in the new formulae repository of salt sls formulas.

Salt 0.14.1 Release Notes¶

Salt 0.15.0 Release Notes¶

The many new features of Salt 0.15.0 have arrived! Salt 0.15.0 comes with many smaller features and a few larger ones. These features range from better debugging tools to the new Salt Mine system.

Major Features¶

The Salt Mine¶

First there was the peer system, allowing for commands to be executed from a minion to other minions to gather data live. Then there was the external job cache for storing and accessing long term data. Now the middle ground is being filled in with the Salt Mine. The Salt Mine is a system used to execute functions on a regular basis on minions and then store only the most recent data from the functions on the master, then the data is looked up via targets. The mine caches data that is public to all minions, so when a minion posts data to the mine all other minions can see it.

IPV6 Support¶

0.13.0 saw the addition of initial IPV6 support but errors were encountered and it needed to be stripped out. This time the code covers more cases and must be explicitly enabled. But the support is much more extensive than before.

Copy Files From Minions to the Master¶

Minions have long been able to copy files down from the master file server, but until now files could not be easily copied from the minion up to the master. A new function called cp.push can push files from the minions up to the master server. The uploaded files are then cached on the master in the master cachedir for each minion.

Better Template Debugging¶

Template errors have long been a burden when writing states and pillar. 0.15.0 will now send the compiled template data to the debug log, this makes tracking down the intermittent stage templates much easier. So running state.sls or state.highstate with -l debug will now print out the rendered templates in the debug information.

State Event Firing¶

The state system is now more closely tied to the master's event bus. Now when a state fails the failure will be fired on the master event bus so that the reactor can respond to it.

Major Syndic Updates¶

The Syndic system has been basically re-written. Now it runs in a completely asynchronous way and functions primarily as an event broker. This means that the events fired on the syndic are now pushed up to the higher level master instead of the old method used which waited for the client libraries to return. This makes the syndic much more accurate and powerful, it also means that all events fired on the syndic master make it up the pipe as well making a reactor on the higher level master able to react to minions further downstream.

Peer System Updates¶

The Peer System has been updated to run using the client libraries instead of firing directly over the publish bus. This makes the peer system much more consistent and reliable.

Minion Key Revocation¶

In the past when a minion was decommissioned the key needed to be manually deleted on the master, but now a function on the minion can be used to revoke the calling minion's key:

Function Return Codes¶

Functions can now be assigned numeric return codes to determine if the function executed successfully. While not all functions have been given return codes, many have and it is an ongoing effort to fill out all functions that might return a non-zero return code.

Functions in Overstate¶

The overstate system was originally created to just manage the execution of states, but with the addition of return codes to functions, requisite logic can now be used with respect to the overstate. This means that an overstate stage can now run single functions instead of just state executions.

Pillar Error Reporting¶

Previously if errors surfaced in pillar, then the pillar would consist of only an empty dict. Now all data that was successfully rendered stays in pillar and the render error is also made available. If errors are found in the pillar, states will refuse to run.

Using Cached State Data¶

Sometimes states are executed purely to maintain a specific state rather than to update states with new configs. This is grounds for the new cached state system. By adding cache=True to a state call the state will not be generated fresh from the master but the last state data to be generated will be used. If no previous state data is available then fresh data will be generated.

Monitoring States¶

The new monitoring states system has been started. This is very young but allows for states to be used to configure monitoring routines. So far only one monitoring state is available, the disk.status state. As more capabilities are added to Salt UI the monitoring capabilities of Salt will continue to be expanded.

Salt 0.15.1 Release Notes¶

The 0.15.1 release has been posted, this release includes fixes to a number of bugs in 0.15.1 and a three security patches.

Security Updates¶

A number of security issues have been resolved via the 0.15.1 release.

Path Injection in Minion IDs¶

Salt masters did not properly validate the id of a connecting minion. This can lead to an attacker uploading files to the master in arbitrary locations. In particular this can be used to bypass the manual validation of new unknown minions. Exploiting this vulnerability does not require authentication. This issue affects all known versions of Salt. This issue was reported by Ronald Volgers.

Patch¶

The issue is fixed in Salt 0.15.1. Updated packages are available in the usual locations. Specific commits: https://github.com/saltstack/salt/commit/5427b9438e452a5a8910d9128c6aafb45d8fd5d3 https://github.com/saltstack/salt/commit/7560908ee62351769c3cd43b03d74c1ca772cc52 https://github.com/saltstack/salt/commit/e200b8a7ff53780124e08d2bdefde7587e52bfca

RSA Key Generation Fault¶

RSA key generation was done incorrectly, leading to very insecure keys. It is recommended to regenerate all RSA keys. This issue can be used to impersonate Salt masters or minions, or decrypt any transferred data. This issue can only be exploited by attackers who are able to observe or modify traffic between Salt minions and the legitimate Salt master. A tool was included in 0.15.1 to assist in mass key regeneration, the manage.regen_keys runner. This issue affects all known versions of Salt. This issue was reported by Ronald Volgers.

Patch¶

The issue is fixed in Salt 0.15.1. Updated packages are available in the usual locations. Specific commits: https://github.com/saltstack/salt/commit/5dd304276ba5745ec21fc1e6686a0b28da29e6fc

Command Injection Via ext_pillar¶

Arbitrary shell commands could be executed on the master by an authenticated minion through options passed when requesting a pillar. Ext pillar options have been restricted to only allow safe external pillars to be called when prompted by the minion. This issue affects Salt versions from 0.14.0 to 0.15.0. This issue was reported by Ronald Volgers.

Patch¶

The issue is fixed in Salt 0.15.1. Updated packages are available in the usual locations. Specific commits: https://github.com/saltstack/salt/commit/43d8c16bd26159d827d1a945c83ac28159ec5865

Salt 0.15.2 Release Notes¶

Salt 0.15.3 Release Notes¶

Salt 0.16.0 Release Notes¶

The 0.16.0 release is an exciting one, with new features in master redundancy, and a new, powerful requisite.

Major Features¶

Multi-Master¶

This new capability allows for a minion to be actively connected to multiple salt masters at the same time. This allows for multiple masters to send out commands to minions and for minions to automatically reconnect to masters that have gone down. A tutorial is available to help get started here: Multi Master Tutorial

Prereq, the New Requisite¶

The new prereq requisite is very powerful! It allows for states to execute based on a state that is expected to make changes in the future. This allows for a change on the system to be preempted by another execution. A good example is needing to shut down a service before modifying files associated with it, allowing, for instance, a webserver to be shut down allowing a load balancer to stop sending requests while server side code is updated. In this case, the prereq will only run if changes are expected to happen in the prerequired state, and the prerequired state will always run after the prereq state and only if the prereq state succeeds.

Peer System Improvements¶

The peer system has been revamped to make it more reliable, faster, and like the rest of Salt, async. The peer calls when an updated minion and master are used together will be much faster!

Relative Includes¶

The ability to include an sls relative to the defined sls has been added, the new syntax id documented here: Includes

More State Output Options¶

The state_output option in the past only supported full and terse, 0.16.0 add the mixed and changes modes further refining how states are sent to users' eyes.

Improved Windows Support¶

Support for Salt on Windows continues to improve. Software management on Windows has become more seamless with Linux/UNIX/BSD software management. Installed software is now recognized by the short names defined in the repository SLS. This makes it possible to run salt '*' pkg.version firefox and get back results from Windows and non-Windows minions alike. When templating files on Windows, Salt will now correctly use Windows appropriate line endings. This makes it much easier to edit and consume files on Windows. When using the cmd state the shell option now allows for specifying Windows Powershell as an alternate shell to execute cmd.run and cmd.script. This opens up Salt to all the power of Windows Powershell and its advanced Windows management capabilities. Several fixes and optimizations were added for the Windows networking modules, especially when working with IPv6. A system module was added that makes it easy to restart and shutdown Windows minions. The Salt Minion will now look for its config file in c:\salt\conf by default. This means that it's no longer necessary to specify the -c option to specify the location of the config file when starting the Salt Minion on Windows in a terminal.

Multiple Targets for pkg.removed, pkg.purged States¶

Both pkg.removed and pkg.purged now support the pkgs argument, which allow for multiple packages to be targeted in a single state. This, as in pkg.installed, helps speed up these states by reducing the number of times that the package management tools (apt, yum, etc.) need to be run.

Random Times in Cron States¶

The temporal parameters in cron.present states (minute, hour, etc.) can now be randomized by using random instead of a specific value. For example, by using the random keyword in the minute parameter of a cron state, the same cron job can be pushed to hundreds or thousands of hosts, and they would each use a randomly-generated minute. This can be helpful when the cron job accesses a network resource, and it is not desirable for all hosts to run the job concurrently.
Since Salt assumes a value of * for unspecified temporal parameters, adding a parameter to the state and setting it to random will change that value from * to a randomized numeric value. However, if that field in the cron entry on the minion already contains a numeric value, then using the random keyword will not modify it.

Confirmation Prompt on Key Acceptance¶

When accepting new keys with salt-key -a minion-id or salt-key -A, there is now a prompt that will show the affected keys and ask for confirmation before proceeding. This prompt can be bypassed using the -y or --yes command line argument, as with other salt-key commands.

Support for Setting Password Hashes on BSD Minions¶

FreeBSD, NetBSD, and OpenBSD all now support setting passwords in user.present states.

Salt 0.16.1 Release Notes¶

Salt 0.16.2 Release Notes¶

Version 0.16.2 is a bugfix release for 0.16.0, and contains a number of fixes.

Windows¶

Grains¶

Pillar¶

Peer Publishing¶

Minion¶

User/Group Management¶

File Management¶

Package/Repository Management¶

Service Management¶

Networking¶

SSH¶

pip¶

MySQL¶

PostgreSQL¶

Miscellaneous¶

Salt 0.16.3 Release Notes¶

Version 0.16.3 is another bugfix release for 0.16.0. The changes include:

Salt 0.16.4 Release Notes¶

Version 0.16.4 is another bugfix release for 0.16.0, likely to be the last before 0.17.0 is released. The changes include:

Salt 0.17.0 Release Notes¶

The 0.17.0 release is a very exciting release of Salt, this brings to Salt some very powerful new features and advances. The advances range from the state system to the test suite, covering new transport capabilities and making states easier and more powerful, to extending Salt Virt and much more! The 0.17.0 release will also be the last release of Salt to follow the old 0.XX.X numbering system, the next release of Salt will change the numbering to be date based following this format: <Year>.<Month>.<Minor> So if the release happens in November of 2013 the number will be 13.11.0, the first bugfix release will be 13.11.1 and so forth.

Major Features¶

Halite¶

The new Halite web GUI is now available on PyPI. A great deal of work has been put into Halite to make it fully event driven and amazingly fast. The Halite UI can be started from within the Salt Master (after being installed from PyPI), or standalone, and does not require an external database to run. It is very lightweight! This initial release of Halite is primarily the framework for the UI and the communication systems, making it easy to extend and build the UI up. It presently supports watching the event bus and firing commands over Salt. At this time, Halite is not available as a package, but installation documentation is available at: http://docs.saltstack.com/topics/tutorials/halite.html Halite is, like the rest of Salt, Open Source! Much more will be coming in the future of Halite!

Salt SSH¶

The new salt-ssh command has been added to Salt. This system allows for remote execution and states to be run over ssh. The benefit here being, that salt can run relying only on the ssh agent, rather than requiring a minion to be deployed. The salt-ssh system runs states in a compatible way as Salt and states created and run with salt-ssh can be moved over to a standard salt deployment without modification. Since this is the initial release of salt-ssh, there is plenty of room for improvement, but it is fully operational, not just a bootstrap tool.

Rosters¶

Salt is designed to have the minions be aware of the master and the master does not need to be aware of the location of the minions. The new salt roster system was created and designed to facilitate listing the targets for salt-ssh. The roster system, like most of Salt, is a plugin system, allowing for the list of systems to target to be derived from any pluggable backend. The rosters shipping with 0.17.0 are flat and scan. Flat is a file which is read in via the salt render system and the scan roster does simple network scanning to discover ssh servers.

State Auto Order¶

This is a major change in how states are evaluated in Salt. State Auto Order is a new feature that makes states get evaluated and executed in the order in which they are defined in the sls file. This feature makes it very easy to see the finite order in which things will be executed, making Salt now, fully imperative AND fully declarative. The requisite system still takes precedence over the order in which states are defined, so no existing states should break with this change. But this new feature can be turned off by setting state_auto_order: False in the master config, thus reverting to the old lexicographical order.

state.sls Runner¶

The state.sls runner has been created to allow for a more powerful system for orchestrating state runs and function calls across the salt minions. This new system uses the state system for organizing executions. This allows for states to be defined that are executed on the master to call states on minions via salt-run state.sls.

Salt Thin¶

Salt Thin is an exciting new component of Salt, this is the ability to execute Salt routines without any transport mechanisms installed, it is a pure python subset of Salt. Salt Thin does not have any networking capability, but can be dropped into any system with Python installed and then salt-call can be called directly. The Salt Thin system, is used by the salt-ssh command, but can still be used to just drop salt somewhere for easy use.

Event Namespacing¶

Events have been updated to be much more flexible. The tags in events have all been namespaced allowing easier tracking of event names.

Mercurial Fileserver Backend¶

The popular git fileserver backend has been joined by the mercurial fileserver backend, allowing the state tree to be managed entirely via mercurial.

External Logging Handlers¶

The external logging handler system allows for Salt to directly hook into any external logging system. Currently supported are sentry and logstash.

Jenkins Testing¶

The testing systems in Salt have been greatly enhanced, tests for salt are now executed, via jenkins.saltstack.com, across many supported platforms. Jenkins calls out to salt-cloud to create virtual machines on Rackspace, then the minion on the virtual machine checks into the master running on Jenkins where a state run is executed that sets up the minion to run tests and executes the test suite. This now automates the sequence of running platform tests and allows for continuous destructive tests to be run.

Salt Testing Project¶

The testing libraries for salt have been moved out of the main salt code base and into a standalone codebase. This has been done to ease the use of the testing systems being used in salt based projects other than Salt itself.

StormPath External Authentication¶

The external auth system now supports the fantastic Stormpath cloud based authentication system.

LXC Support¶

Extensive additions have been added to Salt for LXC support. This included the backend libs for managing LXC containers. Addition into the salt-virt system is still in the works.

macOS User/Group Support¶

Salt is now able to manage users and groups on Minions running macOS. However, at this time user passwords cannot be managed.

Django ORM External Pillar¶

Pillar data can now be derived from Django managed databases.

Fixes from RC to release¶

Salt 0.17.1 Release Notes¶

NOTE:
The 0.17.1 release comes with a number of improvements to salt-ssh, many bugfixes, and a number of security updates. Salt SSH has been improved to be faster, more featureful and more secure. Since the original release of Salt SSH was primarily a proof of concept, it has been very exciting to see its rapid adoption. We appreciate the willingness of security experts to review Salt SSH and help discover oversights and ensure that security issues only exist for such a tiny window of time.

SSH Enhancements¶

Shell Improvements¶

Improvements to Salt SSH's communication have been added that improve routine execution regardless of the target system's login shell.

Performance¶

Deployment of routines is now faster and takes fewer commands to execute.

Security Updates¶

Be advised that these security issues all apply to a small subset of Salt users and mostly apply to Salt SSH.

Insufficient Argument Validation¶

This issue allowed for a user with limited privileges to embed executions inside of routines to execute routines that should be restricted. This applies to users using external auth or client ACL and opening up specific routines. Be advised that these patches address the direct issue. Additional commits have been applied to help mitigate this issue from resurfacing.

CVE¶

CVE-2013-4435

Affected Versions¶

0.15.0 - 0.17.0

Patches¶

https://github.com/saltstack/salt/commit/6d8ef68b605fd63c36bb8ed96122a75ad2e80269 https://github.com/saltstack/salt/commit/ebdef37b7e5d2b95a01d34b211c61c61da67e46a https://github.com/saltstack/salt/commit/7f190ff890e47cdd591d9d7cefa5126574660824 https://github.com/saltstack/salt/commit/8e5afe59cef6743fe5dbd510dcf463dbdfca1ced https://github.com/saltstack/salt/commit/aca78f314481082862e96d4f0c1b75fa382bb885 https://github.com/saltstack/salt/commit/6a9752cdb1e8df2c9505ea910434c79d132eb1e2 https://github.com/saltstack/salt/commit/b73677435ba54ecfc93c1c2d840a7f9ba6f53410 https://github.com/saltstack/salt/commit/07972eb0a6f985749a55d8d4a2e471596591c80d https://github.com/saltstack/salt/commit/1e3f197726aa13ac5c3f2416000089f477f489b5

Found By¶

Feth Arezki, of Majerti

MITM SSH attack in salt-ssh¶

SSH host keys were being accepted by default and not enforced on future SSH connections. These patches set SSH host key checking by default and can be overridden by passing the -i flag to salt-ssh.

CVE¶

CVE-2013-4436

Affected Versions¶

0.17.0

Found By¶

Michael Scherer, Red Hat

Insecure Usage of /tmp in salt-ssh¶

The initial release of salt-ssh used the /tmp directory in an insecure way. These patches not only secure usage of files under /tmp in salt-ssh, but also add checksum validation for all packages sent into the now secure locations on target systems.

CVE¶

CVE-2013-4438

Affected Versions¶

0.17.0

Patches¶

https://github.com/saltstack/salt/commit/aa4bb77ef230758cad84381dde0ec660d2dc340a https://github.com/saltstack/salt/commit/8f92b6b2cb2e4ec3af8783eb6bf4ff06f5a352cf https://github.com/saltstack/salt/commit/c58e56811d5a50c908df0597a0ba0b643b45ebfd https://github.com/saltstack/salt/commit/0359db9b46e47614cff35a66ea6a6a76846885d2 https://github.com/saltstack/salt/commit/4348392860e0fd43701c331ac3e681cf1a8c17b0 https://github.com/saltstack/salt/commit/664d1a1cac05602fad2693f6f97092d98a72bf61 https://github.com/saltstack/salt/commit/bab92775a576e28ff9db262f32db9cf2375bba87 https://github.com/saltstack/salt/commit/c6d34f1acf64900a3c87a2d37618ff414e5a704e

Found By¶

Michael Scherer, Red Hat

YAML Calling Unsafe Loading Routine¶

It has been argued that this is not a valid security issue, as the YAML loading that was happening was only being called after an initial gateway filter in Salt has already safely loaded the YAML and would fail if non-safe routines were embedded. Nonetheless, the CVE was filed and patches applied.

CVE¶

CVE-2013-4438

Patches¶

https://github.com/saltstack/salt/commit/339b0a51befae6b6b218ebcb55daa9cd3329a1c5

Found By¶

Michael Scherer, Red Hat

Failure to Drop Supplementary Group on Salt Master¶

If a salt master was started as a non-root user by the root user, root's groups would still be applied to the running process. This fix changes the process to have only the groups of the running user.

CVE¶

CVE not considered necessary by submitter.

Affected Versions¶

0.11.0 - 0.17.0

Patches¶

https://github.com/saltstack/salt/commit/b89fa9135822d029795ab1eecd68cce2d1ced715

Found By¶

Michael Scherer, Red Hat

Failure to Validate Minions Posting Data¶

This issue allowed a minion to pose as another authorized minion when posting data such as the mine data. All minions now pass through the id challenge before posting such data.

CVE¶

CVE-2013-4439

Affected Versions¶

0.15.0 - 0.17.0

Patches¶

https://github.com/saltstack/salt/commit/7b850ff3d07ef6782888914ac4556c01e8a1c482 https://github.com/saltstack/salt/commit/151759b2a1e1c6ce29277aa81b054219147f80fd

Found By¶

David Anderson

Fix Reference¶

Version 0.17.1 is the first bugfix release for 0.17.0. The changes include:

Salt 0.17.2 Release Notes¶

Version 0.17.2 is another bugfix release for 0.17.0. The changes include:

Salt 0.17.3 Release Notes¶

NOTE:
Version 0.17.3 is another bugfix release for 0.17.0. The changes include:

Salt 0.17.4 Release Notes¶

Version 0.17.4 is another bugfix release for 0.17.0. The changes include:

Salt 0.17.5 Release Notes¶

Version 0.17.5 is another bugfix release for 0.17.0. The changes include:

Salt 0.6.0 release notes¶

The Salt remote execution manager has reached initial functionality! Salt is a management application which can be used to execute commands on remote sets of servers. The whole idea behind Salt is to create a system where a group of servers can be remotely controlled from a single master, not only can commands be executed on remote systems, but salt can also be used to gather information about your server environment. Unlike similar systems, like Func and MCollective, Salt is extremely simple to setup and use, the entire application is contained in a single package, and the master and minion daemons require no running dependencies in the way that Func requires Certmaster and MCollective requires activeMQ. Salt also manages authentication and encryption. Rather than using SSL for encryption, salt manages encryption on a payload level, so the data sent across the network is encrypted with fast AES encryption, and authentication uses RSA keys. This means that Salt is fast, secure, and very efficient. Messaging in Salt is executed with ZeroMQ, so the message passing interface is built into salt and does not require an external ZeroMQ server. This also adds speed to Salt since there is no additional bloat on the networking layer, and ZeroMQ has already proven itself as a very fast networking system. The remote execution in Salt is "Lazy Execution", in that once the command is sent the requesting network connection is closed. This makes it easier to detach the execution from the calling process on the master, it also means that replies are cached, so that information gathered from historic commands can be queried in the future. Salt also allows users to make execution modules in Python. Writers of these modules should also be pleased to know that they have access to the impressive information gathered from PuppetLabs' Facter application, making Salt module more flexible. In the future I hope to also allow Salt to group servers based on Facter information as well. All in all Salt is fast, efficient, and clean, can be used from a simple command line client or through an API, uses message queue technology to make network execution extremely fast, and encryption is handled in a very fast and efficient manner. Salt is also VERY easy to use and VERY easy to extend. You can find the source code for Salt on my GitHub page, I have also set up a few wiki pages explaining how to use and set up Salt. If you are using Arch Linux there is a package available in the Arch Linux AUR. Salt 0.6.0 Source: https://cloud.github.com/downloads/saltstack/salt/salt-0.6.0.tar.gz GitHub page: https://github.com/saltstack/salt Wiki: https://github.com/saltstack/salt/wiki Arch Linux Package: https://aur.archlinux.org/packages/salt-git/ I am very open to contributions, for instance I need packages for more Linux distributions as well as BSD packages and testers. Give Salt a try, this is the initial release and is not a 1.0 quality release, but it has been working well for me! I am eager to get your feedback!

Salt 0.7.0 release notes¶

I am pleased to announce the release of Salt 0.7.0! This release marks what is the first stable release of salt, 0.7.0 should be suitable for general use. 0.7.0 Brings the following new features to Salt:
0.7.0 Fixes the following major bugs:
The next release of Salt should see the following features:
Coming up next is a higher level management framework for salt called Butter. I want salt to stay as a simple and effective communication framework, and allow for more complicated executions to be managed via Butter. Right now Butter is being developed to act as a cloud controller using salt as the communication layer, but features like system monitoring and advanced configuration control (a puppet manager) are also in the pipe. Special thanks to Joseph Hall for the status and network modules, and thanks to Matthias Teege for tracking down some configuration bugs! Salt can be downloaded from the following locations; Source Tarball: https://cloud.github.com/downloads/saltstack/salt/salt-0.7.0.tar.gz Arch Linux Package: https://aur.archlinux.org/packages/salt-git/ Please enjoy the latest Salt release!

Salt 0.8.0 release notes¶

Salt 0.8.0 is ready for general consumption! The source tarball is available on GitHub for download: https://cloud.github.com/downloads/saltstack/salt/salt-0.8.0.tar.gz A lot of work has gone into salt since the last release just 2 weeks ago, and salt has improved a great deal. A swath of new features are here along with performance and threading improvements! The main new features of salt 0.8.0 are: Salt-cp Cython minion modules Dynamic returners Faster return handling Lowered required Python version to 2.6 Advanced minion threading Configurable minion modules

Salt-cp¶

The salt-cp command introduces the ability to copy simple files via salt to targeted servers. Using salt-cp is very simple, just call salt-cp with a target specification, the source file(s) and where to copy the files on the minions. For instance: # salt-cp ‘*’ /etc/hosts /etc/hosts Will copy the local /etc/hosts file to all of the minions. Salt-cp is very young, in the future more advanced features will be added, and the functionality will much more closely resemble the cp command.

Cython minion modules¶

Cython is an amazing tool used to compile Python modules down to c. This is arguably the fastest way to run Python code, and since pyzmq requires cython, adding support to salt for cython adds no new dependencies. Cython minion modules allow minion modules to be written in cython and therefore executed in compiled c. Simply write the salt module in cython and use the file extension “.pyx” and the minion module will be compiled when the minion is started. An example cython module is included in the main distribution called cytest.pyx: https://github.com/saltstack/salt/blob/develop/salt/modules/cytest.pyx

Dynamic Returners¶

By default salt returns command data back to the salt master, but now salt can return command data to any system. This is enabled via the new returners modules feature for salt. The returners modules take the return data and sends it to a specific module. The returner modules work like minion modules, so any returner can be added to the minions. This means that a custom data returner can be added to communicate the return data so anything from MySQL, Redis, MongoDB, and more! There are 2 simple stock returners in the returners directory: https://github.com/saltstack/salt/blob/develop/salt/returners The documentation on writing returners will be added to the wiki shortly, and returners can be written in pure Python, or in cython.

Configurable Minion Modules¶

Minion modules may need to be configured, now the options passed to the minion configuration file can be accessed inside of the minion modules via the __opt__ dict. Information on how to use this simple addition has been added to the wiki: Writing modules The test module has an example of using the __opts__ dict, and how to set default options: https://github.com/saltstack/salt/blob/develop/salt/modules/test.py

Advanced Minion Threading¶

In 0.7.0 the minion would block after receiving a command from the master, now the minion will spawn a thread or multiprocess. By default Python threads are used because for general use they have proved to be faster, but the minion can now be configured to use the Python multiprocessing module instead. Using multiprocessing will cause executions that are CPU bound or would otherwise exploit the negative aspects of the Python GIL to run faster and more reliably, but simple calls will still be faster with Python threading. The configuration option can be found in the minion configuration file: https://github.com/saltstack/salt/blob/develop/conf/minion

Lowered Supported Python to 2.6¶

The requirement for Python 2.7 has been removed to support Python 2.6. I have received requests to take the minimum Python version back to 2.4, but unfortunately this will not be possible, since the ZeroMQ Python bindings do not support Python 2.4. Salt 0.8.0 is a very major update, it also changes the network protocol slightly which makes communication with older salt daemons impossible, your master and minions need to be upgraded together! I could use some help bringing salt to the people! Right now I only have packages for Arch Linux, Fedora 14 and Gentoo. We need packages for Debian and people willing to help test on more platforms. We also need help writing more minion modules and returner modules. If you want to contribute to salt please hop on the mailing list and send in patches, make a fork on GitHub and send in pull requests! If you want to help but are not sure where you can, please email me directly or post tot he mailing list! I hope you enjoy salt, while it is not yet 1.0 salt is completely viable and usable! -Thomas S. Hatch

Salt 0.8.7 release notes¶

It has been a month since salt 0.8.0, and it has been a long month! But Salt is still coming along strong. 0.8.7 has a lot of changes and a lot of updates. This update makes Salt’s ZeroMQ back end better, strips Facter from the dependencies, and introduces interfaces to handle more capabilities. Many of the major updates are in the background, but the changes should shine through to the surface. A number of the new features are still a little thin, but the back end to support expansion is in place. I also recently gave a presentation to the Utah Python users group in Salt Lake City, the slides from this presentation are available here: https://cloud.github.com/downloads/saltstack/salt/Salt.pdf The video from this presentation will be available shortly. The major new features and changes in Salt 0.8.7 are:
The new ZeroMQ topology allows for better scalability, this will be required by the need to execute massive file transfers to multiple machines in parallel and state management. The new ZeroMQ topology is available in the aforementioned presentation. 0.8.7 introduces the capability to declare states, this is similar to the capabilities of Puppet. States in salt are declared via state data structures. This system is very young, but the core feature set is available. Salt states work around rendering files which represent Salt high data. More on the Salt state system will be documented in the near future. The system for loading salt modules has been pulled out of the minion class to be a standalone module, this has enabled more dynamic loading of Salt modules and enables many of the updates in 0.8.7 – https://github.com/saltstack/salt/blob/develop/salt/loader.py Salt Job ids are now microsecond precise, this was needed to repair a race condition unveiled by the speed improvements in the new ZeroMQ topology. The new grains interface replaces the functionality of Facter, the idea behind grains differs from Facter in that the grains are only used for static system data, dynamic data needs to be derived from a call to a salt module. This makes grains much faster to use, since the grains data is generated when the minion starts. Virtual salt modules allows for a salt module to be presented as something other than its module name. The idea here is that based on information from the minion decisions about which module should be presented can be made. The best example is the pacman module. The pacman module will only load on Arch Linux minions, and will be called pkg. Similarly the yum module will be presented as pkg when the minion starts on a Fedora/RedHat system. The new salt-call command allows for minion modules to be executed from the minion. This means that on the minion a salt module can be executed, this is a great tool for testing Salt modules. The salt-call command can also be used to view the grains data. In previous releases when a minion module threw an exception very little data was returned to the master. Now the stack trace from the failure is returned making debugging of minion modules MUCH easier. Salt is nearing the goal of 1.0, where the core feature set and capability is complete! Salt 0.8.7 can be downloaded from GitHub here: https://cloud.github.com/downloads/saltstack/salt/salt-0.8.7.tar.gz -Thomas S Hatch

Salt 0.8.8 release notes¶

Salt 0.8.8 is here! This release adds a great deal of code and some serious new features. The latest release can be downloaded here: https://cloud.github.com/downloads/saltstack/salt/salt-0.8.8.tar.gz Improved Documentation has been set up for salt using sphinx thanks to the efforts of Seth House. This new documentation system will act as the back end to the salt website which is still under heavy development. The new sphinx documentation system has also been used to greatly clean up the salt manpages. The salt 7 manpage in particular now contains extensive information which was previously only in the wiki. The new documentation can be found at: http://docs.saltstack.com/ We still have a lot to add, and when the domain is set up I will post another announcement. More additions have been made to the ZeroMQ setup, particularly in the realm of file transfers. Salt 0.8.8 introduces a built in, stateless, encrypted file server which allows salt minions to download files from the salt master using the same encryption system used for all other salt communications. The main motivation for the salt file server has been to facilitate the new salt state system. Much of the salt code has been cleaned up and a new cleaner logging system has been introduced thanks to the efforts of Pedro Algarvio. These additions will allow for much more flexible logging to be executed by salt, and fixed a great deal of my poor spelling in the salt docstrings! Pedro Algarvio has also cleaned up the API, making it easier to embed salt into another application. The biggest addition to salt found in 0.8.8 is the new state system. The salt module system has received a new front end which allows salt to be used as a configuration management system. The configuration management system allows for system configuration to be defined in data structures. The configuration management system, or as it is called in salt, the “salt state system” supports many of the features found in other configuration managers, but allows for system states to be written in a far simpler format, executes at blazing speeds, and operates via the salt minion matching system. The state system also operates within the normal scope of salt, and requires no additional configuration to use. The salt state system can enforce the following states with many more to come: Packages Files Services Executing commands Hosts The system used to define the salt states is based on a data structure, the data structure used to define the salt states has been made to be as easy to use as possible. The data structure is defined by default using a YAML file rendered via a Jinja template. This means that the state definition language supports all of the data structures that YAML supports, and all of the programming constructs and logic that Jinja supports. If the user does not like YAML or Jinja the states can be defined in yaml-mako, json-jinja, or json-mako. The system used to render the states is completely dynamic, and any rendering system can be added to the capabilities of Salt, this means that a rendering system that renders XML data in a cheetah template, or whatever you can imagine, can be easily added to the capabilities of salt. The salt state system also supports isolated environments, as well as matching code from several environments to a single salt minion. The feature base for Salt has grown quite a bit since my last serious documentation push. As we approach 0.9.0 the goals are becoming very clear, and the documentation needs a lot of work. The main goals for 0.9.0 are to further refine the state system, fix any bugs we find, get Salt running on as many platforms as we can, and get the documentation filled out. There is a lot more to come as Salt moves forward to encapsulate a much larger scope, while maintaining supreme usability and simplicity. If you would like a more complete overview of Salt please watch the Salt presentation: Slides: https://cloud.github.com/downloads/saltstack/salt/Salt.pdf -Thomas S Hatch

Salt 0.8.9 Release Notes¶

Salt 0.8.9 has finally arrived! Unfortunately this is much later than I had hoped to release 0.8.9, life has been very crazy over the last month. But despite challenges, Salt has moved forward! This release, as expected, adds few new features and many refinements. One of the most exciting aspect of this release is that the development community for salt has grown a great deal and much of the code is from contributors. Also, I have filled out the documentation a great deal. So information on States is properly documented, and much of the documentation that was out of date has been filled in.

Download!¶

The Salt source can be downloaded from the salt GitHub site: https://cloud.github.com/downloads/saltstack/salt/salt-0.8.9.tar.gz Or from PyPI: https://pypi.python.org/packages/source/s/salt/salt-0.8.9.tar.gz Here s the md5sum: 7d5aca4633bc22f59045f59e82f43b56 For instructions on how to set up Salt please see the installation instructions.

New Features¶

Salt Run¶

A big feature is the addition of Salt run, the salt-run command allows for master side execution modules to be made that gather specific information or execute custom routines from the master. Documentation for salt-run can be found here

Refined Outputters¶

One problem often complained about in salt was the fact that the output was so messy. Thanks to help from Jeff Schroeder a cleaner interface for the command output for the Salt CLI has been made. This new interface makes adding new printout formats easy and additions to the capabilities of minion modules makes it possible to set the printout mode or outputter for functions in minion modules.

Cross Calling Salt Modules¶

Salt modules can now call each other, the __salt__ dict has been added to the predefined references in minion modules. This new feature is documented in the modules documentation.

Watch Option Added to Salt State System¶

Now in Salt states you can set the watch option, this will allow watch enabled states to change based on a change in the other defined states. This is similar to subscribe and notify statements in puppet.

Root Dir Option¶

Travis Cline has added the ability to define the option root_dir which allows the salt minion to operate in a subdir. This is a strong move in supporting the minion running as an unprivileged user

Config Files Defined in Variables¶

Thanks again to Travis Cline, the master and minion configuration file locations can be defined in environment variables now.

New Modules¶

Quite a few new modules, states, returners, and runners have been made.

New Minion Modules¶

apt¶

Support for apt-get has been added, this adds greatly improved Debian and Ubuntu support to Salt!

useradd and groupadd¶

Support for manipulating users and groups on Unix-like systems.

moosefs¶

Initial support for reporting on aspects of the distributed file system, MooseFS. For more information on MooseFS please see: http://www.moosefs.org Thanks to Joseph Hall for his work on MooseFS support.

mount¶

Manage mounts and the fstab.

puppet¶

Execute puppet on remote systems.

shadow¶

Manipulate and manage the user password file.

ssh¶

Interact with ssh keys.

New States¶

user and group¶

Support for managing users and groups in Salt States.

mount¶

Enforce mounts and the fstab.

New Returners¶

mongo_return¶

Send the return information to a MongoDB server.

New Runners¶

manage¶

Display minions that are up or down.

Salt 0.9.0 Release Notes¶

Salt 0.9.0 is here. This is an exciting release, 0.9.0 includes the new network topology features allowing peer salt commands and masters of masters via the syndic interface. 0.9.0 also introduces many more modules, improvements to the API and improvements to the ZeroMQ systems.

Download!¶

The Salt source can be downloaded from the salt GitHub site: https://cloud.github.com/downloads/saltstack/salt/salt-0.9.0.tar.gz Or from PyPI: https://pypi.python.org/packages/source/s/salt/salt-0.9.0.tar.gz Here is the md5sum: 9a925da04981e65a0f237f2e77ddab37 For instructions on how to set up Salt please see the installation instructions.

New Features¶

Salt Syndic¶

The new Syndic interface allows a master to be commanded via another higher level salt master. This is a powerful solution allowing a master control structure to exist, allowing salt to scale to much larger levels then before.

Peer Communication¶

0.9.0 introduces the capability for a minion to call a publication on the master and receive the return from another set of minions. This allows salt to act as a communication channel between minions and as a general infrastructure message bus. Peer communication is turned off by default but can be enabled via the peer option in the master configuration file. Documentation on the new Peer interface.

Easily Extensible API¶

The minion and master classes have been redesigned to allow for specialized minion and master servers to be easily created. An example on how this is done for the master can be found in the master.py salt module: https://github.com/saltstack/salt/blob/develop/salt/master.py The Master class extends the SMaster class and set up the main master server. The minion functions can now also be easily added to another application via the SMinion class, this class can be found in the minion.py module: https://github.com/saltstack/salt/blob/develop/salt/minion.py

Cleaner Key Management¶

This release changes some of the key naming to allow for multiple master keys to be held based on the type of minion gathering the master key. The -d option has also been added to the salt-key command allowing for easy removal of accepted public keys. The --gen-keys option is now available as well for salt-key, this allows for a salt specific RSA key pair to be easily generated from the command line.

Improved 0MQ Master Workers¶

The 0MQ worker system has been further refined to be faster and more robust. This new system has been able to handle a much larger load than the previous setup. The new system uses the IPC protocol in 0MQ instead of TCP.

New Modules¶

Quite a few new modules have been made.

New Minion Modules¶

apache¶

Work directly with apache servers, great for managing balanced web servers

cron¶

Read out the contents of a systems crontabs

mdadm¶

Module to manage raid devices in Linux, appears as the raid module

mysql¶

Gather simple data from MySQL databases

ps¶

Extensive utilities for managing processes

publish¶

Used by the peer interface to allow minions to make publications

Salt 0.9.1 Release Notes¶

Salt 0.9.2 Release Notes¶

Salt 0.9.2 has arrived! 0.9.2 is primarily a bugfix release, the exciting component in 0.9.2 is greatly improved support for salt states. All of the salt states interfaces have been more thoroughly tested and the new salt-states git repo is growing with example of how to use states. This release introduces salt states for early developers and testers to start helping us clean up the states interface and make it ready for the world! 0.9.2 also fixes a number of bugs found on Python 2.6.

Download!¶

The Salt source can be downloaded from the salt GitHub site: https://cloud.github.com/downloads/saltstack/salt/salt-0.9.2.tar.gz Or from PyPI: https://pypi.python.org/packages/source/s/salt/salt-0.9.2.tar.gz For instructions on how to set up Salt please see the installation instructions.

New Features¶

Salt-Call Additions¶

The salt-call command has received an overhaul, it now hooks into the outputter system so command output looks clean, and the logging system has been hooked into salt-call, so the -l option allows the logging output from salt minion functions to be displayed. The end result is that the salt-call command can execute the state system and return clean output:

State System Fixes¶

The state system has been tested and better refined. As of this release the state system is ready for early testers to start playing with. If you are interested in working with the state system please check out the (still very small) salt-states GitHub repo: https://github.com/saltstack/salt-states This git repo is the active development branch for determining how a clean salt-state database should look and act. Since the salt state system is still very young a lot of help is still needed here. Please fork the salt-states repo and help us develop a truly large and scalable system for configuration management!

Notable Bug Fixes¶

Python 2.6 String Formatting¶

Python 2.6 does not support format strings without an index identifier, all of them have been repaired.

Cython Loading Disabled by Default¶

Cython loading requires a development tool chain to be installed on the minion, requiring this by default can cause problems for most Salt deployments. If Cython auto loading is desired it will need to be turned on in the minion config.

Salt 0.9.3 Release Notes¶

Salt 0.9.3 is finally arrived. This is another big step forward for Salt, new features range from proper FreeBSD support to fixing issues seen when attaching a minion to a master over the Internet. The biggest improvements in 0.9.3 though can be found in the state system, it has progressed from something ready for early testers to a system ready to compete with platforms such as Puppet and Chef. The backbone of the state system has been greatly refined and many new features are available.

Download!¶

The Salt source can be downloaded from the salt GitHub site: https://cloud.github.com/downloads/saltstack/salt/salt-0.9.3.tar.gz Or from PyPI: https://pypi.python.org/packages/source/s/salt/salt-0.9.3.tar.gz For instructions on how to set up Salt please see the installation instructions.

New Features¶

WAN Support¶

Recently more people have been testing Salt minions connecting to Salt Masters over the Internet. It was found that Minions would commonly loose their connection to the master when working over the internet. The minions can now detect if the connection has been lost and reconnect to the master, making WAN connections much more reliable.

State System Fixes¶

Substantial testing has gone into the state system and it is ready for real world usage. A great deal has been added to the documentation for states and the modules and functions available to states have been cleanly documented. A number of State System bugs have also been founds and repaired, the output from the state system has also been refined to be extremely clear and concise. Error reporting has also been introduced, issues found in sls files will now be clearly reported when executing Salt States.

Extend Declaration¶

The Salt States have also gained the extend declaration. This declaration allows for states to be cleanly modified in a post environment. Simply said, if there is an apache.sls file that declares the apache service, then another sls can include apache and then extend it:
The notable behavior with the extend functionality is that it literally extends or overwrites a declaration set up in another sls module. This means that Salt will behave as though the modifications were made directly to the apache sls. This ensures that the apache service in this example is directly tied to all requirements.

Highstate Structure Specification¶

This release comes with a clear specification of the Highstate data structure that is used to declare Salt States. This specification explains everything that can be declared in the Salt SLS modules. The specification is extremely simple, and illustrates how Salt has been able to fulfill the requirements of a central configuration manager within a simple and easy to understand format and specification.

SheBang Renderer Switch¶

It came to our attention that having many renderers means that there may be a situation where more than one State Renderer should be available within a single State Tree. The method chosen to accomplish this was something already familiar to developers and systems administrators, a SheBang. The Python State Renderer displays this new capability.

Python State Renderer¶

Until now Salt States could only be declared in yaml or json using Jinja or Mako. A new, very powerful, renderer has been added, making it possible to write Salt States in pure Python:
This renderer is used by making a run function that returns the Highstate data structure. Any capabilities of Python can be used in pure Python sls modules. This example of a pure Python sls module is the same as this example in yaml:

FreeBSD Support¶

Additional support has been added for FreeBSD, this is Salt's first branch out of the Linux world and proves the viability of Salt on non-Linux platforms. Salt remote execution already worked on FreeBSD, and should work without issue on any Unix-like platform. But this support comes in the form of package management and user support, so Salt States also work on FreeBSD now. The new freebsdpkg module provides package management support for FreeBSD and the new pw_user and pw_group provide user and group management.

Module and State Additions¶

Cron Support¶

Support for managing the system crontab has been added, declaring a cron state can be done easily:

File State Additions¶

The file state has been given a number of new features, primarily the directory, recurse, symlink, and absent functions.

Sysctl Module and State¶

The sysctl module and state allows for sysctl components in the kernel to be managed easily. the sysctl module contains the following functions:
The sysctl state allows for sysctl parameters to be assigned:

Kernel Module Management¶

A module for managing Linux kernel modules has been added. The new functions are as follows:
The kmod state can enforce modules be either present or absent:

Ssh Authorized Keys¶

The ssh_auth state can distribute ssh authorized keys out to minions. Ssh authorized keys can be present or absent.

Salt 0.9.4 Release Notes¶

Salt 0.9.4 has arrived. This is a critical update that repairs a number of key bugs found in 0.9.3. But this update is not without feature additions as well! 0.9.4 adds support for Gentoo portage to the pkg module and state system. Also there are 2 major new state additions, the failhard option and the ability to set up finite state ordering with the order option. This release also sees our largest increase in community contributions. These contributors have and continue to be the life blood of the Salt project, and the team continues to grow. I want to put out a big thanks to our new and existing contributors.

Download!¶

The Salt source can be downloaded from the salt GitHub site: https://cloud.github.com/downloads/saltstack/salt/salt-0.9.4.tar.gz Or from PyPI: https://pypi.python.org/packages/source/s/salt/salt-0.9.4.tar.gz For instructions on how to set up Salt please see the installation instructions.

New Features¶

Failhard State Option¶

Normally, when a state fails Salt continues to execute the remainder of the defined states and will only refuse to execute states that require the failed state. But the situation may exist, where you would want all state execution to stop if a single state execution fails. The capability to do this is called failing hard.

State Level Failhard¶

A single state can have a failhard set, this means that if this individual state fails that all state execution will immediately stop. This is a great thing to do if there is a state that sets up a critical config file and setting a require for each state that reads the config would be cumbersome. A good example of this would be setting up a package manager early on:
In this situation, the yum repo is going to be configured before other states, and if it fails to lay down the config file, than no other states will be executed.

Global Failhard¶

It may be desired to have failhard be applied to every state that is executed, if this is the case, then failhard can be set in the master configuration file. Setting failhard in the master configuration file will result in failing hard when any minion gathering states from the master have a state fail. This is NOT the default behavior, normally Salt will only fail states that require a failed state. Using the global failhard is generally not recommended, since it can result in states not being executed or even checked. It can also be confusing to see states failhard if an admin is not actively aware that the failhard has been set. To use the global failhard set failhard: True in the master configuration

Finite Ordering of State Execution¶

When creating salt sls files, it is often important to ensure that they run in a specific order. While states will always execute in the same order, that order is not necessarily defined the way you want it. A few tools exist in Salt to set up the correct state ordering, these tools consist of requisite declarations and order options.

The Order Option¶

Before using the order option, remember that the majority of state ordering should be done with requisite statements, and that a requisite statement will override an order option. The order option is used by adding an order number to a state declaration with the option order:
By adding the order option to 1 this ensures that the vim package will be installed in tandem with any other state declaration set to the order 1. Any state declared without an order option will be executed after all states with order options are executed. But this construct can only handle ordering states from the beginning. Sometimes you may want to send a state to the end of the line, to do this set the order to last:
Substantial testing has gone into the state system and it is ready for real world usage. A great deal has been added to the documentation for states and the modules and functions available to states have been cleanly documented. A number of State System bugs have also been founds and repaired, the output from the state system has also been refined to be extremely clear and concise. Error reporting has also been introduced, issues found in sls files will now be clearly reported when executing Salt States.

Gentoo Support¶

Additional experimental support has been added for Gentoo. This is found in the contribution from Doug Renn, aka nestegg.

Salt 0.9.5 Release Notes¶

Salt 0.9.5 is one of the largest steps forward in the development of Salt. 0.9.5 comes with many milestones, this release has seen the community of developers grow out to an international team of 46 code contributors and has many feature additions, feature enhancements, bug fixes and speed improvements. WARNING:

Community¶

Nothing has proven to have more value to the development of Salt that the outstanding community that has been growing at such a great pace around Salt. This has proven not only that Salt has great value, but also the expandability of Salt is as exponential as I originally intended. 0.9.5 has received over 600 additional commits since 0.9.4 with a swath of new committers. The following individuals have contributed to the development of 0.9.5:
This makes 21 new developers since 0.9.4 was released! To keep up with the growing community follow Salt on Ohloh ( http://www.ohloh.net/p/salt), to join the Salt development community, fork Salt on GitHub, and get coding ( https://github.com/saltstack/salt)!

Major Features¶

SPEED! Pickle to msgpack¶

For a few months now we have been talking about moving away from Python pickles for network serialization, but a preferred serialization format had not yet been found. After an extensive performance testing period involving everything from JSON to protocol buffers, a clear winner emerged. Message Pack ( http://msgpack.org/) proved to not only be the fastest and most compact, but also the most "salt like". Message Pack is simple, and the code involved is very small. The msgpack library for Python has been added directly to Salt. This move introduces a few changes to Salt. First off, Salt is no longer a "noarch" package, since the msgpack lib is written in C. Salt 0.9.5 will also have compatibility issues with 0.9.4 with the default configuration. We have gone through great lengths to avoid backwards compatibility issues with Salt, but changing the serialization medium was going to create issues regardless. Salt 0.9.5 is somewhat backwards compatible with earlier minions. A 0.9.5 master can command older minions, but only if the serial config value in the master is set to pickle. This will tell the master to publish messages in pickle format and will allow the master to receive messages in both msgpack and pickle formats. Therefore the suggested methods for upgrading are either to just upgrade everything at once, or:
Since pickles can be used as a security exploit the ability for a master to accept pickles from minions at all will be removed in a future release.

C Bindings for YAML¶

All of the YAML rendering is now done with the YAML C bindings. This speeds up all of the sls files when running states.

Experimental Windows Support¶

David Boucha has worked tirelessly to bring initial support to Salt for Microsoft Windows operating systems. Right now the Salt Minion can run as a native Windows service and accept commands. In the weeks and months to come Windows will receive the full treatment and will have support for Salt States and more robust support for managing Windows systems. This is a big step forward for Salt to move entirely outside of the Unix world, and proves Salt is a viable cross platform solution. Big Thanks to Dave for his contribution here!

Dynamic Module Distribution¶

Many Salt users have expressed the desire to have Salt distribute in-house modules, states, renderers, returners, and grains. This support has been added in a number of ways:

Modules via States¶

Now when salt modules are deployed to a minion via the state system as a file, then the modules will be automatically loaded into the active running minion - no restart required - and into the active running state. So custom state modules can be deployed and used in the same state run.

Modules via Module Environment Directories¶

Under the file_roots each environment can now have directories that are used to deploy large groups of modules. These directories sync modules at the beginning of a state run on the minion, or can be manually synced via the Salt module salt.modules.saltutil.sync_all. The directories are named:
The modules are pushed to their respective scopes on the minions.

Module Reloading¶

Modules can now be reloaded without restarting the minion, this is done by calling the salt.modules.sys.reload_modules function. But wait, there's more! Now when a salt module of any type is added via states the modules will be automatically reloaded, allowing for modules to be laid down with states and then immediately used. Finally, all modules are reloaded when modules are dynamically distributed from the salt master.

Enable / Disable Added to Service¶

A great deal of demand has existed for adding the capability to set services to be started at boot in the service module. This feature also comes with an overhaul of the service modules and initial systemd support. This means that the service state can now accept - enable: True to make sure a service is enabled at boot, and - enable: False to make sure it is disabled.

Compound Target¶

A new target type has been added to the lineup, the compound target. In previous versions the desired minions could only be targeted via a single specific target type, but now many target specifications can be declared. These targets can also be separated by and/or operators, so certain properties can be used to omit a node:
will match all minions with ids starting with webserv via a glob and minions matching the os:Debian grain. Or minions that match the db.* regular expression.

Node Groups¶

Often the convenience of having a predefined group of minions to execute targets on is desired. This can be accomplished with the new nodegroups feature. Nodegroups allow for predefined compound targets to be declared in the master configuration file:
And then used via the -N option:

Minion Side Data Store¶

The data module introduces the initial approach into storing persistent data on the minions, specific to the minions. This allows for data to be stored on minions that can be accessed from the master or from the minion. The Minion datastore is young, and will eventually provide an interface similar to a more mature key/value pair server.

Major Grains Improvement¶

The Salt grains have been overhauled to include a massive amount of extra data. this includes hardware data, os data and salt specific data.

Salt -Q is Useful Now¶

In the past the salt query system, which would display the data from recent executions would be displayed in pure Python, and it was unreadable. 0.9.5 has added the outputter system to the -Q option, thus enabling the salt query system to return readable output.

Packaging Updates¶

Huge strides have been made in packaging Salt for distributions. These additions are thanks to our wonderful community where the work to set up packages has proceeded tirelessly.

FreeBSD¶

Salt on FreeBSD? There a port for that: http://svnweb.freebsd.org/ports/head/sysutils/py-salt/ This port was developed and added by Christer Edwards. This also marks the first time Salt has been included in an upstream packaging system!

Fedora and Red Hat Enterprise¶

Salt packages have been prepared for inclusion in the Fedora Project and in EPEL for Red Hat Enterprise 5 and 6. These packages are the result of the efforts made by Clint Savage (herlo).

Debian/Ubuntu¶

A team of many contributors have assisted in developing packages for Debian and Ubuntu. Salt is still actively seeking inclusion in upstream Debian and Ubuntu and the package data that has been prepared is being pushed through the needed channels for inclusion. These packages have been prepared with the help of:

More to Come¶

We are actively seeking inclusion in more distributions. Primarily getting Salt into Gentoo, SUSE, OpenBSD, and preparing Solaris support are all turning into higher priorities.

Refinement¶

Salt continues to be refined into a faster, more stable and more usable application. 0.9.5 comes with more debug logging, more bug fixes and more complete support.

More Testing, More BugFixes¶

0.9.5 comes with more bugfixes due to more testing than any previous release. The growing community and the introduction a a dedicated QA environment have unearthed many issues that were hiding under the covers. This has further refined and cleaned the state interface, taking care of things from minor visual issues to repairing misleading data.

Custom Exceptions¶

A custom exception module has been added to throw salt specific exceptions. This allows Salt to give much more granular error information.

New Modules¶

data¶

The new data module manages a persistent datastore on the minion. Big thanks to bastichelaar for his help refining this module

freebsdkmod¶

FreeBSD kernel modules can now be managed in the same way Salt handles Linux kernel modules. This module was contributed thanks to the efforts of Christer Edwards

gentoo_service¶

Support has been added for managing services in Gentoo. Now Gentoo services can be started, stopped, restarted, enabled, disabled, and viewed.

pip¶

The pip module introduces management for pip installed applications. Thanks goes to whitinge for the addition of the pip module

rh_service¶

The rh_service module enables Red Hat and Fedora specific service management. Now Red Hat like systems come with extensive management of the classic init system used by Red Hat

saltutil¶

The saltutil module has been added as a place to hold functions used in the maintenance and management of salt itself. Saltutil is used to salt the salt minion. The saltutil module is presently used only to sync extension modules from the master server.

systemd¶

Systemd support has been added to Salt, now systems using this next generation init system are supported on systems running systemd.

virtualenv¶

The virtualenv module has been added to allow salt to create virtual Python environments. Thanks goes to whitinge for the addition of the virtualenv module

win_disk¶

Support for gathering disk information on Microsoft Windows minions The windows modules come courtesy of Utah_Dave

win_service¶

The win_service module adds service support to Salt for Microsoft Windows services

win_useradd¶

Salt can now manage local users on Microsoft Windows Systems

yumpkg5¶

The yumpkg module introduces in 0.9.4 uses the yum API to interact with the yum package manager. Unfortunately, on Red Hat 5 systems salt does not have access to the yum API because the yum API is running under Python 2.4 and Salt needs to run under Python 2.6. The yumpkg5 module bypasses this issue by shelling out to yum on systems where the yum API is not available.

New States¶

mysql_database¶

The new mysql_database state adds the ability to systems running a mysql server to manage the existence of mysql databases. The mysql states are thanks to syphernl

mysql_user¶

The mysql_user state enables mysql user management.

virtualenv¶

The virtualenv state can manage the state of Python virtual environments. Thanks to Whitinge for the virtualenv state

New Returners¶

cassandra_returner¶

A returner allowing Salt to send data to a cassandra server. Thanks to Byron Clark for contributing this returner

Salt 0.9.6 Release Notes¶

Salt 0.9.6 is a release targeting a few bugs and changes. This is primarily targeting an issue found in the names declaration in the state system. But a few other bugs were also repaired, like missing support for grains in extmods. Due to a conflict in distribution packaging msgpack will no longer be bundled with Salt, and is required as a dependency.

New Features¶

HTTP and ftp support in files.managed¶

Now under the source option in the file.managed state a HTTP or ftp address can be used instead of a file located on the salt master.

Allow Multiple Returners¶

Now the returner interface can define multiple returners, and will also return data back to the master, making the process less ambiguous.

Minion Memory Improvements¶

A number of modules have been taken out of the minion if the underlying systems required by said modules are not present on the minion system. A number of other modules need to be stripped out in this same way which should continue to make the minion more efficient.

Minions Can Locally Cache Return Data¶

A new option, cache_jobs, has been added to the minion to allow for all of the historically run jobs to cache on the minion, allowing for looking up historic returns. By default cache_jobs is set to False.

Pure Python Template Support For file.managed¶

Templates in the file.managed state can now be defined in a Python script. This script needs to have a run function that returns the string that needs to be in the named file.

Salt 0.9.7 Release Notes¶

Salt 0.9.7 is here! The latest iteration of Salt brings more features and many fixes. This release is a great refinement over 0.9.6, adding many conveniences under the hood, as well as some features that make working with Salt much better. A few highlights include the new Job system, refinements to the requisite system in states, the mod_init interface for states, external node classification, search path to managed files in the file state, and refinements and additions to dynamic module loading. 0.9.7 also introduces the long developed (and oft changed) unit test framework and the initial unit tests.

Major Features¶

Salt Jobs Interface¶

The new jobs interface makes the management of running executions much cleaner and more transparent. Building on the existing execution framework the jobs system allows clear introspection into the active running state of the running Salt interface. The Jobs interface is centered in the new minion side proc system. The minions now store msgpack serialized files under /var/cache/salt/proc. These files keep track of the active state of processes on the minion.

Functions in the saltutil Module¶

A number of functions have been added to the saltutil module to manage and view the jobs: running - Returns the data of all running jobs that are found in the proc directory. find_job - Returns specific data about a certain job based on job id. signal_job - Allows for a given jid to be sent a signal. term_job - Sends a termination signal (SIGTERM, 15) to the process controlling the specified job. kill_job Sends a kill signal (SIGKILL, 9) to the process controlling the specified job.

The jobs Runner¶

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

active¶

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

lookup_jid¶

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

list_jobs¶

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

External Node Classification¶

Salt can now use external node classifiers like Cobbler's cobbler-ext-nodes. Salt uses specific data from the external node classifier. In particular the classes value denotes which sls modules to run, and the environment value sets to another environment. An external node classification can be set in the master configuration file via the external_nodes option: https://salt.readthedocs.io/en/latest/ref/configuration/master.html#external-nodes External nodes are loaded in addition to the top files. If it is intended to only use external nodes, do not deploy any top files.

State Mod Init System¶

An issue arose with the pkg state. Every time a package was run Salt would need to refresh the package database. This made systems with slower package metadata refresh speeds much slower to work with. To alleviate this issue the mod_init interface has been added to salt states. The mod_init interface is a function that can be added to a state file. This function is called with the first state called. In the case of the pkg state, the mod_init function sets up a tag which makes the package database only refresh on the first attempt to install a package. In a nutshell, the mod_init interface allows a state to run any command that only needs to be run once, or can be used to set up an environment for working with the state.

Source File Search Path¶

The file state continues to be refined, adding speed and capabilities. This release adds the ability to pass a list to the source option. This list is then iterated over until the source file is found, and the first found file is used. The new syntax looks like this:
The source option can take sources in the list from the salt file server as well as an arbitrary web source. If using an arbitrary web source the checksum needs to be passed as well for file verification.

Refinements to the Requisite System¶

A few discrepancies were still lingering in the requisite system, in particular, it was not possible to have a require and a watch requisite declared in the same state declaration. This issue has been alleviated, as well as making the requisite system run more quickly.

Initial Unit Testing Framework¶

Because of the module system, and the need to test real scenarios, the development of a viable unit testing system has been difficult, but unit testing has finally arrived. Only a small amount of unit testing coverage has been developed, much more coverage will be in place soon. A huge thanks goes out to those who have helped with unit testing, and the contributions that have been made to get us where we are. Without these contributions unit tests would still be in the dark.

Compound Targets Expanded¶

Originally only support for and and or were available in the compound target. 0.9.7 adds the capability to negate compound targets with not.

Nodegroups in the Top File¶

Previously the nodegroups defined in the master configuration file could not be used to match nodes for states. The nodegroups support has been expanded and the nodegroups defined in the master configuration can now be used to match minions in the top file.

Salt 0.9.8 Release Notes¶

Salt 0.9.8 is a big step forward, with many additions and enhancements, as well as a number of precursors to advanced future developments. This version of Salt adds much more power to the command line, making the old hard timeout issues a thing of the past and adds keyword argument support. These additions are also available in the salt client API, making the available API tools much more powerful. The new pillar system allows for data to be stored on the master and assigned to minions in a granular way similar to the state system. It also allows flexibility for users who want to keep data out of their state tree similar to 'external lookup' functionality in other tools. A new way to extend requisites was added, the "requisite in" statement. This makes adding requires or watch statements to external state decs much easier. Additions to requisites making them much more powerful have been added as well as improved error checking for sls files in the state system. A new provider system has been added to allow for redirecting what modules run in the background for individual states. Support for openSUSE has been added and support for Solaris has begun serious development. Windows support has been significantly enhanced as well. The matcher and target systems have received a great deal of attention. The default behavior of grain matching has changed slightly to reflect the rest of salt and the compound matcher system has been refined. A number of impressive features with keyword arguments have been added to both the CLI and to the state system. This makes states much more powerful and flexible while maintaining the simple configuration everyone loves. The new batch size capability allows for executions to be rolled through a group of targeted minions a percentage or specific number at a time. This was added to prevent the "thundering herd" problem when targeting large numbers of minions for things like service restarts or file downloads.

Upgrade Considerations¶

Upgrade Issues¶

There was a previously missed oversight which could cause a newer minion to crash an older master. That oversight has been resolved so the version incompatibility issue will no longer occur. When upgrading to 0.9.8 make sure to upgrade the master first, followed by the minions.

Debian/Ubuntu Packages¶

The original Debian/Ubuntu packages were called salt and included all salt applications. New packages in the ppa are split by function. If an old salt package is installed then it should be manually removed and the new split packages need to be freshly installed. On the master:
On the minions:
And on any Syndics:
The official Salt PPA for Ubuntu is located at: https://launchpad.net/~saltstack/+archive/salt

Major Features¶

Pillar¶

Pillar offers an interface to declare variable data on the master that is then assigned to the minions. The pillar data is made available to all modules, states, sls files etc. It is compiled on the master and is declared using the existing renderer system. This means that learning pillar should be fairly trivial to those already familiar with salt states.

CLI Additions¶

The salt command has received a serious overhaul and is more powerful than ever. Data is returned to the terminal as it is received, and the salt command will now wait for all running minions to return data before stopping. This makes adding very large --timeout arguments completely unnecessary and gets rid of long running operations returning empty {} when the timeout is exceeded. When calling salt via sudo, the user originally running salt is saved to the log for auditing purposes. This makes it easy to see who ran what by just looking through the minion logs. The salt-key command gained the -D and --delete-all arguments for removing all keys. Be careful with this one!

Running States Without a Master¶

The addition of running states without a salt-master has been added to 0.9.8. This feature allows for the unmodified salt state tree to be read locally from a minion. The result is that the UNMODIFIED state tree has just become portable, allowing minions to have a local copy of states or to manage states without a master entirely. This is accomplished via the new file client interface in Salt that allows for the salt:// URI to be redirected to custom interfaces. This means that there are now two interfaces for the salt file server, calling the master or looking in a local, minion defined file_roots. This new feature can be used by modifying the minion config to point to a local file_roots and setting the file_client option to local.

Keyword Arguments and States¶

State modules now accept the **kwargs argument. This results in all data in a sls file assigned to a state being made available to the state function. This passes data in a transparent way back to the modules executing the logic. In particular, this allows adding arguments to the pkg.install module that enable more advanced and granular controls with respect to what the state is capable of. An example of this along with the new debconf module for installing ldap client packages on Debian:

Keyword Arguments and the CLI¶

In the past it was required that all arguments be passed in the proper order to the salt and salt-call commands. As of 0.9.8, keyword arguments can be passed in the form of kwarg=argument.

Matcher Refinements and Changes¶

A number of fixes and changes have been applied to the Matcher system. The most noteworthy is the change in the grain matcher. The grain matcher used to use a regular expression to match the passed data to a grain, but now defaults to a shell glob like the majority of match interfaces in Salt. A new option is available that still uses the old style regex matching to grain data called grain-pcre. To use regex matching in compound matches use the letter P. For example, this would match any ArchLinux or Fedora minions:
And the associated compound matcher suitable for top.sls is P:
NOTE: Changing the grains matcher from pcre to glob is backwards incompatible. Support has been added for matching minions with Yahoo's range library. This is handled by passing range syntax with -R or --range arguments to salt. More information at: https://github.com/ytoolshed/range/wiki/%22yamlfile%22-module-file-spec

Requisite in¶

A new means to updating requisite statements has been added to make adding watchers and requires to external states easier. Before 0.9.8 the only way to extend the states that were watched by a state outside of the sls was to use an extend statement:
But the new Requisite in statement allows for easier extends for requisites:
Requisite in is part of the extend system, so still remember to always include the sls that is being extended!

Providers¶

Salt predetermines what modules should be mapped to what uses based on the properties of a system. These determinations are generally made for modules that provide things like package and service management. The apt module maps to pkg on Debian and the yum module maps to pkg on Fedora for instance. Sometimes in states, it may be necessary for a non-default module to be used for the desired functionality. For instance, an Arch Linux system may have been set up with systemd support. Instead of using the default service module detected for Arch Linux, the systemd module can be used:
Default providers can also be defined in the minion config file:
When default providers are passed in the minion config, then those providers will be applied to all functionality in Salt, this means that the functions called by the minion will use these modules, as well as states.

Requisite Glob Matching¶

Requisites can now be defined with glob expansion. This means that if there are many requisites, they can be defined on a single line. To watch all files in a directory:
This example will watch all defined files that match the glob /etc/http/conf.d/*

Batch Size¶

The new batch size option allows commands to be executed while maintaining that only so many hosts are executing the command at one time. This option can take a percentage or a finite number:
This will only run test.ping on 10 of the targeted minions at a time and then restart apache on 25% of the minions matching os:RedHat at a time and work through them all until the task is complete. This makes jobs like rolling web server restarts behind a load balancer or doing maintenance on BSD firewalls using carp much easier with salt.

Module Updates¶

This is a list of notable, but non-exhaustive updates with new and existing modules. Windows support has seen a flurry of support this release cycle. We've gained all new file, network, and shadow modules. Please note that these are still a work in progress. For our ruby users, new rvm and gem modules have been added along with the associated states The virt module gained basic Xen support. The yum module gained Scientific Linux support. The pkg module on Debian, Ubuntu, and derivatives force apt to run in a non-interactive mode. This prevents issues when package installation waits for confirmation. A pkg module for OpenSUSE's zypper was added. The service module on Ubuntu natively supports upstart. A new debconf module was contributed by our community for more advanced control over deb package deployments on Debian based distributions. The mysql.user state and mysql module gained a password_hash argument. The cmd module and state gained a shell keyword argument for specifying a shell other than /bin/sh on Linux / Unix systems. New git and mercurial modules have been added for fans of distributed version control.

In Progress Development¶

Master Side State Compiling¶

While we feel strongly that the advantages gained with minion side state compiling are very critical, it does prevent certain features that may be desired. 0.9.8 has support for initial master side state compiling, but many more components still need to be developed, it is hoped that these can be finished for 0.9.9. The goal is that states can be compiled on both the master and the minion allowing for compilation to be split between master and minion. Why will this be great? It will allow storing sensitive data on the master and sending it to some minions without all minions having access to it. This will be good for handling ssl certificates on front-end web servers for instance.

Solaris Support¶

Salt 0.9.8 sees the introduction of basic Solaris support. The daemon runs well, but grains and more of the modules need updating and testing.

Windows Support¶

Salt states on windows are now much more viable thanks to contributions from our community! States for file, service, local user, and local group management are more fully fleshed out along with network and disk modules. Windows users can also now manage registry entries using the new "reg" module.

Salt 0.9.9 Release Notes¶

0.9.9 is out and comes with some serious bug fixes and even more serious features. This release is the last major feature release before 1.0.0 and could be considered the 1.0.0 release candidate. A few updates include more advanced kwargs support, the ability for salt states to more safely configure a running salt minion, better job directory management and the new state test interface. Many new tests have been added as well, including the new minion swarm test that allows for easier testing of Salt working with large groups of minions. This means that if you have experienced stability issues with Salt before, particularly in larger deployments, that these bugs have been tested for, found, and killed.

Major Features¶

State Test Interface¶

Until 0.9.9 the only option when running states to see what was going to be changed was to print out the highstate with state.show_highstate and manually look it over. But now states can be run to discover what is going to be changed. Passing the option test=True to many of the state functions will now cause the salt state system to only check for what is going to be changed and report on those changes.
Now states that would have made changes report them back in yellow.

State Syntax Update¶

A shorthand syntax has been added to sls files, and it will be the default syntax in documentation going forward. The old syntax is still fully supported and will not be deprecated, but it is recommended to move to the new syntax in the future. This change moves the state function up into the state name using a dot notation. This is in-line with how state functions are generally referred to as well: The new way:

Use and Use_in Requisites¶

Two new requisite statements are available in 0.9.9. The use and use_in requisite and requisite-in allow for the transparent duplication of data between states. When a state "uses" another state it copies the other state's arguments as defaults. This was created in direct response to the new network state, and allows for many network interfaces to be configured in the same way easily. A simple example:
This makes the 2 lower state decs inherit the options from their respectively "used" state decs.

Network State¶

The new network state allows for the configuration of network devices via salt states and the ip salt module. This addition has been given to the project by Jeff Hutchins and Bret Palsson from Jive Communications. Currently the only network configuration backend available is for Red Hat based systems, like Red Hat Enterprise, CentOS, and Fedora.

Exponential Jobs¶

Originally the jobs executed were stored on the master in the format: <cachedir>/jobs/jid/{minion ids} But this format restricted the number of jobs in the cache to the number of subdirectories allowed on the filesystem. Ext3 for instance limits subdirectories to 32000. To combat this the new format for 0.9.9 is: <cachedir>/jobs/jid_hash[:2]/jid_hash[2:]/{minion ids} So that now the number of maximum jobs that can be run before the cleanup cycle hits the job directory is substantially higher.

ssh_auth Additions¶

The original ssh_auth state was limited to accepting only arguments to apply to a public key, and the key itself. This was restrictive due to the way the we learned that many people were using the state, so the key section has been expanded to accept options and arguments to the key that over ride arguments passed in the state. This gives substantial power to using ssh_auth with names:

LocalClient Additions¶

To follow up the recent additions in 0.9.8 of additional kwargs support, 0.9.9 also adds the capability to send kwargs into commands via a dict. This addition to the LocalClient api can be used like so:
This update has been added to all cmd methods in the LocalClient class.

Better Self Salting¶

One problem faced with running Salt states, is that it has been difficult to manage the Salt minion via states, this is due to the fact that if the minion is called to restart while a state run is happening then the state run would be killed. 0.9.9 slightly changes the process scope of the state runs, so now when salt is executing states it can safely restart the salt-minion daemon. In addition to daemonizing the state run, the apt module also daemonizes. This update makes it possible to cleanly update the salt-minion package on Debian/Ubuntu systems without leaving apt in an inconsistent state or killing the active minion process mid-execution.

Wildcards for SLS Modules¶

Now, when including sls modules in include statements or in the top file, shell globs can be used. This can greatly simplify listing matched sls modules in the top file and include statements:

External Pillar¶

Since the pillar data is just, data, it does not need to come expressly from the pillar interface. The external pillar system allows for hooks to be added making it possible to extract pillar data from any arbitrary external interface. The external pillar interface is configured via the ext_pillar option. Currently interfaces exist to gather external pillar data via hiera or via a shell command that sends yaml data to the terminal:
The initial external pillar interfaces and extra interfaces can be added to the file salt/pillar.py, it is planned to add more external pillar interfaces. If the need arises a new module loader interface will be created in the future to manage external pillar interfaces.

Single State Executions¶

The new state.single function allows for single states to be cleanly executed. This is a great tool for setting up a small group of states on a system or for testing out the behavior of single states:
The test interface functions here as well, so changes can also be tested against as:

New Tests¶

A few exciting new test interfaces have been added, the minion swarm allows not only testing of larger loads, but also allows users to see how Salt behaves with large groups of minions without having to create a large deployment.

Minion Swarm¶

The minion swarm test system allows for large groups of minions to be tested against easily without requiring large numbers of servers or virtual machines. The minion swarm creates as many minions as a system can handle and roots them in the /tmp directory and connects them to a master. The benefit here is that we were able to replicate issues that happen only when there are large numbers of minions. A number of elusive bugs which were causing stability issues in masters and minions have since been hunted down. Bugs that used to take careful watch by users over several days can now be reliably replicated in minutes, and fixed in minutes. Using the swarm is easy, make sure a master is up for the swarm to connect to, and then use the minionswarm.py script in the tests directory to spin up as many minions as you want. Remember, this is a fork bomb, don't spin up more than your hardware can handle!

Shell Tests¶

The new Shell testing system allows us to test the behavior of commands executed from a high level. This allows for the high level testing of salt runners and commands like salt-key.

Client Tests¶

Tests have been added to test the aspects of the client APIs and ensure that the client calls work, and that they manage passed data, in a desirable way. SEE ALSO:
SEE ALSO:

AUTHOR¶

Thomas S. Hatch <thatch45@gmail.com> and many others, please see the Authors file